Files

T

iomgaa 3058f4c744 chore: bootstrap project scaffolding

Add architecture doc (research-wiki/ARCHITECTURE.md), CLAUDE.md with
tiered SOP for Fable 5, adapted .claude skills/hooks/settings, package
skeleton (src/polygateway), pyproject with import-linter contracts,
Makefile, .env.example and smoke test.

2026-07-20 00:49:10 -04:00

4.0 KiB

Raw Blame History

name, description

name	description
writing-plans	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 限流、跨进程熔断、错误分类、遥测等):

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

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

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

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

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

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

4.0 KiB Raw Blame History