按设计文档实现代码

严格按照设计文档和已有的测试用例实现功能代码。

<!-- @include templates/prompts/iron-law.md（已内联于下方，无需另读） --> ⛔ IRON LAW · 不可违反的硬门禁

以下规则为不可协商的执行约束：

1. 文件必须落盘：所有带编号（功能ID / 缺陷ID）的文档，必须作为实际文件写入磁盘，不可仅在对话中输出。
2. 阶段必须落章：每个阶段完成后必须在状态机 docs/.pdlc-state/<feature-id>.json 追加 history，不可跳过。
3. 测试必须存在：进入 /pdlc-implement 前，对应测试必须存在且处于红灯状态。违反则中止。
4. 自检必须执行：段二自检为强制步骤，不得以"已经很好了"为由跳过。
5. 防循环：段三修复为单次，不递归。无法自动修复的问题记录到报告，继续往下走。
6. 状态必推进：成功执行某 phase 后 current_stage 必须变更。收尾时若发现 current_stage 未推进，视为失败并报错，不得静默返回（防止外层循环拿滞后的状态空转烧额度）。唯一例外：命中人工点主动 block 时，current_stage 保持不变但必须写 last_phase_result.ok=false + blocked_reason。

违反任一条 = 立即中止当前命令，输出违规详情，等待人工介入。 <!-- @include-end templates/prompts/iron-law.md --> <!-- @include templates/prompts/noninteractive.md（已内联于下方，无需另读） -->

非交互模式（--autonomous）

若本命令的参数含 --autonomous，本命令进入无人值守模式，按以下规则处理原本需要人应答的交互点。参数是唯一真源：不带 --autonomous 即为交互模式，一切照旧正常询问用户；绝不回读状态机 run_mode 兜底（「掉出 autonomous」是安全的失败方向）。

1. 流程性确认（如「测试已绿是否继续」「是否覆盖已有文件」）→ 不询问，按预设默认前进，并把决策追加到状态机 history[].auto_decisions[]

（写状态机的命令：推进时给状态推进脚本传 --decision "<确认点描述>=<所选默认>"，可重复；脚本写成下面的样子）：

   { "point": "<确认点描述>", "chose": "<所选默认>", "at": "<ISO 8601>" }

1. 真需人判断（PRD 关键取舍、评审「需人工确认」项、真实循环依赖、测试与设计 / PRD 矛盾等无法安全默认的点）→ 不猜。

改测试、改检查命令让它变绿，永远不是「流程性默认」，不能记成 --decision：

• current_stage 保持不变（不推进）
• 写 last_phase_result.ok = false 且 blocked_reason = "<原因>"（写状态机的命令：给状态推进脚本传 --blocked "<原因>"）
• 末行输出哨兵：<<<PDLC blocked reason="<原因>">>>
• 立即结束命令，交还人类
• 守卫拦截也走这一条：前置守卫（缺设计文档、缺测试、测试没红等）在 --autonomous 下拦住本命令时，

不能只输出 ⛔ 就停——同样写 ok=false + blocked_reason（写明哪条守卫、缺什么）并输出哨兵。 否则状态机里仍是上一阶段的 ok=true，循环驱动只看到 current_stage 没动，会把「被拦」误报成「卡住」，真实原因丢失。

1. 破坏性操作（发布 / 部署 / 打 tag / 触发 CI / DROP / force-push 等不可逆·外发操作）→ --autonomous 无效，仍必须人工显式确认。
2. 顺手的 sidecar 产物（如缺失时创建 CHANGELOG.md、补全文档 PDLC-TRACE 的创建时间等本阶段职责内、可安全默认的辅助改动）→ 视为流程性默认，直接做并记入 `auto_decisions[]`；这类改动不新增外部副作用，不属破坏性操作。

进入 autonomous 模式时，在状态机顶层写 run_mode: "autonomous" 仅供留痕（复盘区分人工 vs 循环产出）。

<!-- @include-end templates/prompts/noninteractive.md -->

PDLC 前置守卫（不可跳过）

1. 从用户输入提取功能名称关键词
2. 按下面的规则搜索与该功能相关的测试代码：

