Claude Md Bootstrap

CLAUDE.md Bootstrap

A reusable workflow for generating a project root CLAUDE.md by reading the project's existing documentation, applying 2026 community best practices, and embedding Karpathy's behavior guidelines.

Why this skill exists

Most projects already have rich documentation — PRD, architecture decisions, design system specs, package.json. The problem isn't lack of content, it's lack of an index that tells Claude Code:

1. What this project is and why it exists (WHAT/WHY)
2. How to find the detailed docs (paths via @import)
3. What behaviors to follow (do/don't, Karpathy principles)
4. What commands to run (from real package.json, not hallucinated)

A good CLAUDE.md is a routing map + behavioral contract, not a content dump. Bad CLAUDE.md files copy entire PRDs into the root, blow past the 200-line ceiling, and cause Claude to ignore real instructions (HumanLayer empirical finding: instruction adherence drops sharply past 200 lines).

When NOT to use this skill

• Brand new empty project, no docs yet → write specs/PRD first
• Project that already has a well-curated CLAUDE.md under 200 lines → just edit the specific section, don't regenerate
• Backend-only project with no design system → some sections (visual rules) don't apply; skip them rather than fabricate

Prerequisites

Verify before starting. If anything is missing, stop and ask.

Optional but valuable:

• .specify/memory/constitution.md (Spec-Kit projects)
• DESIGN.md (projects with explicit visual system)
• design-reference/ (projects with visual prototype samples)
• Existing CLAUDE.md (for merge-not-overwrite mode)

The 4-step workflow

Step 1 · Source inventory       (which files exist, what's in them)
Step 2 · Section mapping        (which file → which CLAUDE.md section)
Step 3 · Generate from sources  (extract, never fabricate)
Step 4 · Verify and finalize    (line count, link integrity, traceability)

Step 1 · Source inventory

Goal: build a list of what documentation actually exists. Don't assume; check.

Read each of these if present:

After reading, report to the user what you found with a brief summary per file. Don't proceed to Step 2 until they confirm coverage is complete.

Step 2 · Section mapping

Goal: decide which section of CLAUDE.md gets generated from which source files.

The standard 9-section template lives in references/template.md. Read it.

Build a mapping table for this specific project:

Show this mapping to the user. Highlight any sections where the source is unclear or missing — surface as Open Questions, don't fabricate.

Step 3 · Generate from sources

Goal: produce the actual CLAUDE.md content, extracting (never fabricating) from the mapped sources.

Inclusion rules:

• package.json scripts → copy verbatim (if exists)
• Tech stack → infer from dependencies keys + real versions
• Karpathy section → use references/karpathy-guidelines.md verbatim (do NOT translate the English principles; the original wording is precise)
• Anti-patterns → bullet list, each item must trace to a source paragraph
• File navigation → only include files that exist; verify each path
• §3 Workflow → extract from whatever workflow signals the project actually has: constitution / discipline / agent-rules / workflow.md / tasks.md label conventions / etc. Section names vary by project. NEVER copy a hardcoded template, NEVER hardcode specific section names. See references/template.md Section 3.

Phase 1 / Phase 2 handling for §4/§5 (greenfield projects)

For projects that have specs but no code yet (no package.json):

• §4 Tech Stack → write placeholder: "技术栈意图见 @specs/research/.md。 M1 启动 npm init 后，由 /init 命令从 package.json 自动同步真实依赖版本。"
• §5 Commands → write placeholder: "待 M1 启动 npm init 后，跑 /init 自动从 package.json scripts 抽取。"

Do NOT fabricate dependency names or commands. If the user wants details sooner, ask them to run npm init first.

Exclusion rules:

• Do NOT copy multi-paragraph content from PRD / constitution / DESIGN.md
• Do NOT translate Karpathy's English principles to Chinese
• Do NOT add framework opinions not stated in source files (if PRD doesn't say "use Redux", don't write "use Redux")
• Do NOT exceed 200 lines total
• Do NOT write §3 Workflow as a past-tense chronology of how the project got to its current state. CLAUDE.md is read by FUTURE Claude sessions during DEVELOPMENT. They don't care about "we did research → debate → brainstorming → PRD → specify → clarify → plan → tasks → constitution". They care about "what do I do RIGHT NOW when starting a task?" §3 must be action-oriented — see references/template.md Section 3 for the right and wrong examples.

Formatting:

• Each @path reference must use the literal @ prefix that Claude Code recognizes (e.g., @specs/prd.md, not [link](specs/prd.md))
• "YOU MUST" and "IMPORTANT" markers: use at most twice in the whole file. Reserve them for genuinely critical rules (typically: "read constitution before any task" and "no hardcoded visual values")
• Use Chinese for project-specific content if the source docs are Chinese; use English for Karpathy section and generic framework names

Step 4 · Verify and finalize

Goal: catch fabrication and ensure the output is usable.

Run these checks:

□ Line count < 200 (`wc -l CLAUDE.md`)
□ Each @import path resolves (file exists at given path)
□ Each command in commands section exists in package.json scripts
□ Each dependency mentioned exists in package.json with matching version
□ Each anti-pattern traces to a specific source paragraph
□ YOU MUST / IMPORTANT used ≤ 2 times total
□ Karpathy section is verbatim English (no translation drift)
□ File navigation table only lists files that actually exist

Final report to user:

- 总行数: N (上限 200)
- token 估算: ~K
- 来源映射表（每个章节抽自哪个文件）
- @import 路径完整性: M 个路径，全部解析成功 ✓
- 命令清单: P 条，全部在 package.json scripts 中验证存在
- 缺失/不确定项: [列出 Open Questions]

If there is an existing CLAUDE.md:

• Don't overwrite. Show diff. Let user decide what to merge.
• Preserve any sections the user wrote manually (look for sections not in the standard 9-section template — those are user-authored).

What success looks like

After running this skill:

1. CLAUDE.md at project root, < 200 lines
2. Uses @path to reference detailed docs, doesn't duplicate content
3. Tech stack and commands match package.json exactly
4. Karpathy 4 principles embedded verbatim in English
5. Anti-patterns each trace to a source paragraph (no fabrication)
6. Every future Claude Code session has a routing map to the right doc

Reference files

• references/template.md — the 9-section template structure with examples
• references/karpathy-guidelines.md — Karpathy's 4 principles, verbatim English

Read these when you need the exact section ordering or the exact Karpathy text.

Ready-to-copy trigger prompt

The user can paste this verbatim to invoke the full workflow:

请帮我在当前项目根目录创建 CLAUDE.md。如果已有，先读现有内容，最后输出 diff
让我确认再写入，不要直接覆盖。

## 第一步 · 读取项目已有文档（信息源）

读取并理解：
1. specs/prd.md                          → §1 WHAT、§2 WHY
2. 架构 / 选型决策文档（任意命名，通常在 specs/research/ 或 docs/） → §4 技术栈
3. .specify/memory/constitution.md       → §3 工作流抽取源 + §8 Anti-Patterns
4. DESIGN.md（或 specs/design-reference/.../DESIGN.md）→ §7 视觉规范
5. package.json（若存在）                 → §4 真实依赖版本 + §5 真实命令
6. specs/ 下任选 2-3 个 feature 目录       → 了解 task 标签体系

读完报告：每个文件抽到了什么，哪些不存在。

## 第二步 · 按 10 章节生成

1. WHAT（从 prd.md 抽一段）
2. WHY（从 prd.md 业务目标抽一段）
3. 工作流 HOW —— 必须 action-oriented，绝对不要列过去步骤的历史
   从项目实际工作流信号抽取（宪法 / 纪律段 / tasks 标签 / workflow 文档等，
   章节名因项目而异，不要假定特定名字），组织成 4-5 个动作块：
   ① 如何启动一个 feature（一条命令）
   ② 每个 task 启动必须读哪些 @path
   ③ 测试纪律（用哪个 skill）
   ④ feature 完成动作
   ⑤ 节奏铁律
   每块只用 1-2 行。目标 20-30 行。
   禁止出现 "(已完成)" / "(已锁定)" / "(已立)" 等历史标记
4. 技术栈表（package.json 存在就抽真实版本，不存在就写 Phase 1 占位
   "见 @<架构决策文档真实路径>，M1 后 /init 自动同步"）
5. 命令清单（同上，不存在就 "待 M1 启动后 /init 补全"）
6. 项目宪法引用 → @.specify/memory/constitution.md
7. 视觉规范引用 → @<DESIGN.md 真实路径>
8. Anti-Patterns（从 constitution 禁止条款抽 6-8 条，每条加来源引用）
9. Behavioral Guidelines（Karpathy 4 原则，英文 verbatim，加中文导语一句）
10. 关键文件导航表（只列真实存在的文件）

## 第三步 · 硬约束

- 总长度 < 200 行
- "YOU MUST" / "IMPORTANT" 全文最多 2 次
- 不要复制宪法 / PRD / 架构基线 / DESIGN.md 的内容——用 @path 引用
- 命令、依赖、技术栈必须从真实文件抽，不知道用 Phase 1 占位，禁止编造
- §3 必须从源文件抽取，不要套模板
- §9 Karpathy 不要翻译成中文

## 第四步 · 完成报告

- 总行数 / token 估算
- 来源映射表（每章节抽自哪个文件的哪一节）
- 缺失/不确定清单（让我补充）

如已有 CLAUDE.md：保留用户手写章节 verbatim，只 merge 标准章节，输出 diff 等确认。

A note on user communication

Users invoking this skill usually have rich docs already and feel the friction of "Claude doesn't know where to look". Your first message should reassure:

"We won't duplicate your PRD into CLAUDE.md. We'll build a 150-200 line routing map that points Claude to the right files. Total effort: ~15-20 minutes including verification."

Then proceed through the 4 steps interactively, pausing between Step 1 (inventory confirmation) and Step 2 (mapping confirmation) so the user can catch missing sources early.