track-roadmap

跟踪路线图

概述

在项目根目录中维护 ROADMAP.md，将其作为持续更新的高层级功能计划，确保后续构建内容的决策经过审慎考虑，而非临时应对。路线图只包含功能（用户可见的能力），不包含任务——任务级工作应归入 track-session。一份完善的路线图应包含 5–15 项已确定的功能，并且能在 2 分钟内读完。

工作流

每种模式都遵循相同的四个步骤——读取当前状态、提出变更、与用户确认、写入文件。只有中间两步因模式而异：

模式	命令	提出 / 确认
生成	/track-roadmap 或 generate	提供代码库扫描，提出 4 个探索问题，拟定功能列表，经用户确认后写入
更新	/track-roadmap update	询问有哪些变化（添加/移除/完成/改写），确认后应用
审查	/track-roadmap audit	扫描代码，将每项功能标记为 Done/In-Progress/Not-Started/Unclear，与用户一起审查相关性并更新
头脑风暴	/track-roadmap brainstorm	发散构思——先探索方向，再做决定；可行的想法以 status:idea 的形式放入“未来想法”
恢复	/track-roadmap resume	检查会话状态，展示剩余功能，由用户选择一项，然后交给 /track-session

更新是最常见的情况：添加一项、将某项标记为已完成，或记录已发布的工作，都属于此模式。没有 save 模式——将 /track-roadmap save 视为更新。当用户要求按路线图逐项推进时，恢复模式会按文件中的顺序处理尚未完成的功能，每项功能开启一个会话；每个会话结束后，无需询问便继续下一项。在更新和审查模式中，应就地编辑受影响的条目，而不是重新生成文件——这样可以保留 ID、顺序和未改动的文本；与其花费更多令牌重写整个文件，不如这样获得同样的结果。只有生成模式会从头写入文件。

各模式的完整流程（探索问题、头脑风暴问题库、审查步骤）：reference/MODES.md。

ROADMAP.md 格式

---
schema: cc-dash/roadmap@1
project: project-name-here
description: One-line project purpose
last_updated: YYYY-MM-DDTHH:MM:SS-TZ
---

# Roadmap

> Project purpose in one sentence.

## Core Features



-  **Feature Name** - What it does and why it matters.
  > Research finding, with its source link.
  > Open: the question still to settle.
-  **Feature Name** - Short description.

## Future Ideas



-  **Feature Name** - Short description.

## Completed



-  ~~**Feature Name**~~ - Short description. *(Completed: YYYY-MM-DD)*

格式规则。 cc-dash 仪表板会解析此文件，因此遗漏标记会导致该条目悄无声息地从看板上消失：

• Frontmatter 必须包含 schema、project、description、last_updated。
• 每个条目都必须有 id 和 status。ID 格式为 r_ + 2–10 个 [a-z0-9_] 字符，且永久不变——绝不修改；新 ID 默认使用 5 个随机字符。写入新 ID 前，先在文件中搜索，避免重复 ID 导致看板上的两个条目无法区分。
• 状态包括：idea / planned / in-progress / done，以及 deferred（仍然需要，但暂不处理）；当用户希望保留条目停止的原因记录而非删除时，使用 dropped / skipped / rejected / cancelled。最后四种状态会显示在看板的 Closed 列。
• 可选元数据：started: 和 completed:，格式为 YYYY-MM-DD；以及 depends:r_abc12,r_def34。cc-dash 会忽略其他日期键（at:、done_date:），并在下次写入时将其删除，因此修改条目时请将它们转换为 completed:。
• 每个类别标题下一行都要加上 ``。类别本身不受限制——可根据项目需要自行创建分组。
• 每个功能占一行：加粗标题 + 1–2 句描述。
• 备注用于记录描述中无法容纳的内容：注明来源的调研结果、待解决问题，以及附带原因的已否决方案。将备注写成条目正下方的 > 行；cc-dash 会在卡片上显示这些内容，并在自身写入时保留。每个条目的备注控制在约五行以内——如果调研内容过多，请将其移至 docs/ 下的文件，并留一条备注链接到该文件，因为将调研内容直接写在路线图中，会让路线图很快变得难以阅读。不要把备注写进描述，也不要在条目下另起一段；仪表板都不会读取。
• 条目移至 Completed 时，将备注精简为后续审查所需的内容（决策及原因），因为调研已经完成了它的作用。

规则

• 路线图由用户决定——提出更改并等待确认，不要自行判断添加、改写或删除功能。
• 只保留高层级内容——写“用户身份验证”，而不是“添加 bcrypt 对密码进行哈希”。
• ROADMAP.md 是唯一事实来源——不在文件中的内容，就不属于路线图。
• 已完成的功能要移动，而不是消失——将它们移至 Completed 部分并添加 completed: 日期，而不要删除，因为审查会将这些记录作为依据。

示例

❌ 错误示例 — - tasks / - lists / - make it look good / - fix bugs：没有描述或分组，将功能与任务混为一谈，也没有 ID 或目的。上面的格式块是对应的 ✅ 正确示例。

✅ 正确示例 — 更新模式下，用户说 “暗色模式昨天上线了”：保留 ID，更改状态，添加日期，并将该行移至 Completed：

-  ~~**Dark mode**~~ - System-level dark/light theme preference. *(Completed: 2026-03-14)*

generate、audit、update、brainstorm 和 resume 模式的完整 ✅/❌ 对照示例：reference/EXAMPLES.md。

集成

• track-session — 选定功能后，使用 track-session 规划并跟踪实现；SESSION_PROGRESS.md 会引用 ROADMAP 条目的 ID。
• 实际验证（完整体验一遍、通过一致性检查、发布签核）在此处都属于普通路线图条目——没有单独的检查清单文件，因此也不会有任何内容从检查清单反馈到路线图中。

注意事项

• 重命名功能时保留其 id。 编辑标题文本，但不要更改 `` — SESSION_PROGRESS.md 中的 roadmap_ref 值和 cc-dash 历史记录都指向它。合并时保留最终采用的 id；拆分时，原功能的一半保留原 id，另一半生成新 id。
• roadmap_ref 只能包含一个 id。 cc-dash 会发出警告并丢弃逗号分隔的列表，导致会话与看板取消关联。当一个会话推进多个功能时，关联主要功能，并在会话的 ## Current Status 中列出其余功能。
• 恢复会话会覆盖活动会话计划。 如果 SESSION_PROGRESS.md 中有未完成的任务，请先询问是否继续该计划，再展示路线图；切换功能会替换该文件，因此请先提供 /track-session save 选项。
• 含糊的审计证据应标为 Unclear，而不是猜测。 不完整或实验性代码（例如没有测试的 src/auth/）应提交给用户裁定，而不是标为 Done。
• 路线图包含 30 个以上条目是一个信号，而非需要保留的状态。 审计路线图，将推测性条目移至 "Future Ideas" 并设为 status:idea，删除不再适用的内容 — git 已保存历史记录，因此在文件中归档只会增加杂乱。
• 路线图出现偏差是意料之中的。 当文件与实际构建内容不符时，运行审计以协调两者，而不是凭记忆逐行修补。

更多边缘情况（代码库扫描噪声、头脑风暴中的死胡同、优先级选择困难、让模糊的功能描述更精确）：reference/TROUBLESHOOTING.md。