Task Execute

持续执行框架（Task Execute）

灵感来源：Anthropic - Effective Harnesses for Long-Running Agents

Agent 在离散的会话中工作，每个新会话对之前的工作没有记忆。这意味着跨越数小时甚至数天的复杂任务很容易失败。本框架解决两个核心失败模式：

1. 过度雄心：试图一次性完成整个项目，在实现中途耗尽上下文，留下未记录的半成品
2. 过早宣告完成：后续会话看到部分进展，错误地声称项目已完成

第一阶段：初始化会话（Initializer）

第一次会话有两个任务：快速建立框架文件，然后立即开始第一个功能的开发。不要把整个会话都花在"准备工作"上——用户希望看到实际进展。

框架搭建限制在 5 次以内的工具调用（创建 init.sh + 创建 claude-progress.md + git add + git commit），完成后立即进入编码。

1. 创建启动脚本 init.sh

根据项目实际情况编写，包含：依赖安装、数据库迁移、服务启动、健康检查。脚本要能幂等运行（重复执行不出错）。

#!/bin/bash
set -e
npm install
npx prisma migrate dev 2>/dev/null || true
npm run dev &
# 等待服务就绪后输出确认
for i in $(seq 1 15); do
  curl -s http://localhost:3000 > /dev/null 2>&1 && echo "就绪" && exit 0
  sleep 1
done
echo "启动超时" && exit 1

2. 创建 claude-progress.md

根据项目是否已有文档体系，选择不同模式：

判断标准：项目中是否存在 docs/specs、docs/plans 或类似的方案/计划目录？

模式 A：完整模式（项目无现有文档体系）

适用于从零开始的项目，progress.md 同时承担功能清单和进度记录。

# 项目进度

## 功能清单

| # | 功能 | 优先级 | 状态 | 依赖 |
|---|------|--------|------|------|
| 1 | 用户登录页面 | high | pending | - |
| 2 | 用户注册流程 | high | pending | #1 |
| 3 | 书籍列表与搜索 | high | pending | - |

## 已完成
（暂无）

## 下一步
- #1: 用户登录页面

## 已知问题
（暂无）

功能清单原则：

• 每个功能点要足够小，能在单次会话内完成。拿不准就拆更细
• done = 代码写完可运行；verified = 通过端到端测试验证。只有 verified 才算完成
• 中途接手的项目：已有功能也列入清单，标记 verified（前提是你亲自验证过）

模式 B：会话日志模式（项目已有 specs/plans 等文档体系）

适用于已有方案文档（docs/specs）和开发计划（docs/plans）的项目。不重复维护功能清单，只记录会话延续信息。

# 会话日志

## 相关文档
- 方案设计：docs/specs/
- 开发计划：docs/plans/
- 产品文档：docs/prd/

## 最近会话

### 2026-03-14 会话 #5
- 做了：购物车 API 的数量修改和删除接口（B3）
- 状态：B3 约 80%，价格计算还没做
- 遗留决策：价格服务端算，快照价格策略（详见 docs/specs/cart.md）
- 下一步：完成 B3 价格计算，然后等设计稿确认再开前端

### 2026-03-13 会话 #4
- 做了：购物车 API 的 CRUD 基础接口（B3）
- 状态：B3 约 40%
- 下一步：数量修改 + 删除接口

## 已知问题
- 搜索接口 >1000 条时慢，需加索引（不阻塞当前任务）

模式 B 的关键原则：

• 不复制：功能清单、方案内容已在 specs/plans 里，不在 progress.md 重复。只用文件路径引用
• 只追加：每次会话结束追加一条记录，保留最近 5-8 条，更早的可以删除（git 历史里有）
• 指向而非包含：遗留决策写"详见 docs/specs/cart.md"，不把方案内容搬过来
• Agent 启动时读最近 2-3 条会话记录即可进入状态，需要方案细节时再按需读 specs/plans

3. 提交并立即开始第一个功能

git add init.sh claude-progress.md
git commit -m "chore(init): 建立长期运行框架文件"

然后直接进入第二阶段的开发循环，开始处理第一个功能。不要等到"下次会话"。

第二阶段：开发会话（Coding Agent）

会话启动例程

每次新会话开始，快速进入状态：

模式 A（完整模式）：

1. cat claude-progress.md    → 功能清单 + 上次做到哪了
2. git log --oneline -10     → 最近的变更历史
3. bash init.sh              → 启动开发环境
4. 快速冒烟测试               → 确认已有功能没坏

模式 B（会话日志模式）：

1. cat claude-progress.md          → 最近 2-3 条会话记录，快速了解上下文
2. 按需读 docs/plans/当前模块.md   → 当前阶段的开发计划和任务清单
3. 按需读 docs/specs/相关方案.md   → 当前功能涉及的设计方案
4. git log --oneline -10           → 最近的变更历史
5. bash init.sh                    → 启动开发环境
6. 快速冒烟测试                     → 确认已有功能没坏

模式 B 的步骤 2-3 是"按需"——只读当前要做的功能相关的文档，不要把所有 specs/plans 都读一遍。

启动例程要快。目的是进入状态，不是做审计。

接续上次未完成的 Plan：如果 progress.md 中有遗留决策（模式 A 在"进行中"区，模式 B 在最近的会话记录中），说明上次会话中断了一个大功能。此时用 EnterPlanMode 基于遗留信息重建 Plan——不是从零开始分析，而是在上次决策的基础上继续。Plan 中标注"沿用上次决策"的部分可以简写，只展开新增或调整的部分。