<!-- @include templates/prompts/test-location.md（已内联于下方，无需另读） -->

测试代码在哪（布局无关的定位规则）

⚠️ 这条规则的要害：红灯守卫必须区分「项目没有测试」和「测试不在我预期的位置」。 前者才该拦；后者拦了就是误伤——真实项目的测试布局千差万别（单体 backend/tests/、 根级 tests/、Go 同包 *_test.go、Node 与源码同目录的 *.test.tsx…）， 按一份写死的路径清单去找、找不到就拦，会让 pdlc 在大量正常项目上直接卡死。

核心原则：优先问 runner，其次翻文件。 测试框架自己最清楚有哪些测试—— 让它报比我们去猜文件位置准得多，也和 pdlc「信退出码、不信目视检查」的哲学一致。 尤其测试写在源文件里的语言（见下），翻文件根本找不到。

按下列顺序定位，命中即停：

1. 项目自己的声明 + 向 runner 查询（最高优先级）

若存在 docs/00_standards/test-commands.yml，它的 unit / e2e 命令就是权威—— 项目已经明确告诉你测试怎么跑。用它去问 runner，而不是去翻目录：

查询结果为空 = 该功能没有测试（这是行为证据，比"我没找到文件"可靠得多）。

2. 测试写在源文件里的语言（必须靠内容匹配，文件名扫描无效）⭐

这类语言没有独立测试文件，只能按代码内标记搜：

⚠️ Rust 尤其要注意：单元测试几乎总在源文件的 #[cfg(test)] mod tests 里， tests/ 目录按 Cargo 约定只放集成测试。所以「tests/ 目录不存在」在 Rust 项目里 完全不能推出「没有单元测试」——照文件清单判红会稳定误伤所有 Rust 项目。

3. 常见布局约定（按项目实际技术栈挑，不要全试）

4. 文件名兜底扫描

前三步都没命中时，按文件名模式全仓搜（*test* / *spec*，排除 node_modules、 .venv、vendor、dist、build、target、.git），再按功能关键词筛。

5. 判定

• 任一步找到相关测试 → 通过，进入下一步（pdlc-implement 还需确认红灯）
• 四步走完确实找不到任何测试 → 这才是真红灯，按各命令的守卫规则中止
• 找到测试但与本功能无关 → 按「本功能无测试」处理（同样是真红灯），但报告里要说明

「项目有测试，只是没覆盖本功能」，别让用户以为项目裸奔

• 无法判定（如 runner 装不上、语言不认识）→ 不要默认放行，也不要假装找到了：

如实报「无法确认本功能是否有测试」并交还人类。「我判断不了」绝不等于「没问题」。

写测试时（pdlc-tdd）同样按本规则决定写到哪：跟随项目既有布局与惯例—— Rust 单测就写进源文件的 #[cfg(test)] mod tests，不要为了迎合某种预设结构 新造一套平行的测试目录。

<!-- @include-end templates/prompts/test-location.md -->

1. 按上述四步走完仍未找到测试代码 → 输出以下后立即中止：

   ⛔ PDLC 守卫：未找到与「<功能名>」相关的测试代码。
   实现代码前必须先编写测试（TDD）。请先运行：
   👉 /pdlc-tdd <功能描述>

1. 找到测试 → 运行测试，确认红灯（失败）。若已全绿：

• 交互模式：提示"测试已全部通过，可能代码已实现，请确认是否需要继续。"
• --autonomous 模式：视为流程性确认，默认跳过实现直接收尾（写 auto_decisions[] 留痕），current_stage 推进为 impl、next_step=pdlc-review、last_phase_result.advanced_to=review（下一阶段短名，非命令名）

1. 提取功能ID（从设计文档或 PRD），继续
2. 任务状态关联（如 docs/06_tasks/ 存在任务文件）：

• 匹配含功能ID的任务文件
• 只动类型为 `feat` / `test` 的任务（本阶段做的就是这两类；design / doc 等不归本阶段，原样不动）
• 其中 ⬜ 未开始 / 🔄 进行中的，标为 🔄，追加 <!-- 开始时间: <今日日期> -->

