configure-repo

设置仓库

配置一次仓库，让其他所有技能都能读取其中的答案，而不必猜测。输出包括 docs/agents/ 下供 Agent 使用的配置文件、种子规范文件，以及仓库 Agent 指令中的一个指针区块。

这是一次对话，不是脚本：先进行探索，展示发现的内容，与用户一次确定一件事，然后再写入。

模板种子文件位于此技能集的 templates/ 目录中。按以下顺序解析套件种子，使用第一个存在的路径：（1）与此 SKILL.md 同级的 templates/；（2）设置了 ${CLAUDE_PLUGIN_ROOT} 变量时的 ${CLAUDE_PLUGIN_ROOT}/templates；（3）相对于此 SKILL.md 的 ../../../templates。

跟踪进度

此技能分为七个步骤（第 2 步包含决定 A–M），漏掉某一步是最常见的失败原因——可能导致跟踪器未配置，或第 6 步的验证关卡从未运行。在第 1 步之前，为下面每个编号步骤创建一项待办任务，并按顺序完成；只有满足相应的完成条件时，才勾选完成。第 6 步（证明配置有效）不可跳过。

1. 查看设置状态

此步骤只做一件事：确定仓库是否已针对该技能集完成配置，以及配置完整到什么程度。只读取仓库自身的文件——不要探测外部服务或其身份验证状态（不要运行 gh auth、gh label list、glab，也不要调用 Linear MCP），不要读取用户的 Shell 环境（不要运行 env，也不要探测 *_API_KEY）。检测不是此处要做的事：第 2 步中由用户决定要设置什么，任何服务或工具链的具体信息都要等到用户已作出选择后，再为该选择收集。仅通过读取仓库中的文件检查以下设置标记：

• docs/agents/project.md、docs/agents/issue-tracker.md、docs/agents/triage-labels.md、docs/agents/verify.md——这些文件是否存在且已填写，还是缺失？
• docs/agents/project.md 中是否有 ## Team 部分——是否存在且已填写，还是缺失？
• CLAUDE.md / AGENTS.md 中是否有 ## Agent skills 部分（注明这两个文件中哪个存在）
• 此技能集要求的种子文件：docs/specs/INDEX.md（领域路由文件）+ docs/specs/catalog/<domain>.md、一个术语表（CONTEXT.md 或 CONTEXT-MAP.md）
• .gitignore 中是否包含 .skills/ 和 .worktrees/

然后根据检查结果分支处理：

• 已配置（全部或部分）——这是一次补齐缺项的运行，不是重建。准确列出已存在的内容，以及缺失或过时的内容，将摘要展示给用户，并提出只补齐缺项。仅按第 2 步中对应输出缺失或用户明确要求修改的部分进行操作；已写入的内容保持不变（第 4 步的增量规则）。
• 未配置——直接进入第 2 步由用户主导的流程。不要根据 Git 远程地址或已连接的 MCP 服务猜测问题跟踪器，也不要自动检测任何应由用户选择的内容。询问用户希望如何设置仓库，每次只讨论一项决定。

仍可读取仓库自身的清单文件（锁文件、package.json 脚本、Cargo.toml、pyproject.toml、Makefile、测试配置），以便在后续步骤中预填建议；读取仓库文件不等于探测服务，而且预填的建议绝不代表替用户作出决定。

**完成条件：**已将仓库归类为已配置／部分配置／未配置，列出所有缺项，并向用户展示了摘要。

2. 逐个部分作出决定

严格按顺序逐个讨论以下十三项决定（A–M；I 为可选项目文档，K 为可选远程环境，L 为可选目录同步，M 为冷启动引导方案）：每项先用两到三句话解释（这是什么、哪些技能会使用它、不同选择会带来什么变化），再用一句话说明你的建议及理由，然后等待用户回答，再继续下一项。绝不要一次性列出所有部分。假设用户之前从未接触过这些概念。

A. Issue tracker

说明：读取或编写 issue 的技能（发布计划时使用的 triage、publish-issues、plan-tasks，以及 land-branch、cut-release）需要知道 issue 存放在哪里，以及哪些命令会操作它们。选项：github、gitlab、linear、local、other。只根据仓库的本地 git 远程地址给出建议：GitHub 远程地址 → github，GitLab 远程地址 → gitlab，没有远程地址 → local，并且始终允许用户否决建议。不要探测服务或其身份验证信息来猜测 issue tracker。Linear 是独立服务，不会出现在 git remote 中，因此要将其列为选项；只要用户表示团队使用 Linear，无论代码托管平台是 GitHub 还是 GitLab，都应选择 Linear。

