claude-md-starter

Claude.md Starter — 项目上下文生成器

扫描代码仓库，推断技术栈和约定，提出至多 3 个有针对性的问题，并生成填充完整的 CLAUDE.md，让 Claude 从第一个会话开始就掌握完整的项目上下文。

触发条件

明确触发：

• “create a CLAUDE.md”
• “my CLAUDE.md is blank”
• “generate project context”
• “initialize CLAUDE.md”
• “set up Claude context for this repo”
• “fill in my CLAUDE.md”
• “run the claude-md-starter skill”

隐式触发：

• 用户粘贴了几乎为空的 CLAUDE.md，并要求 Claude 填充内容
• 用户在每次会话开始时都要反复解释相同的项目上下文

触发后立即运行——扫描前不要先提问。

工作流（6 个节点）

节点	职责
1 — 检测	检查 CLAUDE.md 是否存在并测量内容长度
2 — 扫描	读取项目根目录中的信号文件（见 references/scan-signals.md）
3 — 推断	起草所有可从扫描信号中推导出的章节
4 — 提问	针对无法推断的内容提出至多 3 个问题
5 — 生成	使用 references/claude-md-template.md 中的模板编写完整的 CLAUDE.md
6 — 验证	确认必需章节均已包含且不是占位内容

节点 1 — 检测

检查项目根目录中是否存在 CLAUDE.md。

如果未找到： 直接进入节点 2。

如果找到且内容 ≤ 200 个字符： 视为为空——进入节点 2。

如果找到且内容 > 200 个字符： 写入前先执行差异对比与合并流程：

1. 读取现有文件

2. 完成节点 2–4，生成新版本

3. 按章节进行比较——对 8 个必需章节中的每一个，归类为：

   • 新增 — 存在于生成版本中，在现有版本中不存在或为空
   • 增强 — 两个版本均有内容；生成版本增加了更多内容
   • 相同 — 两个版本的内容等效
   • 冲突 — 两个版本均有非空内容，但内容不同

4. 展示差异摘要表：

Section              | Existing | Generated | Action
---------------------|----------|-----------|-------
Project Overview     | present  | enhanced  | +additions available
Tech Stack           | absent   | new       | will add
Commands             | present  | enhanced  | +2 commands found
Architecture         | absent   | new       | will add
Code Conventions     | present  | same      | no change
Testing              | absent   | new       | will add
What NOT To Do       | absent   | new       | will add
Environment Setup    | absent   | new       | will add

5. 提供三个选项：

   • A（推荐） — 保留现有内容 + 仅添加新增和增强的章节（安全、仅增补）
   • B — 用生成版本完全替换
   • C — 写入前逐一审查每个冲突章节

6. 写入所选的合并结果。

节点 2 — 扫描

使用 references/scan-signals.md 中的目录读取信号文件。对于找到的每个文件，提取其揭示的字段。找不到的文件静默跳过。

尽可能并行读取：

1. package.json — 框架、脚本、包管理器、依赖项
2. pyproject.toml / requirements.txt / setup.py — Python 技术栈
3. Cargo.toml / go.mod / pom.xml / build.gradle — 编程语言
4. Makefile / justfile — 命名命令
5. .github/workflows/*.yml — CI/CD 步骤、部署目标
6. Dockerfile / docker-compose.yml — 运行时环境、服务
7. .eslintrc.* / .prettierrc.* / eslint.config.* — JS/TS 代码风格
8. ruff.toml / .flake8 / mypy.ini — Python lint/类型配置
9. jest.config.* / vitest.config.* / pytest.ini / conftest.py — 测试框架
10. tsconfig.json — TypeScript 设置
11. .env.example / .env.sample — 必需的环境变量
12. README.md（仅前 40 行）— 项目描述
13. 顶层目录列表 — 架构模式
14. .gitignore — 构建产物和生成文件

节点 3 — 推断

利用扫描到的数据，在提问前尽可能填写各个部分：

• 项目概览 → 来自 README.md 第一段；若没有，则使用 package.json 的 description 字段
• 技术栈 → 来自语言文件和框架依赖
• 命令 → 来自 package.json 脚本、Makefile 目标、工作流运行步骤
• 架构 → 来自顶层目录结构
• 代码规范 → 来自 eslint/prettier/ruff 配置值
• 测试 → 来自测试配置文件和测试目录位置
• 禁止事项 → 来自 .gitignore 构建产物、工作流分支保护、锁定文件
• 环境设置 → 来自 .env.example 变量名和 docker-compose 服务

节点 4 — 集中提问

只询问无法推断的信息。最多 3 个问题。扫描文件中已有明确答案的问题一律跳过。

将所有适用的问题集中在一条消息中提出——绝不分多轮提问：

快速回答几个问题，完善你的 CLAUDE.md（按需回答）：

1. 用一句话说明这个项目的用途是什么？（如果找到了 README，请跳过）
2. 有没有任何文件、目录或系统是 Claude 绝不能触碰或自动修改的？
3. 有没有 lint 配置中未体现的团队规范？（命名模式、PR 大小、提交格式、审查流程）

节点 5 — 生成

使用 references/claude-md-template.md 中的确切章节结构生成 CLAUDE.md。

关键规则：

• 每个已填写的章节都必须包含实际内容——不得使用 [TODO: add your X here] 占位符
• 如果某个章节完全无法填写，则将其整个省略，而不是写占位内容
• 命令必须准确且可运行（npm run dev，而不是“运行开发服务器”）
• 禁止事项至少列出 2 条
• 使用祈使、直接的表达方式（“使用……运行测试”“切勿编辑……”）
• 章节内的标题级别不得深于 H2

节点 6 — 验证

写入前，根据 references/validation-checklist.md 进行验证：

• 所有已填写的章节都包含实际内容（无占位符）
• 命令章节至少包含 2 条可运行的命令
• 禁止事项至少包含 2 条
• 没有残留未替换的占位文本
• 如果现有 CLAUDE.md 超过 200 个字符，已完成差异比较与合并流程

如果命令或禁止事项不符合要求：写入前再提出一个有针对性的最终问题。

输出

将文件写入项目根目录下的 CLAUDE.md。写入后，打印一行确认信息：

✓ CLAUDE.md written — X sections populated from repo scan, Y from your answers.

如果处于差异比较与合并模式，还要打印哪些章节已添加、哪些章节保持不变。

应拒绝的反模式

• 未先运行扫描就生成 CLAUDE.md
• 提出超过 3 个收集信息的问题
• 写入占位章节（“在此添加命令”）
• 未运行差异比较与合并流程，就覆盖已有内容的 CLAUDE.md
• 写入与扫描到的项目无关的通用模板内容
• 写入信号文件中未找到、且用户未确认的命令

参考资料

• references/scan-signals.md — 信号文件的完整目录，以及每种文件能揭示的信息
• references/claude-md-template.md — CLAUDE.md 的规范章节结构和风格规则
• references/validation-checklist.md — 写入前的必填字段和质量门槛

---

版本： 1.0.0