规格转实施计划

中文简介

规格转实施计划：把 PRD、技术规格、设计说明、仓库上下文和验收标准转成可执行、可审查的交付计划。它先判断需求和仓库证据是否足以实施，再明确文件职责、接口、依赖、测试、迁移、发布、回滚、监控和验证；不把猜测的文件路径或接口伪装成事实。

使用背景

在开始编码、拆分 Issue、估算工作量或交接给另一位工程师前使用。它消费 PRD、设计、技术约束、仓库证据和验收标准，产出文件级计划、接口契约、任务依赖、测试与发布验证。它不是代码库导览、架构重写或替代产品决策：没有足够仓库证据时，先交付探索计划或转交 codebase-onboarding。

核心原则

• 先通过需求可实施性门槛，再写实施任务；未决目标、验收、权限、数据或发布约束是计划阻塞项，不是可忽略细节。
• 文件路径、现有职责、测试命令和接口现状只能来自已读仓库材料、用户提供路径或可定位证据。未读代码库时只能写候选职责、搜索线索和探索任务，不能杜撰文件名。
• 每个任务应产生一个可审查交付物，明确它消费什么、产出什么、依赖谁、由何种测试或观察验收。
• 接口契约要覆盖输入、输出、错误、权限、幂等/并发、兼容性和消费者；“加一个 API”不是契约。
• 数据迁移、feature flag、回滚、监控和可验证命令按风险决定是否适用；不适用时说明原因。

适用场景

• 已有相对完整的 PRD 和仓库上下文，需要拆出可并行、可合并的工程任务。
• 设计或技术规格已定，需要确认 UI、服务、存储、事件和测试之间的接口边界。
• 需求不完整，但团队需要一份条件计划，说明最小待确认项和探索顺序。
• 改动涉及公开 API、数据写入、迁移、异步任务、灰度、权限、第三方依赖或上线风险。

不适用场景

• 还没有要解决的问题、目标用户或成功标准时，先用 prd-builder 或研究流程；不要为一句口号虚构工程范围。
• 需要找入口、当前路径或可运行命令而尚未阅读仓库时，先用 codebase-onboarding。
• 已有明确改动、复现步骤和测试位置，只需执行 Issue 时，交给 issue-to-pr；不要重复做全量规划。
• 需要判断根因、复现异常或修复线上故障时，使用 bug-debugging-playbook。

输入要求

保留输入原文和来源；未提供的内容标为 [未知]，不要补造：

1. 目标、目标用户、范围、非目标、业务/合规限制和决策人。
2. 可观察验收标准，包括主路径、失败/恢复、权限、性能或数据正确性要求。
3. PRD、设计、技术规格、Issue、已有决定及其版本或可定位来源。
4. 仓库证据：已读的路径/符号/行号、测试与构建配置、接口 schema、迁移方式、部署/监控约束。
5. 交付约束：目标环境、兼容窗口、发布窗口、feature flag、数据量、依赖团队、允许命令和截止时间。

信息不足时的处理

• 需求模糊或没有验收： 输出条件计划，先列最小澄清问题、假设和不做决定的边界；只安排探索、原型或验证任务，不能承诺文件级实现。
• 未读代码库却要求精确文件： 明确拒绝给出精确路径。交付候选职责、搜索词、最小阅读顺序和停止条件；路径栏写 [未知，待仓库证据]，必要时转交 codebase-onboarding。
• 有 PRD 但缺少数据/权限/兼容信息： 标记为实施阻塞，提出 owner、最晚确认时间和可判定问题；不要以默认 schema 或权限模型补齐。
• 测试或命令未验证： 区分“仓库中发现的候选命令”和“已运行结果”。未运行命令只写计划工作目录、前提、期望信号和阻断原因，不宣称通过。
• 迁移或上线信息缺失： 按风险写出待确认的迁移、flag、回滚和监控决策；不能因为未提供而默认为无需处理。

