# Task Execute

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

- Skill: `312362115/task-execute` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add 312362115/task-execute`
- Raw SKILL.md: https://api.skillmd.com/api/skills/312362115/task-execute/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: 312362115 (https://skillmd.com/u/312362115)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/312362115/task-execute

---


# 持续执行框架（Task Execute）

> 灵感来源：[Anthropic - Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)

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

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

---

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

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

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

### 1. 创建启动脚本 `init.sh`

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

```bash
#!/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 同时承担功能清单和进度记录。

```markdown
# 项目进度

## 功能清单

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

## 已完成
（暂无）

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

## 已知问题
（暂无）
```

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

---

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

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

```markdown
# 会话日志

## 相关文档
- 方案设计：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. 提交并立即开始第一个功能

```bash
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** 的更新内容——改功能清单状态 + 在"已完成"区写清楚做了什么：

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

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

```markdown
### 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`：

```markdown
## 进行中
- #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 自检 + 复盘沉淀
```