forge-projectbrain

Forge playbook — top-tier project-CLAUDE.md generation

Why this exists

A thin CLAUDE.md that is just a bullet list of file paths gives an agent no real leverage — it doesn't say what the project actually IS, which of the owner's global rulesets actually apply here, or which rules are non-negotiable. Deep research on Anthropic's own published best practices (code.claude.com/docs/best-practices, the Agent Skills docs, and independent 2026 field guides) converges on the same verdict: the worst CLAUDE.md files aren't empty, they're thorough ones — bloat dilutes the rules that matter until Claude quietly stops following them. The gold-standard shape (proven in the AutoWeb project, now formalized against that research) is a real PROJECT BRAIN: a tight five-part core (description, stack+versions, exact commands, architecture, conventions) + boundaries + pointers to detail docs, environment rules ADAPTED to the project's real tooling, universal anti-generic guardrails kept verbatim, a real Hard Rules section, and Governance. This skill is the repeatable METHOD for producing that shape for any Forge project; forge-bin/forge-projectbrain.cjs automates it.

The research this method is built on (cite before you deviate)

• The five-part core framework: (1) one-line project description, (2) tech stack with versions, (3) EXACT build/test/lint/run/deploy commands, (4) architecture as 3-5 key dirs with file:line-style pointers (never prose describing a "typical" layout), (5) conventions a linter can't enforce. Plus boundaries/off-limits dirs and pointers to detail docs.
• The prune test (official Anthropic guidance): for every line, ask "would removing this cause Claude to make mistakes? If not, cut it." A bloated CLAUDE.md causes Claude to ignore the instructions that actually matter — conciseness is not a nice-to-have, it is the mechanism that keeps the file effective.
• EXCLUDE, always: anything derivable from the code itself, standard conventions Claude already knows, file-by-file listings, pasted code blocks, frequently-changing information, and "obvious advice" filler ("write clean code", "follow best practices"). None of these belong in a generated CLAUDE.md.
• Imperative language, not hedging: "Never commit .env" beats "we generally prefer not to commit .env".
• Emphasis discipline: reserve IMPORTANT/YOU-MUST-style emphasis for the 1-2 truly critical rules (honesty, project-isolation) — emphasizing everything is the same as emphasizing nothing.
• A practical line budget (guidance, not a hard gate): keep the generated document in the neighborhood of ~150-200 lines for a typical project. The verbatim anti-generic guardrails block for website-flavored projects is a deliberate, documented exception to that budget (see step 3) — verbatim reuse there is a strength, not bloat, because it is the SAME trusted rule every project quotes.
• KEY INSIGHT — skills/docs are NOT reliably auto-invoked. Independent evals (Vercel) measured a 56% non-invocation rate for progressive-disclosure Skills matched only by a vague trigger description. A Hard Rule or an environment-ruleset line is not a Skill — it is always-loaded text — so every rule this generator emits must be a sharp, explicit, self-contained imperative ("Apply the frontend-design method before writing ANY frontend code"), never a bare pointer like "see the frontend-design skill for guardrails." When a real Skill genuinely needs to be referenced, name WHEN it triggers, not just that it exists.
• @-imports buy organization, not context budget. An @path reference inside CLAUDE.md loads automatically alongside it at session start (unlike a Skill) — so the generated "Detail docs" pointers are honest about that: they are real, but they are not a free lunch, and each imported doc should stay focused.