---
title: "agent-foreman：长任务 Agent 的外部记忆"
subtitle: "从 Anthropic long-running agent harness 文章看状态持久化与交叉验证"
last_updated: 2025-12-07
---

# agent-foreman：长任务 Agent 的外部记忆

### 💡 痛点

用 Claude 写代码，小需求没问题，大需求 AI 就傻了。我相信模型能力是够的，肯定是方法不对。正好 Anthropic 发了一篇文章，讨论了这个问题：

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

文章总结了 AI Agent 的 **三大翻车现场**：

1. **Doing too much at once** —— 一口气想做完，上下文爆了
2. **Declaring victory too early** —— 没做完就说搞定了
3. **Superficial testing** —— 没测就标完成

文章的核心思路是：**借鉴有效软件工程师的日常做法**，给 AI 设计一套"轮班交接"机制——用功能清单划定工作边界，用进度日志记录做了什么，用 Git 追踪代码变化，确保每个会话都能继承清晰的工作状态。

### 🔍 找到了开源实现

看完文章，我去找有没有现成的开源实现，发现了 **agent-foreman** 这个项目：

> https://github.com/mylukin/agent-foreman

它完整实现了文章里的理念，而且还做成了 Claude Code 插件。下面来拆解一下它是怎么做的。

### 🔧 agent-foreman 的解法

> 把 AI 的工作记忆外化到文件系统

具体怎么做？

```
ai/
├── feature_list.json   ← 功能清单 + 状态
├── progress.log        ← 操作日志
└── capabilities.json   ← 项目能力缓存
```

每次 AI 开始工作，先读这些文件，就知道：
- 项目目标是什么
- 上次做到哪个功能
- 哪些已完成、哪些待做

### 🎯 架构挺巧妙

项目分两部分：插件 + CLI 程序。

插件就是一堆 Markdown 文件，本质是预置的 prompt 模板，告诉 AI "该执行什么命令"。CLI 程序负责维护状态文件，还能调用 Codex/Gemini/Claude 做交叉验证。

工作流程也很清晰：读取状态 → 选下一个任务 → AI 实现功能 → 验证完成 → 更新状态 → Git 提交 → 循环。

### 🤔 有趣的发现

拆解代码的时候发现几个有意思的点：

核心逻辑其实特别简单，就是读写 JSON 文件，20 行代码就能搞定。但项目有 60 多个文件，大部分都是"智能化"功能——AI 验证、TDD 指导、自动发现项目能力这些。

验证功能的时候会调用另一个 AI 来 review，默认优先用 Codex，不行再试 Gemini，最后才是 Claude。这个设计和我平时用的体感一样：Codex 逻辑性很强，做计划和 review 很靠谱。而 Claude 自己写的代码让它自己查，往往查不出问题——就像自己检查自己作业，容易有盲点。

还有个发现：Claude Code 的插件机制其实很简单，就是把 Markdown 文件的内容注入到对话里。所谓"插件开发"，本质就是写 prompt 模板。

### 🏗️ 整体设计图

```
┌─────────────────────────────────────────────────────────────┐
│                     agent-foreman 全局架构                   │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                    外部记忆层                        │    │
│  │  ai/                                                │    │
│  │  ├── feature_list.json  功能清单 (failing/passing)  │    │
│  │  ├── progress.log       操作日志 (跨会话连续)       │    │
│  │  └── init.sh            环境脚本 (测试/构建命令)    │    │
│  └─────────────────────────────────────────────────────┘    │
│                             ↑↓                               │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                    状态维护程序                      │    │
│  │                                                     │    │
│  │  读取状态 → 选择任务 → 验证完成 → 更新状态 → Git提交  │    │
│  │                  ↓                                  │    │
│  │           调用 AI 验证 (Codex > Gemini > Claude)    │    │
│  └─────────────────────────────────────────────────────┘    │
│                             ↑↓                               │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                    插件层 (Prompt)                   │    │
│  │                                                     │    │
│  │  commands/   斜杠命令 → 告诉 AI 执行什么            │    │
│  │  skills/     工作流 → 指导 AI 怎么做                │    │
│  │  agents/     角色定义 → AI 应该扮演什么             │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

**单次迭代工作流**：
```
┌──────────────────────────────────────────────────────────┐
│                                                          │
│  1. 读取状态                                              │
│     └── 从 feature_list.json 获取下一个 failing 任务     │
│                     ↓                                    │
│  2. 执行任务                                              │
│     └── AI 根据验收标准实现功能                          │
│                     ↓                                    │
│  3. 验证完成                                              │
│     └── 调用另一个 AI (Codex) 交叉验证                   │
│                     ↓                                    │
│  4. 更新状态                                              │
│     └── 标记 passing + 写日志 + Git commit               │
│                     ↓                                    │
│  5. 下一个任务 (循环)                                     │
│                                                          │
└──────────────────────────────────────────────────────────┘
```

### 📚 相关资料

- 项目地址：https://github.com/mylukin/agent-foreman
- Anthropic 原文：https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents