# exec-plans/ — 执行计划与技术债

> 目录名与结构对齐 [learn-harness-engineering 的 OpenAI 高级包](https://walkinglabs.github.io/learn-harness-engineering/zh/resources/openai-advanced/)。
> 核心原则：**计划与代码一起、放在仓库里** —— 不是只存在于聊天里，也不是存在于仓库外。

## 🚨 计划类文件**必须**写在这个目录里

**这条是硬规则，踩过。** 实际发生过：实施计划被写到了 Claude Code 自己的
计划目录（`~/.claude/plans/xxx.md`，**在本仓库之外**），仓库里什么都没有 ——
换个会话接手的人看不到它，等于计划不存在。

| 做法 | 判定 |
|---|---|
| 计划写在 `harness/docs/exec-plans/active/` | ✅ 唯一正确位置 |
| 计划只写在聊天回复里 | ❌ 聊天下一次就没了 |
| 计划写在 `~/.claude/plans/`（工具自带的 plan 目录） | ❌ 仓库外，别人看不到。**工具生成的那份只算草稿**，必须落到本目录才算数 |
| 计划写在项目根目录、`src/` 下 | ❌ 污染代码目录 |

> 用 plan 类工具时：工具把草稿放在别处没关系，**收尾前必须把内容写进本目录**。

## 结构

| 位置 | 放什么 | 生命周期 |
|---|---|---|
| `active/` | 进行中的计划。一个计划一个文件 | 做完移入 `completed/` |
| `completed/` | 已完成的计划，保留作决策追溯 | 长期保留 |
| `tech-debt-tracker.md` | 技术债清单 | 持续维护 |

## 一个计划文件长什么样

不需要长，但要能让"换一个会话接手"的人看懂：

```markdown
# <计划名>

## 目标
一句话说清要达成什么、为什么现在做。

## 现状
动手前的相关事实：涉及哪些文件、当前是什么行为、有什么约束。

## 步骤
1. …

## 验证
怎么确认做成了（可执行的命令或可观察的现象）。

## 风险 / 未决
可能出问题的地方；需要谁拍板的决策。
```

事实与决策写**结论**，不要抄一遍代码。已经落地、且属于长期约束的内容，
应该从计划里**提炼进 `../architecture.md`**，计划本身只留决策过程。

## 什么时候写计划

- 改动跨多个文件 / 需要多轮会话 → **写**
- 有多个可选方案、需要先定方向 → **写**（把选项和取舍列出来）
- 单文件小修 → **不写**，直接做

> 反模式：把小改动硬撑成一个大计划，或把大改动不做计划直接开干。
> 判断标准是"换个人能不能照着继续做"。

## tech-debt-tracker.md

技术债**和功能一样列出来**：每条写清是什么、为什么先欠着、欠久了会怎样、
什么条件下该还。不要留在脑子里。

不是所有债都要马上还 —— 写下来是为了**它是有意欠的，不是忘了**。

## 机械检查

`harness/tools/validate-harness.mjs` 会校验本目录的存在性与基本形态
（见该脚本）。机械约束优先于口头约定 —— 文档写"要放这里"是不够的，
得有个命令能让违反的时候报错。