roadmap

路线图

概述

路线图将一个过于庞大的想法转化为持久化、带检查点的拆解方案：一份包含可检查步骤的文档，每个步骤都足够小，可以独立交付而不致使应用无法正常运行，并且每个步骤都能追溯到一个工单。它不是一份更大的规格说明——规格说明描述一项连贯的变更；路线图描述一系列有序的变更，以及这些变更之间的状态。

此技能是所有路线图相关工作的唯一触发入口。它负责存储、命名和状态文件约定（见下文——所有参考文件共用），并根据实际流程引导至相应参考文件：

情况	阅读
编写全新的路线图	references/writing.md
泛泛地说“我们继续路线图吧”——不清楚是指继续编写文档还是开始实施	references/resuming-work.md
用户指定某个检查点／任务，并要求开始或着手处理	references/executing-checkpoints.md
批量起草并验证多个步骤的规格说明／计划（来自此路线图，或来自明确列出的任务）	references/batch-plan-validate.md
最新的默认分支、未关闭 PR 的状态叠加，以及从分支中隐藏其他路线图（以上各项共用）	references/sync-and-isolate.md

执行上述任何操作之前（编写全新路线图除外），先运行 references/sync-and-isolate.md 的 A 和 B 节：获取更新，检查默认分支中的变更（无论你是基于该分支还是基于与路线图相关的分支工作），并据此读取路线图数据；然后叠加未关闭 PR 中路线图工作的状态。选定检查点并创建其分支后，再运行同一文件的 C 节（从工作树中移除其他路线图）。

只阅读当前情况所需的参考文件——这些文件都假定本文件中的存储、命名和状态文件约定已作为共享背景，因此不要在每个参考文件中重新推导这些约定。

**硬性规则，无一例外：**在此技能下编写的路线图文件、每份设计／规格说明文档以及每份实施计划（直接编写，或通过 superpowers:brainstorming／superpowers:writing-plans 编写），都必须完全使用俄语——包括标题、正文和任务描述，无论请求使用何种语言。代码块、标识符、文件路径和工单 ID 保持原样。实施计划保留 superpowers 标记格式中的英文内容（### Task N: <俄语标题> 标题——由 task-brief 脚本解析——以及复选框和 Step／Files／Interfaces／Global Constraints 标签）。如果项目自身的 rules/skills/writing-plans.md／rules/skills/brainstorming.md 存在，其中的规则同样适用——这项规则不以该文件是否存在为条件。

工作流配方

路线图规模的功能会经历三个阶段，每个阶段都完全由此处的一个参考文档负责——无需单独的编排器：

• 阶段 1 — 路线图： references/writing.md。分析功能，将其拆分为检查点（核心原则：每完成一步，应用都应保持可构建状态），并编写路线图。功能的目标和需求写在路线图自身的 Context 部分中——无需单独的 PRD 文档。
• 阶段 2 — 逐步编写并验证规格： 针对路线图的检查清单使用 references/batch-plan-validate.md，并将每项任务的起草模式设为 brainstorming，仅限设计——暂不生成实施计划。结果：每个步骤都有一份经过验证的设计/规格（brainstorming），其中也包含该步骤的需求和成功标准，并通过标准的 EnterPlanMode → ExitPlanMode → Plannotator 流程进行审核。
• 阶段 3 — 按需为每个步骤制定实施计划： 实际选定某个步骤开始工作时，调用 references/executing-checkpoints.md。它会找到该步骤已批准的规格，并在此时编写实施计划（superpowers:writing-plans）——而不是提前编写——这样计划就能反映工作开始时的仓库状态，而不是最初拆分路线图时的状态。

不要在阶段 2 提前为每个步骤编写实施计划——阶段 2 的仅限设计模式正是为避免这种情况而设。

存储

• 位置：仓库根目录下的 docs/<feature-slug>/。由 Git 跟踪并永久保留，作为迁移/发布历史——绝不放在 tmp/，检查点发布后也绝不删除。
• 在此处写入内容前，必须先使用原生 Plan Mode；brainstorming/writing-plans 也是如此。

存储优先级

上述步骤文件夹存储方式（docs/<feature-slug>/steps/<step-slug>/...，永久保留并由 Git 跟踪）优先于项目级别对 writing-plans/brainstorming 的任何通用存储覆盖规则（例如“将计划/规格保存到项目根目录，实施后删除”），但仅适用于属于路线图步骤的工件。对于在路线图步骤上下文之外编写的独立非路线图计划和规格，项目的计划/规格存储覆盖规则仍按原样适用；此优先级规则仅为路线图步骤工件设定例外。references/writing.md 已说明，发生冲突时，项目自身的约定优先于其默认值；本节明确规定了步骤级工件的例外情况。

无 PRD 文档

路线图及其步骤均不包含 PRD。功能级别的目标、当前/目标状态和硬性约束写在路线图的 Context 部分中；步骤的需求和成功标准写在其设计/规格（-design.md）的专用需求部分中。不得在任何一级创建 *-prd.md 文件。

文件命名

文件	用途
docs/<feature-slug>/YYYY-MM-DD-<feature-slug>-roadmap.md	路线图本身。每个检查点/步骤都作为顶层复选框：- [ ] <TICKET> <short name>。使用项目实际的 Issue 跟踪器前缀（例如 SCB-NNN）；在工单创建之前，使用字面占位符 TBD。
docs/<feature-slug>/roadmap-state.json	每个检查点的机器可读进度状态——参见下文的 ## State File。
docs/<feature-slug>/steps/<step-slug>/YYYY-MM-DD-<step-slug>-design.md	步骤规格——该步骤的需求、成功标准，以及（如有必要）架构决策（来自 brainstorming）。
docs/<feature-slug>/steps/<step-slug>/YYYY-MM-DD-<ticket>-<name>.md	该步骤的详细实施计划（来自 writing-plans）。

