---
name: init
description: 使用代码库文档初始化新的 CLAUDE.md 文件。
---

为此仓库设置一个最小化的 CLAUDE.md（以及可选的技能和 hooks）。CLAUDE.md 在每次 Claude Code 会话中都被加载，因此必须简洁——只包含没有它 Claude 会出错的内容。

## 阶段 0：检查是否有现有的 CLAUDE.md

在询问任何事情之前，检查 CLAUDE.md 是否已在项目根目录存在（只需 `cat ./CLAUDE.md`——仅项目根文件算数；现在不需要探索目录树）。这会影响阶段 1 的分支。

## 阶段 1：询问要设置什么

使用 AskUserQuestion 来了解用户想要什么。你问哪个问题取决于阶段 0。调用 AskUserQuestion 时**仅包含 Q1**——不要在同一次调用中包含 Q2。只有在你看到 Q1 的答案后才问 Q2，因为"让 Claude 决定"会跳过 Q2。

在第一个问题之前，将以下入门内容作为普通助手文本打印出来，以便新用户了解术语：

> 快速背景：
> - **CLAUDE.md** 文件为 Claude 提供项目、个人工作流或组织的持久指令。Claude 在每次会话开始时读取它们。
> - **技能**是打包的指令，当任务匹配时 Claude 自动调用，或者你通过斜杠命令（例如 `/frontend-design`、`/commit-push-pr`）触发。
> - **Hooks** 允许你在生命周期事件上自动运行 shell 命令：在 Claude 被阻塞等待你的输入时收到通知、编辑后自动格式化、提交前强制执行检查——这些是确定性的，Claude 无法跳过它们。

**如果 CLAUDE.md 已存在**，询问：
- "我发现了一个现有的 CLAUDE.md。你想做什么？"
  选项："审查和改进它" | "保留它，设置其他东西" | "从头开始（替换它）"
  "改进"的描述："探索代码库中变化的内容，并对现有文件提出有针对性的编辑建议。"
  "保留它"的描述："跳过 CLAUDE.md。直接进入技能和 hooks。"
  "从头开始"的描述："丢弃它并写入新文件。"
  路由：
  - "审查和改进它" → 跳过 Q1/Q2；探索（阶段 2），问一个阶段 3 的轻量问题，然后进入阶段 4 的差异提案，然后是阶段 8。
  - "保留它" → 跳过 Q1，问 Q2（将其第四个选项重命名为"都不——跳过设置"）。如果他们选择"都不——跳过设置"，直接跳到阶段 8："无事可设置——你的 CLAUDE.md 未更改。"否则：阶段 2 → 阶段 3 提案（无缺口填补访谈）→ 按队列进行阶段 6/7 → 阶段 8。对于阶段 7 的 hook 目标文件默认值，将此路径视为"项目"（`.claude/settings.json`）。
  - "从头开始" → 继续下面的 Q1，就像文件不存在一样。

**如果不存在 CLAUDE.md**（或用户选择了"从头开始"），询问：
- Q1："/init 应该设置哪些 CLAUDE.md 文件？"
  选项："项目 CLAUDE.md" | "个人 CLAUDE.local.md" | "项目 + 个人两者" | "让 Claude 决定"
  "项目"的描述："团队共享的指令，纳入源码控制——架构、编码标准、常见工作流。"
  "个人"的描述："你对此项目的私有偏好（已在 gitignore 中，不共享）——你的角色、沙盒 URL、首选测试数据、工作流怪癖。"
  "让 Claude 决定"的描述："最快路径——项目 CLAUDE.md 加上任何适合此仓库的技能或 hooks。没有后续问题；你将在所有内容被写入之前批准。"
  如果用户选择"让 Claude 决定"，跳过 Q2——将其视为项目 CLAUDE.md，无技能/hooks 约束。

- Q2："也设置技能和 hooks？"
  选项："技能 + hooks" | "仅技能" | "仅 hooks" | "都不，仅 CLAUDE.md"
  "技能"的描述："打包的指令，当任务匹配时 Claude 自动调用，或者你通过斜杠命令（例如 `/frontend-design`、`/commit-push-pr`）触发。"
  "hooks"的描述："在工具事件上运行的确定性 shell 命令（例如，每次编辑后格式化）。Claude 无法跳过它们。"
  Q2 是一个提示，不是筛选器——阶段 3 会提出适合代码库的建议，并注明任何偏差。

