er-s-an/long-task-agent

长任务双 Agent 管理

基于 Anthropic 官方 claude-quickstarts/autonomous-coding 实现，采用双 agent 模式（Initializer + Coding Agent）进行长周期软件开发。

核心架构

┌─────────────────────────────────────────────────────────────────┐
│                    长任务双 Agent 模式                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   Session 1          Session 2+          Session N              │
│   ┌──────────┐       ┌──────────┐       ┌──────────┐           │
│   │ Initializer      │ Coding   │       │ Coding   │           │
│   │ Agent            │ Agent    │  ...  │ Agent    │           │
│   │ (Initializer)    │ (Coding) │       │ (Coding) │           │
│   └────┬─────┘       └────┬─────┘       └────┬─────┘           │
│        │                  │                  │                 │
│        ▼                  ▼                  ▼                 │
│   ┌──────────────────────────────────────────────────────┐     │
│   │ 共享状态文件 (Source of Truth)                        │     │
│   │ • feature_list.json - 功能清单 (200+ 测试用例)        │     │
│   │ • app_spec.txt      - 项目规格说明                    │     │
│   │ • claude-progress.txt - 进度日志和交接笔记            │     │
│   │ • init.sh           - 环境启动脚本                    │     │
│   │ • git commits       - 代码状态                        │     │
│   └──────────────────────────────────────────────────────┘     │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

角色分工

Initializer Agent（Session 1 专属）

启动协议（必须执行）：

# 1. 读取项目规格
cat app_spec.txt

# 2. 创建功能清单 (200+ 详细测试用例)
# feature_list.json - 唯一真相源

# 3. 创建环境脚本
# init.sh

# 4. 初始化 git
# 首次提交

核心职责：

1. 创建 feature_list.json - 200+ 详细端到端测试用例

   • category: "functional" | "style"
   • description: 功能描述
   • steps: 测试步骤（2-15 步）
   • passes: false（初始状态）

2. 创建 init.sh - 环境启动脚本

3. 初始化 git - 首次提交包含：

   • feature_list.json
   • init.sh
   • README.md

4. 创建项目结构 - 基于 app_spec.txt

关键约束：

• 功能清单一旦创建，永不修改（只能改 passes 字段）
• 功能按优先级排序（基础功能优先）
• 至少 25 个测试必须有 10+ 步骤

Coding Agent（Session 2+）

启动协议（每个 session 必须执行）：

# 1. 获取方位
pwd && ls -la

# 2. 读取规格
cat app_spec.txt

# 3. 查看功能清单
cat feature_list.json | head -50

# 4. 读取进度笔记
cat claude-progress.txt

# 5. 检查 git 历史
git log --oneline -20

# 6. 统计剩余任务
cat feature_list.json | grep '"passes": false' | wc -l

核心职责：

1. 启动环境 - 运行 ./init.sh

2. 验证测试（关键！） - 运行 1-2 个已标记 passes: true 的核心测试，确保没有回归

3. 选择功能 - 找到最高优先级的 passes: false 功能

4. 实现功能 - 一次只做一个功能

5. 浏览器自动化验证 - 通过真实 UI 测试（截图验证）

6. 更新 feature_list.json - 只改 passes: false → true

7. 提交 git - 描述性提交信息

8. 更新 claude-progress.txt - 记录完成内容和下一步

关键约束：

• 一次只做一件事
• 必须通过浏览器自动化验证（截图）
• 修复回归问题优先于新功能
• 只能修改 passes 字段，不能删改测试

文件格式规范

app_spec.txt（项目规格）

# 项目名称

## 概述
简要描述项目目标和核心功能。

## 技术栈
- 前端: React + TypeScript + Tailwind
- 后端: Node.js + Express
- 数据库: PostgreSQL + Prisma

## 核心功能
1. 用户认证（登录/注册/找回密码）
2. 仪表盘（数据可视化）
3. 设置页面

## 设计要求
- 深色主题
- 响应式布局
- 现代化 UI

## 交付标准
- 零控制台错误
- 所有功能通过 UI 测试
- 生产级代码质量

feature_list.json（功能清单）