每个步骤都应在 docs/<feature-slug>/steps/ 下拥有自己的文件夹，并以该步骤自身的 slug 命名（例如 steps/general-information/）——不要只用数字命名。该步骤的两份文档（规格、计划）应放在同一文件夹中；如果某个步骤无需做架构决策，则只需保存计划，无需 -design.md。

状态文件

docs/<feature-slug>/roadmap-state.json 会跟踪整个路线图的进度——哪些检查点已有规格说明、已验证的规格说明、计划，哪些已实现或已关闭——因此进度不再仅依赖 Markdown 复选框。存储策略与路线图本身相同：由 Git 跟踪、永久保留，在路线图本身删除之前绝不删除（见下文“路线图全部勾选完成时”）。

{
  "feature": "<feature-slug>",
  "roadmapPath": "docs/<feature-slug>/<date>-<feature-slug>-roadmap.md",
  "updatedAt": "<ISO-8601>",
  "steps": [
    {
      "id": "A1",
      "title": "...",
      "ticket": "TBD",
      "dependsOn": [],
      "stepFolder": "docs/<feature-slug>/steps/<step-slug>/",
      "status": "not-started",
      "specPath": null,
      "planPath": null
    }
  ]
}

status 的取值依次为：not-started → spec-drafted → spec-validated → plan-drafted → implemented → closed。对于没有设计文档的步骤（直接使用 writing-plans 起草，或不需要架构决策的步骤），会跳过 spec-* 阶段——状态从 not-started 直接变为 plan-drafted，且 specPath: null。

谁在何时更新该文件：

• references/writing.md 在保存路线图后立即创建该文件——每个检查点对应一条记录，status: "not-started"；只有已立即创建文件夹的检查点才填写 stepFolder（大多数检查点会保持平铺状态，直到在 Phase 2/3 中开始处理）。
• references/batch-plan-validate.md 在任务的每次阶段转换后更新该文件：Phase 1 起草设计/计划后 → spec-drafted + specPath；如果直接选择 writing-plans，则为 plan-drafted + planPath；Phase 2 批准后 → spec-validated（如果直接验证了计划，则保持 plan-drafted）。如果 stepFolder 仍为空，也会填写。
• references/executing-checkpoints.md 在开始处理某个步骤时（Phase 3）更新该文件：编写实现计划后 → plan-drafted + planPath；实现的最终验证通过后 → implemented；收尾时（勾选复选框、删除计划文件）→ closed，planPath: null。

依赖项

检查点的 Markdown 行末尾可以带有机器可读的依赖标签：(depends: <id>[, <id>...])，列出必须先关闭的检查点。单独的 <id> 指向同一份路线图中的检查点；<feature-slug>:<id> 指向相邻路线图中的检查点，其中 <feature-slug> 是该路线图的 docs/<feature-slug>/ 文件夹名称。检查点没有依赖时，完全省略该标签——大多数检查点，尤其是位于不同步骤、只需等待各自设计完成的检查点，都没有依赖。其他外部依赖（如身份验证/用户前置条件、合并无关 PR 等）仍应以自由文本形式写在检查点所在行，或路线图的 Context/Зависимости от ... 部分中。

- [ ] 1.1b — [backend] ... (Jira: ACD-59) (depends: 1.1a)
- [ ] A1 — [ui-kit] ... (Jira: TBD) (depends: ui-kit-e2e:B1, ui-kit-e2e:B2)

docs/<feature-slug>/roadmap-state.json 以机器可读的形式镜像同一信息：每个步骤条目都包含 "dependsOn": string[] 字段（检查点 ID 数组，按标签中的写法原样填写——"A1" 或 "ui-kit-e2e:B1"；无依赖时使用空数组）——创建状态文件时，references/writing.md 会直接从 Markdown 标签填充该字段（参见上文的 ## State File）。

当检查点未勾选（- [ ]）且其 dependsOn 中的每一项都已满足时，该检查点便可以开始处理。若是单独的 ID，则当本路线图的 roadmap-state.json 中相应步骤的 status: "closed" 时，即表示已满足。<slug>:<id> 条目以相同方式在 docs/<slug>/roadmap-state.json 中解析，并且：

• 如果 docs/<slug>/ 已不存在，则视为已满足——已全部勾选的路线图会被删除（参见“路线图全部勾选后”），因此文件夹不存在就意味着该路线图已完成；
• 如果文件夹存在但没有状态文件，则回退到该路线图 Markdown 中对应依赖项的复选框（- [x] = 已满足）；
• 如果状态文件存在，但没有对应 ID 的步骤，则该引用是无效的：将检查点视为受阻，并告知用户修复标签，不要自行猜测。

跨路线图引用是单向且只读的：检查点绝不会修改其他路线图的文件。多个检查点可以同时进入就绪状态——这正是它们可以安全并行处理的原因。references/executing-checkpoints.md 会据此决定可以提供哪些检查点，而不是始终假定必须严格按从上到下的顺序执行。

提交策略

绝不自动提交路线图/规格/计划文件——与其他所有产物一样，只有在用户明确要求时才提交。

路线图全部勾选后

路线图中的所有复选框都变为 - [x] 后，应删除路线图文件；如果 docs/<feature-slug>/ 文件夹此时为空，也应一并删除，而不是将其作为无用文件保留。具体触发时机参见 references/executing-checkpoints.md。