## 阶段 2：探索代码库

启动一个子代理来审查代码库，让它读取关键文件以了解项目：清单文件（package.json、Cargo.toml、pyproject.toml、go.mod、pom.xml 等）、README、Makefile/构建配置、CI 配置、现有的 CLAUDE.md、.claude/rules/、AGENTS.md、.cursor/rules 或 .cursorrules、.github/copilot-instructions.md、.windsurfrules、.clinerules、.mcp.json。

检测：
- 构建、测试和 lint 命令（尤其是非标准的）
- 语言、框架和包管理器
- 项目结构（带工作区的单体仓库、多模块还是单项目）
- 不同于语言默认值的代码风格规则
- 非明显的陷阱、必需的环境变量或工作流怪癖
- 现有的 .claude/skills/ 和 .claude/rules/ 目录
- 格式化器配置（prettier、biome、ruff、black、gofmt、rustfmt 或统一的格式化脚本如 `npm run format` / `make fmt`）
- Git worktree 使用：运行 `git worktree list` 检查此仓库是否有多个 worktree（仅当用户想要个人 CLAUDE.local.md 时相关）

记下你无法仅从代码中弄清楚的内容——这些会成为访谈问题。

## 阶段 3：填补缺口

使用 AskUserQuestion 收集你仍然需要的信息，以编写好的 CLAUDE.md 文件和技能。只问代码无法回答的事情。

如果用户选择了项目 CLAUDE.md、两者或"让 Claude 决定"：询问关于代码库实践的问题——非明显的命令、陷阱、分支/PR 约定、必需的环境设置、测试怪癖。跳过已在 README 中存在或从清单文件中明显的内容。不要将任何选项标记为"推荐"——这是关于他们团队的工作方式，不是最佳实践。

如果用户选择了个人 CLAUDE.local.md 或两者：询问关于他们自己而非代码库的问题。不要将任何选项标记为"推荐"——这是关于他们个人的偏好，不是最佳实践。示例问题：
  - 他们在团队中的角色是什么？（例如，"后端工程师"、"数据科学家"、"新员工入职培训"）
  - 他们对此代码库及其语言/框架有多熟悉？（以便 Claude 可以校准解释深度）
  - 他们有个人沙盒 URL、测试账户、API 密钥路径或 Claude 应了解的本地设置细节吗？
  - 仅当阶段 2 发现多个 git worktree 时才问：询问他们的 worktree 是嵌套在主仓库内（例如，`.claude/worktrees/<name>/`）还是同级/外部（例如，`../myrepo-feature/`）。如果是嵌套的，向上文件遍历会找到主仓库的 CLAUDE.local.md 自动——不需要特殊处理。如果是同级/外部，个人内容应放在主目录文件（例如，`~/.claude/<project-name>-instructions.md`），每个 worktree 获得一个单行 CLAUDE.local.md 存根导入它：`@~/.claude/<project-name>-instructions.md`。永远不要将此导入放在项目 CLAUDE.md 中——这会将个人引用纳入团队共享文件。
  - 任何沟通偏好？（例如，"简洁"、"始终解释权衡"、"末尾不要总结"）

如果用户在阶段 0 中选择了"审查和改进"：只问一个问题——"自从这个 CLAUDE.md 被编写以来，团队的工作方式是否发生了变化（新的约定、命令、陷阱）？"选项为"不，没有变化" | "是的——让我描述"。如果他们选择"是"，在继续之前询问变化了什么（自由文本）。然后跳到阶段 4。

**综合阶段 2 的发现和缺口填补答案，提出建议。** 对于每个项目，选择适合证据的制品类型：

  - **Hook**——确定性的、快速的、每次编辑后运行的 shell 命令（格式化、lint 检查已更改文件）。
  - **技能**——按需的多步骤工作流（`/verify`、`/deploy-staging`、会话报告）。
  - **CLAUDE.md 注释**——塑造行为但非强制执行的指导（约定、沟通风格）。

将 Q1 隐含的 CLAUDE.md 文件（项目、个人、两者或"让 Claude 决定"→项目）作为提案的第一个项目符号，附上每个将涵盖的内容的一行摘要。然后列出技能/hooks/注释。在"保留它"路径上，省略 CLAUDE.md 文件项目符号和注释（阶段 4 不会运行）。在"从头开始"路径上，如果 Q1 = 仅个人，添加一个项目符号说明现有的项目 CLAUDE.md 将保持不动（他们选择不将其替换为项目文件）。

