在过去几个月深入使用Claude Code的过程中，我发现了一个有趣的现象：当我让Claude执行跨越多个会话的复杂任务时，它总是面临一个共同的困境——上下文窗口切换时的"失忆"问题。

每次新会话启动，代理都需要重新理解项目状态，这导致重复工作、遗漏测试、甚至功能半途而废。直到我读到Anthropic发布的《Effective harnesses for long-running agents》这篇工程文档，我才意识到这个问题有系统的解决方案。

今天我想和你分享这套框架的核心逻辑。

核心问题

想象一个软件项目由轮班工程师负责开发——每当新工程师到岗时，他对前一班发生的一切毫无记忆。

AI代理面临的正是这个问题：当上下文窗口重置时，代理对之前的工作、决策和环境状态一无所知。

这种"失忆"导致了三类典型失败模式：

• 一次性尝试完成全部：代理试图在一个会话内完成整个应用，结果上下文耗尽，功能半途而废
• 过早宣布完成：看到某些进展后就声明任务完成，跳过了关键的端到端测试
• 环境状态混乱：留下有bug、缺少文档或代码不整洁的遗留物

关键洞察是：这不是模型能力问题，而是架构设计问题。

解决方案

Anthropic提出的方案采用分工制的双代理架构，通过外部状态管理和结构化流程，确保长期任务的连贯性。

2.1 初始化代理（Init Agent）

初始化代理在项目启动时运行一次，职责是为整个项目奠定基础。核心工作包括：

• 分析用户需求，拆分为100+个细粒度的、可测试的功能点
• 创建核心管理文件（feature_list.json、init.sh、claude-progress.txt）
• 初始化版本控制和项目结构

init.sh 脚本示例：

#!/bin/bash
# init.sh - 环境初始化脚本

# 安装依赖
npm install

# 启动开发服务器
npm run dev &

# 等待服务器启动
sleep 5

# 基础健康检查
curl -f http://localhost:3000 || exit 1

echo "✅ 开发环境已就绪"

2.2 编码代理（Coding Agent）

编码代理在每个后续会话中运行，负责增量开发单个功能。会话启动时的关键流程：

1. 运行 pwd 确认工作目录
2. 读取 claude-progress.txt 了解最近进展
3. 读取 feature_list.json 查看待完成功能列表
4. 查看 git log --oneline -20 了解代码历史
5. 运行 init.sh 启动开发环境
6. 运行基础功能测试确保环境正常

三大核心文件的运作机制

3.1 功能列表文件（feature_list.json）

这是整个系统的"任务台账"，记录所有功能及其完成状态。每个功能包含详细的测试步骤，确保验收标准明确。

结构示例：

{
  "features": [
    {
      "id": "F001",
      "category": "functional",
      "description": "用户可以创建新对话",
      "priority": 1,
      "steps": [
        "导航到主界面",
        "点击'新对话'按钮",
        "验证创建了新对话",
        "检查聊天区域显示欢迎状态",
        "验证对话出现在侧边栏"
      ],
      "passes": false
    },
    {
      "id": "F002",
      "category": "functional",
      "description": "用户可以发送消息并收到AI回复",
      "priority": 2,
      "steps": [
        "在输入框输入消息",
        "点击发送按钮或按回车",
        "验证消息显示在对话中",
        "等待AI回复",
        "验证AI回复正确显示"
      ],
      "passes": false
    }
  ]
}

⚠️ 严格规则：编码代理只能修改 passes 字段（true/false），绝不能删除或修改功能定义和测试步骤。这确保了功能列表的完整性和可审计性。

3.2 进度日志文件（claude-progress.txt）

这是代理之间的"交接笔记"，记录每个会话的具体工作内容和决策。

格式示例：

# Claude 开发进度日志

## 2025-12-05 会话 1
- ✅ 初始化项目结构
- ✅ 配置开发环境
- ✅ 实现基础路由

