setup

设置

• 功能： 访谈用户，了解此仓库的情况，搭建 docs/dev-agents/，并编写 docs/dev-agents/config.md，供其他所有技能读取。
• 使用时机： 每个仓库只需运行一次，且应在使用此技能集中的其他技能之前运行。重新运行可更改跟踪工具，或将旧配置更新为当前字段。
• 依赖项： git。使用 GitHub 跟踪工具时需要 gh，使用 Linear 跟踪工具时需要 Linear MCP 服务；使用本地跟踪工具时两者都不需要。
• 调用方式： Claude Code /setup、Codex $setup、Kiro CLI /setup。
• 输入： 当前仓库，以及用户对访谈问题的回答。
• 输出： docs/dev-agents/config.md、docs/dev-agents/rules/、项目上下文文件中的一行引用，以及任何一次性跟踪工具设置。

幂等：可以安全地重新运行；未经询问绝不覆盖现有文件。

1. 检测模式

检查当前目录以确定状态（读取文件，不要臆测）：

• 从零开始： 为空或几乎为空（没有源代码树）。
• 已有项目： 已有代码（源代码目录、包清单、Git 历史）。

在提问前还要读取：

• 已有的 docs/dev-agents/config.md。其中保留了项目已做出的选择；访谈只补充缺失内容。
• git rev-parse --git-dir，以确认这是否为 Git 仓库。
• git remote -v，以确认是否存在 GitHub 远程仓库。
• 根目录下的 AGENTS.md 和 CLAUDE.md，以确认已存在的上下文文件。
• 已有的产品意图文档（docs/PRD.md、docs/product/、AGENTS.md 中的规格说明）。
• 从项目清单读取项目的测试命令（package.json 脚本、pyproject.toml、Makefile）。

首先要解决的是没有 Git 仓库的情况。 在访谈开始前，先提供执行 git init 的选项。每种后端都会在第 7 步提供提交选项，而 github 后端必须依托一个仓库才能关联远程仓库，因此若过几个章节才发现这一点，就得回退访谈流程。应单独询问此事，并在 A 部分显示之前询问；绝不能把它作为访谈选项之一放进同一个选择器：A 部分的 GitHub 检查要求仓库已经存在。

2. 访谈

总结已有内容和缺失内容。然后按顺序逐个处理各个部分。每次只回答一个部分，再继续下一个。

仅当选项确实存在分歧时，才用一行解释；如果步骤 1 已经确定了某个部分，就完全跳过它。

先提问，然后停下。 提问必须是本轮的最后内容：提问之后不得调用工具，也不得在等待答复时继续工作。仍在执行任务的 harness 无法接收普通回复。

让回答尽可能简单。 为选项编号，把推荐选项放在第一位，并说明回复一个数字就够了。使用 harness 自带的选项选择器（如果有）；大多数 harness 都没有，因此编号文本就是正确的提问方式，不要把它当作退而求其次的做法来道歉。不要询问屏幕上已经显示的路径：直接展示它，只需等用户简单回复“是”。

多问题选择器不会打乱访谈顺序。 Claude Code 的选择器会在一次调用中提出四个问题，这样可以更快地完成一个部分，但绝不会把 A 到 D 部分同时显示出来。对于所有 harness，必须先确定 A 部分及其表格中的所有前置条件，之后才能显示 B 部分：A 部分的答案决定后端是否能够正常工作；如果不能，之后的部分就白费了。仅当同一部分中的问题答案不会相互影响时，才将它们合并提问。

A 部分：问题跟踪工具。

说明：此仓库的问题存放在哪里。其他所有技能都会通过 tracker 读取和写入这些问题。请选择你实际用来跟踪工作的地方。

• GitHub：问题存放在仓库的 GitHub Issues 中（使用 gh CLI）
• Linear：问题存放在 linear.app（使用 Linear MCP 服务）。询问团队 key 和项目名称；两者都要写入配置。
• 本地 Markdown：问题以文件形式存放在此仓库的 docs/dev-agents/issues/ 下（适合个人项目或没有远程仓库的仓库）。一次只能有一个会话：在某个分支上分配的问题，在该分支合并之前，无法从 main 看到。
• 其他（Jira、GitLab 等）：请用户用一段话描述工作流；将其作为自由文本记录在配置正文中，并设置 issue_tracker: other

在此处、进入 B 部分之前，确定后端的前置条件。 缺少前置条件时，应立即提问，而不是等到运行结束时再报告。用户刚刚选择了这个后端，就在眼前；如果把问题留到步骤 5 才处理，用户就得在不知道第一个部分能否运行的情况下，再回答三个部分的问题。

后端	检查项	缺失时的处理
github	gh auth status，以及 git remote -v 中的 GitHub 远程仓库	询问要使用哪个仓库，并提供两种方案：现有仓库使用 git remote add origin <url>，新建仓库使用 gh repo create <name> --private --source=. --remote=origin。是否创建仓库由用户决定，因此应提供此选项并等待答复。
linear	Linear MCP 服务能否响应 list_teams	停下。说明如何连接；在它能够响应之前，不要将任何 Linear 字段写入配置。
local	无

将已确认的 OWNER/REPO，或已确认的团队和项目，写入配置。绝不要记录稍后再设置的意向。

B 部分：产品意图文档。 确定需求、规范和路线图存放的位置，以便后续技能读取正确的文件。默认路径为 docs/dev-agents/PRD.md、SPEC.md 和 ROADMAP.md。如果 AGENTS.md 或 CLAUDE.md 已经是相关文档，就将字段指向它。

