roadmap

路线图：轻量级项目创意追踪器

在 gitignored 的 ROADMAP.md 中管理项目的功能待办清单。快速记录创意、在 PR 和版本发布后跟踪进展、从类似仓库中获取竞品情报，并定期审视，确保优先级合理。

这不是项目管理系统。没有阶段、执行计划或里程碑。它只是一个随项目不断演进的草稿区。

适用场景

• 记录项目的功能创意、头脑风暴或“如果……”的想法
• 跟踪哪些创意已通过 PR 或版本发布上线
• 浏览竞品或类似仓库，寻找功能灵感
• 审视并确定创意待办清单的优先级
• 为尚无 ROADMAP.md 的项目创建初始文件
• 用户表示“添加到路线图”“我接下来应该构建什么”或“竞品在做什么”

不适用场景

• 需要阶段、里程碑和执行计划的结构化项目管理
• 带有任务依赖关系的冲刺或迭代计划
• 代码审查或 PR 审查——使用 code-review
• 编写项目文档或 README——使用 update-docs
• ROADMAP.md 中声明的版本号或版本亮点文案与事实不符——使用 update-docs。此技能负责条目状态本身：模式 2 会将已上线的 [planned] / [exploring] 条目移至 Shipped。update-docs 负责标题中的版本号和亮点文案；路线图负责界定哪些条目算作已上线。
• 跟踪 Bug 或事故——直接使用问题追踪器

---

AI 自检

编写或修改 ROADMAP.md 前，请确认：

• 已加入 Git 忽略：ROADMAP.md 已加入 .gitignore（或用户明确选择不将其加入 Git 忽略）
• 不含机密信息：条目不包含 API 密钥、内部 URL 或敏感业务信息
• 保留来源标注：竞品情报注明来源仓库或项目
• 没有重复项：新创意不会重复现有条目（检查意图，而不仅是措辞）
• 保留格式：编辑遵循现有文件结构——不要重新格式化用户未要求更改的部分
• 已上线条目注明来源：已完成的条目注明对应的 PR、版本发布或提交
• 没有臆造竞品数据：关于竞品仓库的每项功能、问题数量或用户需求主张，都有实际链接或引文作为依据——不得凭推断得出
• 没有夸大优先级：P0 条目确实是阻碍因素，而不是一厢情愿的目标
• 标注证据质量：竞品情报、用户反馈和假设均注明来源及可信度
• 保持待办清单整洁：将过时的创意搁置或删除，而不是一再调整优先级
• 应用跨领域 Agent 卫生规范——参见 references/agent-hygiene.md

路线图格式

章节（固定顺序）

每份 ROADMAP.md 都按以下顺序排列章节。空章节可以省略，但顺序不可更改——保持一致有助于快速浏览文件。向之前省略的章节添加内容时，应根据现有章节，将其放在规范位置。

# Roadmap

> Project: {name} | Updated: {date} | Current: v{version}
> Local planning doc, gitignored. Not a commitment.

## Snapshot

{1-2 paragraphs: project state, what the next milestone means, current focus}

## Exit Criteria

What "done" means for the next milestone. Each criterion has a verdict.

### {Criterion Name}

**Verdict**: Pass | Fail | Partial

- {Requirement}
- {Requirement}

## Now - P0

Blocks the next milestone or release. Active work only.

- [in-progress] {Description} - {area} | PR #{n}
- [planned] {Description} - {area}

## Next - P1

Committed direction. Happens after Now is clear.

- [planned] {Description} - {area}
- [exploring] {Description} - {area}

## Later - P2

Good ideas, no timeline. Revisit during review.

- {Description} - {context}

## Experiments

Low confidence. Build only with real demand signal.

- {Description} - {what would validate it}

## Shipped

### v{X.Y.Z} ({date})

- ~~{Description}~~ - {area} | PR #{n}, v{X.Y.Z} ({date})

## Competitive Intel

### {owner/repo}

- {Feature} ({strong signal | weak signal | noise}) - {evidence}
- User demand: {issue links, discussion quotes, vote counts}

