task-execute

用途

持续执行框架（Task Execute）用于让 Claude 在跨多轮会话的长期任务中保持高效运行。Agent 在离散的会话中工作，每个新会话对之前的工作没有记忆，跨越数小时甚至数天的复杂任务很容易失败。本框架解决两个核心失败模式：

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

主要能力

框架分为三个阶段。

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

第一次会话有两个任务：快速建立框架文件，然后立即开始第一个功能的开发。框架搭建限制在 5 次以内的工具调用（创建 init.sh + 创建 claude-progress.md + git add + git commit），完成后立即进入编码。

创建启动脚本 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

创建 claude-progress.md：根据项目是否已有文档体系选择模式。判断标准是项目中是否存在 docs/specs、docs/plans 或类似的方案/计划目录。

模式 A：完整模式（项目无现有文档体系），适用于从零开始的项目，progress.md 同时承担功能清单和进度记录，包含功能清单表格、已完成、下一步、已知问题。功能清单原则：每个功能点要足够小，能在单次会话内完成；done = 代码写完可运行，verified = 通过端到端测试验证，只有 verified 才算完成；中途接手的项目已有功能也列入清单并标记 verified（前提是亲自验证过）。

模式 B：会话日志模式（项目已有 specs/plans 等文档体系），不重复维护功能清单，只记录会话延续信息，包含相关文档路径、最近会话记录、已知问题。关键原则：不复制（功能清单、方案内容已在 specs/plans 里，只用文件路径引用）、只追加（每次会话结束追加一条记录，保留最近 5-8 条）、指向而非包含（遗留决策写"详见 docs/specs/cart.md"）。

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

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

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

会话启动例程：模式 A 依次执行 cat claude-progress.md、git log --oneline -10、bash init.sh、快速冒烟测试；模式 B 依次执行 cat claude-progress.md、按需读 docs/plans/当前模块.md、按需读 docs/specs/相关方案.md、git log --oneline -10、bash init.sh、快速冒烟测试。启动例程要快，目的是进入状态，不是做审计。

接续上次未完成的 Plan：如果 progress.md 中有遗留决策，说明上次会话中断了一个大功能，此时用 EnterPlanMode 基于遗留信息重建 Plan，标注"沿用上次决策"的部分可以简写。

单功能开发循环：选择功能 → Plan 方案设计 → 用户 approve → 实现 → 验证 → 提交 → 更新进度。

选择功能：从清单中选优先级最高的、依赖已满足的、状态为 pending 的功能。
Plan 方案设计：使用 EnterPlanMode 做方案设计。Plan 负责"这次会话怎么做"，claude-progress.md 负责"整个项目做到哪了"。简单功能（改动不超过 2-3 个文件、实现路径明确无歧义）可以跳过 Plan。
实现：每完成一个有意义的步骤就 git commit。
验证：用 Playwright/Puppeteer 或测试框架做端到端验证，绝对不能为了让测试通过而修改测试。
更新进度：每完成一个功能就立即更新 claude-progress.md 并 git commit。

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

上下文保护：Agent 没有 API 可以查"还剩多少 token"，需要依赖可观测信号主动管理。信号包括：系统压缩了早期消息（高，必须立即收尾）、已完成 2-3 个中等功能（中）、当前功能做完下一个很大（中）、对早期代码记忆模糊（高）、单次会话工具调用超过 30 次（中）。经验法则：宁可早收尾一次，也不要晚收尾。

安全退出协议：停止开始新功能；把当前工作提交到可运行状态；蒸馏 Plan 到 progress.md（只写下次会话需要但无法从代码推断的信息——设计决策、技术选型理由、未完成步骤的上下文）。绝不留下的状态：编译不通过、运行报错、数据库迁移没跑。

中途接手项目：当用户说"项目做了一半"时，先摸清现状再建框架。接手流程：阅读项目结构和技术栈 → 阅读已有代码 → git log --oneline -30 → 尝试运行项目 → 验证用户说的"已完成"功能 → 建立框架文件 → 开始第一个新功能。

第三阶段：验证与收尾

当所有功能都标记为 verified 时：全量端到端测试、回归检查、代码清理、最终进度更新、触发 task-finish 复盘。复盘重点关注：会话间的衔接是否顺畅、哪些功能的拆分粒度合适、方案设计和实际实现的偏差在哪里，可复用的经验沉淀到 memory 系统。

使用方式

评估规模：功能点 ≤ 3 个且每个改动 ≤ 5 个文件不需要此框架；功能点 > 3 个或任一功能涉及 > 5 个文件、预计需要跨 2 次以上会话、用户说"项目很大""分阶段做""长期任务"时需要此框架。
功能状态流转：pending → in-progress → done → verified。只有 verified 才算"完成"。
初始化会话的第一个功能跳过 Plan，直接编码。
冒烟测试：有测试套件跑 npm test 或等价命令；无测试套件手动验证最近修改的功能；API 项目用 curl 调 2-3 个关键接口。目标是 2 分钟内确认"已有功能没坏"。
会话结束时用模板与用户沟通，4 行以内说清楚完成、进行中、下次计划、已知问题。

适用场景

用户的任务规模较大、需要跨多个上下文窗口完成。
触发场景包括：用户提到"长期任务"、"多阶段项目"、"跨会话开发"、"大型功能开发"、"需要多次对话才能完成"等。
功能点 > 3 个，或任一功能涉及 > 5 个文件。
预计需要跨 2 次以上会话。

限制

功能点 ≤ 3 个且每个改动 ≤ 5 个文件时不需要此框架。
Agent 没有 API 可以查"还剩多少 token"，只能依赖可观测信号主动管理上下文。
本技能的具体收费、价格、平台支持等信息暂未提供。