选择 issue tracker 后，读取本文件旁的 issue-tracker-followups.md 并严格遵循其中的要求 — 各选项的含义、PR-surface、Publish unit、Program sync 和 Draft surface 的后续问题、写入范围表，以及 IC-default 规则都在该文件中。

**完成条件：**已确认 tracker 选择、PR-surface（如适用）、Publish unit、Program sync、Program write role 和 Draft surface（或明确选择默认值：feature + local + ic + repo）。

B. Triage 标签映射

执行此决策时，读取本文件旁的 triage-label-mapping.md 并严格遵循其中的要求 — 规范角色表、映射提案、创建标签的许可，以及 Linear 专属分支都在该文件中。

**完成条件：**每个规范角色都映射到一个已确认的标签字符串。

C. 验证命令

说明：test-first、prove-claim、build-in-waves 和 cut-release 都会运行此仓库的验证命令；这些命令必须准确，不能猜测。逐一确认每项命令，并根据检测结果预填：类型检查、lint、单元测试、e2e/smoke，以及单个测试文件模式（运行单个测试文件的命令格式，即 test-first 所使用的紧密循环；它必须缩小构建范围，而不只是缩小运行范围 — 例如 cargo nextest run -p <crate> --test <file>，绝不能使用只按名称筛选、却会编译包中所有测试二进制文件的命令）。然后确认两个可选关卡：Task gate（更改单元及其依赖项的测试 — 例如 cargo nextest run -p a -p b、vitest related、nx affected）和 Wave gate（编译并 lint 每个目标 — 例如 cargo check --workspace --all-targets + lint）。如果完整测试套件只需几分钟，就将它们标记为 “none” — 此时测试套件本身就是关卡。**完成条件：**用户已确认每条命令（或明确标记为 “none”）。

D. 可追溯性（仅限文档）

