Interview Question: How Do You Maintain CLAUDE.md in Claude Code? My Honest Reply

01 | What Is CLAUDE.md?

CLAUDE.md is a markdown file placed at the project root that Claude reads automatically before any conversation, acting as a "ground truth" for the AI. Unlike a README, it is consumed by the model as default context for every request.

Example: creating a CLAUDE.md with a single rule "When explaining any technical concept, start with a metaphor." causes Claude to prepend a metaphor to its answer about agents, even though the question didn’t mention the rule.

02 | Why Writing Too Much Can Be Counterproductive

Initial intuition that more rules improve Claude’s behavior proved wrong. A study by SFEIR Institute showed that keeping CLAUDE.md under 200 lines yields ~92% rule compliance, while exceeding 400 lines drops compliance dramatically.

Splitting a 200‑line file into five 30‑line modules in .claude/rules/ raised compliance to 96%.

Two main reasons:

Token economy: Each line consumes tokens, reducing space for conversation, code, and tool results.

Attention dilution: The model’s attention is finite; too many rules dilute the weight of each.

Therefore, it’s crucial to prune unnecessary content.

03 | What Makes a Rule Effective?

Effective rules are short, specific, explain the rationale, and are continuously updated. For example, "All TypeScript files must use 2‑space indentation" (specific) is better than "Code should follow formatting guidelines" (vague).

Short, concrete, explain why, continuously update.

Four categories of bad rules to remove:

Redundant copies of project documentation (replace with a reference link).

Wishful statements like "We aim for 90% test coverage" (keep only enforceable actions).

Glossaries of common terms (LLMs already know them; keep only team‑specific jargon).

Include the reason behind hard constraints, e.g., "Never write to the production database – last year a test cleared the users table, causing an incident."

04 | CLAUDE.md Is Not Just a Single File

CLAUDE.md can be layered:

Project root CLAUDE.md: General tech stack, commands, hard constraints.

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

Global ~/.claude/CLAUDE.md : Personal preferences across projects.

The loader walks up the directory tree, merging each CLAUDE.md and .claude/CLAUDE.md it finds.

Path‑scoped rules can be placed in .claude/rules/ with a YAML front‑matter paths field, ensuring they load only for matching files (e.g., test files, API files).

---
paths: ["**/*.test.ts", "**/*.spec.ts"]
---
- Use <code>describe/it</code>, not <code>test()</code>
- Mock external deps with <code>vi.mock</code>

05 | Getting Started: /init and /memory

To bootstrap a CLAUDE.md, run the /init command inside Claude Code. It scans the repository and generates a draft with detected tech stack, directory layout, and common commands.

During a session, use /memory to edit CLAUDE.md on the fly or let Claude add a rule when it makes a mistake. A practical rule‑addition trigger is: "If Claude fails twice on the same task, add a defensive rule."

Plan Mode (Shift+Tab twice) lets Claude propose a plan before writing code, incorporating all active CLAUDE.md rules for higher quality output.

06 | A Ready‑to‑Use Template

The article provides a six‑section template (≈80 lines) covering Project Overview, Commands, Architecture, Conventions, Hard Constraints, and Gotchas. Each section includes concrete examples, command snippets, and rationale.

# CLAUDE.md

## 1. Project Overview
- B‑side order management system
- Tech stack: TypeScript, Next.js 14, PostgreSQL
- Deploy: Vercel + Supabase

## 2. Commands
- Install deps: `pnpm install`
- Start dev: `pnpm dev`
- Run tests: `pnpm test`
- Type check: `pnpm typecheck`
- Lint: `pnpm lint`

## 3. Architecture
- Frontend in app/
- API routes in app/api/
- DB schema in prisma/schema.prisma
- Detailed docs in docs/architecture.md

## 4. Conventions
- Component files PascalCase
- Utility files kebab-case
- API responses { data, error }
- Use Result type for errors

## 5. Hard Constraints
- Never write to production DB (last year accident)
- Do not modify merged migrations
- .env must stay out of git
- All API routes require auth middleware

## 6. Gotchas
- Run `pnpm db:push` before dev
- Prisma may crash on macOS; restart server
- Vercel logs are in the dashboard

The template emphasizes brevity, specificity, rationale, and continuous updates.

Key Takeaways

1. CLAUDE.md is an agent‑focused onboarding document, not a human README.

2. Aim for ~200 lines or fewer; split into modular files for higher compliance.

3. Write short, verifiable rules, explain why they exist, and keep the file alive with regular reviews.