Write Your First CLAUDE.md in Ten Minutes

You can write a good first CLAUDE.md in ten minutes: let the tool draft one, delete everything the agent could discover itself, add the three or four facts it keeps getting wrong, and test it on a real task. The result should fit on one screen. Short beats complete.

Step 1: Generate a draft

Claude Code has an /init command that analyses the project and writes a starting CLAUDE.md. Run it inside the session:

> /init

Review the file it creates. If you prefer to start from scratch, or use a tool without this command, create the file by hand in the project root.

Step 2: Cut it down

Generated drafts tend to include a long file tree and generic advice. Remove:

• Anything an agent learns in one command, such as a full directory listing.
• Generic advice ("write tests", "use meaningful names").
• Text copied from the README.
• Rules your linter or formatter already enforces.

Keep what is specific and non-obvious. Ask of each line: if I deleted this, would the agent make a mistake?

Step 3: Add the facts it gets wrong

Think of the last few corrections you would give a new colleague. Typical items:

• The real test command and how to run one file.
• The package manager or tool version to use.
• A rule that differs from the framework default.
• Files that are generated or off limits.
• The definition of done for this repo.

A complete first file

# Shop API

Express + TypeScript + Prisma on PostgreSQL. Package manager: pnpm (not npm).

## Commands
- pnpm dev               start the API on port 3000
- pnpm test              unit tests (no database needed)
- pnpm test:int          integration tests (needs docker compose up -d db)
- pnpm check             lint + typecheck + unit tests

## Rules
- Route handlers stay thin: parse input, call a service in src/services, return JSON.
- Validate all request bodies with the zod schemas in src/schemas.
- Never edit prisma/migrations by hand; create one with pnpm prisma migrate dev.
- Do not edit src/generated/.

## Definition of done
- pnpm check passes.
- New behaviour has a test.
- Summarise what changed and anything you were unsure about.

Notice the style: imperative, specific, and each line is checkable. "Route handlers stay thin" is a bit abstract, but the next clause makes it concrete.

Step 4: Test it

Start a new session so the file is loaded fresh, and give a small real task, such as adding a field to one endpoint. Watch for two things. Did the agent run pnpm check at the end without being asked? Did it follow the rules about schemas and migrations? If not, check whether the instruction is clear or buried. Rewrite and try again.

You can also ask the agent directly:

What instructions from CLAUDE.md apply to adding a new endpoint?

If it lists the right rules, the file is being loaded and understood.

Why short files win

A first draft often feels too thin, and the temptation is to add everything you know about the project. Resist it. The file is read on every session, and every sentence competes with the code the agent needs to see. A few precise lines about commands and gotchas beat pages of general description. If you later find that the agent needs deeper background for one area, put that in a separate document and mention its path in a single line, so the agent reads it only when relevant. The post on structuring instruction files for large repositories shows how.

Step 5: Commit and maintain

git add CLAUDE.md
git commit -m "Add CLAUDE.md with commands and conventions"

When you correct the agent for the same thing twice, add a line to the file. Claude Code also lets you add notes to its memory from within a session; check the current documentation for the exact command, and review anything it writes before you commit it.

Example of a rule earning its place

Imagine the agent keeps writing integration tests that call the real payment sandbox, which makes the suite slow and flaky. You correct it once, then twice. That is the signal to add a line: "Integration tests must use the fake gateway in test/support/fake-gateway.ts, never the real sandbox." The next session follows it without being told. Rules that come from real corrections are far more valuable than rules you invent in advance, because they target mistakes the model actually makes in your codebase. Keep a running list while you work, and spend two minutes at the end of the week turning the repeated items into lines in the file.

It also helps to write rules in positive, concrete terms. "Use the fake gateway" is easier to follow than "do not make slow tests". Where you must forbid something, say what to do instead, so the agent has a path forward rather than only a wall.

Quality checklist

1. Under about 100 lines.
2. Commands are copy-pasteable and tested.
3. No secrets or personal data.
4. Rules are specific and verifiable.
5. No duplication of the README.
6. Reviewed by a teammate.