段一：实现代码

<!-- @include templates/prompts/batch-review.md（已内联于下方，无需另读） -->

大功能：按任务分批实现，每批做一次小评审

什么时候分批：本功能的任务清单（docs/06_tasks/<功能ID>-*-tasks.md）里有 4 个及以上 feat 任务。 少于 4 个、或没有任务清单 → 不分批，照下面的步骤一次做完，不写分批评审记录。

怎么分：按任务清单的顺序，每 2～3 个 feat 任务一批，同一模块 / 同一接口的放在同一批。每批做完下面四步再开始下一批：

1. 实现这一批，跑单测。只要这一批对应的测试转绿；后面批次的测试还是红的，正常
2. 小评审这一批的改动（只看这一批碰过的代码）：对照设计文档有没有漏掉或做偏；命名、错误处理、日志；

安全快查（拼接 SQL、未转义输出、敏感字段进日志）。能直接修的当场修一轮并重跑单测，修不了的记下来留给最终评审。 不改 tdd 写的测试——测试和设计对不上时，按状态推进规则交给人

1. 记一笔：追加到 docs/07_reviews/code/<功能ID>-<功能名>-batch-review.md，每批一节：

   ## 第 <N> 批：<任务ID>、<任务ID>
   - 单测：<通过数> / <总数>（本批对应的测试全部为绿）
   - 发现 <X> 项，当场修复 <Y> 项
   - [已修复] <问题> — <改了哪里>
   - [待最终评审] <问题> — <为什么这一步修不了>

1. 把这一批的任务标成 ✅（追加完成时间），再开始下一批

所有批次做完，再按下面的自检清单把整个功能过一遍。/pdlc-review 会读这份分批评审记录：已修过的不重复报，「待最终评审」的每一项都必须在最终结论里处理掉。 <!-- @include-end templates/prompts/batch-review.md -->

不分批时按下面的步骤一次做完；分批时第 4～6 步按批进行，第 8 步在每批结束时做。

1. 阅读设计文档：docs/02_design/ 对应子目录下的文档，逐字理解
2. 阅读测试用例：对应服务/应用下的测试代码，理解每条意图
3. 阅读编码规范：docs/00_standards/coding/（未命中 → 提示 consider /pdlc-standard add coding/<topic>）
4. 最少量实现：使所有测试通过的最小代码
5. 运行测试：确认绿灯
6. 重构优化：测试通过前提下优化代码结构
7. 更新服务 CHANGELOG：条目格式 - <简要描述>（<功能ID 或缺陷ID>）；[未发布] 里已有同一 ID 的条目就不再追加（/pdlc-ship 按 ID 去重）
8. 任务完结：第 6 步标为 🔄 的任务（仅 feat / test 类型）由 🔄 改 ✅，追加 <!-- 完成时间: <今日日期> -->

段二：自检（强制）

<!-- @include templates/prompts/self-audit.md（已内联于下方，无需另读） -->

段二：自检（强制）

重新阅读本次产出物，按质量关卡清单逐项检查。勾选已通过，标注未通过原因。

注意：自检清单的具体内容由各命令自行定义，本片段只规定结构。

段三：修复（单次，不递归）

针对自检段标注为未通过的项：

• 可自动修复：直接修复（如补缺字段、修正格式、补齐缺失段落）
• 修复后回验：再次运行自检，确认被修复项现在通过
• 无法自动修复：记录到自审报告，不再尝试，流程继续

⚠️ 单次修复原则：若一轮修复后仍有项未通过，不再递归修复，防止死循环。 <!-- @include-end templates/prompts/self-audit.md -->

实现自检清单（必须全部检查）

1. 分批评审记录（分批时）：每一批都有一节，本批任务都已标 ✅；「待最终评审」的项原样留着，交给 /pdlc-review
2. 设计偏离检查：重读设计文档，确认没有遗漏接口或功能点

• 遗漏 → 补充实现并确认测试通过
• 偏离 → 修正代码或补充设计说明

1. 编码规范快检：运行项目 lint 工具

