Write Claude Md

---
name: write-claude-md
description: Write or tighten a CLAUDE.md for the current repo from what the code actually does. Use when asked to "write a CLAUDE.md", "set up Claude for this repo", "improve our CLAUDE.md", or when Claude keeps getting the same project conventions wrong.
---

# Write a CLAUDE.md

A good CLAUDE.md is short and holds only what Claude can't work out quickly by reading the code: how to build and test, the rules the team actually enforces, and the traps. Every line costs context on every request, so a 60-line file that is all true beats a 300-line file that restates the README.

## 1. Check what exists

- Read `CLAUDE.md`, `.claude/CLAUDE.md` and any nested `CLAUDE.md` files if present. You are improving them, not starting over.
- Read `README.md`, `CONTRIBUTING.md`, and any `AGENTS.md`, `.cursorrules` or `.github/copilot-instructions.md`. Reuse what is still true.

## 2. Learn the project from the code, not from guesses

Find each of these and note the exact command or path. Skip any you can't confirm.

1. **Stack and layout.** Languages, frameworks, package manager (look at lockfiles), monorepo tool, the top-level folders that matter.
2. **Commands.** Install, dev server, build, test (all and a single file), lint, format, typecheck, migrations. Take them from `package.json` scripts, `Makefile`, `justfile`, `pyproject.toml`, `Cargo.toml`, CI workflow files. Prefer what CI runs.
3. **Conventions that are enforced.** Linter and formatter configs, commit message rules (commitlint, PR templates), branch naming, required checks in CI.
4. **Conventions that are only habits.** Read 3 to 5 recent, typical files in the main source folder and the tests next to them. Note naming, error handling, how modules are structured, test style and fixtures. Only keep a habit if you saw it at least three times.
5. **Traps.** Generated files that must not be edited by hand, env vars needed to run anything, slow or flaky test suites, services that must be running, folders that look dead but aren't. Search for `DO NOT EDIT`, `generated`, `.env.example`, and TODO/FIXME comments that warn about something.

Run the test and lint commands once if they are cheap and safe, so you know they work as written. Never run deploy, release or migration commands against shared environments.

## 3. Write it

Use this shape and drop any section that would be empty:

```markdown
# <Project name>

<One or two sentences: what this is and who uses it.>

## Commands
- Install: `...`
- Dev: `...`
- Test all: `...`  Single file: `...`
- Lint / format / typecheck: `...`

## Layout
- `src/api/` HTTP handlers; business logic lives in `src/core/`.
- ...

## Rules
- <Rule stated as an instruction, with the reason when it isn't obvious.>
- ...

## Watch out
- `src/gen/` is generated by `make gen`; edit the `.proto` files instead.
- ...
```

Writing rules:

- Write instructions ("Use `pnpm`, not `npm`"), not descriptions ("The project uses pnpm").
- One fact per line. No marketing, no history, no praise of the codebase.
- Don't repeat what a linter already enforces, and don't paste config files.
- Don't invent rules. If you think something should be a rule but the code doesn't follow it yet, put it under **Suggestions** in your reply, not in the file.
- Keep it under about 80 lines. If a part of the repo has many rules of its own, put them in a nested `CLAUDE.md` in that folder instead.

## 4. Hand it over

Show the full file (or the diff, if one existed) and then, in at most five lines:

- Commands you ran and whether they passed.
- Anything you could not confirm and left out.
- Suggestions for rules the team might want to adopt.

Write the file only after showing it, unless the user already asked you to just write it.