## Parked

Items deferred with reason.

- {Description} - {reason for parking}

条目格式

条目按所在位置分为两类：

活跃条目（Now、Next）——结构化，包含状态和跟踪信息：

- [status] Description - area | tracking

状态值：exploring、planned、in-progress

领域值是项目特定的简写，表示组件或领域（例如：ui、api、backend、infra、docs、auth）。根据项目结构推断。如果不确定，请省略领域，不要猜测。

待办条目（Later、Experiments）——轻量、快速记录：

- Description - context or source

条目在晋升时逐步补充结构。Later 中的一个简单想法移至 Next 后，就会成为需要跟踪的条目。

已上线条目始终注明来源：

- ~~Description~~ - area | PR #N (or MR #N), vX.Y.Z (date)

已有 ROADMAP.md 时

先阅读现有结构。如果与此格式不符：

• 在 add 或 update 模式下：沿用现有结构，不要重新调整结构
• 在 review 模式下：如果当前结构杂乱，建议迁移到此格式
• 如果用户要求重新调整结构：逐节迁移，并保留所有内容

---

优先级实践

• 限制活跃的 P0/P1 项目数量，让优先级仍有意义。
• 将重复的想法归组，并链接相关证据，而不是反复复制冗长的备注。
• 为每个近期项目明确关联用户、业务或技术成果。
• 在开始实施前记录退出标准。
• 将承诺事项与实验分开，避免推测性工作挤占交付资源。

---

工作流

步骤 0：活动检测（每次调用时运行）

在报告路线图状态之前，检查可访问的仓库根目录、ROADMAP.md、忽略规则、 README 和主要软件包／项目元数据。区分已观察到、缺失和无法访问的状态； 当无法检查仓库时，切勿推断路线图不存在或已被忽略。指出无法获取的项目上下文。

如果尚无 ROADMAP.md，或成功的活动查询未返回近期活动，则跳过提醒。将查询失败报告为无法获取的证据。

否则，检查近期项目活动：

command -v gh; command -v glab   # forge CLI: gh (GitHub), glab (GitLab), or git-only
# GitHub
gh pr list --state merged --limit 10 \
  --json number,title,mergedAt
# GitLab
glab mr list --merged --per-page 10

# Always available (portable - no GNU date required)
git tag --sort=-creatordate | head -5
git log --oneline --since="2 weeks ago" | head -15

如果 gh 和 glab 均不可用，说明一次（“PR 跟踪不可用—— 安装 gh 或 glab 以获得完整覆盖”），并继续仅使用 git 数据（标签 + 提交）。

如果已合并的 PR 或新版本看起来与未完成的路线图项目相符，请在继续前简要提及：

“提醒一下：自上次更新路线图以来，PR #142 和 v0.15.0 已落地。 要我先将它们标记为已完成，还是继续执行{请求的模式}？”

不要因此中断。如果用户没有回应，继续处理其请求。

---

模式 1：添加想法（默认）

触发条件：用户向项目提出想法、说“添加到路线图”，或描述功能。

步骤 1：按需初始化

1. 检查项目根目录中是否存在 ROADMAP.md（在 monorepo 中，默认使用 git 根目录，除非用户指定某个软件包；如果存在多个 ROADMAP.md 文件，请询问）
2. 写入任何内容之前，确保 /ROADMAP.md 已被忽略，除非用户明确选择将其纳入跟踪。如有需要，添加：

   # Project roadmap (local planning doc)
   /ROADMAP.md
   

   使用 git check-ignore --no-index ROADMAP.md 验证，并检查 git ls-files --error-unmatch ROADMAP.md：已被跟踪的文件即使符合忽略规则，仍会保持跟踪状态；不要在未告知的情况下取消跟踪。
3. 如果文件不存在，使用起始结构创建。阅读 README 或主要清单文件，用真实上下文填写 Snapshot。报告添加的任何忽略条目。

步骤 2：解析并放置想法

从用户输入中提取可执行项目。对于每个想法：

• 撰写清晰、简洁的描述（保留用户的表达方式；仅在不清楚时润色）
• 将其放入恰当的优先级层级（确实不明确时先询问，默认设为 P1）
• 补充上下文：想法来源、它能实现什么，以及提到的任何限制

将项目追加到相应章节。不要重新排序现有项目。

步骤 3：提供竞品扫描

如果路线图没有竞品情报章节，且这是第一批想法，请询问：

“要我扫描类似的仓库，寻找可能适合 {project-name} 的功能创意吗？”

每次会话只问一次。如果用户拒绝，不要再次询问。

---

模式 2：更新／标记完成

触发条件：用户说“更新路线图”、要求标记项目完成，或在 PR 合并／发布后。

如果不存在 ROADMAP.md，先转到模式 1（初始化）。

复制此清单并跟踪进度：

• 步骤 1：已收集近期活动（或已获取指定的 PR）
• 步骤 2：已展示匹配项并获得确认
• 步骤 3：已将确认的项目移至 Shipped 并注明归属；已更新标题日期
• 步骤 4：已重新读取文件；如果确认的项目仍处于活跃层级或缺少归属信息，则修正并返回步骤 4

步骤 1：收集近期动态

# Always available (portable - no GNU date required)
git log --oneline --since="2 weeks ago"
git tag --sort=-creatordate | head -5

# GitHub
gh pr list --state merged --limit 20 \
  --json title,number,mergedAt
# GitLab
glab mr list --merged --per-page 20

如果用户指定了时间范围，请相应调整。如果用户直接提及特定 PR（例如“PR #45”），请使用 gh pr view 45 --json title,mergedAt（或 glab mr view 45）获取这些 PR，而不要依赖按时间范围筛选的列表。

步骤 2：将动态与路线图项目匹配

将提交信息、PR 标题和发行说明与未完成的路线图项目进行比较。 使用语义匹配——“添加暗色模式支持”与“暗色模式主题选项”相匹配。

进行更改前，先向用户展示匹配结果：

找到以下潜在匹配项：

• PR #142“添加暗色模式切换” -> 匹配“暗色模式主题选项”（P1）
• v0.15.0 版本包含备份/恢复功能 -> 匹配“备份与恢复”（P0）

要将这些项目标记为已完成吗？

步骤 3：更新文件

如果用户已经说明了哪些项目已交付（例如“PR #45 添加了暗色模式”），则视为已预先确认——展示计划进行的更改供用户审核，不要再询问“要将这些项目标记为已完成吗？”

对于已确认的匹配项：

1. 添加删除线：~~description~~
2. 按照 Item format 中已交付项目的格式添加归属信息：- area | PR #N, vX.Y.Z (date)（如果 PR 和版本均适用，则两者都要包含）
3. 移至“Shipped”部分（如果不存在则创建），按版本或日期分组

更新标题中的 Updated: 日期。

步骤 4：验证编辑结果

重新读取 ROADMAP.md。每个已确认的项目都应在 Shipped 下出现一次，并注明其 PR 或版本归属；未确认的项目应保持不变。修复任何遗漏并重复此步骤。

---

模式 3：竞品扫描

触发条件：用户要求扫描竞品、提供仓库 URL，或接受模式 1 的提议。

读取 references/competitive-scan.md，了解目标选择、forge CLI 命令、严格的匹配筛选、审批流程和 Competitive Intel 格式。

模式 3 必须使用范围受限、按 reaction 排序的 forge 查询；如果该 forge 不支持按 reaction 排序，则使用有记录的等效方法。应用参考文档中针对仓库规模校准的强匹配/弱匹配/噪声阈值，注明每个候选项的来源，并在写入前将候选项交由用户审批。

---

模式 4：审查 / 排定优先级

触发条件：用户要求审查路线图、排定优先级，或询问“接下来我应该做什么”。

步骤 1：加载并总结

读取 ROADMAP.md。提供以下摘要：

• 各优先级级别的项目数量
• 当前正在进行的项目（如果有跟踪）
• 最近交付的项目
• 陈旧项目：60 天以上未触及的项目可考虑归档或重新排定优先级（使用每个项目的日期或记录的历史；git blame 无法确定未纳入版本控制的文件的日期，文件 mtime 也无法确定单个项目的存续时间）

步骤 2：建议采取的行动

根据当前状态，指出以下任何情况：

• 无人处理的 P0 项目——按理说应当紧急；需要说明原因或降低优先级
• 60 天以上未触及的项目——说明原因后暂缓处理或提升优先级；搁置本身并不代表优先事项
• 分散在不同优先级中的相关项目——整合为协调一致的工作
• 仍位于进行中部分的已交付项目——移至 Shipped
• 缺少结构——建议改进组织方式

步骤 3：提出结构性改进

如果路线图缺乏清晰的组织结构，建议进行以下改进：

• 如果所有项目都在一个平面列表中，则添加优先级分级
• 将产品工作与推广/上市工作分开
• 添加 Snapshot 部分，记录项目背景
• 为重要里程碑添加退出标准
• 为低置信度想法创建 Experiments 部分

展示建议。仅应用用户批准的更改。

步骤 4：应用更改

获得用户批准后，重新组织、调整优先级、暂缓处理或移除项目。切勿悄无声息地删除项目——应说明原因并移至 Parked，或明确征得用户同意后再删除。

---

参考文件

• references/trigger-integration.md - Claude Code hooks、GitHub Actions 和 git hooks 的可选自动触发设置。当用户希望通过推送来更新路线图，而不是（或同时）依赖内置活动检测时，请阅读此文件。
• references/competitive-scan.md - 竞品／仓库扫描工作流、证据门槛，以及 ROADMAP.md 竞争情报的格式规范。

输出约定

完整约定请参阅 references/output-contract.md。

• 技能名称： ROADMAP
• 交付物目录： deliverables
• 模式： 有条件。当调用此技能来分析、审查、审计或改进现有路线图（例如“审查我的 ROADMAP.md”）时，请遵循 references/output-contract.md 中的报告长度和证据规则，并将交付物写入 docs/local/deliverables/roadmap/<YYYY-MM-DD>-<slug>.md。当调用此技能来构建或更新路线图（其主要模式，将内容写入用户工作目录中的 ROADMAP.md）时，可自由作答，无需遵循该约定；构建模式的输出应写入工作目录中的 ROADMAP.md，而不是 docs/local/。
• 严重性级别： P0 | P1 | P2 | P3 | info（请参阅共享约定；仅在审计／审查模式下使用）。

相关技能

• 在竞争扫描（模式 3）期间，使用宿主的浏览工具阅读竞品仓库和文档；仅靠网页抓取无法满足需要时尤其如此。
• git - 更新模式（模式 2）会读取 git 历史记录和 PR 数据，以匹配已发布的工作
• code-review - 审查代码正确性。本技能跟踪要构建的内容；code-review 评估实现这些内容的代码。
• update-docs - 更新项目文档，并审计 ROADMAP.md 中的标题版本和发布亮点说明是否存在事实偏差。本技能负责优先级排序、记录、竞争情报和项目状态（模式 2 会将已发布项目移出活跃级别）；update-docs 负责确保所述版本和亮点文本与 HEAD 保持同步。

规则

1. 默认加入 gitignore。 创建或写入 ROADMAP.md 前，确保将其加入 .gitignore。只有用户明确要求将其纳入 git 版本控制时，才可跳过。
2. 标注竞争情报来源。 来自其他仓库的每个创意都必须附上来源标签。绝不要将外部功能说成原创创意。
3. 勾选前先询问。 展示匹配项并让用户确认。不要仅凭模糊匹配自动将路线图项目标记为已完成。
4. 无头模式。 在非交互环境（--bare、Cursor Automations、Codex exec）中：跳过确认提示；模式 2 仅应用精确匹配项；模式 3 仅添加强信号项目；模式 1 不提供竞争扫描。