说明：需求 ID 位于 docs/specs/** 中。audit-trace 检查仅限文档 — 它会搜索需求和任务页脚，而不是应用测试。对于使用者应用，不要要求添加 /// REQ:、@CODE-N.M 或测试标题中的 ID。可在 project.md 中备注：忽略旧版注释；不要添加新的注释。若 specs 目录路径不是默认值，请确认该路径；不要自行编造测试注释表。**完成条件：**已确认仅限文档的可追溯性策略（specs 路径；不强制要求使用者在测试中遵循 ID 约定）。

E. 发布步骤

说明：cut-release 技能会按顺序执行项目专属命令列表 — 构建、打包、签名、发布 — 并且不会自行编造命令。根据已找到的内容（构建脚本、打包配置）拟定有序列表并进行确认。若存在 smoke-check 命令，也要包含在内。**完成条件：**已确认有序发布步骤（对于无需构建的库，空列表也是有效答案）。

F. 文档布局

说明：规范和发现技能会读取 docs/specs/、docs/adr/ 和领域词汇表；它们需要了解其布局。确认 specs 位于 docs/specs/，ADR 位于 docs/adr/（若目录不存在则创建），并确认词汇表布局 — single-context（单个根目录 CONTEXT.md — 大多数仓库）或 multi-context（根目录 CONTEXT-MAP.md 指向各上下文的 CONTEXT.md 文件 — 通常用于 monorepo）。**完成条件：**已确认布局。

G. 项目定位

说明：关于项目的三项既定事实——交付目标（输出必须达到的质量标准）、生命周期阶段（项目当前所处的阶段）以及兼容性义务（哪些人已经依赖当前的架构、端点和格式）。frame-change 和 clarify-decisions 会读取这些信息，以确定合适的流程严谨度——只有兼容性义务决定迁移／向后兼容／弃用的考量视角——interpret-session 也会复用这些信息，避免重复询问。它们位于 docs/agents/project.md，项目阶段变化时，用户直接编辑相应行。根据仓库信号预填并进行确认——绝不凭空编造：

• 交付目标 — Production / MVP / Run Spike / Research / Learning。这是质量标准，不是发布状态：Production 绝不意味着项目已经发布。根据仓库情况给出建议（已发布的软件包或已完成发布的工作流 → Production；纯粹的绿地探索 → Run Spike）；不明确时默认为 MVP。
• 生命周期阶段 — Idea / Early development / Active development / Cut Released / Scaling / Maintenance。根据 Git 信号给出建议（有标签或已完成发布的历史记录 → Cut Released；较新的仓库且提交较少 → Early development）；不明确时默认为 Early development。
• 兼容性义务 — None / Internal / External。只有当仓库情况与模板「项目定位」部分根据生命周期阶段给出的推导结果相矛盾时才询问（发布前 → None，已发布 → External）：若在发布前阶段已有已发布的软件包、带版本的公开 API 或已部署的数据库，则应考虑书面覆盖。否则省略该行，沿用推导结果——未书写的行是当前默认值，而非遗漏。

完成条件： 用户已确认交付目标和生命周期阶段，并确认兼容性义务的覆盖值，或明确选择沿用推导结果。

H. 团队

当决策 H 执行时，读取本文件旁的 team-inference.md 并严格遵循——说明为何分档很重要、面向用户的解释、推荐默认值；仅使用本地 Git／CODEOWNERS／AUTHORS／CONTRIBUTORS／软件包清单；先推断，再确认。

想法	实际情况
“我会通过 gh api 获取协作者”	仅使用本地元数据——不调用协作者 API
“提交量能证明谁是技术负责人”	绝不编造头衔；默认为 Contributor，直到用户重新指定角色
“Git 历史为空——编造一个独立开发者”	留空草稿并提问；绝不编造姓名
“先写好草稿，以后再修正”	确认关卡：本次运行中未经明确确认，不得写入团队信息

完成条件： 用户已确认团队名单（按姓名和／或人数确认）、可选的归属说明及可选的分档覆盖值，或明确推迟团队信息的确认（仍视为缺项）。

I. 项目文档层（可选——默认为 No）

提供此决策时，读取本文件旁的 project-docs-layer.md 并严格遵循——说明该层的作用、哪些技能会参考它，以及已有其他指南时的迁移建议。建议选择 No，除非这是一个大型多功能项目。完成条件： 用户已选择启用或拒绝该层。

J. 默认 PR 基础分支

说明：land-branch 会将 docs/agents/project.md 中的 Default PR base: 作为其基础分支解析流程的第三步读取——排在显式调用时指定的基础分支以及现有 PR 上已记录的基础分支之后。因此，一旦记录了主干分支，它就不会再询问。仅将 dev、staging、main 和仓库本地分支列表作为建议；不预选任何值——始终由用户自行指定分支。建议：仓库实际使用的主干分支（通常为 main）——除非另有说明，否则这是 land-branch 已默认采用的分支。若用户拒绝选择：不写入任何值，并跳过 Step 4 中关于此字段的条目——此后 land-branch 每次调用都会询问基础分支，这样才能确保该字段在 ARCH-2 下确实是可选项。

**完成条件：**用户已确认一个值，或明确拒绝选择且不会写入任何值。

K. 远程环境（可选——默认情况下，若未部署则跳过）

提供此决策选项时，请阅读本文件旁的 remote-environments.md，并严格遵循其中说明——包括每个环境需要确认的内容、令牌规则和对应的写入步骤。**完成条件：**表格已确认，或已明确跳过（None — not deployed / 拒绝）。

L. 目录同步（可选——默认不设置 / 完整三元组行为）

提供此决策选项时，请阅读本文件旁的 catalog-sync-choice.md，并严格遵循其中说明——包括精简目录同步的含义、三种选项的定义和写入步骤（Step 4，第 11 项）。指南：docs/guide/skills/catalog-sync.md。

想法	实际情况
“现在所有人都应该只使用索引模式”	仅限主动选择；默认不设置可保留现有仓库的行为
“我会添加 gitignore，但不声明只使用索引模式”	仅当 L=index-only 且用户已确认时才添加片段

**完成条件：**目录同步值已确认，或明确保持未设置。

M. 冷启动运行配方（可选——存在可运行入口时默认选 Yes）

提供此决策选项时，请阅读本文件旁的 verify-control.md，并严格遵循其中说明——包括选项、跳过规则、写入步骤和验证步骤。npm test 不是启动并点击验证的配方。**完成条件：**选择 Yes 并创建 docs/agents/verify.md，或明确选择 Skip。

3. 起草并确认

写入任何内容之前，向用户展示：

• docs/agents/*.md 文件的内容（包括决策 M 选择 Yes 时的 verify.md，以及决策 H 已确认时的 ## Team）
• 将写入 CLAUDE.md/AGENTS.md 的 ## Agent skills 区块

允许用户编辑。**完成条件：**用户批准草案。

4. 写入

**增量规则：原有文件须就地编辑，绝不覆盖。**如果目标文件已存在，请将内容合并其中，并保留用户编写的所有内容。

1. 以 templates/agents/project.md、templates/agents/issue-tracker.md 和 templates/agents/triage-labels.md 为模板，写入 docs/agents/project.md、docs/agents/issue-tracker.md 和 docs/agents/triage-labels.md。在 issue-tracker 文件中仅保留所选跟踪器的操作章节，记录 PR 界面答案，并根据决策 A 填写 Publish unit、Program sync、Program write role、Draft surface（若为 notion，还须包含其 ### Notion draft surface 区块）和 Close linkage（默认值：feature / local / ic / repo / 跟踪器原生关闭语法）。已配置的仓库只需补上模板中缺少的行。

2. 如果缺少 docs/specs/INDEX.md，则从 templates/specs-INDEX.md 创建该文件，并从 templates/specs-catalog-domain.md 创建 docs/specs/catalog/app.md（将 <Domain> 替换为 App）。如果 INDEX 已存在但其中是平铺的 Code 表，则指出需要执行 /map-features Domain boundary migrate——不要擅自创建分片。

3. 如果缺少词汇表，请从 templates/CONTEXT.md 创建 CONTEXT.md（或根据用户的回答，为多上下文项目创建 CONTEXT-MAP.md）。

4. 在 docs/agents/project.md 的 Project posture 部分填写已确认的交付意图和生命周期阶段（决策 G），替换模板占位符。只有在决策 G 确认覆盖时，才写入 - **Compat obligation:** \`行；如果决策 G 保留了原有推导，则删除占位符行，让推导规则生效。（增量修改：如果该部分已有实际值，只更新用户要求更改的内容。）如果决策 L 确认了 **index-only** 或 **full-triad**，则在同一部分设置- Catalog sync: ```（增量修改）。如果决策 L 未设置，则不写入 Catalog sync 行。

5. 根据已确认的决策 H 内容（团队名单、职责说明、可选的级别覆盖）填写 ## Team，并合并到 templates/agents/project.md 的模板结构中。只替换 Team 部分中已确认的字段；不要覆盖其他部分。如果用户暂缓填写 Team，则保留模板占位符，或等到补齐信息时再填写。

6. 如果选择启用项目文档层（决策 I）： 根据 templates/product-vision.md、templates/architecture-INDEX.md 和 templates/product-guidelines.md，分别创建 docs/product/vision.md、docs/architecture/INDEX.md 和 docs/product/guidelines.md（按上述规则进行增量修改）。如果是在迁移，将现有工程规则移至 docs/product/guidelines.md，并在 docs/agents/project.md 中留下指针。如果未启用该层，则跳过此项——不要写入这些文件。

7. 添加 ## Agent skills 区块。它只能存在于一个规范文件中；任何第二个文件只能是简短指针，不能复制该区块。

   • CLAUDE.md 和 AGENTS.md 都不存在（默认情况）：将 AGENTS.md 设为规范文件（其中包含该区块），并创建一个简短的 CLAUDE.md，其全文指向 AGENTS.md——这样 Claude Code 可以通过其原生文件名找到指令，同时避免重复。不要询问要创建哪个文件；此模式适用于两者。
   • 仅存在其中一个文件： 将该文件设为规范文件——在其中添加或更新该区块。如果它是 AGENTS.md 且 Claude Code 是目标，则同时添加 CLAUDE.md 指针。如果它是 CLAUDE.md，则保留其规范文件地位——不要将其降为指针，也不要创建与之竞争的 AGENTS.md。
   • 两个文件都存在： 将该区块放入已有实际 Agent 指令的文件中；只有在另一个文件尚无实质内容时，才将其改为指针。绝不要在两个文件中都放置该区块。
   • 如果规范文件中已存在 ## Agent skills 部分，则在原处更新——绝不要追加重复内容，也不要改动周围部分。

   创建 CLAUDE.md 指针时，必须逐字采用 templates/claude-md-pointer.md 的内容。

该区块必须逐字采用 templates/agent-skills-block.md 的内容；只有在决策 I 为 Yes 时才包含项目文档条目。 8. 确保本地工作目录已加入 Git 忽略：技能的临时产物——build-in-waves 的台账和简报，以及规范技能写入的扫描／审查摘要——位于 .skills/ 下，隔离工作区位于 .worktrees/ 下（与 isolate-workspace 使用同一父目录）；两者都不应纳入版本控制。对每个模式幂等地执行：grep -qxF '.skills/' .gitignore 2>/dev/null || printf '.skills/\n' >> .gitignore（.worktrees/ 同理），然后暂存 .gitignore。不要添加 .isolate-workspace/ 行——那是旧的并行父目录。保留已有的 .isolate-workspace/ 忽略规则（只增不删）。（检查行是否存在，不要使用 git check-ignore——带尾斜杠的模式只会匹配已存在的目录，因此目录尚不存在时，check-ignore 会再次追加规则。） 9. 如果已确认决策 J（默认 PR 基础分支），则在 docs/agents/project.md 的 Project posture 部分中，按照上述只增不删规则添加 - **Default PR base:** \`——合并添加，绝不要覆盖用户已设置的值。如果用户拒绝了决策 J，则不写入任何内容：保留该字段为空缺状态，以便 land-branch在每次调用时询问。 10. 按照remote-environments.md中针对决策 K 的写入步骤执行。 11. 按照catalog-sync-choice.md中针对决策 L 的写入步骤执行（仅追加 index-only gitignore）。 12. 按照verify-control.md` 中针对决策 M 的写入步骤执行。

**完成条件：**所有文件均已写入，.skills/ 和 .worktrees/ 已加入 Git 忽略，仅当 L=index-only 时应用仅针对索引的 gitignore 规则，已执行或跳过 M 的写入操作，并且 git status 仅显示预期的新增／编辑内容。

5. 推荐 Context7 MCP

运行此步骤时，请阅读本文件旁的 optional-offers.md 并严格遵循其中的说明——即 Context7 MCP 推荐。

**完成条件：**已明确答复是否接受 Context7 MCP 推荐；若接受，则已在 docs/agents/project.md 中记录。

6. 证明配置确实可用 — GATE

向用户确认过，不代表它在本项目中可用。命令是根据检测结果预先填写的；清单路径错误、脚本缺失或工具未安装，都可能在几周后的 test-first、prove-claim 或 cut-release 中途失败。趁你还掌握上下文，现在就证明它们可用。这是将 prove-claim 技能的纪律应用于刚刚写好的配置：运行命令、阅读输出、相信输出——而不是相信配置。**浏览器驱动。**运行这些命令前，请阅读本文件旁边的 webbridge-setup.md，并严格遵循其中的说明。

逐一重新运行每条已配置的验证命令，并对结果分类。关键区别在于接线问题与内容问题：

• 接线失败 — 命令无法按原样运行：“command not found” / 退出码 127、“missing script”、“no such file or directory”、--manifest-path 错误或未知标志、工具未安装。这是必须修复的配置错误：重新检测、修正 docs/agents/project.md，然后重新运行，直到问题消失。只要还有任何命令接线错误，设置就不算完成。
• 内容失败 — 工具正常运行，但报告了问题（类型错误、lint 警告、测试失败）。命令接线正确；仓库存在预先已有的问题。请将这些问题记录下来告知用户；它们不会阻碍设置。
• 通过 — 接线正确且运行结果为绿色。

注意成本——不要为了证明接线正确而运行整套测试：

• 类型检查和 lint：完整运行（范围受限）。
• 单元测试 / 端到端测试运行器：低成本证明运行器能解析其配置——使用 project.md 中的单个测试文件模式，针对一个现有测试文件运行；或者使用运行器的仅收集 / 列表模式。设置期间绝不要触发完整的端到端测试；说明完整测试应由用户之后运行。
• Audit Trace 检查：运行该检查（必需的子技能：使用 audit-trace），并确认检查结果集干净——没有要求也是有效的干净状态。该检查通过 grep / git 检查 docs/specs/（以及可选的架构文档），而不是应用测试目录。
• 如果跟踪器是远程服务（github / gitlab / linear），通过一次只读调用证明其可访问且已认证——运行 gh issue list / glab issue list；对于 Linear，则进行一次 MCP 列表调用（或一个最简的 issues GraphQL 查询）。这是在验证用户已经选择的跟踪器，并非设置期间禁止的第 1 步检测——选择已经完成，此调用只用于证明它可用。如果 CLI 缺失、会话未经认证，或者 MCP 服务未连接或未认证，都属于接线失败；否则这些问题会一直隐藏，直到几周后 triage 失败才暴露。local 和 other 无需检查可访问性。
• 决策 M = Yes：遵循 verify-control.md 中的 Prove 步骤（先运行 Doctor，再运行一次 Drive）。从未执行过的配方只是草稿。

报告一个简短的表格：每条命令 → 接线正确？→ 通过 / 失败 / 预先已有。

完成条件：每条已配置命令都已证明接线正确（没有遗留接线失败），audit-trace 检查运行正常，已配置的跟踪器响应了一次只读调用，决策 M 已证明可用或已跳过，webbridge-setup.md 中的检查已运行，并且已将任何内容失败列出告知用户。

7. 完成

告诉用户设置已完成，哪些技能现在会读取该配置，prove-claim 表格会显示哪些命令已接线、哪些问题是预先已有的，并说明之后可以直接编辑 docs/agents/*.md——只有在切换跟踪器或从头开始时，才需要重新运行此向导。