工作流

1. 建立计划卡。 固定要支持的决定、范围、非目标、目标环境、截止时间和交付深度。
2. 过可实施性门槛。 检查目标/验收、技术边界、数据/权限、仓库证据和发布约束；将每项标为通过、条件通过或阻塞。
3. 建立证据账本。 分开 [已知]、[推测]、[未知]；每个已知结论回链到用户材料、路径/符号、schema 或命令记录。
4. 映射责任和关键路径。 仅为有证据的文件写路径与责任；无证据时写候选责任和搜索动作。串起触发、校验、业务规则、存储/外部服务、响应和失败恢复。
5. 写接口契约。 为跨任务、跨层或公开边界列出 producer、consumer、请求/事件、响应/副作用、错误、鉴权、兼容和契约测试。
6. 拆分独立任务。 每项只交付一个可审查结果，写 consumes、produces、修改责任、依赖、验收和最小测试；避免两个任务并写同一职责却没有顺序或 owner。
7. 画依赖与合并顺序。 用 DAG 或有向清单表达阻塞关系，标明可并行项、串行原因和集成检查点。
8. 选择测试层级。 将需求风险映射到单元、组件、集成、契约、端到端、迁移、性能/安全或人工验证；每层写行为、fixture/环境和失败信号。
9. 规划数据与兼容性。 对 schema、回填、双读写、保留期、幂等、隐私和旧客户端兼容性明确选择或待确认项。
10. 规划发布与恢复。 为高风险改动定义 flag 受众、默认值、扩大/停止条件、监控指标、告警 owner、回滚动作和数据修复边界。
11. 写验证与交接。 给出可运行或待运行的命令、工作目录、前提和期望结果；复核 13 项模板后交给实施者。

专业判断规则

可实施性与仓库证据

门槛	通过证据	未通过时的交付
目标与范围	用户结果、非目标、决策人	条件计划和范围澄清问题
可验收行为	主路径与失败/权限/恢复验收	验收草案，禁止承诺完成时间
技术落点	已读路径/符号、调用链或用户提供的仓库材料	搜索线索和最小阅读任务
数据与权限	schema/数据 owner/访问规则	阻塞项、owner 和确认时点
发布与运行	环境、兼容、迁移、回滚或适用性说明	风险决策卡，不默认跳过

• [已知] 必须引用可定位输入；[推测] 写出推断依据和验证动作；[未知] 写出它阻断的决定。
• 文件地图中只有 [已知] 项可使用具体路径。无仓库证据时允许“候选职责：路由注册处”或 rg 搜索词，不允许写 src/routes/...、api/... 等看似真实的路径。
• 用户提供的文件名只证明该文件存在，不自动证明其责任、调用者或修改必要性；责任仍需阅读证据。

文件、接口与任务边界

• 文件条目写“路径、当前/目标责任、证据、改动类型、拥有任务”；不要把目录树当计划。
• 每个接口至少写 I-*、类型、契约定义 owner、运行时角色、触发、consumes、produces、校验/鉴权、失败、幂等/顺序、兼容策略和契约测试。内部函数不必因形式主义成为接口；跨任务、跨进程、跨包或公开边界必须成为接口。
• 数据 schema、运行时数据流和调用 capability 不是同一个接口：schema 记录定义 owner；事件记录运行时 producer/sink；capability 记录 provider/consumer 与调用结果。capability consumes schema，不得用同一 I-* 同时代指 schema 和 capability。
• 每个 T-* 任务有一个可独立审查的主要结果，明确 consumes/produces、依赖、涉及职责、验收和测试。若任务同时改 schema、服务、UI、发布且无法分别验收，继续拆分或说明为何不可拆。
• 共享文件可由多个任务触及，但必须指定主责任任务与合并顺序；不要把冲突留给实施时猜测。前置任务验收后，其职责和产出视为冻结；后续任务只消费它，若需改变已验收契约，新增显式的修订任务而不是回头混改。

