Claude Code prompt: write a CLAUDE.md for an existing repo

A CLAUDE.md is only useful if it's true. Generic ones list commands that don't run and conventions nobody follows. This work order makes Claude read the repo first, actually run the commands it plans to list, and back every convention with a real file. You get a short draft to review, plus a list of the things it wasn't sure about.

The work order

Copy it, fill in the [brackets], and paste it into Claude Code. It also works in Cursor's Agent mode.

Write CLAUDE.md for an existing repo Claude Code · repo setup

Write a CLAUDE.md for this repo, based on what's actually here. Read first, write second.

Look at: the README, the build and package files ([package.json / pyproject.toml / go.mod / Makefile]), CI config, lint and format config, the test setup, and a few recently changed files to see how code is written today. If a CLAUDE.md or AGENTS.md already exists, read it and improve it instead of starting over.

The file should cover:
1. What this repo is, in two or three sentences.
2. Commands: install, dev server, run one test, run all tests, lint, typecheck, build. Run each one you safely can (skip anything that deploys, migrates a database, or calls paid services). Only list the ones that worked. Mark the others "not verified".
3. Layout: the folders that matter and what belongs in each.
4. Conventions a linter doesn't already enforce, each backed by a real example path.
5. What to leave alone or ask about first: generated code, migrations, secrets, vendored code.
6. Gotchas a new person would trip on: services that must be running, required env vars, slow or flaky tests.

Rules:
- Under [150] lines. Short lines, written as instructions to an agent, not a tour of the codebase.
- Don't invent conventions. If you saw something only once, leave it out.
- No secrets or values copied from .env files.

Show me the draft before saving it, along with a list of what you weren't sure about.

Running /init gives you a quick first draft. This prompt is for when you want every command tested and every rule tied to a real file. You can also run it right after /init to fix up what /init wrote.

Variations

Variation 1: Trim a CLAUDE.md that got too long Maintenance

Our CLAUDE.md has grown to [N] lines. Cut it to under [150] without losing anything an agent needs.

Remove rules the linter or formatter already enforces, things that are obvious from the code, and notes about code that no longer exists (check before you cut). Don't delete long step-by-step procedures; list them at the end as candidates to move into skills. Show me the before and after line counts and the diff.

Variation 2: Turn a repeated mistake into one line After a correction

You've [mistake, e.g. "put new API routes in the wrong folder"] twice now. Add one line to CLAUDE.md that would have prevented it.

Put it in the right section, write it as a direct instruction, and check it doesn't contradict anything already in the file. Show me the line before you add it.

Variation 3: A CLAUDE.md for one odd folder Subfolder

[folder] works differently from the rest of the repo ([why: legacy code, a generated client, a different language]). Write a short CLAUDE.md for that folder only, covering the rules that differ from the root file. Don't repeat anything the root CLAUDE.md already says. Keep it under 40 lines.

Claude Code picks up CLAUDE.md files in subfolders when it works on files there, so folder-specific rules don't have to clutter the root file.

When to use it

You're bringing Claude Code into a repo that's been around for a while and has no CLAUDE.md.
Your current CLAUDE.md was written months ago and you're not sure it's still accurate.
New teammates (human or agent) keep hitting the same setup problems.
If you want a starting template to fill in by hand instead, the hub guide has one.

What good output looks like

Every command listed was run, or is clearly marked "not verified".
Conventions point at real files you can open and check.
It's short. If it's over your line limit, it ignored the brief.
No generic advice like "write clean code" or "follow best practices".
A separate list of open questions instead of guesses written into the file.

Common mistakes

Accepting a CLAUDE.md that restates the README. The agent can already read the README.
Letting it run setup or migration commands against a real database to "verify" them.
Listing every style rule. If the linter catches it, it doesn't need a line.
Never updating it. Use the second variation every time you correct the same mistake twice.
Putting personal preferences in the project file. Those belong in your user-level ~/.claude/CLAUDE.md.

Need a different prompt? Describe your coding goal and get ranked prompts with quality, match & confidence scores.

Rank prompts for my goal →

More Claude Code work orders

Related prompts in the library

FAQ

Is /init enough, or do I need this prompt?

/init is a fine start and takes seconds. Its draft is based on a quick scan, though, so commands and conventions can be off. This prompt adds two checks: it runs the commands before listing them and ties each convention to a real file. Many people run /init first and then this prompt to correct it.

How long should a CLAUDE.md be?

Short enough that every line earns its place. Anthropic's guidance is to keep each CLAUDE.md under about 200 lines. We default to 150 in the prompt so there's room to add lines later.

Should I commit CLAUDE.md to git?

Yes, the project-level file is meant to be shared so everyone's sessions follow the same rules. Keep personal preferences in your user-level file instead.

CLAUDE.md or AGENTS.md?

If your team also uses Cursor or other agents, put shared rules in AGENTS.md and keep CLAUDE.md short with an @AGENTS.md import. The hub guide explains the setup and has templates for both.