README.md 3.0 KB
exec-plans/ — 执行计划与技术债
目录名与结构对齐 learn-harness-engineering 的 OpenAI 高级包。 核心原则：计划与代码一起、放在仓库里 —— 不是只存在于聊天里，也不是存在于仓库外。
🚨 计划类文件必须写在这个目录里
这条是硬规则，踩过。 实际发生过：实施计划被写到了 Claude Code 自己的
计划目录（~/.claude/plans/xxx.md，在本仓库之外），仓库里什么都没有 ——
换个会话接手的人看不到它，等于计划不存在。
| 做法 | 判定 |
|---|---|
计划写在 harness/docs/exec-plans/active/ |
✅ 唯一正确位置 |
| 计划只写在聊天回复里 | ❌ 聊天下一次就没了 |
计划写在 ~/.claude/plans/（工具自带的 plan 目录） |
❌ 仓库外，别人看不到。工具生成的那份只算草稿，必须落到本目录才算数 |
计划写在项目根目录、src/ 下 |
❌ 污染代码目录 |
用 plan 类工具时：工具把草稿放在别处没关系，收尾前必须把内容写进本目录。
结构
| 位置 | 放什么 | 生命周期 |
|---|---|---|
active/ |
进行中的计划。一个计划一个文件 | 做完移入 completed/ |
completed/ |
已完成的计划，保留作决策追溯 | 长期保留 |
tech-debt-tracker.md |
技术债清单 | 持续维护 |
一个计划文件长什么样
不需要长，但要能让"换一个会话接手"的人看懂：
# <计划名>
## 目标
一句话说清要达成什么、为什么现在做。
## 现状
动手前的相关事实：涉及哪些文件、当前是什么行为、有什么约束。
## 步骤
1. …
## 验证
怎么确认做成了（可执行的命令或可观察的现象）。
## 风险 / 未决
可能出问题的地方；需要谁拍板的决策。
事实与决策写结论，不要抄一遍代码。已经落地、且属于长期约束的内容，
应该从计划里提炼进 ../architecture.md，计划本身只留决策过程。
什么时候写计划
- 改动跨多个文件 / 需要多轮会话 → 写
- 有多个可选方案、需要先定方向 → 写（把选项和取舍列出来）
- 单文件小修 → 不写，直接做
反模式：把小改动硬撑成一个大计划，或把大改动不做计划直接开干。 判断标准是"换个人能不能照着继续做"。
tech-debt-tracker.md
技术债和功能一样列出来：每条写清是什么、为什么先欠着、欠久了会怎样、 什么条件下该还。不要留在脑子里。
不是所有债都要马上还 —— 写下来是为了它是有意欠的，不是忘了。
机械检查
harness/tools/validate-harness.mjs 会校验本目录的存在性与基本形态
（见该脚本）。机械约束优先于口头约定 —— 文档写"要放这里"是不够的，
得有个命令能让违反的时候报错。