How to Design a CLAUDE.md That Actually Works

CLAUDE.md is not a README for humans. It's onboarding docs for your AI teammate.

That distinction changes everything about how you write it. A README explains what the project does. CLAUDE.md tells an AI agent what to do, how to behave, what the rules are, and where to find things — so it can act, not just understand.

Most CLAUDE.md files are written like READMEs. They describe the project. They don't direct the agent. The result: the agent reads it, nods along, and then does whatever it would have done anyway.

Here's how to write one that actually changes agent behavior.

The 3 Scopes (Don't Confuse Them)

Before you write a single line, understand where this CLAUDE.md will live:

Global (~/.claude/CLAUDE.md)

Personal defaults across all your projects. Coding style preferences, universal rules, how you like tests structured. This is your agent's personality layer.

Project (./CLAUDE.md)

Project-specific rules, build commands, test setup, team conventions. The most important file in the stack. This is what your whole team shares.

Folder (./src/CLAUDE.md)

Module-level overrides for specific subsystems — different rules for the API layer vs the components layer vs the utils. Use sparingly; only when a subsystem has genuinely different conventions.

Resolution order: Global → Project → Folder. Last scope wins on conflicts.

The WHAT / WHY / HOW Framework

Structure your CLAUDE.md around three questions:

WHAT — Give Context

• Project name and purpose (one sentence)
• Tech stack and versions
• Repository structure map
• Key dependencies
• Environment variables

WHY — Set Principles

• Architecture decisions and their reasoning (not just what, but why)
• Naming conventions
• Code style and lint rules
• Anti-patterns to avoid — this is crucial and often skipped

HOW — Define Workflows

• Build commands: npm run build
• Test commands: npm test
• Lint commands: eslint . --fix
• Commit format expectations
• Deploy and CI/CD steps

Vague vs Precise: The Critical Distinction

Most CLAUDE.md files fail because they're vague. Vague instructions are worse than no instructions — they give the agent false confidence that it knows the rules while providing no actual constraint on behavior.

Vague → Precise:

❌ "Write clean code"

✅ "Use camelCase for variables, PascalCase for components. Maximum function length: 40 lines. No nested ternaries."

❌ "Test everything"

✅ "Run npm test -- --watch, minimum 80% coverage for utils/. New functions require tests before PR approval."

❌ "Follow best practices"

✅ "Use App Router only — no pages/ directory. Server Components by default, 'use client' only when required."

The test: can a new team member follow this instruction without asking a clarifying question? If not, it's too vague.

The 5 Rules That Make It Work

1. Run /init first

Let Claude scaffold the baseline from your project structure, then curate. Don't write CLAUDE.md from scratch — you'll miss things the codebase already implies.

2. Stay under 500 lines

Too long = ignored context. The agent's attention degrades as the file grows. Every line should earn its place.

3. Use Hooks for 100% enforcement

CLAUDE.md is followed ~70% of the time. Hooks are deterministic — they run every time. For critical rules (no rm -rf, linting on every write, security checks), implement them as hooks, not CLAUDE.md instructions.

4. Update it monthly

CLAUDE.md is a living document. It should reflect your actual architecture, not the architecture you had when you first wrote it. Stale CLAUDE.md is worse than none — it actively misleads the agent.

5. Reference files, don't duplicate

Point to package.json for scripts. Point to tsconfig.json for TypeScript rules. Don't copy content from other config files into CLAUDE.md — they'll diverge and you'll have two sources of truth.

The Anti-Patterns

These are the patterns that make CLAUDE.md actively harmful:

• 500+ lines → causes context bloat, agent skips or skims
• Vague instructions → "Write good code" gives the agent nothing to work with
• Duplicating docs → link, don't copy; divergence creates contradictions
• No test guidance → skipped tests, inconsistent coverage
• No error patterns → agent handles errors differently every time
• Architecture that's already changed → the agent will confidently implement the old approach

The One-Sentence Summary

CLAUDE.md is your agent's constitution — write it with the precision of a policy document and the conciseness of a reference card.

Jason Newell is an AI practitioner, builder, and writer covering agentic systems, developer tooling, and the future of AI engineering.