提出适合的建议。如果用户给出了 Q2 提示，而你的提案偏离了它（例如他们说"仅 hooks"但没有适合 hook 形式的东西），在提案顶部用一行说明，并仍然建议更适合的制品。

**将提案打印为普通助手文本**，每个项目一行：

> 以下是我要设置的：
> • **[制品类型: 文件/hook/技能/注释]**——[一行描述]
> • …

然后调用 AskUserQuestion，询问一个简单的问题（"这样行吗？"）和选项如"看起来不错——继续" | "去掉 hook" | "去掉技能"。不要使用 `preview` 字段——提案在滚动回溯中已经可见。该工具会自动添加"其他"选项以供自定义调整。

**从接受的提案中构建偏好队列。** 每个条目：{类型: hook|技能|注释，描述，目标文件，任何阶段 2 来源的细节，如实际的测试/格式化命令}。阶段 6 和阶段 7 的 hooks 子项目消费此队列；阶段 4/5 直接取决于批准提案中的文件项目符号；阶段 7 的 GitHub-CLI 和 lint 检查无论队列内容如何都会运行。

## 阶段 4：编写 CLAUDE.md（如果批准的提案包含它，或在"审查和改进"路径上）

在项目根目录编写一个最小化的 CLAUDE.md。每一行都必须通过这个测试："删除这行会导致 Claude 犯错误吗？"如果不行，删除它。

如果用户在阶段 0 中选择了"审查和改进"：不要重新编写——读取现有文件，对照阶段 2 的发现和阶段 3 轻量答案进行比较，并提出具体的添加/删除作为差异，每个附上一行理由。现有文件是基线；你的工作是捕捉缺失、过时或膨胀的内容。在打印差异之后，在写入任何内容之前调用 AskUserQuestion（"应用这些编辑？"选项如"应用所有" | "让我挑选哪些" | "跳过——保持原样"）。

**消费来自阶段 3 偏好队列、目标为 CLAUDE.md 的 `note` 条目**（团队级注释）——将每条作为简洁的一行添加到最相关的章节。这些是用户希望 Claude 遵循但不需保证的行为（例如，"实施前提出计划"、"重构时解释权衡"）。将个人目标的注释留给阶段 5。

包括：
- Claude 无法猜测的构建/测试/lint 命令（非标准脚本、标志或序列）
- 不同于语言默认的代码风格规则（例如，"偏好 type 而非 interface"）
- 测试指令和怪癖（例如，"运行单个测试使用：pytest -k 'test_name'"）
- 仓库礼仪（分支命名、PR 约定、提交风格）
- 必需的环境变量或设置步骤
- 非明显的陷阱或架构决策
- 存在的来自现有 AI 编码工具配置的重要内容（AGENTS.md、.cursor/rules、.cursorrules、.github/copilot-instructions.md、.windsurfrules、.clinerules）

排除：
- 逐文件结构或组件列表（Claude 可以通过阅读代码库发现这些）
- Claude 已经知道的标准语言约定
- 通用建议（"编写干净的代码"、"处理错误"）
- 详细的 API 文档或长引用——改用 `@path/to/import` 语法（例如，`@docs/api-reference.md`）按需内联内容而不膨胀 CLAUDE.md
- 频繁变化的信息——用 `@path/to/import` 引用来源，以便 Claude 始终读取当前版本
- 长教程或演练（移到单独的文件并用 `@path/to/import` 引用，或放在技能中）
- 从清单文件中显而易见的命令（例如，标准 "npm test"、"cargo test"、"pytest"）

要具体："在 TypeScript 中使用 2 空格缩进"优于"正确格式化代码。"

不要重复自己，不要编造像"常见开发任务"或"开发提示"这样的章节——只包含你在读取的文件中明确找到的信息。

为文件添加以下前缀：

```
# CLAUDE.md

此文件为 Claude Code (claude.ai/code) 在此仓库中处理代码时提供指导。
```

对于有多重关注点的项目，建议将指令组织到 `.claude/rules/` 中作为独立聚焦的文件（例如，`code-style.md`、`testing.md`、`security.md`）。这些文件与 CLAUDE.md 一起自动加载，可以使用 `paths` 前置元数据限定到特定文件路径。