• 可自动修复 → 直接修复
• 修复后重跑测试确认不破坏功能
• lint fix 导致失败 → 回滚并记录人工处理

1. 覆盖率验证：覆盖率达标线以项目配置为准：优先取 docs/00_standards/test-commands.yml 的 coverage 命令阈值参数（那才是强制点，退出码即判定），其次 quality-targets.yml；两者都没有时按 >= 80% 兜底。

• 不达标 → 补测试用例并确认通过

段三：修复（单次，不递归）

<!-- @include templates/prompts/loop-prevention.md（已内联于下方，无需另读） -->

防循环规则

本命令所有的自检-修复循环均受以下约束：

1. 单次检查：同一个自检清单在本次命令执行中只跑一次（起始 + 修复后验证共两次读）
2. 单次修复：发现的问题只尝试修复一轮
3. 不递归：修复后不再重新触发自检的全量重跑
4. 失败降级：无法自动修复的问题 → 记录到自审报告 → 流程继续 → 最终报告标注待人工处理

这是为了防止 agent 在"修完再查、查完再修"的往返中陷入死循环。 <!-- @include-end templates/prompts/loop-prevention.md -->

段四：更新状态机 + 交接

<!-- pdlc:meta 由 frontmatter 生成（adapters/sync_skills.py），勿手改 -->

本命令的状态机取值：阶段短名 impl（写进 history[].stage 与 last_phase_result.stage）；下一跳 pdlc-review（写进 next_step，交接时提示）。

<!-- pdlc:meta-end --> <!-- @include templates/prompts/state-update.md（已内联于下方，无需另读） -->

状态机更新（段四必须执行）

本命令完成主产出后，必须推进状态机文件 docs/.pdlc-state/<feature-id>.json。

用脚本推进，不要手写状态 JSON

bash scripts/pdlc-advance.sh <功能ID> --stage <本阶段短名> --next <下一跳命令名|null> \
  [--produced <产物路径，逗号分隔>] [--autonomous] [--decision "<确认点>=<所选默认>"]... \
  [--name <kebab-case>（状态文件还不存在时）] <项目根>

• 脚本是本 skill 自带的 scripts/pdlc-advance.sh。阶段短名与下一跳就是本命令正文里「本命令的状态机取值」那两个值；带了 --autonomous 就照传
• 检查由脚本自己跑：它按阶段调用同目录的 scripts/pdlc-checks.sh（tdd 验红灯；impl / fix / refactor 跑 unit、coverage、lint；

review 再加 e2e；e2e 只跑 e2e；文档类阶段不跑），据此判 ok、整段写入 history 与 last_phase_result， 写完调用 scripts/pdlc-state-lint.sh 体检。不要自己先写 checks，也不要挑检查项

• tdd 阶段的 --produced 必须列出写的测试文件：脚本记下它们的指纹，之后 impl / refactor / review 推进时比对
• 主动交还人类（命中人工点、评审有阻塞项、测试本身有矛盾等）→ 加 --blocked "<原因>"：脚本照跑检查、如实记录，但不推进，原因写进 blocked_reason
• /pdlc-ship 写 ship_done、/pdlc-deploy 写 deploy_done → 加 --done（只有这两个命令能用）

脚本的退出码决定怎么收尾：

退出码 3 且原因是「tdd 阶段写的测试被改动」：实现阶段不改测试。测试是否真的写错了（与设计 / PRD 矛盾），只有人能判断： - 交互模式：先把矛盾讲清楚、问人；人同意后再带 --tests-changed "<理由>" 重跑，理由记进 auto_decisions - --autonomous：没有人可问，不要改测试，带 --blocked "<矛盾在哪>" 收尾。自主模式下带 --tests-changed 脚本也不推进

>

项目开了 PDLC 护栏（docs/00_standards/pdlc-hooks.yml）时，用 Write / Edit 直接写状态文件会被拦下。

状态文件格式（读状态时参考；只有脚本跑不了时才照它手写）

