December 2025
agent-foreman：长任务 Agent 的外部记忆
从 Anthropic long-running agent harness 文章看状态持久化与交叉验证
💡 痛点
用 Claude 写代码，小需求没问题，大需求 AI 就傻了。我相信模型能力是够的，肯定是方法不对。正好 Anthropic 发了一篇文章，讨论了这个问题：
文章总结了 AI Agent 的 三大翻车现场：
- Doing too much at once —— 一口气想做完，上下文爆了
- Declaring victory too early —— 没做完就说搞定了
- Superficial testing —— 没测就标完成
文章的核心思路是：借鉴有效软件工程师的日常做法，给 AI 设计一套"轮班交接"机制——用功能清单划定工作边界，用进度日志记录做了什么，用 Git 追踪代码变化，确保每个会话都能继承清晰的工作状态。
🔍 找到了开源实现
看完文章，我去找有没有现成的开源实现，发现了 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. 下一个任务 (循环) │
│ │
└──────────────────────────────────────────────────────────┘