对于有不同子目录的项目（单体仓库、多模块项目等）：提及可以添加子目录 CLAUDE.md 文件以获取模块特定指令（当 Claude 在这些目录中工作时会自动加载）。如果用户愿意，主动创建它们。

## 阶段 5：编写 CLAUDE.local.md（如果批准的提案包含它）

在项目根目录编写一个最小化的 CLAUDE.local.md。此文件与 CLAUDE.md 一起自动加载。创建后，将 `CLAUDE.local.md` 添加到项目的 .gitignore 中，使其保持私有。

**消费来自阶段 3 偏好队列、目标为 CLAUDE.local.md 的 `note` 条目**（个人级注释）——将每条作为简洁的一行添加。如果用户在阶段 1 中选择了仅个人，这是 note 条目的唯一消费者。

包括：
- 用户的角色及其对代码库的熟悉程度（以便 Claude 可以校准解释）
- 个人沙盒 URL、测试账户或本地设置细节
- 个人工作流或沟通偏好

保持简短——只包含会使 Claude 对该用户的回应明显更好的内容。

如果阶段 2 发现多个 git worktree 且用户确认他们使用同级/外部 worktree（不是嵌套在主仓库内的）：向上文件遍历不会从所有 worktree 找到同一个 CLAUDE.local.md。将实际的个人内容写入 `~/.claude/<project-name>-instructions.md`，使 CLAUDE.local.md 成为导入它的单行存根：`@~/.claude/<project-name>-instructions.md`。用户可以将此单行存根复制到每个同级 worktree。永远不要将此导入放在项目 CLAUDE.md 中。如果 worktree 嵌套在主仓库内（例如 `.claude/worktrees/`），不需要特殊处理——主仓库的 CLAUDE.local.md 会被自动找到。

如果 CLAUDE.local.md 已存在：读取它，提出具体的添加建议，不要静默覆盖。

## 阶段 6：建议和创建技能（如果批准的提案包含任何技能）

技能添加了 Claude 可以在需要时使用的能力，而不膨胀每个会话。

**首先，消费来自阶段 3 偏好队列的 `skill` 条目。** 每个排队的技能偏好成为根据用户描述量身定制的 SKILL.md。对于每个：
- 从偏好中命名（例如，"verify-deep"、"session-report"、"deploy-sandbox"）
- 使用用户访谈中的话语加上阶段 2 发现的任何内容（测试命令、报告格式、部署目标）编写正文。如果偏好映射到现有的捆绑技能（例如 `/verify`），编写一个项目技能，在上面添加用户的具体约束——告诉用户捆绑的仍然存在，他们的是附加的。
- 如果偏好规格不足，快速跟进询问（例如，"verify-deep 应该运行哪个测试命令？"）

**然后建议额外的技能**，超越队列，当你发现：
- 特定任务的参考知识（约定、模式、子系统的风格指南）
- 用户想要直接触发的可重复工作流（部署、修复问题、发布流程、验证变更）

对于每个建议的技能，提供：名称、一句话目的以及为什么它适合此仓库。

如果 `.claude/skills/` 已经存在，首先审查它们。不要覆盖现有技能——只建议补充已有内容的新技能。

在 `.claude/skills/<skill-name>/SKILL.md` 处创建每个技能：

```yaml
---
name: <skill-name>
description: <what the skill does and when to use it>
---

<Instructions for Claude>
```

用户（`/<skill-name>`）和 Claude 都可以默认调用技能。对于有副作用的工作流（例如 `/deploy`、`/fix-issue 123`），添加 `disable-model-invocation: true` 以便只有用户可以触发它，并使用 `$ARGUMENTS` 接受输入。

## 阶段 7：建议额外的优化

告诉用户，既然 CLAUDE.md 和技能（如果选择）已经就位，你将建议一些额外的优化。

检查环境并询问你发现的每个缺口（使用 AskUserQuestion）：

- **GitHub CLI**：运行 `which gh`（Windows 上为 `where gh`）。如果缺失且项目使用 GitHub（检查 `git remote -v` 中是否有 github.com），询问用户是否要安装它。说明 GitHub CLI 让 Claude 可以直接帮助提交、拉取请求、问题和代码审查。

