CLAUDE.md is the file Claude Code reads into context on every single run. Most of them are wish lists — "write clean code", "be careful" — and those change nothing. Answer six questions and get one built out of facts Claude cannot guess by reading your repo.
Nothing is uploaded. The file is assembled locally by JavaScript on this page.
This single line is usually the highest-value thing in the whole file.
Save this as CLAUDE.md in your repo root and commit it.
Fill in the form above and hit Generate.
pytest, not unittest; tests live beside the code as test_*.py" changes output every time.git push unless I ask" is enforceable and gets followed.Real, whole files — not fragments. Copy one, change the names, delete the lines that don't apply to you. Every line here earns its place by telling Claude something it could not have worked out from reading the repo.
# CLAUDE.md ## What this is Billing API for the customer portal. FastAPI + SQLAlchemy on Postgres 16. `app/` is the service; `worker/` is a separate Celery process that shares the same models. Both must be running for anything end-to-end to work. ## Commands - Test: `pytest -q` (needs Postgres up: `docker compose up -d db`) - Run: `uvicorn app.main:app --reload` - Lint/format: `ruff check . && ruff format .` - Migrations: `alembic upgrade head` — never edit a migration that is already committed ## Conventions - Tests live beside the code as `test_*.py`, using pytest. Not unittest. - Money is `Decimal` everywhere, never `float`. Amounts are stored in minor units (cents). - All external HTTP goes through `app/clients/`, never `requests` inline in a route. - New endpoints need a Pydantic response model — no bare dicts. ## The thing that trips everyone up `app/models/` is imported by both the API and the worker. Adding a non-nullable column without a default breaks the worker on deploy, because the worker rolls out before the API. Always ship the column nullable first. ## You can do these without asking Run tests, run ruff, run `alembic upgrade head` against the local dev database, read logs, add files under `tests/`. ## Don't - Never `git push` unless I ask. - Never run migrations against anything but the local dev database. - Don't add new dependencies without telling me which one and why.
# CLAUDE.md ## What this is Marketing site + logged-in dashboard. Next.js 15 App Router, TypeScript strict, Tailwind. Data comes from the billing API (separate repo) via `lib/api.ts`. ## Commands - Test: `npm test` (Vitest) - Run: `npm run dev` - Typecheck: `npm run typecheck` — run this before you say you're done - Lint: `npm run lint` ## Conventions - Server Components by default. Add `"use client"` only when you actually need state or an event handler, and put a one-line comment saying which. - Data fetching happens in Server Components or route handlers, never in a `useEffect`. - Styling is Tailwind utility classes inline. There is no CSS module in this repo and we are not adding one. - Components live in `components/`, one per file, named export matching the filename. ## The thing that trips everyone up `lib/api.ts` runs on both server and client. Anything you import into it must be edge-safe — no `fs`, no `crypto` from Node. This is why the auth helpers are duplicated in `lib/auth-server.ts`; that duplication is deliberate, don't "fix" it. ## You can do these without asking Run tests, typecheck, lint, format, read the dev server output. ## Don't - Never commit or push unless I ask. - Don't refactor a component you were only asked to change one line in. - Don't add a state management library. We use React state and URL params.
# CLAUDE.md
## What this is
`ferry` — a CLI that syncs S3 buckets across accounts. Single Go module, no
external service dependencies. `cmd/ferry` is the entrypoint, `internal/sync`
is where the actual logic lives.
## Commands
- Test: `go test ./...`
- Build: `go build ./cmd/ferry`
- Vet: `go vet ./...`
- Integration tests: `go test -tags=integration ./...` (needs AWS creds; skip by default)
## Conventions
- Errors are wrapped with `fmt.Errorf("...: %w", err)` and handled at the top of
`cmd/`. Library code never calls `log.Fatal` or prints.
- Table-driven tests. New behaviour means a new row in the existing table, not a
new test function.
- No third-party dependencies without asking. Standard library plus aws-sdk-go-v2
is the whole dependency list and I want to keep it that way.
## The thing that trips everyone up
`internal/sync/plan.go` is deliberately pure — it takes two file listings and
returns a plan, with no I/O at all. That is what makes it testable. If you find
yourself wanting to call S3 from inside it, the call belongs in `executor.go`.
## You can do these without asking
`go test ./...`, `go vet`, `go build`, `gofmt`.
## Don't
- Never run the integration tests — they touch real buckets.
- Never `git push` unless I ask.
- Don't rename exported symbols; this is consumed as a library by two other repos.
# CLAUDE.md ## What this is pnpm + Turborepo monorepo. - `apps/web` — Next.js customer app - `apps/admin` — internal React SPA (Vite) - `packages/ui` — shared components, consumed by both apps - `packages/config` — eslint/tsconfig bases ## Commands Run everything from the repo root; the per-package scripts assume it. - Test everything: `pnpm test` - Test one package: `pnpm --filter @acme/ui test` - Run the web app: `pnpm --filter web dev` - Typecheck all: `pnpm typecheck` ## Conventions - A change to `packages/ui` affects both apps. Typecheck both before you're done. - Cross-package imports use the workspace alias (`@acme/ui`), never a relative path that climbs out of the package. - New shared component means: add it to `packages/ui/src/`, export it from `packages/ui/src/index.ts`, or nothing can import it. ## The thing that trips everyone up `apps/admin` is still on React 18 and `apps/web` is on 19. `packages/ui` has to compile against both, so it cannot use `use()` or any 19-only API. The CI job that catches this only runs on PRs, so it will look fine locally. ## You can do these without asking Run tests, typecheck, lint, build any package. ## Don't - Never `git push` unless I ask. - Don't bump a dependency in one app only — versions are pinned across the workspace. - Don't add a new package without asking; each one has CI and release cost.
The single test: could a competent stranger work this out in two minutes of reading the repo? If yes, leave it out — it's costing you context on every run and telling Claude nothing.
ls would producepackage.json already says itIn your repository root, committed to git, so everyone on the team gets the same behaviour. Claude Code reads it automatically at the start of every session. You can also put a CLAUDE.md in a subdirectory — it gets picked up when Claude works on files there, which is useful in a monorepo where each package has its own conventions.
Shorter than you think. 30–60 lines is a good target for a single project. The file is re-read into context on every run, so every line competes with every other line for attention — a 300-line file dilutes the five rules that actually matter. If it's growing, the fix is usually to delete the things the repo already says about itself, not to reorganise.
Almost always because the instructions are adjectives rather than commands. "Write good tests" describes a preference the model already has, so it changes nothing observable. "Tests go beside the code as test_*.py, using pytest" is checkable and gets followed. The second most common cause is length — a rule buried at line 200 of a wish list competes with 199 other lines. The third is contradiction: if the file says "don't add dependencies" and the repo's existing code adds them freely, the observed code usually wins.
Commit it. Project conventions belong to the project. If you have personal preferences that shouldn't be imposed on your teammates, those go in your user-level settings instead, not in the repo file.
CLAUDE.md is project memory — durable facts about this repo that apply to every session in it. It isn't the place for task instructions ("refactor the auth module"), which belong in your actual message. A good rule: if it will still be true in six months, it goes in the file; if it's true only today, say it in the prompt.
The file format is plain Markdown with no special syntax, so the content transfers. Other tools look for their own filenames (AGENTS.md, .cursorrules) — several teams just symlink them to the same file so there's one source of truth.
This generator writes the one file. The Claude Code Ship Kit is the full configuration a working repo needs — including a PreToolUse guard hook that blocks rm -rf on system paths, force-pushes to shared branches, reads of .env, and npm publish, shipped with 13 test cases so you can prove it actually blocks them.