Your CLAUDE.md should grow with your project through four intentional stages, adding rejected alternatives and 'never do this' rules to prevent Claude from re-litigating settled decisions.
Stop Rewriting CLAUDE.md: The 4-Stage Evolution That Cuts Context Waste 40%
Last Tuesday you pasted the same 15 lines of project context into Claude—for the 47th time. Stack, conventions, database schema, the "don't use localStorage for JWT" rule. Every. Single. Session.
That's when it hits you: your CLAUDE.md is frozen in time, written for a prototype that became a production app six months ago.
Most guides tell you what to put in CLAUDE.md. This is about when to put it there. Your CLAUDE.md should grow with your project. Here are the four stages, from empty file to enterprise harness.
Stage 1: The Blank Canvas (Prototype)
When you mkdir a new project, you don't need a 200-line CLAUDE.md. You need 10 lines.
# CLAUDE.md
## Project
Name: TaskFlow (working title)
Purpose: Team task management system
## Stack
- Frontend: React + TypeScript
- Backend: Node.js + Express
- Database: PostgreSQL
## Rules
- TypeScript strict mode
- Conventional Commits
That's it. At this stage, record what is, not why. You haven't made enough decisions to document reasoning yet. The prototype will pivot three times before lunch.
The mistake I see most often: copying someone else's 150-line CLAUDE.md template on day one. Claude dutifully follows rules written for a different project, a different team, a different architecture. Start small. Grow intentionally.
Stage 2: The MVP Harness
Your prototype survived. Users exist. Now decisions start accumulating, and the most valuable thing you can document is what you chose NOT to use.
## Architecture decisions
### Frontend
- React 18 + TypeScript 5.0
- State: Zustand (Redux was overkill for our scale)
- UI: Material-UI (minimizing custom design work)
- Routing: React Router v6
### Backend
- Node.js 18 + Express 4
- API: REST (GraphQL postponed -- added complexity, no consumer demand yet)
- Auth: JWT + refresh token
- DB: PostgreSQL 15
### Rejected alternatives (and why)
- Vue.js: team has deeper React experience
- GraphQL: REST covers current use cases, less overhead
- MongoDB: relational data model fits better
The "rejected alternatives" section is the hidden gem. Without it, every new team member (and every new Claude session) will suggest the same alternatives you already evaluated. You'll waste tokens re-litigating decisions that were settled months ago.
I learned this the hard way. Claude kept suggesting GraphQL migrations in code reviews until I added one line: GraphQL: postponed -- REST covers current needs. That single line saved dozens of conversations.
This stage is also where you start recording architecture decisions as they happen. Every time you pick a library, reject an approach, or settle a debate in a PR review—add it to CLAUDE.md. Future-you and future-Claude will thank present-you. The cost is one line per decision. The payoff is every session after that starts with shared context instead of a blank slate.
Stage 3: The Production Rulebook
Your app is live. Users are paying. Now the stakes are higher, and the most important section becomes the one most teams skip: "never do this".
## Coding standards
### TypeScript
- Interface names: PascalCase, no I prefix
- Prefer undefined over null (API consistency)
- Shared types in types/, component-local types inline
### React
- Functional components only (no class components)
- Custom hooks: use- prefix required
- Props: destructure when 3+ properties
## Never do this
### Security
- Never store JWT in localStorage -> use httpOnly cookies
- Never embed API keys in frontend code
- Never build SQL with string concatenation -> parameterized queries only
### Performance
- Never skip useEffect dependency arrays (infinite loop risk)
- Never use key={index} on dynamic lists
- Never render images without optimization (use next/image)
### Operations
- Never push directly to production branch
- Never run migrations without backup
- Never rollback without checking logs first
The "never do this" section works because Claude treats it as a hard constraint. When you ask Claude to implement auth, it won't even suggest localStorage—the option is pre-eliminated. That's Context Engineering at its core: shaping the solution space before the question is asked—or, more practically, you write rules in a text file and Claude stops arguing about things you've already decided.
This is also where security constraints belong. If your CLAUDE.md says "parameterized queries only", Claude will generate parameterized queries by default. No reminder needed. No code review catch needed. The context does the work.
Stage 4: The Enterprise Harness
Your team grew to 12 people. Your monolith split into 6 services. Your CLAUDE.md is now 300 lines long and eating your context window.
Time to split it up.
project/
├── CLAUDE.md # Core rules only (~50 lines)
├── docs/
│ ├── ARCHITECTURE.md # System design details
│ ├── API-DESIGN.md # API design guide
│ └── SECURITY.md # Security requirements
└── .claude/
└── agents/
├── frontend.md # Frontend specialist
├── backend.md # Backend specialist
└── devops.md # DevOps specialist
The parent CLAUDE.md stays lean—project overview, shared rules, and a map of where specialist knowledge lives. Each sub-agent file contains domain-specific context that only loads when relevant.
The real power comes from hooks that auto-inject context based on what you're working on:
#!/bin/bash
# .claude/hooks/user-prompt-submit.sh
PROMPT="$1"
if echo "$PROMPT" | grep -qi "react\|component\|hook\|frontend"; then
cat .claude/agents/frontend.md
fi
if echo "$PROMPT" | grep -qi "api\|database\|auth\|backend"; then
cat .claude/agents/backend.md
fi
# Security context always loads for auth-related work
if echo "$PROMPT" | grep -qi "auth\|token\|security"; then
cat docs/SECURITY.md
fi
This is the same pattern that large codebases use for CI/CD: don't run everything every time. Load what's relevant. Your context window is a budget—spend it wisely.
What This Looks Like in Practice
On my team, the split reduced our average context consumption by roughly 40%. Before the split, every Claude session loaded 300+ lines of rules regardless of the task. After: a frontend bug fix loads ~80 lines (core + frontend.md), a database migration loads ~90 lines (core + backend.md), and a deployment task loads ~70 lines (core + devops.md).
The unexpected benefit was consistency. When the frontend specialist context lives in one file, everyone gets the same frontend rules. No more "which version of the rules did you load?" conversations.
The Evolution Mindset
Your CLAUDE.md isn't a document you write once. It's a living system that should evolve with your project:
- Stage 1 (Prototype): What exists today
- Stage 2 (MVP): What we rejected and why
- Stage 3 (Production): What we must never do
- Stage 4 (Enterprise): Where the rules live
The key insight: Add context when decisions become permanent, not when they're made. That first prototype decision might change tomorrow. Wait until it survives three PR reviews before documenting it.
Stop pasting the same context. Start evolving your CLAUDE.md.
Originally published on gentic.news
Top comments (0)