1. Your project

Nothing is uploaded. The file is assembled locally by JavaScript on this page.

Project name

Primary language

What it is, in one line

Test command

Run / dev command

The thing that trips up every new contributor

This single line is usually the highest-value thing in the whole file.

Rules to include

Let it run tests/linters without asking No narrating comments on obvious code Don't create summary .md files unprompted Never commit or push unless asked Don't refactor beyond what was asked Verify by running, not by asserting it works

2. Your file

Save this as CLAUDE.md in your repo root and commit it.

Fill in the form above and hit Generate.

Why most CLAUDE.md files do nothing

• Adjectives are invisible. "Write clean, maintainable code" is already in the model's priors. It costs you context and changes no output. "Use pytest, not unittest; tests live beside the code as test_*.py" changes output every time.
• Write only what the repo can't say for itself. If a competent stranger could work it out in two minutes of reading, it doesn't belong in the file. If they'd need to be told — a non-obvious build step, a service that must be running, a directory that looks dead but isn't — that's exactly what belongs.
• Permission is a behaviour lever. Explicitly allowing the boring things (tests, linters, type checks) is what buys you an agent that verifies its own work instead of stopping to ask you six times.
• Prohibitions need a target. "Be careful with git" does nothing. "Never git push unless I ask" is enforceable and gets followed.
• Shorter is stronger. Every line is re-read on every run. A tight 40-line file outperforms a 300-line one, because in the long file the rules that matter get diluted by the ones that don't.

Four complete CLAUDE.md examples

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.

1. Python API service (FastAPI + Postgres)

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

2. TypeScript front end (Next.js App Router)

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

3. Go CLI

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

4. Monorepo

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

What belongs in CLAUDE.md, and what doesn't

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.

Earns its place

• The exact test command, including anything that must be running first
• Which of two plausible conventions this repo actually uses (pytest vs unittest, Tailwind vs CSS modules)
• A directory that looks dead or looks generated but isn't
• A constraint with a non-obvious reason ("ui must compile against React 18 and 19")
• Deliberate duplication or ugliness you don't want "fixed"
• Explicit permission to run tests, linters and typecheckers unprompted
• Prohibitions with a concrete target ("never git push unless I ask")

Wasted context

• "Write clean, readable, maintainable code" — already the default
• "Follow best practices" / "be careful" / "think step by step"
• A file tree that ls would produce
• The tech stack when package.json already says it
• Restating what the README says
• Coding style a formatter already enforces
• Long prose explaining your architecture philosophy

Common questions

Where does CLAUDE.md go?

In 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.

How long should it be?

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.

Why is Claude ignoring my CLAUDE.md?

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.

Should I commit it or keep it local?

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.

What's the difference between CLAUDE.md and a system prompt?

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.

Does it work with other AI coding tools?

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.

Want the rest of the setup?

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.

• 4 CLAUDE.md templates (API, frontend, monorepo, data)
• The guard hook + its 13-case test suite
• 3 permission presets (autonomous / balanced / cautious)
• 8 slash commands and 5 subagent definitions
• 3 field guides on context, permissions and hooks

One payment, instant download.