Writing an Effective CLAUDE.md

CLAUDE.md is the single highest-leverage file in an agentic coding project. It’s not documentation — it’s a constraint system. Every rule exists because the agent got something wrong at least once.

What CLAUDE.md Actually Does

When Claude Code starts a session, it reads CLAUDE.md before doing anything else. The file sets:

• Boundaries — what the agent must not touch
• Conventions — how code should look in this project
• Build commands — how to verify changes work
• File pointers — where to find key parts of the codebase

Without CLAUDE.md, the agent falls back on training data. Training data is generic. Your project is specific. The gap between those two is where bugs live.

Structure That Works

A well-structured CLAUDE.md has four sections, in this order:

1. Stack Declaration

State the framework, language, and key libraries. Be specific about versions when it matters.

## Stack
- Astro 6 (NOT Astro 4 — the content collections API changed)
- Svelte 5 for interactive islands (NOT React)
- TypeScript
- Cloudflare Pages hosting

The “NOT X” pattern is critical. Agents are trained on millions of React examples and far fewer Svelte ones. Without explicit exclusions, the agent will suggest what it’s seen most.

2. Key Paths

Point to the files the agent will need most. Don’t list every file — list the ones that matter for decision-making.

## Key Paths
- `src/content.config.ts` — content schema (Zod)
- `src/layouts/KBEntry.astro` — entry layout
- `src/components/` — Svelte islands + Astro components
- `tests/kb.spec.ts` — e2e tests

3. Build & Test Commands

Give the agent the exact commands to verify its work. Include the working directory if it’s not the repo root.

## Build & Test
npm run build          # astro build + pagefind
npx playwright test    # e2e tests

4. Boundaries

The most important section. List what the agent must not modify, must not install, and must not change.

## Boundaries
- `research/corpus/` is READ-ONLY — never modify
- `notes/` is private — never reference in published content
- No new npm dependencies without discussion
- Don't change the build command in package.json

Every boundary rule traces to an incident. The agent installed React once — now “Svelte only” is a boundary. The agent modified reference material — now “READ-ONLY” is a boundary.

Anti-Patterns

Too Long

CLAUDE.md over 200 lines loses effectiveness. The agent processes it, but signal-to-noise drops. If your CLAUDE.md is getting long, move reference material into separate files and point to them.

Too Vague

“Write good code” tells the agent nothing. “Use Svelte 5 runes syntax ($state, $derived) not the legacy let-based reactivity” tells it exactly what to do.

Duplicating the Codebase

Don’t paste large code blocks into CLAUDE.md. Point to the file instead: “See src/content.config.ts for the content schema.” The agent can read the file — it doesn’t need a copy.

Static Rules

CLAUDE.md should evolve. After every session where the agent makes a mistake, add a rule. After every session where a rule prevented a mistake, keep it. Rules that never fire can be pruned.

The Compound Effect

A good CLAUDE.md doesn’t just fix one session. It fixes every future session. Every developer (or agent) who opens the project reads the same constraints. The cost of writing ten lines of rules is repaid across hundreds of sessions.

Testing Your CLAUDE.md

The simplest test: start a fresh agent session and ask it to make a change. If it violates a convention you care about, you’re missing a rule. If it follows conventions you never stated, your rules are working.