task-execute

name	task-execute
version	1.0.0
last_updated	"2026-03-20T00:00:00.000Z"
repository	https://github.com/312362115/claude
changelog	skills/task-execute/CHANGELOG.md
description	持续执行框架：让 Claude 在跨多轮会话的长期任务中保持高效运行。当用户的任务规模较大、需要跨多个上下文窗口完成时使用此技能。 触发场景包括：用户提到"长期任务"、"多阶段项目"、"跨会话开发"、"大型功能开发"、"需要多次对话才能完成"， 或任何明显超出单次上下文窗口能力范围的复杂工程任务。即使用户没有明确提到"长期运行"， 只要任务复杂度高、涉及多个功能模块、预计需要大量代码变更，都应该触发此技能。 工作流位置：task-start → task-execute → task-finish

持续执行框架（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"，所以需要依赖可观测的信号主动管理。

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

信号	怎么判断	紧急程度
系统压缩了早期消息	Claude Code 会自动压缩对话历史，你会发现早期细节变模糊	高——必须立即收尾
已完成 2-3 个中等功能	数一下本次会话完成了几个功能	中——完成当前功能后收尾
当前功能做完，下一个很大	看清单里下一个功能的复杂度	中——不要开始，留给下次
你开始对早期代码记忆模糊	需要重新读之前改过的文件才能想起来	高——说明上下文已被压缩
单次会话工具调用超过 30 次	大致估算你调用了多少次工具	中——开始关注，准备收尾

经验法则：宁可早收尾一次（代价：多一次会话启动的 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 要根据项目实际情况编写，不是套模板
• 新代码必须与已有代码保持风格一致——阅读代码时注意记录规范

---

第三阶段：验证与收尾

当所有功能都标记为 verified 时：

1. 全量端到端测试：走一遍所有功能的用户流程
2. 回归检查：重点关注功能间的交互
3. 代码清理：删除调试代码、console.log、临时文件
4. 最终进度更新：标记项目完成
5. 触发 task-finish 复盘：使用 task-finish skill 的复盘流程执行。跨多会话的长期项目是典型的"大任务"，必须复盘。重点关注：
   • 会话间的衔接是否顺畅？progress.md 的信息够不够？
   • 哪些功能的拆分粒度合适？哪些拆大了或拆小了？
   • 方案设计和实际实现的偏差在哪里？
   • 可复用的经验沉淀到 memory 系统（feedback 或 project 类型）

---

失败模式速查表

问题	根因	对策
过早宣告完成	没有功能清单对照	会话开始必读 claude-progress.md
代码有 bug 但标记完成	没做端到端验证	verified = 测试通过，不是"我觉得写完了"
上下文耗尽留下半成品	没有主动管理上下文	检测信号 + 安全退出协议
后续会话不知从何开始	进度记录太模糊	写具体事实：做了什么、commit hash、下一步
环境配置浪费 token	每次重新摸索	init.sh 一键启动
新代码风格不一致	没读已有代码就动手	中途接手流程的第 2 步
复杂功能实现方向跑偏	没做方案设计就动手	用 task-start 对焦 + Plan 对齐方案
Plan 和 progress.md 内容重复	职责不清	Plan = 当前会话怎么做；progress = 项目做到哪了

---

使用指南

1. 评估规模：要不要启用此框架？

条件（满足任一）	判断
功能点 ≤ 3 个，且每个改动 ≤ 5 个文件	不需要，直接做
功能点 > 3 个，或任一功能涉及 > 5 个文件	需要此框架
预计需要跨 2 次以上会话	需要此框架
用户说"项目很大"、"分阶段做"、"长期任务"	需要此框架

2. 功能状态流转

pending → in-progress → done → verified

状态	含义	转换条件
pending	未开始	初始状态
in-progress	正在做	开始编码时标记
done	代码写完	代码可运行、已 commit
verified	验证通过	通过端到端测试或手动验证完整用户流程

只有 verified 才算"完成"。done 意味着还需要在后续会话中验证。

3. 初始化会话的第一个功能

初始化会话选择的第一个功能跳过 Plan，直接编码。原因：初始化阶段已经对项目有了全面了解，第一个功能通常是基础功能（如项目脚手架、数据模型），路径明确。从第二个功能开始，根据复杂度判断是否走 Plan。

4. 冒烟测试具体做什么

启动例程第 4 步"快速冒烟测试"的具体操作：

• 有测试套件：npm test 或等价命令，跑全量测试。如果超过 2 分钟，只跑与最近 commit 相关的测试
• 无测试套件：手动验证最近修改的功能——打开页面、点击核心路径、确认无报错
• API 项目：用 curl 调 2-3 个关键接口，确认返回正常

目标是 2 分钟内确认"已有功能没坏"，不是做全面回归。

5. 会话结束时告诉用户什么

每次会话结束（不管是正常收尾还是安全退出），都用以下模板与用户沟通：

## 本次会话总结
- 完成：#1 用户登录、#2 用户注册
- 进行中：#3 书籍搜索（约 70%，API 完成，前端待对接）
- 下次会话计划：完成 #3 剩余部分，然后开始 #4 购物车
- 已知问题：搜索分页超过 100 条时性能下降，需要加索引

不需要长篇大论，4 行以内说清楚。

---

与其他 skill 的衔接

task-start — 启动：对焦需求 + 设计方案
  │
  ↓
task-execute（本 skill）— 执行：持续编码 + 跨会话进度管理
  │
  ├─ 子任务开始 → 按需触发 task-start（需求模糊或 3+ 文件时）
  ├─ 子任务完成 → 触发 task-finish 的 CR 自检
  ├─ 全部完成 → 触发 task-finish 的完整复盘
  │
  ↓
task-finish — 收尾：CR 自检 + 复盘沉淀