[
  {
    "category": "functional",
    "description": "用户可以通过邮箱和密码登录",
    "steps": [
      "Step 1: 打开登录页面",
      "Step 2: 输入有效邮箱地址",
      "Step 3: 输入密码",
      "Step 4: 点击登录按钮",
      "Step 5: 验证跳转到仪表盘"
    ],
    "passes": false
  },
  {
    "category": "style",
    "description": "登录页面视觉设计符合规范",
    "steps": [
      "Step 1: 打开登录页面",
      "Step 2: 截图验证布局",
      "Step 3: 检查颜色对比度",
      "Step 4: 验证字体大小"
    ],
    "passes": false
  }
]

约束：

• 最少 200 个功能（演示可减少到 20-50）
• functional 和 style 类别混合
• 步骤数：2-5 步（简单）+ 10+ 步（复杂，至少 25 个）
• 按优先级排序
• 只能修改 passes 字段

claude-progress.txt（进度日志）

# 任务进度日志

## 项目信息
- 项目名称: xxx
- 开始时间: 2026-02-17
- 当前 session: 3

## 已完成

### Session 1 (2026-02-17) - Initializer
- ✅ 创建 feature_list.json (200 个测试用例)
- ✅ 创建 init.sh 脚本
- ✅ 初始化 git 仓库
- ✅ 搭建项目结构

