基于 Claude Code 的自主多 Agent 开发系统。
AP 将软件项目拆解为任务，分发给隔离的子 Agent 执行，通过独立的代码审查验证质量，自动推进项目直到完成——你只需要偶尔看一眼进度。
📖 设计详解：我给 Claude 设计了一个自动驾驶系统 — 从一个朴素想法到四角色编排系统的完整构思过程
买了 Claude Max plan，20 倍的 Opus 用量。然而：
- 人的交互带宽是瓶颈：Claude Code 每写一段代码都需要你 review、确认。不管算力多少倍，产出上限取决于你做 code review 的速度。
- Context 窗口会退化：长 session 后代码质量明显下降——命名随意、逻辑混乱、前后矛盾。新 session 又丢失所有上下文。
- 自己审自己不可信：同一个 agent 写代码又审代码，缺乏独立性。
AP 的解法：把人从循环里摘出来，把长对话拆成短命实例，让不同角色互相制约。
AP 使用四个角色，每个角色在独立的上下文窗口中运行，避免长会话导致的代码质量下降：
| 角色 | 类比 | 职责 |
|---|---|---|
| Architect | 架构师 | 将需求拆解为带依赖关系和验收标准的任务计划。只规划，不写代码 |
| Orchestrator | 项目经理 | 定时唤醒，从磁盘读状态，分发任务，更新状态，退出。天然无状态 |
| Implementer | 程序员 | 接收单一任务，写代码、写测试、跑测试。不超出任务范围 |
| Reviewer | 审查员 | 独立评估产出，看不到 Implementer 的推理过程，只看代码 diff |
状态存储在项目根目录的 .ap/ 目录中。全局注册表在 ~/.ap/registry.json。没有任何 Agent 在调用之间保留记忆——一切都在磁盘上。
将 autopilot/ 文件夹复制到 ~/.claude/skills/ 即可。
| 命令 | 触发方式 | 说明 |
|---|---|---|
| setup | ap setup |
需求访谈 → 创建 .ap/ → Architect 规划 → 你确认 → 定时任务启动 |
| adopt | ap adopt |
深度理解现有代码库 → 创建 .ap/ → Architect 基于现状规划 |
| status | ap status |
列出所有 AP 项目的进度、健康状态和待回答问题 |
| interact | ap interact |
回答 Orchestrator 正在等待的问题 |
| analyze | ap analyze <项目名> |
深入查看任务历史、Reviewer 反馈和当前状态 |
| recover | ap recover <项目名> |
修复卡死的 Orchestrator（清除过期锁、恢复异常周期） |
| kill | ap kill <项目名> |
暂停 AP，保留所有状态。ap resume 恢复运行 |
| resume | ap resume <项目名> |
恢复已暂停的项目 |
| config | ap config |
修改模型（opus/sonnet/haiku）或轮询间隔 |
.ap/ 就在项目目录内。 没有独立的工作区目录。状态文件、架构文档和日志与代码放在一起，就像 .git/ 属于项目本身。不想提交到 git 就加到 .gitignore。
无状态 Orchestrator。 每个周期都是一个全新的 Claude 实例。从 .ap/state.json 读状态，做一件事，写回状态，退出。没有上下文累积，没有质量退化。崩溃也不怕——state.json 就是恢复点。
同步阻塞调用。 Orchestrator 通过 claude -p 启动子 Agent，调用本身就是阻塞的——子 Agent 完成后命令返回结果，无需轮询、无需定时器。执行流简洁可靠：启动 Implementer → 等完成 → 启动 Reviewer → 等完成 → 处理结果 → 循环。
Reviewer 信息隔离。 Reviewer 看不到 Implementer 的推理过程，只看产出的代码 diff。就像真实团队中 code review 只看 PR，不看开发者的内心独白。这确保了审查的独立性和可信度。
should_run 与 status 正交。 status 描述任务生命周期（planning、running、completed），should_run 是自动执行的开关。两个维度互不干扰——可以 status: running（还有任务）同时 should_run: false（AP 已暂停）。
orchestrator_notes：跨实例的便签纸。 每个周期结束时写 1-2 句摘要给"下一个自己"，比如"Task-03 首轮通过，Task-04 是下一个"。不是完整的上下文传递（那会重蹈上下文爆炸的覆辙），而是精炼的短期记忆。
必须明确触发。 AP 永远不会悄悄启动。项目有 .ap/ 目录不代表所有操作都走 AP。你必须明确说 "ap" 或 "autopilot"。对于大型改动，AP 可能建议使用——但会等你确认。
增量规划。 项目完成后可以追加需求。ap resume 保留所有历史上下文（架构决策、已完成任务），Architect 只规划新增部分，新任务追加到已有列表后面。
- 状态外置 — 不信任任何 Agent 的记忆，一切持久化到文件系统
- 角色隔离 — 每个角色只看到它该看到的信息，避免上下文污染
- 短命实例 — 没有长寿 Agent，每次调用都是新生
- 人在回路 — 关键节点（计划确认、失败升级）必须有人参与
- 显式优于隐式 — 宁可让用户多说一句 "ap setup"，也不自作聪明地自动启动
your-project/
├── .ap/
│ ├── state.json # 唯一的状态来源
│ ├── context/
│ │ ├── architecture.md # Architect 的技术决策
│ │ └── role-prompts.md # 子 Agent 的 prompt 模板
│ └── logs/
│ └── cycle-*.json # 每个周期的 Orchestrator 日志
├── src/
└── ...
所有配置都在项目的 .ap/state.json 中：
model_config— 按角色选择模型：{"architect": "opus", "implementer": "sonnet", "reviewer": "opus", ...}poll_interval_minutes— Orchestrator 唤醒间隔（默认 5 分钟）should_run— 自动执行的总开关
运行时修改：使用 ap config 命令或直接编辑 state.json。
Skill 完成后进行了系统性评估，对比有 Skill 和无 Skill 基线：
| 场景 | 有 Skill | 基线 | 差异 |
|---|---|---|---|
| setup（创建项目） | 60% | 20% | +40% |
| status（查看状态） | 100% | 75% | +25% |
| analyze（分析项目） | 100% | 100% | 速度快 2x，token 省 22% |
关键发现：没有 Skill 时，Claude 面对"setup 项目"会直接写应用代码，而不是创建编排基础设施。Skill 教会了 Claude 一套结构化的开发流程。
- 需要 Claude Code 环境，依赖定时任务和 Agent tool
- Orchestrator 的上下文窗口限制了单个任务的大小——保持每个任务涉及 2-4 个文件
- Description 触发存在已知的召回率问题，建议使用
ap前缀确保可靠触发 - 暂无 Web 看板（计划中）
MIT