## 2025-12-05 会话 2
- 🔧 修复了登录页面的样式问题
- ✅ 完成用户认证功能 (F001)
- 📝 下一步：实现对话创建功能 (F002)

## 待解决问题
- [ ] 移动端响应式布局需要优化
- [ ] 消息发送需要添加加载状态

这个文件让每个新会话的代理能够快速掌握历史脉络，避免重复工作或遗漏问题。

3.3 版本控制（Git）

每个功能完成后，编码代理必须：

• 使用描述性的commit message记录变更
• 确保代码处于可合并状态（无bug、有文档、符合代码规范）
• 为下一个会话留下清晰的代码历史

核心原则

⚠️ 关键原则：每次会话只开发一个功能

这是解决"一次性尝试完成所有事情"问题的核心策略。具体做法：

1. 编码代理从 feature_list.json 中选择优先级最高的未完成功能
2. 完整实现该功能的所有步骤
3. 使用浏览器自动化工具（如Puppeteer、Selenium）进行端到端测试，验证功能的每个步骤
4. 只有所有测试步骤都通过，才将 passes 标记为 true
5. 更新进度日志，创建Git提交，会话结束

这种约束强制了代理的"专注力"，避免了多任务并发导致的上下文混乱。

常见问题

实践清单

初始化代理清单

• [ ] 分析用户需求，拆分为100+个细粒度功能
• [ ] 创建 feature_list.json，所有功能初始状态为 "passes": false
• [ ] 创建 init.sh 启动脚本，包含依赖安装、服务启动、健康检查
• [ ] 创建 claude-progress.txt 进度文件
• [ ] 初始化Git仓库并创建首次提交
• [ ] 记录项目结构和详细的运行方式文档

编码代理清单（每次会话）

会话开始：

• [ ] 运行 pwd 确认工作目录
• [ ] 读取 claude-progress.txt 了解最近进展
• [ ] 读取 feature_list.json 查看待完成功能
• [ ] 查看 git log --oneline -20 了解代码历史
• [ ] 运行 init.sh 启动开发环境
• [ ] 运行基础功能测试

开发阶段：

• [ ] 每次只选择一个功能开发
• [ ] 实现功能后进行端到端测试
• [ ] 使用浏览器自动化工具验证UI功能的每个步骤

会话结束：

• [ ] 只有测试全部通过才将 passes 设为 true
• [ ] 更新 claude-progress.txt
• [ ] 创建描述性的Git提交
• [ ] 确保代码处于可合并状态（无bug、有文档、整洁）

关键提示词模板

初始化代理提示词

你是一个项目初始化代理。你的任务是：

1. 分析用户的需求，将其拆分为100+个具体的、可测试的功能点
2. 创建 feature_list.json 文件，列出所有功能及测试步骤
3. 创建 init.sh 脚本，用于启动开发环境
4. 创建 claude-progress.txt 进度跟踪文件
5. 初始化 Git 仓库并创建首次提交

请确保每个功能都是独立的、可增量实现的。

编码代理提示词

你是一个编码代理，负责增量开发功能。每次会话请遵循以下流程：

1. 运行 `pwd` 确认工作目录
2. 读取 claude-progress.txt 和 git log 了解当前状态
3. 读取 feature_list.json 选择一个未完成的功能
4. 运行 init.sh 启动开发环境
5. 运行基础测试确保环境正常

开发时：
- 每次只开发一个功能
- 使用浏览器自动化进行端到端测试
- 只有测试通过才将 passes 设为 true

会话结束时：
- 更新 claude-progress.txt
- 创建 Git 提交
- 确保代码处于干净、可合并状态

⚠️ 严禁删除或修改 feature_list.json 中的功能定义！

参考资源

Claude Agent SDK ：https://platform.claude.com/docs/en/agent-sdk/overview

自主编码快速入门：https://github.com/anthropics/claude-quickstarts/tree/main/autonomous-coding