单功能开发循环

选择功能 → Plan 方案设计 → 用户 approve → 实现 → 验证 → 提交 → 更新进度

选择功能：从清单中选优先级最高的、依赖已满足的、状态为 pending 的功能。

Plan 方案设计：选定功能后，使用 EnterPlanMode 做方案设计。Plan 负责"这次会话怎么做"，claude-progress.md 负责"整个项目做到哪了"——两者职责不同，不要混淆：

• Plan（单次会话）：当前功能的实现思路、涉及哪些文件、技术决策、实施步骤
• claude-progress.md（跨会话）：功能清单、完成状态、进行中的工作、已知问题

Plan 中不需要重复 progress.md 里已有的项目全景信息，只聚焦当前功能的实现方案。用户 approve 后再开始编码。

简单功能可以跳过 Plan：如果功能很小（改动不超过 2-3 个文件、实现路径明确无歧义），可以直接编码，不需要走 Plan 流程。

实现：每完成一个有意义的步骤就 git commit。好处——出错可回退，后续会话有细粒度历史。

验证：不能只靠"代码看起来对"。用 Playwright/Puppeteer 或测试框架做端到端验证。绝对不能为了让测试通过而修改测试——这会掩盖真实问题，让后续会话在错误前提上继续。

更新进度：每完成一个功能就立即更新 claude-progress.md 并 git commit，不要攒到最后一起更新。原因：你不知道什么时候会中断，攒着更新 = 中断时丢失进度记录。

模式 A 的更新内容——改功能清单状态 + 在"已完成"区写清楚做了什么：

## 已完成
- #1: 用户登录页面 — commit abc1234
  - 登录表单 + 客户端验证 + 对接 /api/auth/login
  - 已通过 Playwright 端到端验证

模式 B 的更新内容——在"最近会话"区追加一条记录：

### 2026-03-14 会话 #5
- 做了：购物车 API 的数量修改和删除接口（B3）
- 状态：B3 约 80%，价格计算还没做
- 遗留决策：价格服务端算（详见 docs/specs/cart.md 第 3 节）
- 下一步：完成 B3 价格计算

两种模式的共同目标：让下一个会话能在 30 秒内理解现状。写具体的事实，不写模糊的总结。

子任务的 task-start / task-finish 衔接

在开发循环中，每个子任务可按需触发工作流中的其他 skill：

• 开始新子任务时：如果子任务有模糊点或涉及 3+ 文件，触发 task-start 进行需求对焦和方案设计
• 子任务完成时：触发 task-finish 进行 CR 自检。大任务全部完成时执行完整复盘

上下文保护：知道什么时候该停

Agent 没有 API 可以查"还剩多少 token"，所以需要依赖可观测的信号主动管理。

具体信号——出现以下任一情况时，准备收尾：

经验法则：宁可早收尾一次（代价：多一次会话启动的 2 分钟），也不要晚收尾（代价：半成品 + 下次会话大量 token 用于恢复）。

安全退出协议——感觉快到极限时：

1. 停止开始新功能
2. 把当前工作提交到可运行状态（宁可功能不完整，也不要代码跑不起来）
3. 蒸馏 Plan 到 progress.md：Plan 是会话级的，下次会话看不到。退出前必须把 Plan 中未执行的关键信息写入 claude-progress.md：

## 进行中
- #5: 购物车（约 60%）
  - ✅ 数据模型和 API
  - ✅ 添加/删除商品
  - ❌ 数量修改（API 已写好，前端待对接，参考 /api/cart/items/[id]）
  - ❌ 价格计算（需考虑优惠券，目前按百分比折扣实现）

### 上次 Plan 遗留的设计决策
- 购物车价格计算采用"先算原价再减折扣"策略，不是"逐项折扣"
- 优惠券模型已建好（见 prisma/schema.prisma），支持百分比和固定金额两种
- 前端购物车组件计划用 /components/Cart.tsx，复用已有的 ProductCard 样式

蒸馏的原则：只写下次会话需要但无法从代码推断的信息——设计决策、技术选型理由、未完成步骤的上下文。代码里能看到的实现细节不需要重复写。

下次会话读到这些信息后，可以快速重建 Plan 继续推进，而不是从头分析"为什么这样设计"。

绝不留下的状态：编译不通过、运行报错、数据库迁移没跑。下一个会话的第一件事是 bash init.sh，如果这都失败了，大量 token 会浪费在调试环境上。

中途接手项目

当用户说"项目做了一半"时，初始化流程需要调整——先摸清现状，再建框架。

接手流程

1. 阅读项目结构和技术栈          → ls, package.json, 核心目录
2. 阅读已有代码                 → 理解架构模式、命名规范、错误处理方式
3. git log --oneline -30        → 了解开发历史
4. 尝试运行项目                 → 确认能跑起来
5. 验证用户说的"已完成"功能      → 不能假设，要亲自验
6. 建立框架文件                 → init.sh + claude-progress.md
7. 开始第一个新功能

关键区别：

• 已有功能要列入清单并标记 verified（但前提是你真的验证了）
• init.sh 要根据项目实际情况编写，不是套模板
• 新代码必须与已有代码保持风格一致——阅读代码时注意记录规范