zhaoshang_client_ui/harness/docs/exec-plans

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