{
  "feature_id": "<F/B ID>",
  "feature_name": "<kebab-case>",
  "created_at": "<首次创建时间 ISO 8601>",
  "current_stage": "<当前阶段名>",
  "run_mode": "interactive | autonomous",
  "history": [
    {
      "stage": "<阶段名>",
      "done_at": "<ISO 8601>",
      "produced": ["<相对路径 1>", "<相对路径 2>"],
      "self_audit": { "passed": <N>, "failed": <N>, "manual": <N> },
      "auto_decisions": [
        { "point": "<autonomous 下自动前进的确认点>", "chose": "<所选默认>", "at": "<ISO 8601>" }
      ]
    }
  ],
  "last_phase_result": {
    "stage": "<本次阶段名>",
    "ok": true,
    "advanced_to": "<推进到的下一阶段 | null>",
    "checks": {},
    "self_audit": { "failed": 0 },
    "blocked_reason": null,
    "run_mode": "interactive | autonomous",
    "at": "<ISO 8601>"
  },
  "relations": {
    "extends": [],
    "depends_on": [],
    "supersedes": [],
    "resolves": [],
    "conflicts_with": [],
    "relates_to": [],
    "_updated_at": "<ISO 8601 | 省略>"
  },
  "next_step": "<下一跳命令名，如 pdlc-design；若流程结束则为 null>"
}

⛔ 示例里的 "checks": {} 是「本阶段没有命令可跑」的样子，不是键名示范——键名与取值见下方 §1。

`relations` 块（RFC#6，Phase 1 可选，Phase 2 推荐）：6 个 key 对应 6 种关系类型，各为 ID 数组，存出边。其中 conflicts_with / relates_to 是对称类型，两端都要写；其余四种有向，只写在源 feature 上。拿不准时用 /pdlc-relate set 写入，它会按规则校验。旧状态文件无此块时视为全空，向后兼容。入边由 /pdlc-relate rebuild 派生到 _relations.json，不在此块手维护。

⛔ 写状态机的四条硬约束——读侧（/pdlc-status、/pdlc-retro、/pdlc-relate）会逐条体检， 违反的每一处都会出现在它们输出的最前面：

>

1. 实例里不写 `terminal_state`。skill frontmatter 的 terminal_state: 是「这个命令走完后应到达的终态名」， 不是状态字段。判终态只看 current_stage 是否以 _done 结尾。 2. `history[].stage` 写本命令的阶段短名（见本命令正文里「本命令的状态机取值」）——pdlc-implement 写 impl， 不写 implement / implementation；pdlc-prd 写 requirements，不写 prd。 3. 时间戳必须带时刻：created_at / done_at / at 一律写完整 ISO 8601（如 2026-07-28T10:40:00+08:00）。 只写日期，同一天内的阶段耗时就全部算成 0——读侧只能记「不可测」。 4. `next_step` 只写命令名或 `null`，不附说明文字（如「pdlc-ship（等评审通过）」）。 要说明原因，阻塞时写进 last_phase_result.blocked_reason。

⛔ `_done` 的含义是「已发布」，只由 `/pdlc-ship`（写 `ship_done`）与 `/pdlc-deploy`（写 `deploy_done`）写入。 其它命令的 current_stage 一律写本命令的阶段短名，走完整条链路的编排命令（/pdlc-feature）也一样—— 它收尾时 current_stage 是最后一个阶段的短名，next_step 是 pdlc-ship。

>

- 「评审通过、等待发布」就是 current_stage 为 review 且 next_step 为 pdlc-ship（/pdlc-e2e 在评审之前，它的下一跳是 pdlc-review）。 循环相关文档里说的 review_done 指的就是这个状态，不是要写进 current_stage 的值。 - 为什么：读侧判「已抵达终态」只看 current_stage 是否以 _done 结尾。评审通过就写 _done， /pdlc-ship 就分不清哪些功能已经发布过，发布说明会重复或漏收。 - 旧版本写入的 feature_done / fix_done / review_done 分不清是否已发布，/pdlc-ship 会列出来请人确认。

手写回退（仅脚本退出码 2 且无法修正时）

