Interview Insight: Mastering CLAUDE.md Maintenance for Claude Code

01 | What Is CLAUDE.md?

CLAUDE.md is a plain markdown file placed at the project root (named CLAUDE.md) that Claude Code reads automatically before every conversation. It serves as the "ground truth" for the agent, similar to a team agreement, and is loaded into the model’s context each time.

Unlike a README, which is for humans, CLAUDE.md is for the agent. Claude never reads a README unless explicitly told.

When Claude starts, it traverses from the current directory up to the filesystem root, collecting every CLAUDE.md and .claude/CLAUDE.md it finds, merges them, and feeds the combined content to the model.

02 | Why Writing Too Much Is Counter‑Productive

Community data from the SFEIR Institute shows that when CLAUDE.md stays under 200 lines, rule‑adherence is about 92 %. Once the file exceeds 400 lines, adherence drops dramatically (around 70 %).

Two main reasons:

Token economics : The whole file is loaded each request, consuming thousands of tokens and leaving less room for actual conversation and tool output.

Attention dilution : More rules mean each rule receives less weight in the model’s reasoning.

Therefore, it’s not enough to simply limit line count; you must also remove content that does not belong in CLAUDE.md.

Typical dead‑weight content

Repetition type : Copy‑pasting the entire project architecture. Instead, reference the architecture file, e.g., "See docs/architecture.md."

Wishful type : Statements like "We hope test coverage reaches 90 %". Claude cannot infer intent; keep only enforceable rules such as "Run npm test before PR."

Glossary type : Generic term definitions ("Repo means repository"). The model already knows these; only project‑specific slang belongs here, and even that can be moved to docs/glossary.md.

03 | What Makes a Rule Effective?

Effective rules are short, specific, explain why, and stay up‑to‑date . For example, instead of "All TypeScript files use 2‑space indentation" (specific) versus "Code should be formatted" (vague), the former is verifiable and Claude can self‑check.

Four principles (illustrated with a table in the original article) are:

Short – stay near the 200‑line sweet spot.

Specific – turn abstract intent into concrete commands or paths.

Explain why – add a brief rationale so Claude can reason about edge cases.

Continuously update – delete stale rules and add new ones when Claude makes mistakes.

04 | CLAUDE.md Is Layered, Not a Single File

Multiple CLAUDE.md files can be active simultaneously:

Project‑root CLAUDE.md : General tech stack, directory layout, hard constraints.

Sub‑directory CLAUDE.md (e.g., frontend/CLAUDE.md, backend/CLAUDE.md): Module‑specific conventions.

Global user CLAUDE.md ( ~/.claude/CLAUDE.md): Personal preferences that apply to every project.

The loading algorithm walks up the directory tree, merges each level’s file, and finally merges the global file.

05 | Path‑Scoped Rules with .claude/rules/

Instead of a monolithic file, place each thematic rule set in .claude/rules/. Each file should be under ~30 lines and can include a YAML front‑matter block that limits when the rule is loaded, e.g.:

---
paths: ["**/*.test.ts", "**/*.spec.ts"]
---
# Testing rules
- Use <code>describe / it</code>, not <code>test()</code>
- Mock external deps with <code>vi.mock</code>
- One assertion per test
- Avoid <code>expect.anything()</code>

Similarly, an API‑design rule can specify paths: ["src/api/**/*.ts"], ensuring it only applies when editing API files. This “path‑scoped rule” approach reduces token waste and improves adherence (the SFEIR study reported 96 % compliance when rules were modularized).

06 | Initialising and Maintaining CLAUDE.md

When a project lacks a CLAUDE.md, run the built‑in /init command. Claude scans the repository, infers the tech stack, common commands, and generates a draft file. Review and trim the draft.

During a session, you can add or edit rules on the fly with /memory. Claude will pop up the current CLAUDE.md for editing, or you can say “remember this rule” and it will append it to the appropriate file.

When Claude makes the same mistake twice, the community recommends adding a defensive rule (“Claude made two errors → add a new rule”).

07 | Plan Mode and Command Extensions

For complex changes, switch to Plan Mode (Shift+Tab twice). Claude first produces a plan that respects all CLAUDE.md rules, then you confirm before code generation. A well‑crafted CLAUDE.md directly improves plan quality.

08 | A Ready‑to‑Use Template

The article ends with a concise 80‑line template divided into six sections: Project Overview, Commands, Architecture, Conventions, Hard Constraints, and Gotchas. Each section includes concrete, verifiable statements and occasional “why” notes (e.g., “Don’t write to production DB – last year we wiped the users table”).

# CLAUDE.md
## 1. Project Overview
- B‑side order‑management system
- Tech stack: TypeScript + Next.js 14 + PostgreSQL
- Deploy: Vercel + Supabase
## 2. Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`
- Type‑check: `pnpm typecheck`
- Lint: `pnpm lint`
## 3. Architecture
- Frontend in `app/` (App Router)
- API routes in `app/api/`
- DB schema in `prisma/schema.prisma`
- Detailed docs in `docs/architecture.md`
## 4. Conventions
- Components use PascalCase
- Utils use kebab-case
- API responses follow `{ data, error }`
- Errors handled via Result type
## 5. Hard Constraints
- Never write to production DB (incident last year)
- Do not modify merged migrations under `prisma/migrations/`
- `.env` must stay out of git
- All API routes require `requireAuth()`
## 6. Gotchas
- Run `pnpm db:push` before dev
- Restart dev server if Prisma crashes on macOS
- Vercel logs are in the dashboard, not the terminal

Key takeaways for interview answers: CLAUDE.md is an agent‑focused onboarding document, keep it under 200 lines, make rules concrete and explain their rationale, and treat it as a living configuration that evolves with the project.

References

Anthropic official docs: CLAUDE.md usage guide.

claudeguide.io – patterns and real examples.

claude‑codex.fr – six‑section template source.

SFEIR Institute – deep‑dive data (200 lines ≈ 92 % compliance, modular ≈ 96 %).