生成路线图
路线图是一份计划，下一位接手的人无需了解生成它的对话就能直接执行。它说明了项目试图达成什么目标、以何种顺序实现、每个部分完成的标志是什么，以及哪些问题尚未决定。它存放在它所描述的代码旁边的仓库中，因此像其他所有内容一样经过审查和版本控制。
路线图记录决策，而非做出决策。当某些事项尚未决定时，路线图会明确说明。
仓库规则优先
在编写任何内容之前，先查找仓库自身的约定：AGENTS.md、CLAUDE.md、CONTRIBUTING.md、文档或 wiki 模式，以及任何已有的路线图。它们决定路线图的存放位置、携带哪些元数据、如何关联议题以及运行哪些检查。当它们与本技能冲突时，以它们为准。遵循已有路线图的格式，而不要引入第二种格式。
工作流程
1. 明确需求
确定用户想要的是以下哪一种，因为每种所需的工作量不同：
- 新路线图： 针对项目、功能、迁移、测试工作等。
- 更新： 添加或更改工作项、重新排序阶段、记录一个决策。
- 同步： 将现有路线图与实际交付的内容对齐。
- 审查： 阅读路线图并报告差距，而不重写。
2. 先收集证据，再提问
阅读项目已知的信息：相关代码和测试、已打开和最近关闭的议题、已合并和打开的拉取请求、现有文档以及该区域的提交历史。记录目前存在什么、哪些已经在进行中、以及哪些内容之前已经尝试过。
任何能通过这种方式了解到的信息，就不要向用户提问。
3. 询问需要判断的问题
路线图的好坏取决于其背后的决策，而大部分决策属于用户。分简短轮次提问，而不是一次性列出长清单。当权衡不明显时，解释为什么这个问题重要。合适的话题：
- 目标： 这项努力值得做的成果是什么？如何知道它已经实现？
- 范围： 明确排除什么？哪些绝对不能改变（API、数据格式、行为）？
- 约束： 截止日期、发布、人员、预算、平台。
- 优先级： 如果只能交付一半，是哪一半？
- 风险： 什么最不确定？是否应该最先处理？
- 完成： 哪些测试、指标或审查可以作为完成的证据？
当证据支持时，给出建议。始终允许用户回答“尚未决定”。该答案放在未决决策中，而不是猜测。
对于小型更新，直接跳到写作。对于新路线图，预计需要两到三轮沟通。
4. 选择结构
- 单个文件（
ROADMAP.md，或与仓库匹配的名称）适用于大多数路线图。 - 一个目录（
roadmaps/<slug>/README.md加上支持页面）仅当计划需要长篇幅的支持材料（如研究笔记、设计草图或测试矩阵）时使用，否则这些材料会淹没工作项。主页面仍然拥有每个工作项 ID 的所有权。
5. 编写
使用下面的模板。以下规则确保其长期有用：
- 稳定 ID。 为每个工作项分配 ID，例如
R-001。切勿重新编号，切勿重用 ID。放弃的工作保留在文件中，标记为dropped并附上原因。 - 阶段有退出标准。 每个阶段说明完成时什么为真。按依赖关系、风险和价值依次排列阶段。
- 验收标准可检查。 编写能够验证的标准：一个通过的测试、一个成功的命令、一个可测量的数字。避免使用“健壮”、“改进”和“干净”等词语。
- 依赖关系显式。 用 ID 列出依赖项。指出团队无法控制的外部因素，例如其他仓库、供应商或决策。
- 用完整 URL 或仓库相对路径链接证据，以便链接在复制到其他地方后仍然有效。
- 描述计划，而非会议。 使用现在时，描述当前状态。历史记录放入变更日志。
6. 检查
在交付之前：
- 每个工作项都有 ID、状态和至少一个验收标准。
- 每个依赖项指向一个存在的 ID。
- 没有阶段依赖于后续阶段。
- 每个未决问题都在未决决策下，而不是隐藏在工作项中。
- 链接可解析，文件路径存在。
- 仓库的格式化和文档检查通过。
- 变更日志中有本次变更的条目。
7. 报告
告诉用户你创建或更改了什么、记录了什么决策，以及哪些问题仍然未决。
同步路线图与实际交付
随着工作落地，路线图会偏离。要同步：
- 列出状态不是
done或dropped的工作项。 - 针对每个工作项，查找已合并的拉取请求、已关闭的议题以及满足其验收标准的代码。
- 仅在每个标准都满足时才将工作项标记为
done。链接证据。 - 如果工作交付方式与计划不同，更新工作项以说明实际发生的情况，并在变更日志中注明差异。
- 将发现的任何新工作作为新工作项添加，并使用新的 ID。
- 向用户总结变更。在删除任何内容之前先询问。
审查路线图
当只要求审查时，不要重写。按重要性从高到低报告：
- 目标或阶段没有完成标志；
- 验收标准模糊的工作项；
- 缺失或循环的依赖关系；
- 看似已决定但证据不支持的决策；
- 代码或议题跟踪器显示已完成或不再相关的工作项；
- 缺失的风险：最困难或最不明确的部分被安排在后期。
模板
# <项目或功能> 路线图
**目标：** <用一两句话说明成果>
**状态：** <草稿 | 活跃 | 完成 | 已取代>
**最后更新：** <YYYY-MM-DD>
## 背景
为什么这项工作现在重要、目前存在什么，以及证据链接。
## 范围
- **包括：** …
- **排除：** …
- **不得更改：** …
## 状态图例
| 状态 | 含义 |
| ------------- | -------------------------------------------- |
| `planned` | 已同意，尚未开始 |
| `in-progress` | 有人正在进行中 |
| `blocked` | 等待依赖项或决策（说明是什么） |
| `done` | 每个验收标准均已满足，附证据 |
| `dropped` | 不执行（说明原因） |
## 阶段 1：<名称>
**退出标准：** <阶段完成时什么为真>
### R-001：<简短标题>
- **状态：** planned
- **原因：** <此工作项解决的问题>
- **验收标准：**
- [ ] <可检查的陈述>
- **依赖项：** <ID，或“无”>
- **证据：** <议题、拉取请求或文件链接>
## 阶段 2：<名称>
…
## 未决决策
| ID | 问题 | 选项 | 阻塞 | 负责人 |
| ----- | ---- | ---- | ---- | ------ |
| D-001 | … | … | R-004| … |
## 风险
| 风险 | 可能性 | 影响 | 缓解措施 |
| ---- | ------ | ---- | -------- |
## 变更日志
- <YYYY-MM-DD>: <变更内容及原因>
删除不适用的章节。一个小型路线图可能只包含一个目标、一个阶段和一个变更日志。
不要做
- 因为路线图看起来不完整而编造一个决策。
- 用没有具体成果的通用项（“添加文档”、“改进测试”）填充计划。
- 重新编号工作项，或删除已放弃的项。
- 仅凭拉取请求标题就将工作项标记为
done，而不检查验收标准。 - 将路线图的全部内容复制到议题中，反之亦然。应使用链接。