### Session 2 (2026-02-17)
- ✅ 实现用户登录功能 (#1)
  - 通过浏览器自动化验证
  - 截图保存在 verification/session2/
- ✅ 实现注册功能 (#2)

### Session 3 (2026-02-18) - 当前
- 🔄 实现仪表盘页面 (#3)
  - 已完成: 布局框架
  - 待完成: 数据图表组件

## 统计
- 总功能: 200
- 已完成: 2
- 进行中: 1
- 待办: 197
- 进度: 1%

## Session 交接笔记

### 当前状态
- 分支: main
- 最后提交: a1b2c3d - "实现注册功能 - 通过端到端测试"
- 未提交更改: 无
- 服务状态: 运行中 (npm run dev)

### 回归测试结果
- ✅ 登录功能 (test #1) - 通过
- ✅ 注册功能 (test #2) - 通过

### 发现的问题
- 登录页面在移动端有布局问题（已记录为 #45）

### 下个 session 建议
1. 完成仪表盘数据图表 (#3)
2. 修复移动端登录页面问题 (#45)
3. 优先实现核心功能，UI 优化延后

### 命令备忘
```bash
# 启动开发服务器
npm run dev

# 运行测试
npm test

# 数据库重置
npx prisma migrate reset

### init.sh（环境启动脚本）

```bash
#!/bin/bash
set -e

echo "🚀 启动开发环境..."

# 安装依赖
echo "📦 安装依赖..."
npm install

# 数据库设置（如需要）
# echo "🗄️ 设置数据库..."
# npx prisma migrate dev

# 启动开发服务器
echo "🔥 启动开发服务器..."
npm run dev &

# 等待服务器启动
sleep 5

echo "✅ 环境已启动！"
echo ""
echo "🌐 应用地址: http://localhost:3000"
echo "📁 项目目录: $(pwd)"
echo ""
echo "常用命令:"
echo "  npm run dev     - 启动开发服务器"
echo "  npm run build   - 构建生产版本"
echo "  npm test        - 运行测试"

工作流程

Phase 1: 初始化（Initializer Agent）

# 1. 创建项目目录
mkdir -p projects/my-project
cd projects/my-project

# 2. 创建 app_spec.txt
cat > app_spec.txt << 'EOF'
[项目规格内容]
EOF

# 3. 运行 Initializer
/long-task-agent init

# 4. Initializer 执行：
#    - 读取 app_spec.txt
#    - 创建 feature_list.json (200 个测试)
#    - 创建 init.sh
#    - git init + 首次提交
#    - 创建 claude-progress.txt

Phase 2: 增量开发（Coding Agent）

# 每个 session 开始：
/long-task-agent resume

# 自动执行启动协议：
# 1. 获取方位 (pwd, ls)
# 2. 读取 app_spec.txt
# 3. 读取 feature_list.json
# 4. 读取 claude-progress.txt
# 5. 检查 git log
# 6. 统计剩余任务

# 然后执行：
# 1. 启动环境 (./init.sh)
# 2. 验证测试（运行 1-2 个已完成功能）
# 3. 选择下一个功能
# 4. 实现功能
# 5. 浏览器自动化验证（截图）
# 6. 更新 feature_list.json
# 7. 提交 git
# 8. 更新 claude-progress.txt

Phase 3: 跨 Session 恢复

# 新 session 开始
/long-task-agent resume

# 自动读取所有状态文件
# 无缝继续上次的进度

关键机制

1. 启动协议（Startup Protocol）

每个 Coding Agent session 必须首先执行：

# 获取方位
pwd && ls -la

# 读取规格
 cat app_spec.txt

# 查看功能清单
cat feature_list.json

# 读取进度笔记
cat claude-progress.txt

# 检查 git 历史
git log --oneline -20

目的： 因为每个 session 都是全新的上下文窗口，必须通过文件重新获取所有状态。

2. 验证测试（Verification Test）

关键规则： 实现新功能前，必须先验证已有功能是否仍然工作。

# 运行 1-2 个核心已完成功能的测试
# 如果发现回归问题：
# 1. 立即标记为 passes: false
# 2. 修复问题
# 3. 然后再进行新功能

3. 浏览器自动化验证

必须通过真实 UI 测试，不能只用 curl：

// 使用 Puppeteer/Playwright
// 1. 导航到页面
// 2. 点击、输入、滚动
// 3. 截图验证
// 4. 检查控制台错误

禁止：

• 只用 curl 测试后端
• 用 JavaScript 绕过 UI
• 跳过视觉验证

4. 单功能聚焦

一次只做一件事：

• 选择一个功能
• 完整实现 + 测试
• 标记 passes: true
• 提交 git
• 再开始下一个

5. 干净状态交接

每个 session 结束必须：

• 所有工作已提交
• 没有未提交的更改
• 应用处于可运行状态
• claude-progress.txt 已更新

命令参考

| 命令 | 作用 | |------|------| | /long-task-agent init | 初始化长任务（Initializer 角色） | | /long-task-agent resume | 恢复任务状态（Coding Agent 角色） | | /long-task-agent status | 查看当前状态 | | /long-task-agent next | 获取下一个待办功能 | | /long-task-agent checkpoint "msg" | 记录检查点 | | /long-task-agent verify | 运行回归测试 |

使用场景

场景 1: 从零开始构建应用

Day 1 (Initializer): 创建规格、功能清单、项目结构
Day 2-10 (Coding):   每天一个 session，实现 2-5 个功能
Day 11+ (Coding):    继续直到所有 200 个功能完成

场景 2: 复杂功能开发

Initializer: 将复杂功能拆分为 200 个小测试
Coding Session 1: 实现功能 1-3，验证通过
Coding Session 2: 实现功能 4-6，验证通过
...

场景 3: 中断恢复

Session 1: 开发了 3 小时，临时中断
Session 2: 运行 resume，读取状态，无缝继续

最佳实践

Initializer 阶段

• 充分规划，避免后期大改
• 功能粒度适中（2-4 小时/个）
• 预留缓冲时间
• 创建详细的测试步骤

Coding 阶段

• 严格遵守"启动协议"
• 先验证回归，再做新功能
• 必须通过浏览器自动化验证
• 及时更新进度日志

交接规范

• 每次结束必须写交接笔记
• 记录命令备忘
• 标记已知问题
• 明确下一步优先级

与 NanoBot 协作

Initializer (Claude)
  ↓
创建 app_spec.txt → 发送给 NanoBot 确认
  ↓
创建 feature_list.json → 发送给 NanoBot 备份
  ↓
Coding (Claude)
  ↓
每个 session 结束 → 发送进度截图给 NanoBot
  ↓
发现重要问题 → 发送通知给 NanoBot
  ↓
功能完成 → 发送演示截图给 NanoBot

来源

基于 Anthropic 官方实现：

• 仓库: anthropics/claude-quickstarts/autonomous-coding
• 核心文件:
  • autonomous_agent_demo.py - 主入口
  • agent.py - Agent 会话逻辑
  • prompts/initializer_prompt.md - Initializer 提示词
  • prompts/coding_prompt.md - Coding Agent 提示词
• 文章: Anthropic 解决长运行 Agent 问题