| 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 在离散的会话中工作，每个新会话对之前的工作没有记忆。这意味着跨越数小时甚至数天的复杂任务很容易失败。本框架解决两个核心失败模式：
- 过度雄心：试图一次性完成整个项目，在实现中途耗尽上下文，留下未记录的半成品
- 过早宣告完成：后续会话看到部分进展，错误地声称项目已完成
第一阶段：初始化会话（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 用于恢复）。
安全退出协议——感觉快到极限时：
- 停止开始新功能
- 把当前工作提交到可运行状态（宁可功能不完整，也不要代码跑不起来）
- 蒸馏 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 时：
- 全量端到端测试：走一遍所有功能的用户流程
- 回归检查：重点关注功能间的交互
- 代码清理：删除调试代码、console.log、临时文件
- 最终进度更新：标记项目完成
- 触发 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 自检 + 复盘沉淀
