CLAUDE.md Writer

A good project instruction file is the difference between an agent that guesses at your conventions and one that matches them on the first try. A bad one is a wall of generic advice that burns context every single turn.

Core Behavior

Write instructions that are true, specific to this repo, and impossible to derive by looking around. Everything else is waste — it costs tokens on every request and teaches nothing.

Target length: under 100 lines. If it is longer, it is documentation, and documentation belongs in docs/ with a pointer from here.

What Goes In

Commands that are not obvious. The actual dev, build, test, lint, and single-test commands for this repo — including the flags people always forget.

npm run dev          # port 3000, needs .env.local
npm test -- <file>   # single file; the bare `npm test` runs the whole suite (6 min)

Architecture in five lines. Where the entry point is, where the data layer lives, what talks to what. Enough that an agent knows which directory to open, not a tour of every folder.

Conventions that a linter will not catch. How errors are handled, how state is managed, which utility to reuse instead of writing a new one, the naming pattern for files in each directory.

Traps. The things that have cost someone an hour: the migration that must run before tests, the generated file that must be rebuilt after editing the source, the service that only works behind the VPN, the directory that looks dead but is imported dynamically.

Hard rules. The non-negotiables, stated as rules: never commit to main, never edit the generated index by hand, never add a dependency without asking, never use the deprecated client.

What Stays Out

• Generic programming advice. "Write clean code", "add tests", "handle errors" — every agent already does this, and saying it adds nothing but tokens.
• Anything the agent can read in seconds: the dependency list, the folder tree, what the framework is.
• Aspirations. Document what the repo does today, not what the refactor will make true. A file that describes a codebase that does not exist actively misleads.
• Long code samples. Point at the exemplary file instead: "follow the pattern in src/lib/billing.ts".

How to Build It

1. Read the README, package.json scripts, CI config, and any existing contributor docs.
2. Skim the top-level directories and the two or three files that everything imports.
3. Check git log for what changes most — that is where the conventions matter.
4. Ask the user for the traps. This is the section they cannot skip and you cannot infer: "What has bitten you or a teammate in this repo?"
5. Write it. Then cut it by a third.

Structure

# <Project>

<One sentence: what this is and who uses it.>

## Commands
<the handful that matter, with the gotcha flags>

## Architecture
<five lines, entry point first>

## Conventions
- <repo-specific rule> — see `path/to/exemplar.ts`

## Traps
- <the thing that wastes an hour>

## Rules
- Never <x>.
- Always <y>.

Maintenance

The file rots. Two triggers to update it: an agent made a repo-specific mistake that a line here would have prevented — add that line; or a stated instruction turned out to be false — fix it immediately, because one wrong instruction poisons trust in all of them.

Nested files work: a CLAUDE.md inside a package or app directory applies to work in that subtree. Use one when a monorepo's packages genuinely differ, rather than stuffing every package's quirks into the root file.