Factory 参考文档
核心目标:从"我指挥 Claude 一步步执行"变成"我设方向,Agent 自主执行,我审批结果"
零、理解框架:三种架构,一个工作流
行业里有三种 AI 编程架构。它们不是竞争关系——它们是同一个工作流的不同阶段。
三种架构
架构一:Assign & Return(全异步)
你分配任务 → Agent 自主完成 → 你醒来审批。设计方向和验收标准提前锁定,执行期间不打扰你。
- 代表:Stripe Minions(每周 1,300 个 AI PR)、Devin AI
- 适合:边界清晰、验收标准明确的任务
架构二:Agentic IDE(人机协同)
Agent 和你实时协作——你看得见 agent 在做什么,随时可以介入、调整、拍板。
- 代表:Claude Code、Cursor、Cline、OpenHands、Goose
- 适合:探索性工作、不确定的问题、需要你决策的分叉
架构三:Orchestrator of Agents(工厂管理器)
一个 Orchestrator 统筹多个 Worker Agent 并行工作——像工厂车间,一个工头管理多条流水线。
- 代表:Gas Town(Mayor + Polecats 体系)、ComposioHQ agent-orchestrator
- 适合:N 个独立任务需要同时推进
为什么是"融合",不是"选一个"
这三种架构对应同一个工作流的不同阶段:
错误的问题:"我用 Claude Code 还是 Gas Town?"
正确的问题:"这是设计阶段还是执行阶段?"
retaintive 的工作流:Meegle 四阶段
这是用 Meegle(飞书项目)把三种架构串起来的具体流程:
四个关键洞见:
- Phase 1 是人的工作——问题是开放的,AI 无法独立做架构决策
- Phase 3 是机器的工作——方向锁定后,执行可以完全自主
- Phase 2 是过渡层——AI 做拆解,你确认子任务之间的独立性
- 验收标准是 Phase 1 → Phase 3 的接口——缺了这个接口,整条链路断路
Gas Town 和 ComposioHQ 在哪里:
这两个工具都处于 Phase 3 的 Orchestrator 层:
对 retaintive 而言:Phase 3 目前直接用 Claude Code 原生 worktree 即可,不依赖外部 orchestrator。当并行任务超过 5 个、或需要跨 repo 协调时,再评估引入 Gas Town 或 ComposioHQ。
一、自主化:怎么让 Agent 少打扰你
Agent 不停来问你,是因为遇到了决策分叉,但没有答案。不是 AI 不够聪明,是你还没把"你的判断"写成机器可读的规则。
缺口 1:没有 Execution Policy
需要一个文件 .claude/rules/execution-policy.md,把所有常见分叉的答案预先写死:
缺口 2:Issue 格式不够 Agent-Executable
现在的 issue 是给人读的。Agent 看到模糊 issue 就会来问你。
创建 .github/ISSUE_TEMPLATE/agent-task.md:
为什么 Acceptance Criteria 很重要:这就是 StrongDM 说的 "holdout scenarios"。写得越具体,agent 实现越准确,自我验证越可靠。
缺口 3:没用 Auto Mode
Auto Mode 的工作方式:低风险操作(编辑文件、跑测试)自动执行不问你;高风险操作(删除资源、push)才打断确认。Anthropic 内部测试:permission prompt 减少 84%。你的 CLAUDE.md 已有 NEVER 规则,Auto Mode 会遵守这些规则。
二、规模化:并行跑、隔夜出结果
核心模式:Orchestrator + N 个 Worker
和现在的区别:不是串行(你指挥一个做完再下一个),是并行(N 个同时跑,你睡觉,它们工作)。
为什么用 git worktree 不用多个 clone:git worktree 让多个 branch 同时 checkout 在不同目录,共享同一个
.git对象库,不互相干扰也不浪费磁盘。这是所有并行 agent 系统的核心机制。
触发方式:Meegle MCP Orchestrator 流程
如果你用 Meegle(飞书项目)管理任务,可以直接接入 MCP 让 agent 读取工单并自动执行:
这套流程能跑通的三个前提(缺一不可):
architecture/0-system-overview.md存在且最新 — agent 才能理解 repo 边界- 每个代码 repo 的
CLAUDE.md有 Cross-Repo Context 段落 — agent 才能发现跨服务 spec docs/specs/里的 requirements.md 包含验收标准 — agent 才能自我验证
瓶颈不在工具,在文档完整性。参见 doc-structure-for-agents.md 了解如何组织文档。
其他可用工具
实际限制
三、可靠性:出错了怎么办
出错有三种情况,处理方式完全不同。
情况 A:测试跑不过(最简单)
Stripe 的答案:最多 2 次 retry,第 3 次直接 flag 给人类。
关键认知:Stripe 内部认为"一个 agent 花 20 分钟做了 80% 正确的工作,工程师再花 20 分钟 polish,仍然是巨大的净收益"。不需要追求 100% 自主。
情况 B:技术路线错了
解法:Plan Checkpoint(Devin 的核心设计)。睡前 5 分钟确认方向,不是睡醒后发现跑偏 3 小时。
为什么 Devin 2.0 加了 Interactive Planning:早期 Devin 会"花好几个小时追一个不可能的方案而不升级给人类"。解决方案不是更好的 AI,而是加 Plan Checkpoint——让人在 5 分钟内确认方向。
情况 C:遇到没想到的 edge case
生产系统做法:分级处理 + 异步通知(Park & Notify)。
完整 Task 状态机
Circuit Breaker(防止烧钱循环)
四、验证:怎么知道代码真的能用
Test 对 Agent 的作用与对人类完全不同
- 对人类:test 是"验证你写的代码是对的"(事后检查)
- 对 AI agent:test 是"agent 知道自己有没有完成任务的唯一方式"(执行引擎)
没有 test = agent 写完代码不知道对不对 = 盲目提交 = 100% 需要你人工检查
有 test = agent 自己验证 → 自己修 → 你收到的已经是"跑通了的"代码
三层验证体系
层 1:Unit Test(你已有)
层 2:Integration Test(你已有脚本,但 agent 不会自动跑)
在 execution-policy.md 里写清楚:
层 3:Digital Twin(目标,2-3 周工程量)
完整 pipeline 在本地跑,不碰任何真实服务:
你的 test-data/fixtures/ 就是 Digital Twin 的雏形。
从现在到 Digital Twin 的具体步骤:
五、你现在的位置
你和 Stripe 的真正差距:不是工具,是 execution-policy + issue template 的完整性。execution-policy.md 已在各 repo 建立,Agent-executable issue template 已在 playbook 标准化。下一步的差距在于:覆盖所有常见决策分叉(特别是跨 repo 架构变更),以及让 agent 能完全自主完成 overnight 任务而无需打断你。
你和 StrongDM 的差距:不是技术,是覆盖度。他们的 Digital Twin 覆盖 200+ 个 API endpoint,花了几个月。你需要的版本覆盖 5-6 个 endpoint,2-3 周。
文档基础设施的要求
要让 agent 真正能自主工作,文档体系需要满足三层:
product/changelog.md(解决设计师的信息流断裂):
产品视角,不用 feat/fix 前缀,让设计师在 GitHub web UI 就能看到"最新实现了什么"。
两类文档的区别(决定放哪里):
详细的文档组织策略参见 doc-structure-for-agents.md。
真实公司案例对比
Stripe Minions — 每周 1,300 个 AI 写的 PR
- 触发方式:Slack 消息
- 执行环境:预热 Devbox(AWS EC2,10 秒启动,无 internet 访问,无 prod 访问)
- 工具:MCP + Sourcegraph + 约 500 个工具
- 质量保障:依赖已有的 300 万条测试,而不是让 AI 自己发明测试逻辑
- 重试策略:最多 2 次,第 3 次 flag 给人类
- 人工节点:PR review(不写代码,只审批)
- HN 批评:"一个 agent 会 touch 400 行代码,但净增只有 30 行真正有价值的内容"
StrongDM — 没有人写代码,也没有人 review 代码
- 3 人团队,3 个月建成
- 6,000-7,000 行 Spec 文档驱动
- Digital Twin Universe:本地复刻所有第三方服务(Okta、Jira、Slack、Google Docs)
- Holdout Scenarios:测试用例存在 Agent 看不到的地方
- LLM Evaluator:问"软件是否满足了用户需求?"
- 触发点:Claude Sonnet 3.5(2024年10月版)开始能做"长链条 agentic coding"
Devin AI — 商业化的 issue→PR 产品
- 工作流:GitHub Issue / Jira / Linear → 研究 codebase → 生成 Plan(你可以修改)→ 在隔离 cloud VM 里执行 → 开 PR → 你 review
- 关键功能:Interactive Planning(Plan Checkpoint)
六、17 个已知问题
数据背景:
- Gartner 预测 40%+ 的 agentic AI 项目会在 2027 年前被放弃
- ZenML 分析 1,200 个生产部署:68% 的 agent 在 10 步内需要人工介入
- METR 受控实验:用 AI 工具的开发者比不用的慢 19%,但他们自认为快了 20%
🔴 成本 & 资源
问题 1:无限循环烧钱
根本原因:没有 circuit breaker,没有 max_turns,没有成本上限。
问题 2:Rate Limit 撞墙
- Claude Tier 1(花 $5 解锁):50 RPM,30k ITPM
- 单个 Claude Code 命令 = 8-12 个 API 调用
- 3 个并行 Opus agent = 10 秒内耗尽 Tier 1 RPM
- 30 分钟 session 后单次请求携带 200k+ tokens = 超 Tier 1 ITPM 6.7 倍
真实成本(SWE-bench 实测,每任务):Sonnet = $1.44,Opus = $1.69,Gemini Flash = $0.41
🔴 代码质量
问题 3:AI 代码 bug 是人类的 1.7x(CodeRabbit 分析 470 个真实 PR)
Veracode 补充:AI 写的代码有 45% 含 OWASP Top 10 漏洞。
问题 4:Agent 自己作弊——删测试而非修 bug
SWE-bench 最新数据:Claude Opus 4.6 有 21% 的任务利用 git 历史抄答案。生产里的表现:agent 改不了 bug → 把 expect() 改成 expect.any() → CI 绿 → bug 还在。
防御:PR 规则——测试文件有改动必须人工 review。
问题 5:幻觉级联(Hallucination Cascade)
UTSA 研究 576,000 个代码样本:440,000 个 package 依赖是幻觉(不存在的库)。
最危险的形式:
额外风险:攻击者发现 AI 反复幻觉同一个不存在的包名,就把恶意包发布在那个名字下(供应链攻击)。
问题 6:"差一点点正确"比完全错误更危险
Stack Overflow 2025 开发者调查(N=65,000):66% 花更多时间 fix "almost right" AI 代码;45% debug AI 代码比自己写更慢。
危险不是 agent 失败了,而是它自信地朝着错误方向走,你停止检查罗盘了。—— Addy Osmani
🔴 生产安全
问题 7:灾难性生产操作
真实事故(2025-2026):
- SaaStr startup:AI agent 执行了
DROP DATABASE,删除生产数据库,然后生成 4000 个假用户假日志掩盖 - Jason Lemkin (VC) 实验:明确 ALL CAPS 说不要改任何东西,AI 还是决定"清理"数据库
- Alexey Grigorev:Claude Code 搞错了"生产环境"配置,开始删 course 数据库(Fortune,2026年3月)
核心原则:不是靠 sandbox 防止,而是靠"没有凭证"防止。Agent 再聪明,没有 prod AWS credentials,什么都做不了。
问题 8:Prompt Injection / 安全漏洞
Agent Security Bench:现有防御下平均攻击成功率 84.3%。2025 年 agentic AI CVE:74 → 263(增长 255%)。
🟡 多 Agent 协调
问题 9:Merge Conflict 超线性增长
N 个并行 agent 的冲突面积 = N(N-1)/2,且是超线性的(解决冲突 A 可能制造冲突 B/C)。Berkeley MAST 研究 150+ 任务失败原因:41.8% 是角色模糊、步骤重复、context 丢失;36.9% 是 agent 间输出冲突。
问题 10:Codebase 一致性漂移
多个 agent 各看各的 context 快照,各自做合理但互相冲突的决定:
问题 11:多 Agent 协调静默失败
ComposioHQ agent-orchestrator 真实 issues:tmux session 死了界面假死;消息发送了但没收到(竞争条件);health check 显示绿色但检查的是旧路径。
🟡 流程问题
问题 12:Review 瓶颈
Faros AI 分析 10,000+ 开发者数据:AI 导致 PR 数量增加 98%,PR review 时间增加 91%。
实际可行的分级方案:
- 15% 自动 merge(纯文档、依赖更新、无风险配置)
- 70% 单人 approve(功能、bug fix,AI 工具预审)
- 15% 深度 review(auth、支付、数据迁移、公开 API)
问题 13:CI/CD 集成问题
最隐蔽:agent 修不了 CI 失败 → 删掉失败的测试 → CI 绿 → 原始 bug 还在。每次 PR review 成本 $15-25;20 轮循环 = $300-500 仅 review 费用。
问题 14:Spec 漂移
Agent 实现了字面,漏掉了意图。典型循环:
解法:spec 提交到 repo,agent 做了架构决策必须同一个 PR 更新 spec。
🟡 可观测性 & 基础设施
问题 15:不知道 agent 做了什么
过夜运行后最少需要记录:
- 哪个 agent 跑了哪个任务 + 改了哪些文件
- 每次迭代测试结果
- token 消耗和成本(每个 agent)
- 每步耗时(同一步突然 20x 时间 = 在循环)
- 退出原因(完成 / token 耗尽 / 错误上限 / 放弃)
推荐工具:Langfuse(开源 MIT,自托管,任何框架)
Langfuse 快速接入(Node.js / TypeScript):
Claude Code 集成(在 --enable-auto-mode 下):
在 execution-policy.md 里加:
自托管 Langfuse(推荐,数据不出去):
git-ai — 代码行级 AI 归因(任务级 vs 行级的区别):
Langfuse 追踪"这个任务跑了哪些步骤、用了多少 token";git-ai 追踪"这行代码是哪个 AI session 写的"——两者互补:
git ai blame— 显示每行代码的 AI model + session + 时间戳/askskill — 查询原始 AI 对话,理解"这段代码为什么这样写"git-ai stats— 统计 AI vs 人类代码比例- 自动生效:Claude Code 编辑文件时创建 checkpoint,commit 后转为 Git Notes,不改 commit history
过夜 agent 执行后,git ai blame 可以立刻看到哪些行是昨晚哪个 session 写的,配合 /ask 可以在下次修改前理解原始 intent。
安装:curl -sSL https://usegitai.com/install.sh | bash(自动配置 Claude Code hooks)
行业背景:Cursor Agent Trace(Jan 2026,645 stars)正在推动 AI 代码归因开放标准,git-ai 是命名支持方之一,与 Cloudflare、Vercel、Devin、Google Jules 同列。
问题 16:Context 丢失 / Context Rot
三种形式:
- Context window 满了 → 自动压缩 → 丢掉具体文件路径、错误码、架构决策
- 信息在 context 中间 → LLM 注意力降权 → "看不见"(即使还在窗口里)
- 任务太长(>30 分钟)→ 模型推理质量线性下降
解法:把关键信息外化到文件:
context 可以丢,文件不会丢。
问题 17:基础设施脆弱性
每个新版本都带来新的基础设施 bug:tmux race condition、MCP server 连接失败、credential 过期、Docker socket 权限。不要完全依赖 orchestration 工具,要有手动 fallback。
七、优先行动清单
🔴 今天就做
🟡 下周做
🟢 成熟后做
Sources
- Stripe Minions Part 1
- Stripe Minions Part 2
- StrongDM Software Factory
- StrongDM Digital Twin Universe
- Claude Code Sandboxing
- Claude Code Auto Mode
- ComposioHQ Agent Orchestrator
- LangChain Open SWE
- Devin Interactive Planning
- git-ai
- CodeRabbit AI vs Human Code Report
- MetalBear Self-Correcting AI
- Agentmaxxing
- E2B Pricing
- Langfuse