用 AI Agent 团队做软件：一种 Core-Adapter 的做法

当你认真用 AI 编码 agent — 不是自动补全，而是把任务交给它出活儿的"行动者" — 问题就从"模型有多强"变成了"怎么把工作组织好让模型能派上用场"。我们一直在做这件事的一个小框架，反复重写之间保持下来的结构是 Core-Adapter 分离。这篇就是它的描述。

Core 小，几乎不变。它定义"什么是一个项目"、"蓝图长什么样"、"任务、记忆、技能各自是什么"、以及"agent 怎么读写这些产物"。Core 不是功能表面 — 它是一套语汇和一套约定。Core 对了，懂 Core 的 agent 就能在所有用 Core 的项目里走通。

Adapter 是其他一切，Adapter 是允许变的。和编辑器的集成、文件浏览器、团队聊天、部署系统。各种可视化和 dashboard。把 Core 连到团队实际在用的环境里的任何可选协议。Adapter 可以有很多，Core 只有一个。

这个分离在实务上为什么重要：Adapter 的寿命就是它适配的工具的寿命。编辑器换来换去，文件浏览器被重做，团队聊天工具被并购。所有这些都不应该要求 Core 改。Core 必须比 Adapter 活得久，而让这件事在成本上可行的唯一办法是把 Core 做小，把 Core 和 Adapter 之间的界面做干净。

我们用第二个轴来约束这件事：对框架本身的三层视角。第一层是元设计 — 框架本身的设计。第二层是运行时上的框架 — 用框架的项目实际持有的文件和约定。第三层是真实项目 — 用框架做出来的具体应用，带自己的蓝图和代码。把这三层在对话里混起来是把讨论搞乱的最稳定的方式。任何一个决定下定之前，我们都先标清楚它属于哪一层。

一件小但很重要的事：产物必须是项目本地的文件，不能是 agent 或某个服务里的内部状态。蓝图、任务、记忆、技能定义 — 全部放在项目仓库里。它们被版本控制、能 diff、能 review、跨任何单次 agent 会话存活。Agent 的工作是读这些文件、做事、写回也是文件的改动。如果框架要靠外部服务记东西，你就做了一个脆弱的系统。

出现的一个模式：一个项目管理角色 + 几个专门角色，但所有人读同一份蓝图、写同一个任务跟踪。我们用一个 orchestrator 加一组固定/按需的角色（设计师、前端、后端、审查员、安全、调试员等）。它们不是不同的模型 — 是同一个底层模型用不同 prompt 和不同工具权限跑。让它们一致的是结构，不是 prompt。

关于技能：每个技能当成一个小合约。在特定条件下触发、有窄定义的指令、能调其他技能、产生可审计的输出。技能更接近一个函数，而不是一个人格。给框架加新能力时，加的是技能 — 不是新 agent，不是某个巨型 prompt 里多分支。这让框架更好维护、更好推理。

关于验证：agent 的工作只有在可检查时才有用。把前进用的回路和抓错用的回路投入对等。Agent 的每一步要么产生一个人或另一个 agent 能 review 的产物，要么就不发生。沉默的状态变更我们学会了不信任 — 它们倾向于积累成需要几天才能撤回的问题。

这种结构具体换来什么：agent 可以在项目进行到一半时进来，几个回合之内变得有用（因为 Core 定义了所有东西在哪）。团队可以换 Adapter — 换编辑器、换聊天工具、换部署平台 — 不需要重写 Core 或项目产物。技能能单独测。蓝图能用纯文本被人 review。如果框架是一坨大 prompt，这些性质一个都不会出现。

还没想清楚的事：agent 之间意见不一致怎么处理才不至于把所有决定变成开会。项目成熟过程中怎么让记忆保持诚实。什么时候让 agent 自组织、什么时候把它放回轨道上。这些都还没有干净的答案。框架是个在工作中的工具，不是完成品，这些笔记是按这个精神写的。