/pdlc-implement

name: pdlc-implement
description: 按设计文档和已有测试用例实现代码（带前置守卫、自检、handoff）
argument-hint: "<功能描述或功能ID>"
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
layer: 2
stage: impl
produces:
  # 跟随项目既有源码布局，不限定固定目录
  - <实现代码 · 项目既有布局>
requires:
  # 只依赖设计文档；测试的位置由 test-location.md 的规则动态定位，不硬编码路径
  - docs/02_design/
next_step: pdlc-review
terminal_state: impl_done
recommended_model: sonnet
recommended_effort: medium

按设计文档实现代码

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

<!-- @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>" }

2. **真需人判断**（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` 没动，会把「被拦」误报成「卡住」，真实原因丢失。 3. **破坏性操作**（发布 / 部署 / 打 tag / 触发 CI / DROP / force-push 等不可逆·外发操作）→ `--autonomous` **无效**，仍必须人工显式确认。 4. **顺手的 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**，而不是去翻目录：

| runner | 列出全部测试 | 只查某功能相关 | |---|---|---| | cargo (Rust) | `cargo test -- --list` | `cargo test <关键词> -- --list` | | pytest | `pytest --collect-only -q` | `pytest --collect-only -q -k <关键词>` | | go test | `go test -list '.*' ./...` | `go test -list '<关键词>' ./...` | | vitest / jest | `npx vitest list` / `--listTests` | `npx vitest list -t <关键词>` | | gradle / maven | `--tests '*'` 干跑 | `--tests '*<关键词>*'` |

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

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

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

| 语言 / 框架 | in-source 测试标记 | |---|---| | **Rust** | `#[cfg(test)]`、`#[test]`、`mod tests` | | **Vitest**（in-source testing） | `import.meta.vitest` | | **Python** doctest | docstring 里的 `>>> ` | | **Elixir** doctest | `@doc` 里的 `iex>` | | **Go**（同包但独立文件） | `*_test.go` + `func Test` |

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

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

| 生态 | 常见测试位置 | |---|---| | Python | `tests/`、`backend/tests/`、`test/`、与源码同目录的 `test_*.py` | | Node / TS | `tests/`、`__tests__/`、`src/**/__tests__/`、与源码同目录的 `*.test.ts(x)` / `*.spec.ts(x)` | | Rust | 源文件内 `#[cfg(test)]`（单测）+ `tests/`（集成测试） | | Go | 与源码同包的 `*_test.go` | | JVM | `src/test/java/`、`src/test/kotlin/` | | Ruby | `spec/`、`test/` | | 微服务 / 单体仓 | 上述任一可能出现在 `backend/`、`backend/services/<名>/`、`frontend/<应用>/` 之下 |

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 -->

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

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

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

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

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

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

段一：实现代码

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

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

**什么时候分批**：本功能的任务清单（`docs/06_tasks/<功