C 部分：上下文文件。 编码 Agent 进入项目的入口文件。默认使用 AGENTS.md；如果项目特意只支持 Claude Code，则使用 CLAUDE.md。如果项目已有约定，就遵循约定：将 context_file 指向所有 harness 最终都会访问的文件，绝不要反过来设置。

D 部分：测试命令。 确认步骤 1 推断出的命令，或询问用户。后续技能会在交还工作之前运行此命令。

3. 初始化框架

开发技能负责的所有内容都放在 docs/dev-agents/ 下；其余内容都由项目负责。 只创建缺失的内容：

docs/dev-agents/
docs/dev-agents/config.md             # entry point on how to use these skills for AI-SDLC
docs/dev-agents/rules/                # promoted learnings, one file per rule
docs/dev-agents/issues/               # only when issue_tracker: local

添加 docs/dev-agents/rules/.gitkeep，以便在添加第一条规则之前，git 就能跟踪此目录。

不要创建空的 PRD.md、SPEC.md 或 ROADMAP.md。这些文件的路径已记录在配置中； 由 research、architect 和 plan 编写这些文件。唯一的例外是步骤 6：它会根据现有代码库 编写规格说明。

**模板：**根据 config-template.md 编写 docs/dev-agents/config.md， 并删除不适用的字段。每个值都来自访谈或步骤 1。绝不要猜测配置中的路径。

**现有项目：**现有的 config.md 保留项目已有的选择。补上缺失字段，并报告更改内容；不要重写正文。

所有权规则：AGENTS.md 和 CLAUDE.md 由项目负责。初始化设置最多只添加步骤 4 中的引用行，绝不移动、合并或重写其中已有的内容。rules_dir 默认值为 docs/dev-agents/rules/；遵循自身约定的项目可以将其设为其他路径，例如 .claude/rules/，Claude Code 会自动加载该路径。绝不要在未获邀请时迁移规则文件。

4. 添加引用行

在配置的 context_file 中添加一行，以便每个会话都加载开发配置：

Read dev workflow for AI-SDLC from docs/dev-agents/config.md

如果该行已经存在，则跳过此步骤；重新运行时不得重复添加。棕地项目： 将该行追加到文件中，其他内容一律不动。没有任何上下文文件的绿地项目：创建一个精简文件 （少于 50 行），写明项目、跟踪器后端和产品文档路径，并将引用行放在末尾。

Claude Code 不会自动加载 AGENTS.md。当 context_file: AGENTS.md 且正在使用或可能会使用 Claude Code 时，还要确保 CLAUDE.md 中包含 @AGENTS.md 导入行：如果不存在 CLAUDE.md，则创建一个仅含一行的文件；如果文件已存在，则追加该行；绝不要替换已有正文。

5. 跟踪器设置

为所选后端执行一次性工作。报告你做了什么；不要因为此处失败就放弃其余设置。

• **github：**远程仓库和 gh auth status 已在 A 节中处理。使用 gh label create 创建四个状态标签，已存在的标签跳过：backlog、ready、in-progress、in-review。done、cancel 或 duplicate 没有对应标签；这三项是 GitHub 的关闭原因，tracker 会读取和写入这些原因。如果已认证用户没有仓库写入权限，则不要创建任何内容，并报告维护者需要运行的确切命令。

• **linear：**MCP 连接已在 A 节中处理。使用 list_issue_statuses 检查团队状态，这些状态按团队设置，并由团队中的所有项目共享。需要以下七个状态，每个状态都必须具有表中所示的类别：

  必需状态	类别
  Backlog	backlog
  Todo	unstarted
  In Progress	started
  In Review	started
  Done	completed
  Canceled	canceled
  Duplicate	duplicate

  预计会缺少 In Review。 使用 Linear 默认模板创建的团队有六个状态，没有 In Review，因此这是首次运行时的常见情况，并非边缘情况。请明确说明这一点，不要把它说成是用户做错了什么。

  缺少任何一个状态都必须停止。 没有 MCP 工具可以创建或重命名状态，因此请准确指出需要在团队设置中添加哪些状态，以及每个状态所属的类别；在匹配之前，不要将 Linear 字段写入配置。不要擅自把状态映射到团队现有的其他状态：写入错误状态的工单会落到无人查看的地方。

  多出的状态只需警告，不必停止。 大声报告多出的状态，注明名称和类别，并说明停留在这些状态的工单不会显示在前沿中，且会被报告为未映射状态。然后将其写入配置正文中的 Tracker notes，这样用户之后可以和 AI 一起做出决定，而不必靠记忆。

• **local：**创建 docs/dev-agents/issues/.gitkeep。

• **other：**无需设置。用户描述的工作流就是约定。

6. 棕地项目：架构考古

提出（但不要强迫用户接受）将当前状态逆向梳理并写入已配置的 spec_file：

1. 调查代码库：入口点、组件、外部服务、数据存储、组件间的契约、测试布局、构建和部署路径。
2. 编写描述当前架构的规范：组件、接口、数据流、已知技术债务和缺口，并明确标注为技术债务，而不是需求。
3. 不要臆造面向未来的需求。这是 architect 的工作。

7. 报告

提出提交脚手架和配置。在全新仓库中，这会创建后续任务分支所需的根提交。

然后总结：模式、跟踪器后端、创建的文件、已执行的一次性跟踪器设置，以及用户仍需自行完成的事项。

下一步：使用本项目的测试工具确认后端有响应。Claude Code 使用 /tracker list，Codex 使用 $tracker list，Kiro CLI 使用 /tracker list。