claude-md-writer

# 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 lo...