- **Linting**：如果阶段 2 没有找到 lint 配置（项目语言没有 .eslintrc、ruff.toml、.golangci.yml 等），询问用户是否要让 Claude 为此代码库设置 lint。说明 linting 可以早期发现问题，并给 Claude 对自己编辑的快速反馈。

- **提案来源的 hooks**（如果批准的提案包含任何）：消费来自阶段 3 偏好队列的 `hook` 条目。如果阶段 2 找到了格式化器且队列中没有格式化 hook，提供编辑后格式化为回退选项。

  对于每个 hook 偏好（来自队列或格式化器回退）：

  1. 目标文件：基于阶段 1 的 CLAUDE.md 选择——项目 → `.claude/settings.json`（团队共享，提交）；个人 → `.claude/settings.local.json`。仅当用户在阶段 1 选择了"两者"或偏好模糊时才询问。对所有 hooks 问一次，而不是每个 hook 一次。

  2. 根据偏好选择事件和匹配器：
     - "每次编辑后" → `PostToolUse`，匹配器为 `Write|Edit`
     - "当 Claude 完成时" / "在我审阅之前" → `Stop` 事件（在每个轮次结束时触发——包括只读的轮次）
     - "运行 bash 之前" → `PreToolUse`，匹配器为 `Bash`
     - "提交之前"（字面的 git-commit 门控） → **不是 hooks.json hook。** 匹配器无法按命令内容过滤 Bash，因此没有办法只针对 `git commit`。将其路由到 git pre-commit hook（`.git/hooks/pre-commit`、husky、pre-commit 框架）——主动编写一个。如果用户实际意思是"在我审阅和提交 Claude 的输出之前"，那是 `Stop`——探测并消除歧义。
     如果偏好模糊则探测。

  3. **加载 hook 参考**（每次 `/init` 运行一次，在第一个 hook 之前）：使用 `skill: 'update-config'` 和以 `[hooks-only]` 开头的 args 调用 Skill 工具，后跟你正在构建的内容的单行摘要——例如 `[hooks-only] 使用 ruff 构建 .claude/settings.json 的 PostToolUse/Write|Edit 格式化 hook`。这会将 hooks schema 和验证流程加载到上下文中。后续 hooks 重用此缓存——不要重新调用。

  4. 遵循技能的 **"构建 Hook"** 流程：去重检查 → 为当前项目构建 → pipe-test 原始 → 包装 → 写入 JSON → `jq -e` 验证 → 实时证明（对于可触发的 `Pre|PostToolUse` 匹配器）→ 清理 → 交付。目标文件和事件/匹配器来自上述步骤 1–2。

  对每个"是"在继续之前进行处理。

## 阶段 8：总结和下一步

回顾已设置的内容——写入了哪些文件以及每个文件中包含的关键点。提醒用户这些文件是起点：他们应该审查和调整它们，并且可以随时再次运行 `/init` 重新扫描。

然后告诉用户，根据你的发现，你将介绍一些更多优化他们的代码库和 Claude Code 设置的建议。将这些呈现为一个单一、格式良好的待办事项列表，其中每项都与此仓库相关。将最具影响力的项放在前面。

在构建列表时，逐步检查这些项，只包括适用的：
- 如果检测到前端代码（React、Vue、Svelte 等）：`/plugin install frontend-design@claude-plugins-official` 给 Claude 设计原则和组件模式，使其生成精美的 UI；`/plugin install playwright@claude-plugins-official` 让 Claude 启动真实浏览器、截图构建的内容并自行修复视觉 bug。
- 如果你在阶段 7 中发现了缺口（缺少 GitHub CLI、缺少 linting）且用户说了不：在此列出它们，并附上一行说明为什么每个有帮助。
- 如果测试缺失或稀疏：建议设置测试框架，以便 Claude 可以验证自己的变更。
- 为了帮助你创建技能并使用评估优化现有技能，Claude Code 有一个官方的技能创建器插件可供安装。使用 `/plugin install skill-creator@claude-plugins-official` 安装它，然后运行 `/skill-creator <skill-name>` 来创建新技能或精炼任何现有技能。（始终包含此项。）
- 使用 `/plugin` 浏览官方插件——这些捆绑了技能、代理、hooks 和 MCP 服务器，你可能会觉得有帮助。你还可以创建自己的自定义插件与他人分享。（始终包含此项。）
