Claude Agent 长时间运行实践指南

参考来源：

Effective Harnesses for Long-Running Agents - Anthropic Engineering

基于 Anthropic 工程团队的实践经验，这份指南总结了如何构建能够跨多个对话会话持续工作的 AI 代理系统。

一、核心问题

AI 代理在长时间项目中面临"失忆症轮班工人"困境：每次新会话开始时，代理都缺乏之前工作的记忆，必须重新理解项目状态，导致效率低下和重复劳动。

二、双代理架构方案

1. 初始化代理（Initializer Agent）

第一个会话负责建立基础设施：

创建 init.sh 脚本用于快速启动开发环境
创建 claude-progress.txt 文件记录代理工作日志
提交初始 Git 记录，标记已添加的文件

2. 编码代理（Coding Agent）

后续会话遵循结构化流程，进行增量开发并保持代码质量。

三、关键实施策略

策略 1：功能列表管理（Feature List Management）

最佳实践：

使用 JSON 格式而非 Markdown 管理功能列表
为复杂项目创建包含 200+ 功能的详细规范文件
每个功能包含详细规格说明和 "passes" 状态字段
约束代理仅修改状态，不允许删除或重写功能项

为什么选择 JSON？ JSON 的结构化特性比 Markdown 更能防止代理擅自修改或删除功能项。

示例结构：

json 复制代码

{
  "features": [
    {
      "id": "feat-001",
      "name": "用户登录功能",
      "description": "实现用户通过邮箱和密码登录",
      "passes": false,
      "priority": "high"
    }
  ]
}

策略 2：增量式进度（Incremental Progress）

工作原则：

每个会话只完成一个功能
使用详细的 Git commit 消息
每次提交包含进度摘要
启用回滚能力
帮助未来会话快速理解最近变更

Git commit 最佳实践：

bash 复制代码

git commit -m "feat: 实现用户登录功能

- 添加登录表单验证
- 集成身份验证 API
- 添加错误处理和用户反馈
- 更新 claude-progress.txt：完成 feat-001"

策略 3：严格的测试验证（Rigorous Testing）

核心要求：

端到端测试优先于单元测试
使用浏览器自动化工具（如 Puppeteer MCP）模拟真实用户交互
单元测试无法发现的真实场景问题必须通过端到端测试发现
代理必须自我验证功能后才能标记为完成

测试流程：

代码实现完成
运行自动化端到端测试
验证所有用户流程正常
修复发现的问题
更新功能状态为 "passes": true

策略 4：标准化启动例程（Startup Routine）

每个会话开始时必须执行：

markdown 复制代码

1. 确认工作目录
   - 运行 `pwd` 确认位置
   - 检查必要文件是否存在

2. 读取上下文信息
   - 查看 `claude-progress.txt` 了解历史工作
   - 运行 `git log --oneline -10` 查看最近提交
   - 读取功能列表 JSON 文件

3. 选择优先级最高的未完成功能
   - 在 JSON 中找到 `"passes": false` 的项
   - 按 `priority` 字段排序

4. 运行基础端到端验证
   - 执行 `init.sh` 启动环境
   - 运行冒烟测试确保系统可用

四、常见失败模式及预防方案

失败模式	预防措施
过早宣告项目完成	使用带明确状态跟踪的功能列表
代码质量低或缺少文档	强制要求会话结束前提交 Git + 更新进度文件
功能未真正完成就标记	强制要求自我验证后才能更新状态
浪费时间理解环境配置	预先编写 `init.sh` 脚本
上下文丢失导致重复工作	结构化进度日志 + Git 历史记录

五、实施检查清单

项目初始化阶段

创建 init.sh 环境启动脚本
创建 claude-progress.txt 工作日志
创建 features.json 功能列表
提交初始 Git 记录

每个工作会话

运行启动例程（确认目录、读取上下文）
选择单个优先级最高的功能
实施功能代码
运行端到端测试验证
更新 claude-progress.txt
提交 Git 并附带详细消息
更新 features.json 状态

质量门控

所有功能必须通过端到端测试
每次修改必须有 Git 提交记录
进度文件必须保持最新
功能列表状态准确反映实际情况

六、进阶技巧

1. 多代理架构探索

考虑将职责分离到专门的代理：

测试代理：专注于编写和运行测试
QA 代理：负责质量保证和代码审查
清理代理：处理代码重构和优化

2. 适用领域扩展

这套框架不仅适用于 Web 开发，还可应用于：

科学研究项目
数据分析工作流
金融建模
任何需要跨会话持续推进的复杂任务

七、核心原则总结

持久化优于记忆：使用文件系统而非依赖代理记忆
结构化优于自由文本：JSON > Markdown 用于关键数据
验证优于声明：强制自我测试而非相信代理报告
增量优于大步：每会话一个功能，保持可回滚
标准化优于临时：固定的启动例程减少混乱

八、在 PixCake-iPhone 项目中的应用建议

适合长时间运行代理的场景

大规模功能模块重构（如 Edit 模块优化）
批量 Bug 修复任务
性能优化项目（图像处理性能提升）
UI 组件库升级迁移

项目特定配置

init.sh 示例：

bash 复制代码

#!/bin/bash
# PixCake-iPhone 开发环境初始化

echo "初始化 PixCake-iPhone 开发环境..."

# 更新 CocoaPods 依赖
pod install

# 更新 Git 子模块
./modules.sh update

# 启动必要的服务
echo "环境准备完成"

claude-progress.txt 模板：

ini 复制代码

=== PixCake-iPhone Claude 工作日志 ===
项目: [功能名称]
开始时间: [YYYY-MM-DD]

=== 会话 1 - [日期] ===
目标: [本次会话目标]
完成:
- [完成项 1]
- [完成项 2]
遇到的问题:
- [问题描述及解决方案]
下次继续: [待办事项]

Git commits:
- [commit hash]: [commit message]

features.json 示例：

json 复制代码

{
  "project": "PixCake-iPhone",
  "version": "1.4.7",
  "features": [
    {
      "id": "edit-001",
      "module": "Edit",
      "name": "批量编辑性能优化",
      "description": "优化同时编辑多张照片时的内存使用和响应速度",
      "priority": "high",
      "passes": false,
      "tests": [
        "选择 10 张照片进行批量编辑",
        "验证内存占用低于 500MB",
        "验证操作响应时间 < 1s"
      ]
    }
  ]
}