Skip to content
BSWEN
Blog

How to Optimize CLAUDE.md for Better AI Coding Results

Cowrie
Cowrie
Dev @ Bswen

The Problem: Claude Started Getting Dumber

I noticed something frustrating. Claude Code, which used to be my sharp coding partner, started giving me generic, unhelpful responses. I’d ask about my project architecture and get boilerplate answers that ignored my actual codebase.

I kept adding more context to my CLAUDE.md file. More project details. More coding standards. More everything. The file grew to 500+ lines, then 800+ lines. Yet Claude’s responses kept getting worse.

The irony hit me: I was drowning Claude in information, and it was choking on the flood.

What Actually Works: Progressive Disclosure

I found a Reddit thread where users discussed why Claude seemed to get worse over time. The top-voted comment (54 points) by ZachVorhies gave the answer I needed:

“Reorganizing CLAUDE.md into a progressive disclosure strategy where information is pushed down into folders and there is a docs/ folder where specific categories of information is stashed.”

This was the breakthrough. Instead of one massive file, I needed a hierarchy. Root CLAUDE.md gives the overview. Details live in subfolders where Claude can find them when needed.

How I Restructured My CLAUDE.md

Before: The Bloated Mess

CLAUDE.md (OLD - 800+ lines)
# Project: My Web Application


## Architecture
[200 lines of architecture details...]


## Coding Standards
[150 lines of style rules...]


## API Endpoints
[100 lines of endpoint documentation...]


## Database Schema
[200 lines of table definitions...]


## Development Workflows
[150 lines of git, CI/CD, deployment...]

Claude had to read all 800+ lines every time. Most of it irrelevant to the task at hand.

After: The Progressive Disclosure Structure

CLAUDE.md (NEW - ~100 lines)
# Current Project: Web Application
# Stack: React, TypeScript, Node.js


# See docs/ for detailed architecture
# See .claude/rules/ for coding standards


# Current Sprint Goals
- Feature: User authentication
- Bug: Fix login redirect issue


# Key Files
- src/auth/ - Authentication logic
- src/api/ - API endpoints
docs/ folder structure
docs/
├── architecture.md    # System design decisions
├── api-endpoints.md    # API documentation
├── database.md         # Schema details
└── workflows.md        # Development workflows
.claude/rules/coding-style.md
# Coding Style


## Immutability (CRITICAL)
ALWAYS create new objects, NEVER mutate existing ones.


## File Organization
- 200-400 lines typical, 800 max
- Extract utilities from large components
- Organize by feature/domain, not by type

Why This Makes Claude Smarter

  1. Context window efficiency: Claude reads relevant context first, not everything
  2. Faster responses: Less noise means faster processing
  3. Better accuracy: Focused context leads to focused answers
  4. Easier maintenance: Update specific docs without touching root config

Common Mistakes to Avoid

I made these mistakes. Learn from my failures:

  • Mistake 1: Putting everything in one file because “Claude needs all the context”
  • Mistake 2: Never updating CLAUDE.md when project scope changes
  • Mistake 3: Copying CLAUDE.md between projects without customization
  • Mistake 4: Including outdated information that contradicts current code

The Results After Restructuring

After I implemented progressive disclosure:

  • Claude started referencing actual file paths in my project
  • Responses became specific to my architecture, not generic suggestions
  • Context loading felt faster (anecdotal, but noticeable)
  • I could update documentation without fear of breaking the “brain” of my AI assistant

Summary

In this post, I showed how to fix a bloated CLAUDE.md by using progressive disclosure. The key insight: organize information into hierarchical folders instead of cramming everything into one file. Keep your root CLAUDE.md focused on current task context. Push detailed documentation into docs/ and rules/ subdirectories where Claude can find them when needed.

A well-organized CLAUDE.md is the difference between a confused AI and a powerful coding partner. Spend the time to structure your context properly.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: