Claude Code CLAUDE.md Generator: Set It Up Once, Not Every Session

You are setting up the project memory file (CLAUDE.md) for this repository so that every future Claude Code session starts already knowing how to work here. CLAUDE.md is loaded into context at the start of every session, so it is a behavioral contract, not documentation — every line must change how the agent acts.

Project: {{PROJECT_NAME}}
Primary language / stack: {{STACK}}
Package manager / runtime: {{PACKAGE_MANAGER}}
Things you already know Claude tends to get wrong here (optional): {{KNOWN_PITFALLS}}

Work in these phases. Do NOT write the file until Phase 3.

PHASE 1 — DISCOVER (read-only, no edits)
1. Detect the real build/test/lint/format/typecheck commands. Read package.json scripts, Makefile, justfile, pyproject.toml, Cargo.toml, go.mod, composer.json, or CI config — whichever exist. Record the EXACT command string (e.g. `pnpm vitest run`, not `npm test`). If multiple are plausible, note which one CI actually runs.
2. Map the directory layout: where source, tests, config, and entry points live. Note any non-obvious folders (generated code, vendored deps).
3. Detect conventions that are decisions, not defaults: indentation, import style, error-handling pattern, naming, how new modules/endpoints/components are added.
4. Detect an existing AGENTS.md, .cursorrules, .windsurfrules, or CLAUDE.md. If a CLAUDE.md already exists, you will IMPROVE it, not overwrite it.

PHASE 2 — TRIAGE (decide what belongs where)
For each candidate instruction, classify it:
- BELONGS IN CLAUDE.md: a fact true in every session — build commands, layout, "always do X" rules, hard prohibitions.
- BELONGS IN A path-scoped rule (.claude/rules/<topic>.md with a `paths:` frontmatter glob): only matters for one file type or subtree (e.g. API-handler rules, test rules).
- BELONGS IN A SKILL (.claude/skills/): a multi-step procedure (deploy, release, migration), not a fact.
State the triage table before writing anything. Reject anything that could be copy-pasted into any random repo unchanged — generic advice wastes context and lowers adherence.

PHASE 3 — WRITE
Write (or, if one exists, propose a diff to) `./CLAUDE.md` with this structure and these rules:
- Target UNDER 200 lines. Shorter = better adherence. If it grows past that, push detail into rules/ or skills/ and reference them.
- Use markdown headers + bullets, not paragraphs.
- Every instruction must be concrete and verifiable: "Run `{{PACKAGE_MANAGER}} test` before committing" not "test your changes"; "API handlers live in src/api/handlers/" not "keep files organized".
- Sections to include (drop any that don't apply, don't pad):
  ## Commands — the exact build / test / lint / typecheck / dev / format commands. This is the single most valuable section.
  ## Project layout — where things live, one line each.
  ## Conventions — only real team decisions (style, patterns, naming).
  ## Do NOT — explicit prohibitions (e.g. never edit generated files, never commit to main, never bump deps without asking). Be specific about paths.
  ## Workflow — required steps Claude must follow (e.g. run typecheck before declaring done).
- If an AGENTS.md exists, do not duplicate it: start CLAUDE.md with `@AGENTS.md` to import it, then add only Claude-specific lines below.
- Do not invent commands, paths, or conventions. If you cannot verify a command actually works, mark it `# unverified — confirm` rather than guessing.
- Use a block-level HTML comment `<!-- ... -->` for any note meant for human maintainers (it is stripped from Claude's context).

AFTER WRITING
- List which items you deliberately did NOT put in CLAUDE.md and where they should go instead (rules/ or skills/), so the human can follow up.
- Note that they can run `/memory` to confirm the file is being loaded, and `/init` for an interactive re-pass later.
- Remind them: CLAUDE.md is guidance the model tries to follow, not hard enforcement. Anything that MUST happen at a fixed moment (e.g. lint on every save) should be a hook instead.