1. 文件不存在 → 创建文件，写入初始结构（history 为含当前阶段的数组）
2. 文件存在 → 读取 JSON，追加当前阶段到 history，更新 current_stage 和 next_step
3. 写回文件：用 jq 或等效工具保持格式化
4. 写完体检：运行 bash scripts/pdlc-state-lint.sh <项目根>，属于本功能状态文件的偏差当场改正。退出码 2（缺 jq 等）= 没体检，报告里写明「未体检」，不得当作通过。

⚠️ 若更新失败（文件损坏/权限问题），必须中止命令并在最终报告中报错。状态机不可跳过。

last_phase_result（机器可读阶段结果；脚本按下面的规则写，手写回退时照做）

顶层 last_phase_result 是循环判停的唯一真源，外层只需 jq '.last_phase_result.ok' 即可决定 继续 / 停止 / 交还人类。规则：

1. `checks` 只放真跑命令的退出码结果（scripts/pdlc-checks.sh 的 stdout 原样），键名只能是 tests_pass / coverage_pass /

lint_clean / e2e_pass（tdd 段 red_verified），值只能是布尔或 null（无法判定）。不照抄 test-commands.yml 的 unit / lint， 不写 "4 passed, 1 failed" 这类摘要。没有检查可跑的阶段（文档类阶段、项目无 test-commands.yml）→ checks: {}， 绝不因为「本阶段成功」就填 true——schema 示例里 checks 是空的，正是这个意思。

1. `self_audit` 单列：只放自检未通过数，仅供参考，不作循环判停依据。
2. `ok` 的定义：没有命中 blocked_reason，且 tdd 段 red_verified 为 true、其它阶段没有任何检查为 false（null 不拦）→ true；否则 false。
3. 命名空间：advanced_to = 下一阶段的短名，不是命令名、也不是本阶段的 `current_stage`。三者关系：stage=本阶段短名、current_stage=本阶段完成后的当前短名、advanced_to=下一阶段短名、next_step=下一跳命令名。

⛔ 短名不是「命令名去掉 `pdlc-` 前缀」——pdlc-implement 的短名是 `impl`，不是 implement。别推导，查下表：

<!-- stage-map:start -->

<!-- stage-map:end -->

next_step 为 null（终态或无后续）时 advanced_to 也是 null。

📌 本表是唯一真源，且是被断言钉住的：每行的短名必须等于该 skill 自己 frontmatter 里声明的 stage:，且任何 skill 的非 null next_step 都必须在表里有行——两个方向 都由 tests/frontmatter-check.sh 检查，所以表不会和实现各自漂移。

>

写错短名的后果与键名写错同类：消费方按契约名匹配，认不出就当没这个阶段。

1. 推进一致：ok=true 时本阶段必须真的推进了 current_stage（与第 6 条 IRON LAW 呼应）；到达终态或无后续时 advanced_to=null。ok=false（含 blocked）时 current_stage 不变、advanced_to=null、blocked_reason 写明原因。
2. `run_mode`：镜像本次调用是否带 --autonomous（带了写 autonomous，没带写 interactive）。

<!-- @include-end templates/prompts/state-update.md -->

本阶段状态机更新：收尾运行 bash scripts/pdlc-advance.sh <功能ID> --stage impl --next pdlc-review --produced <改动的源码，逗号分隔> <项目根>（带了 --autonomous 就照传）。

• 脚本自己跑 unit、coverage、lint，全部不为 `false` 才推进到 impl；红了就写 ok=false、current_stage 保持原值，

不要自己改写成 impl——那会让 current_stage 不再表示「最后一个真正完成的阶段」，外层循环的 stuck-stop 因此失效

• 不得用自检结果冒充 checks；项目没有 test-commands.yml 时脚本写 checks: {}，报告里提示建立该文件
• tdd 阶段写的测试被你改过，脚本会拒绝推进（退出码 3）。实现阶段不改测试；测试像是写错了，交互模式下先问人、人同意才带 --tests-changed，--autonomous 下带 --blocked 交还

<!-- @include templates/prompts/check-commands.md（已内联于下方，无需另读） -->

跑 check 命令：退出码的三态语义

用脚本跑，不要手写 `checks`：

bash scripts/pdlc-checks.sh --only <本阶段要的项，如 unit,lint> <项目根>

