---
name: writing-plans
description: "Use for milestone-scale or multi-file feature work: write an implementation plan before coding. MANDATORY for work spanning multiple modules or implementing an approved design. For small, well-bounded changes (single file, clear fix), plan inline and skip this skill."
---

# Writing Plans

## 触发边界

- **强制**: 里程碑级任务、跨多文件的新功能、实现一份已批准设计的工作。
- **自判**: 单文件小改动、明确的 bug 修复、纯文档/配置变更——不值得为它们写计划文档。

计划保存至 `research-wiki/plans/YYYY-MM-DD-<feature-name>.md`(≤1000 行)。

## 计划要写给谁

假设执行者(可能是 subagent、可能是未来的你)对本代码库零上下文。计划要交代:每个任务动哪些文件(精确路径)、验收标准是什么、怎么验证。DRY、YAGNI、频繁提交。不写计划外的重构与抽象。

## 计划必备内容

**头部**: 目标(一句话)、方案概述(2-3 句)、涉及技术。

**文件结构**: 开始拆任务前,先列出将创建/修改的文件及各自职责——分解决策在这里锁定。遵循既有架构(`ports/types/errors` 内核 + middleware/transports/backends/telemetry,见 ARCHITECTURE.md §8)。

**任务清单**: 每个任务包含:
- 精确文件路径(创建/修改/测试);
- 要实现的行为与验收标准;
- 测试要求:该任务合并前必须能出示"先失败后通过"的测试证据(见 `test-driven-development` 的结果门);
- 验证命令及预期输出(如 `conda run -n PolyGateway pytest tests/... -v` → PASS);
- 提交点(checkbox `- [ ]` 语法便于追踪)。

任务粒度以"一次提交、独立可验证"为准,不必把每个动作拆成几分钟一格的脚本步骤——执行者会自己安排动作顺序。

## No Placeholders(计划失败模式,禁止出现)

- "TBD" / "TODO" / "以后补充" / "实现细节略"
- "添加适当的错误处理 / 校验 / 边界处理"(不说清楚是什么)
- "为上文写测试"(没有说明测什么行为)
- "同 Task N"(执行者可能乱序读,关键内容要重复或明确引用)
- 引用了任何任务中都未定义的类型/函数/方法

关键接口(跨任务消费的类型、函数签名)必须在计划中写出实际代码;其余代码执行时再写。

## 保真校验(迁移类计划必做)

本库的主体工作是把 `reference/` 三项目的治理代码迁移进库。若计划涉及 ARCHITECTURE.md §1.4"关键资产索引"中列出的任何移植蓝本(治理主循环、流式看门狗、Redis+Lua 限流、跨进程熔断、错误分类、遥测等):

1. 在对应任务中标注参考文件路径,要求实现时**逐段比对参考实现**;
2. 为该任务加"保真校验"检查点:核心逻辑(条件分支、Lua 脚本语义、状态机转换、退避公式)不得被简化或悄悄改变行为——重构结构可以,改变语义必须在设计中声明过。

计划不涉及迁移时,注明"本计划不涉及参考实现迁移,保真校验不适用"。

## 审核门(保留;plan 无需人类批准)

1. **自审**: 对照 spec 逐节检查覆盖(每条需求能指到任务)、扫 placeholder、检查跨任务类型/签名一致性。发现问题就地修。
2. **Codex 审**: 用 `/codex:rescue --fresh --wait` 只读审查(设计覆盖、每步可执行性、测试证据要求是否齐全),模板见 `plan-document-reviewer-prompt.md`。意见仅供参考,逐条核验后自行决定采纳,就地修订。
3. 通过后**直接进入执行**,无需人类批准(与 design 的人类门不同)。执行方式自选:任务多且相互独立的大计划可用 `subagent-driven-development`;中小计划直接按计划实现。

## Wiki 注册(`research-wiki/` 存在时)

```bash
.claude/tools/research_wiki.py add_entity research-wiki/ --type plan --id <slug> --title "<title>"
.claude/tools/research_wiki.py add_edge research-wiki/ --from "plan:<id>" --to "design:<id>" --type implements --evidence "..."
.claude/tools/research_wiki.py rebuild_index research-wiki/
```