creating-claude-md

Creating a CLAUDE.md From Scratch

Generate a lean, high-signal CLAUDE.md for a repository by combining an autonomous repo scan with a focused 6-question user interview.

Core principle: Every line must earn its place. If removing a line would not cause Claude to make a specific mistake, it does not belong in the file.

When to Use vs. Not Use

Use when:

• •Repo has no CLAUDE.md and user wants one.
• •Repo has a CLAUDE.md that the user considers unsalvageable and wants rewritten from scratch.
• •User says "set this repo up for Claude Code", "bootstrap project memory", "write me a CLAUDE.md".

Do NOT use when:

• •User wants to audit, improve, or incrementally fix an existing CLAUDE.md. Route to claude-md-improver instead.
• •User wants to add a single rule / gotcha to an existing file. Edit directly.
• •Repo is a scratch directory with no meaningful content yet.

The Iron Rule

Target ≤ 80 lines. Hard cap 120. This is a forcing function. Bloat triggers the harness to uniformly down-weight all instructions in the file (not just the tail). If the draft exceeds 80 lines, split oversized sections into agent_docs/*.md before writing anything to disk.

4-Phase Workflow

Follow in order. Do not skip phases.

Phase 1: Scan the Repo (Autonomous)

Gather mechanical content the repo can tell you:

• •Manifests — read whichever exist: package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, build.gradle, Gemfile, composer.json, Makefile. Extract: language, framework, versions, scripts.
• •Structure — ls top-level + one level deep. Detect monorepo via workspaces in package.json, pnpm-workspace.yaml, lerna.json, turbo.json, nx.json, or packages/ / apps/ directories.
• •Enforced conventions — read .editorconfig, .eslintrc*, biome.json, .prettierrc*, ruff.toml, pyproject.toml ([tool.ruff] / [tool.black]), rustfmt.toml, .golangci.yml. Record these — the corresponding rules are BANNED from CLAUDE.md (linter does the job).
• •Existing docs — README.md, any agent_docs/, .claude/rules/, subdirectory CLAUDE.md files. Do not overwrite auxiliary files that already exist without asking.
• •Git — git log --oneline -20 to detect commit conventions (Conventional Commits, prefix patterns).
• •Boundary check — look for existing CLAUDE.md, AGENTS.md, CLAUDE.local.md. If CLAUDE.md exists with meaningful content (> 20 lines, not just a stub), STOP and ask user: [rewrite / run claude-md-improver / cancel]. Proceed only if they confirm rewrite.
• •Auto-memory — check ~/.claude/projects/<path-hash>/memory/ if it exists. Note what Claude has already auto-learned so you do not duplicate it.
• •External-doc MCPs — check which MCPs are configured in this session for external docs. Common names include confluence-dc, confluence, notion, atlassian. Record the exact MCP name (e.g., confluence-dc) so Phase 3 can reference it by the same name in the generated ## External Docs section. If none are configured but the user references external docs in Q6, record that as plain URLs without MCP instructions.

Phase 2: Interview the User

Ask all questions in a single numbered list. User answers all together. Do not ask one at a time.

Fixed 6 (always ask):

1. WHY — In one sentence, what does this project do and who uses it?
2. Gotchas — What has tripped up new contributors or Claude in this repo? Non-obvious traps, modules with weird behavior, required setup steps not in the README.
3. Out of scope — Any files, directories, or areas Claude should NEVER modify autonomously? (auto-generated files, migrations, infra, other teams' code)
4. Approval gates — Any actions that require your explicit approval before Claude runs them? (destructive git, DB schema changes, deploys, production-adjacent changes)
5. Testing philosophy — How do you verify changes work? Is there any check that must always pass before shipping?
6. External docs — Are there Confluence pages (or Notion / wiki / Google Docs) that document parts of this repo? For each, paste: (a) the URL, (b) a one-line description of what it covers, (c) policy — read (reference only, never modify) or update (keep in sync when related code changes). Leave blank if none.

Adaptive follow-ups (add up to 3, only when the scan surfaced ambiguity):

• •Monorepo detected → "I see N packages: X, Y, Z. Which ones does Claude frequently confuse or work across incorrectly?"
• •migrations/ directory found → "Any rules around creating or running migrations?"
• •Multiple lockfiles (package-lock.json + yarn.lock + pnpm-lock.yaml) → "Which package manager is authoritative?"
• •CI config present but no local check script → "Any CI checks that must pass locally before pushing?"
• •External infra configs present (docker-compose.yml, terraform/, k8s manifests) → "Which of these does Claude own versus another team?"

Ask at most 9 total questions (6 fixed + up to 3 adaptive). If the user's answers are vague, re-ask once; do not invent content.

Phase 3: Draft (In-Memory Only)

Compose the file against the Output Spec below. Before writing anything to disk:

1. Count lines.
2. If > 80: pick the section(s) that contributed most (typically Gotchas or Architecture detail) and extract them into agent_docs/*.md stubs. Replace with a 1-line pointer under ## References.
3. If still > 120 after aux-file splits: drop the least-load-bearing rules. The file must fit.
4. Run the Red Flag Self-Check (below). Fix every flag before writing.

Phase 4: Write

• •Write CLAUDE.md to repo root.
• •Write any auxiliary files to agent_docs/*.md.
• •Do NOT commit to git.
• •Report to the user:

- Files written, with line counts. - Brief summary of what lives where. - Reminder: "Add CLAUDE.local.md to .gitignore if you want personal overrides. Do not create it here — that is your personal concern."

Output Spec

Section Set

Include a section only if the scan or interview produced real content for it. Empty sections are worse than missing ones.

Formatting Rules

• •Max 3 heading levels (#, ##, ###).
• •Commands in fenced `bash blocks with inline # ... comments for flags. Never in prose.
• •Every rule in imperative form: "Use X", "Never Y; instead do Z".
• •Every negative rule paired with a positive alternative. "Never force-push" alone leaves Claude stuck; "Never force-push; rebase locally then push normally" gives it a path.
• •Max 2 IMPORTANT: or YOU MUST markers in the entire file. Reserved for security or data-integrity rules only. More than 2 makes emphasis invisible.
• •No pasted code blocks > 10 lines. Use path/to/file.ts:42 pointers instead.
• •No @path/to/doc.md import syntax. Use plain see path/to/doc.md references — plain references load only when Claude decides they are relevant; @ imports load immediately and burn context.

The ## External Docs Section (Confluence / Notion / Wiki)

Emit this section only if Q6 produced at least one page. One bullet per page. Each bullet has three parts: URL + one-line purpose + policy (read vs. update) + which MCP name to use.

Template (substitute the MCP name recorded in Phase 1; if no external-doc MCP is configured, drop the MCP clause and leave the URL as a plain reference):

## External Docs

- **<One-line purpose>** — <URL>
  - READ via `<mcp-name>` MCP when working on <specific code area, e.g., `app/api/**`>. Prefer reading this page over inferring behavior from code.
  - UPDATE via `<mcp-name>` MCP before pushing any change that <specific trigger, e.g., adds/removes/modifies endpoints, changes request/response shapes>.

- **<One-line purpose>** — <URL>
  - READ-ONLY. Never modify this page. If content here conflicts with code, flag the discrepancy to the user.

Rules for the section:

• •Pages with policy read → emit only the READ or READ-ONLY bullet.
• •Pages with policy update → emit both READ and UPDATE bullets. The UPDATE bullet MUST specify a concrete trigger (what kind of code change forces a doc update), sourced from the user's Q6 answer or the file globs most relevant to the page. Never emit a generic "update when things change".
• •Never paste Confluence page content into CLAUDE.md. URL + purpose + policy only.
• •If the user lists > 5 external doc pages, emit only the top 3 most-referenced and move the rest into agent_docs/external-docs.md with the same format.

Automatic rule when Q6 surfaces any `update` pages: append one line to ## Approval Required:

- Before `git push`, if any change touches code referenced by an `update`-policy page in `## External Docs`, update that page (or confirm with me first).

This is the forcing function that makes per-page update rules actually fire. Do not add it if all Q6 pages are read-only.

Banned Content

Delete from the draft on sight:

• •Personality instructions: "be a senior engineer", "think step by step", "approach this carefully".
• •Style rules already enforced by linter configs detected in Phase 1 (indentation, quote style, semicolons, import order, etc.).
• •Standard language idioms Claude already knows (use async/await, use pathlib, prefer const over var).
• •Pasted architecture essays. Summarize in two sentences, link the doc.
• •Secrets, tokens, connection strings, API keys.
• •Descriptive prose ("we generally prefer…", "try to…"). Rewrite as imperative or delete.
• •Contributor names, roadmap items, sprint-specific notes.
• •Version numbers inside descriptive prose (stale within weeks). Put versions in the Stack section only, sourced from manifests.
• •Pasted content from Confluence / Notion / wiki pages. CLAUDE.md is not a cache. URL + purpose + policy only.

Auxiliary Files (Moderate Progressive Disclosure)

Trigger aux-file splits only when the root file exceeds 80 lines after drafting. Do not scaffold them speculatively.

Typical splits:

• •agent_docs/architecture.md — layered architectures with > 3 components worth describing.
• •agent_docs/testing.md — when the test workflow has > 3 commands or non-trivial patterns.
• •agent_docs/<domain>.md — when gotchas cluster around one domain (e.g., agent_docs/auth.md).

Each aux file follows the same rules as root: imperative, no pasted code, pointers not copies, no linter-replaceable style rules.

Root references them via a ## References section:

## References

- `agent_docs/architecture.md` — service boundaries and data flow
- `agent_docs/testing.md` — how to run and write tests

For monorepos with packages that have materially different conventions, offer (do not force) to stub packages/<name>/CLAUDE.md files. These are loaded on demand only when Claude works in that directory.

Red Flag Self-Check (Before Writing)

Run every item before writing to disk. Fix any flag or start that section over.

• •[ ] File > 120 lines → split to aux file.
• •[ ] Empty section with a stub header → delete the section.
• •[ ] Any rule duplicated in a linter/formatter config detected in Phase 1 → delete.
• •[ ] Any rule phrased as "we generally…" / "try to…" / "it is preferred that…" → rewrite imperative or delete.
• •[ ] Any negative rule without a positive alternative → fix or delete.
• •[ ] More than 2 IMPORTANT: / YOU MUST markers → reduce to the 2 most critical.
• •[ ] Pasted code block > 10 lines that is not a verbatim command → replace with path:line pointer.
• •[ ] Personality instruction present → delete.
• •[ ] @ import syntax used → replace with plain reference.
• •[ ] Rule covers a hypothetical rather than a real incident the user described → delete.

Boundary: Handling an Existing CLAUDE.md

If Phase 1 finds an existing CLAUDE.md with meaningful content (> 20 lines, not an auto-generated stub):

Existing CLAUDE.md found (N lines). This skill rewrites from scratch; it does not preserve content. Choose:

- rewrite — overwrite with a fresh one

- improver — exit and run the claude-md-improver skill to audit and improve what's there

- cancel — do nothing

Proceed only on rewrite. On improver, exit and tell the user to invoke that skill. On cancel, exit.

Stub / near-empty existing files (< 20 lines, clearly auto-generated) can be overwritten without prompting.

Anti-Pattern Rationalizations

Capture these so the model cannot rationalize around the rules under pressure:

Example Output (Reference, Not Template)

Here is what a well-shaped CLAUDE.md looks like for a mid-size Next.js app. Do not copy verbatim — generate based on actual scan + interview results.

# ShopFront

Next.js 14 e-commerce site with Stripe payments, served to retail customers.

## Stack

- Next.js 14 (App Router), TypeScript 5.4, Node 20
- Prisma ORM + Postgres 15
- Tailwind CSS 3, shadcn/ui components

## Project Structure

- `app/` — Next.js App Router pages and API routes
- `components/` — reusable UI (shadcn-based)
- `lib/` — shared utilities and DB client
- `prisma/` — schema and migrations

## Commands

pnpm install # Install deps (pnpm only — do not use npm/yarn) pnpm dev # Dev server on :3000 pnpm test # Vitest unit tests pnpm test:e2e # Playwright end-to-end pnpm lint # Biome check pnpm db:migrate # Prisma migrate dev

## Gotchas

- Stripe webhooks in `app/api/webhooks/stripe/route.ts:14` require `stripe-signature` validation — never short-circuit it.
- Product images live in Cloudinary, not the repo. Never commit binary assets under `public/`.
- `lib/auth.ts:42` has custom retry logic; do not "simplify" it — it handles a known race with our identity provider.

## Out of Scope

- `prisma/migrations/` — never edit existing migration files; create a new one via `pnpm db:migrate`.
- `infra/` — owned by platform team; ask before changing.

## Approval Required

- Any schema change (Prisma migration).
- `git push --force` on any branch (rebase locally then push normally instead).
- Touching `app/api/webhooks/stripe/route.ts` (payment-critical).
- Before `git push`, if any change touches code referenced by an `update`-policy page in `## External Docs`, update that page (or confirm with me first).

## Testing

Run `pnpm test && pnpm test:e2e` before any PR. IMPORTANT: Stripe webhook changes require running the signature verification test suite (`pnpm test -- webhooks`).

## External Docs

- **REST API reference** — https://confluence.example.com/display/ENG/ShopFront+API
  - READ via `confluence-dc` MCP when working on any `app/api/**` route. Prefer reading this page over inferring behavior from code.
  - UPDATE via `confluence-dc` MCP before pushing any change that adds/removes/modifies endpoints, request/response shapes, or auth requirements.

- **Payments runbook** — https://confluence.example.com/display/ENG/ShopFront+Payments+Runbook
  - READ-ONLY. Never modify this page. If content here conflicts with code, flag the discrepancy to the user.

Notice what is NOT there: no indentation rules (Biome enforces), no "be careful" prose, no contributor list, no roadmap, no @imports, no pasted code, no personality instructions, no pasted Confluence content. Every line prevents a specific mistake.

After Writing

Report to the user with:

• •Files written (paths + line counts).
• •One-line summary of what each aux file covers (if any).
• •Reminder: "For personal overrides (editor preferences, verbose logging, etc.), create CLAUDE.local.md and add it to .gitignore. That is a personal file and this skill does not generate it."
• •Suggestion: "Review the file — every line should prevent a real mistake. Delete anything that does not."