structured-project-execution

结构化项目执行

围绕磁盘上的单一事实来源开展大型工作，确保进度在上下文丢失、会话结束和 Agent 交接后仍能保留。执行原则：规划 → 同一时间只推进一个任务 → 验证 → 记录 → 重复。

适用场景

多阶段功能、迁移，以及任何跨越多个会话或可能由其他 Agent／人员接手的工作。单次即可完成的任务无需使用——记录工作所花的精力比节省的更多。

执行文件

在仓库根目录维护 PROGRESS.md（或遵循项目惯例）：

# <Project> — Progress

## Goal
<one paragraph: what done looks like>

## Plan
- [x] Phase 1: <deliverable> — verified by <check>
- [ ] Phase 2: <deliverable> — verified by <check>
- [ ] Phase 3: ...

## Now
<the single task currently in flight>

## Decisions
- <date>: chose X over Y because <reason>

## Blocked / Open
- <question or blocker, with what's needed to unblock>

此文件就是约定。将更新作为工作的一部分，而不是事后补上。

循环

1. 规划 — 拆分为多个阶段，每个阶段都以可验证的交付成果收尾。优先处理风险最高的阶段。
2. 选定一个 — ## Now 中恰好有一个任务。不要并行推进多个未完成的工作；上下文重置后，它们无法延续。
3. 执行 — 实现满足该阶段要求的最小切片。
4. 验证 — 运行阶段中注明的检查（测试、构建、手动复现）。不是“看起来完成了”，而是检查确实通过。
5. 记录 — 勾选复选框，清空 ## Now，记录任何决策或新阻碍。保持状态可供提交。
6. 从计划中重复上述流程；如果实际情况有出入，就重新规划。

恢复工作（新会话／交接）

先阅读 PROGRESS.md。## Now 和最后一个未勾选的复选框会明确指出应从哪里继续。如果 ## Now 不为空，说明该任务在执行中被中断——继续前先重新验证其状态（任务可能只完成了一部分）。

质量标准

• 任何人都能仅凭 PROGRESS.md 恢复工作，无需查看聊天记录。
• 每个已勾选的复选框都经过其注明的检查验证，而非凭假定勾选。
• 任意时刻最多只有一个进行中的任务。
• 记录决策及其原因，避免反复讨论。

反模式

• 只在聊天中规划——上下文重置后内容就会消失，也无法用于交接。
• 未运行验证就标记阶段完成。
• 同时有五个阶段处于“进行中” → 中断后状态将无法恢复。
• 因为没有记录原因，而重新推导过去已经做过的决策。
• 说“稍后”再更新 PROGRESS.md——等到稍后，上下文可能已经消失。