脚本是本 skill 自带的 scripts/pdlc-checks.sh。它读 docs/00_standards/test-commands.yml（唯一真源），逐条真跑，按下表映射，stdout 只有一行 JSON—— 原样写进 last_phase_result.checks，不改键名、不改值、不补不删。每条命令的退出码与输出末尾回显在 stderr，报告里引用那几行即可。脚本退出码 2（没有 yml 等）= 没有可跑的 check → checks: {}。

为什么不手写：键名、布尔类型、三态这几件事是确定性的，交给模型写，真机上同一份项目轮与轮之间就换一种错法 （键名照抄 yml 的 unit、值写成 "4 passed, 1 failed"、127 写成 false）。 环境里没有 bash 时才按下表手工映射。

脚本按退出码分三态——不是两态。这是 IRON LAW「checks 只认客观事实」在执行层的落法：

⛔ 唯一的红线是不许写 `false`：那是会误导人的虚报——它说的是"检查失败了"， 于是有人去查代码，但真正的问题是配置过期，代码可能完全没毛病。

>

省略键与 `null` 等价，两种都可以：对消费方而言无法区分（jq '.checks.lint_clean' 在两种情况下都返回 null）。null 甚至更明确——省略是歧义的（"没看"还是"看了判不出"）， null 明说"看了，判不出"。别在这上面纠结，力气花在不写 `false` 上。

>

这与「没有检查命令可跑的阶段 → checks: {}」同源。

「跑不了」＝ test-commands.yml 过期信号（顺带检测，零额外成本）

命令跑不起来，几乎总意味着这份 yml 已经跟不上项目了——脚本改名、runner 换了、 工具从依赖里移除、子项目路径调整。真实项目里这类漂移是常态（例如某前端框架升级后 移除了内置 lint 子命令，而 yml 里那条命令还在）。

由于各阶段本来就在跑这些命令，这个信号是白捡的。检测到时：

1. 在本阶段的报告里单列一条：「`test-commands.yml` 疑似过期」，写明是哪一项、

观察到什么（退出码 / 报错原文）、以及为什么判定为"跑不了"而非"没通过"。

1. 提示补救：/pdlc-test-setup --refresh（重新探测并给出 diff）。
2. 不要自作主张改 yml——本阶段的职责是干活，不是改配置；只报告，不动手。

变更方向决定自动化程度（--refresh 时适用）

更新这份 yml 等于改变"通过"的定义，所以按方向区别对待：

⚠️ 这条方向规则是防「自动修复把闸门修没了」：lint 命令坏掉时，把它留空是最省事的 "修法"，结果闸门悄悄松了、报告还是绿的——比不更新更危险。 变严可以自动，变松必须由人签字。

<!-- @include-end templates/prompts/check-commands.md -->

<!-- @include templates/prompts/handoff.md（已内联于下方，无需另读） -->

段四：交接（Handoff）

命令完成后必须输出以下格式的最终消息：

✅ <阶段名> 完成：<主要产出物路径>
📊 自检：<通过数>/<总数> 通过（若有未通过，附要点）
📦 状态快照：docs/.pdlc-state/<feature-id>.json
👉 下一步：/pdlc-<next_step>
   （如果有分叉）或 /pdlc-<alt>（条件：<选择依据>）

规则：

• 主流程命令（写状态机的命令；下一跳见正文里「本命令的状态机取值」）必须显式输出"下一步"，不可省略
• 工具型命令（Layer 3）可以没有 next_step，此时输出 👉 下一步：（本次流程结束，无后续）
• 分叉场景必须说明选择条件，例如"若需补充测试用例 → /pdlc-tdd；若测试已齐 → /pdlc-review"

<!-- @include-end templates/prompts/handoff.md -->

本命令的 handoff 输出：

✅ 实现完成，自检通过
  - 设计一致性：<✅/部分>
  - lint 检查：<✅/X 项已自动修复/X 项待人工>
  - 测试覆盖率：<XX>%
📦 状态快照：docs/.pdlc-state/<feature-id>.json
👉 下一步：/pdlc-review <feature-id>

实现目标: $ARGUMENTS