依赖、测试与验证

• 依赖使用 T-A -> T-B 表示 B 消费 A 的已验收产出，并说明是接口、schema、fixture、环境还是决策依赖；没有依赖的任务可并行。依赖图必须给出可执行的拓扑合并顺序，后续任务不得修改前置任务的既定职责。
• 测试按最小充分层级选择：纯规则优先单元，跨模块/存储优先集成，公开契约补契约测试，关键用户旅程补端到端；每个验收至少有一个验证归属。
• 验证命令必须给出工作目录、前提、命令、期望观察和状态。[未运行] 不写退出码或“通过”；只有实际运行记录才可报告结果。

迁移、发布与恢复

• 变更持久化数据、事件 schema、公开 API 或异步消费时，显式决定兼容窗口、读写顺序、回填、重试/幂等、保留与恢复；无影响也写出证据和不适用理由。
• feature flag 不是默认装饰。高影响、可分批、可关闭的用户行为适合 flag；纯内部重构或不可隔离的数据迁移要写为何不使用，以及替代恢复控制。
• 回滚包括代码、flag、数据和外部副作用的边界。不可逆迁移不能假装可一键回滚，必须定义前置备份、暂停条件和修复路径。
• 监控至少关联一个用户/系统信号、阈值或异常模式、观察窗口、owner 和触发动作；没有现成监控时写补齐任务。

输出契约

按 references/templates.md 输出 13 项，缺失信息也必须显式保留：

1. 计划卡与可实施性门槛。
2. 需求、验收、假设与开放问题账本。
3. 仓库证据与文件职责地图。
4. 目标行为与关键路径。
5. 接口契约（I-*，consumes/produces）。
6. 独立可审查任务（T-*）。
7. 依赖图、并行机会和合并顺序。
8. 测试层级与验收追溯。
9. 数据、迁移与兼容策略。
10. 发布、feature flag、回滚与监控。
11. 验证命令与人工检查。
12. 风险、阻塞项、owner 与决策时点。
13. 实施交接与完成定义。

质量门槛

• 不交付未通过可实施性门槛却写成“可直接开发”的计划。
• 不把未读仓库的候选职责写成精确文件路径，也不把用户给出的路径自动推断为正确修改点。
• 不交付缺 consumes/produces、依赖、验收或测试的任务；不以大而全任务替代独立审查边界。
• 不交付缺 producer/consumer、失败、兼容或契约测试判断的跨边界接口。
• 不以“补测试”代替测试层级、行为、环境/fixture 和预期失败信号。
• 不忽略数据、迁移、flag、回滚或监控；每项必须有方案或明确不适用理由。
• 不把建议命令写成已运行结论；交付前用 references/checklists.md 与相近示例复核。

常见失败与修正

失败	修正
PRD 很完整就立刻列实现文件	先核验仓库证据；未知时列职责、搜索线索和阅读任务。
把“新增 API”写成一个任务	写 I-* 的 producer、consumer、字段、失败、鉴权、兼容和契约测试，再拆实现任务。
一个任务同时覆盖迁移、服务、页面和上线	以可独立验收的产出拆分，并用依赖图控制顺序。
只给单元测试或只写“测试通过”	将验收映射到合适层级，并把命令和期望信号写完整。
发布计划只写“灰度上线”	补 flag 受众/默认、扩大与停止条件、监控、owner 和恢复动作。
没提迁移就默认无影响	依据 schema、事件、存储和兼容证据写不适用理由，或保留阻塞项。

参考资料

• references/usage-guide.zh.md：中文调用、准备度判断与下游交接。
• references/templates.md：13 项实施计划、接口、任务、依赖和发布模板。
• references/checklists.md：需求、证据、接口、测试、迁移和发布质量门。
• references/examples.md：完整 PRD、模糊需求、未读代码库索要路径的闭环示例。