> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 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 个独立任务需要同时推进

### 为什么是"融合"，不是"选一个"

这三种架构对应同一个工作流的不同阶段：

| 阶段      | 用哪种架构                          | 原因               |
| ------- | ------------------------------ | ---------------- |
| 设计 / 探索 | **架构二**（Agentic IDE）           | 问题本身是开放的，你需要全程参与 |
| 拆解 / 规划 | **架构二**（你 + AI 共同产出 Task Spec） | 验收标准必须你来拍板，不能外包  |
| 执行      | **架构一 + 三**（全异步 + 并行）          | 方向锁定后，执行可以完全自主   |

错误的问题："我用 Claude Code 还是 Gas Town？"

正确的问题："**这是设计阶段还是执行阶段？**"

### retaintive 的工作流：Meegle 四阶段

这是用 Meegle（飞书项目）把三种架构串起来的具体流程：

```
Phase 0：创建大任务（你，5 分钟）
    在 Meegle 创建一个模糊的大目标（例："改进 Lead Tracker 温度系统"）
    此时不需要知道所有细节——细节由 Phase 1 填补
        ↓
Phase 1：发现 / 设计（架构二，你 + AI 交互，30–60 分钟）
    AI 读代码库 → 告诉你现状、可行路径、风险
    你提问、质疑、拍板 → AI 填补信息空白
    产出：一份 Task Spec（含验收标准）
    [关键] 这一步必须是人机交互，因为问题是开放的，AI 无法独立决策
        ↓
Phase 2：AI 拆解（AI 辅助，10–20 分钟）
    AI 把大任务拆成 N 个独立子任务
    每个子任务带：受影响文件边界 + 验收标准 + 参考实现路径
    写入 Meegle sub-tasks 或 GitHub Issues
    [关键] 子任务之间文件域不重叠，才能并行执行不打架
        ↓
Phase 3：并行执行（架构一 + 三，全自动，你去睡觉）
    N 个 Worker Agent 各自读 task spec
    各自在独立 git worktree 里实现 → 跑测试 → 开 PR
    CI 失败 → 自动修（最多 2 次）→ 还是失败 → Draft PR + 通知你
    完成 → Meegle finish_node 自动关闭工单
    你醒来：N 个 PR 等你，每个 PR 里有验收标准完成情况
```

**四个关键洞见**：

1. **Phase 1 是人的工作**——问题是开放的，AI 无法独立做架构决策
2. **Phase 3 是机器的工作**——方向锁定后，执行可以完全自主
3. **Phase 2 是过渡层**——AI 做拆解，你确认子任务之间的独立性
4. **验收标准是 Phase 1 → Phase 3 的接口**——缺了这个接口，整条链路断路

**Gas Town 和 ComposioHQ 在哪里**：

这两个工具都处于 Phase 3 的 **Orchestrator 层**：

| 工具                                | 适合场景                                       |
| --------------------------------- | ------------------------------------------ |
| **Gas Town**（Mayor + Polecats）    | 长期维护的工厂：Mayor 持续管理 Polecats，任务持续涌入         |
| **ComposioHQ agent-orchestrator** | 批量一次性执行：读 spec → 拆任务 → 并行 worktree → 批量 PR |

对 retaintive 而言：**Phase 3 目前直接用 Claude Code 原生 worktree 即可**，不依赖外部 orchestrator。当并行任务超过 5 个、或需要跨 repo 协调时，再评估引入 Gas Town 或 ComposioHQ。

***

## 一、自主化：怎么让 Agent 少打扰你

Agent 不停来问你，是因为遇到了决策分叉，但没有答案。不是 AI 不够聪明，是你还没把"你的判断"写成机器可读的规则。

### 缺口 1：没有 Execution Policy

需要一个文件 `.claude/rules/execution-policy.md`，把所有常见分叉的答案预先写死：

```markdown
# Autonomous Execution Policy

## 遇到不确定时的决策顺序
1. 先看 .claude/rules/ 有没有覆盖这个场景
2. 参考 conversation history（`~/.claude/projects/[project]/` JSONL）了解负责人的决策偏好
3. 看现有代码里同类问题怎么解决（以现有代码为范本）
4. 有设计含义的决策（影响多文件、架构选择）→ 考虑 long-term 影响与可维护性，在 PR 里说明理由
5. 绝不因为不确定就停下来问用户

## 数据存储
- 新的持久化数据 → Neon (PostgreSQL)
- 现有 DDB 表的读取 → 继续用 DDB（不迁移）
- 跨服务通信 → SQS

## 测试策略
- 所有新 Lambda 必须有 unit test（80%+ coverage）
- 集成测试用 test 环境（从 config/index.ts 读 URL，不问用户）
- 测试失败 → 自己修，最多 3 次，第 4 次在 PR 里标注问题

## 遇到构建失败
- 先读错误信息 → 查 CLAUDE.md troubleshooting → 自行修复，不打断用户

## 遇到这些情况直接决定，不用问我
- contacts 表缺索引 → 加索引
- 字段类型不确定 → 用 string
- DDB vs Neon 不确定 → Neon（新数据都用 Neon）

## 遇到这些情况 Park & Notify 我
- 需要改 prod 环境配置
- 发现设计文档有矛盾
- 影响超过 2 个 Lambda 的架构变更
```

### 缺口 2：Issue 格式不够 Agent-Executable

现在的 issue 是给人读的。Agent 看到模糊 issue 就会来问你。

创建 `.github/ISSUE_TEMPLATE/agent-task.md`：

```markdown
---
name: Agent Task
labels: agent-task
---

## 任务描述
[一句话]

## 执行方针（读完直接执行，不用问我）
- [ ] 先读这些文件: `lambda/xxx/handler.ts`
- [ ] 参考这个现有实现: `lambda/yyy/` 作为代码范本
- [ ] 不要改这些文件: `lib/config/environments.ts`

## 验收标准（每条都必须可以跑命令验证）
- [ ] `npm test` 全部通过，覆盖率 ≥ 80%
- [ ] `cdk diff` 显示无 replacement
- [ ] 当 [具体输入] 时，[具体输出] 符合预期

## 已经决定的事（不用再讨论）
- 用 Neon，不用 DDB
- 不改现有 API endpoint
```

> **为什么 Acceptance Criteria 很重要**：这就是 StrongDM 说的 "holdout scenarios"。写得越具体，agent 实现越准确，自我验证越可靠。

### 缺口 3：没用 Auto Mode

```bash
# 启动时开启
claude --enable-auto-mode

# 或 session 内按 Shift+Tab 切换
```

Auto Mode 的工作方式：低风险操作（编辑文件、跑测试）自动执行不问你；高风险操作（删除资源、push）才打断确认。Anthropic 内部测试：permission prompt 减少 84%。你的 CLAUDE.md 已有 `NEVER` 规则，Auto Mode 会遵守这些规则。

***

## 二、规模化：并行跑、隔夜出结果

### 核心模式：Orchestrator + N 个 Worker

```
你的 Design Doc（已有）
      ↓
[Orchestrator Agent] 读 doc → 拆分成 N 个独立任务
      ↓
并行启动 N 个 Worker Agents（每个独立 git worktree）
  ├── Agent 1: GAP 3 → worktree-1 → branch-1 → PR #1
  ├── Agent 2: GAP 7 → worktree-2 → branch-2 → PR #2
  └── Agent 3: GAP 8 → worktree-3 → branch-3 → PR #3
      ↓
CI 失败 → 自动路由回对应 Agent 修复
      ↓
你第二天醒来 → N 个 PR 等你
      ↓
批量 review（看 summary，不是逐行）→ approve → merge
```

**和现在的区别**：不是串行（你指挥一个做完再下一个），是并行（N 个同时跑，你睡觉，它们工作）。

> **为什么用 git worktree 不用多个 clone**：git worktree 让多个 branch 同时 checkout 在不同目录，共享同一个 `.git` 对象库，不互相干扰也不浪费磁盘。这是所有并行 agent 系统的核心机制。

### 触发方式：Meegle MCP Orchestrator 流程

如果你用 Meegle（飞书项目）管理任务，可以直接接入 MCP 让 agent 读取工单并自动执行：

```
Meegle（飞书项目）工单
    ↓ MCP Server（project.larksuite.com/mcp_server/v1）
    ↓ get_node_detail / create_workitem
    ↓
[Orchestrator Agent]
    读 docs/architecture/0-system-overview.md → 知道哪些 repo 受影响
    读 cross-repo-features/ → 知道跨 repo 的设计
    读 docs/specs/[feature]/requirements.md → 知道验收标准
    ↓
拆分为 N 个独立 Task Spec（一个 repo = 一个 spec）
    ↓
并行 Worker Agents（git worktree × N）
    读各自 repo 的 execution-policy.md → 知道怎么决策
    ↓
各自开 PR → Meegle finish_node 自动关闭工单
```

**这套流程能跑通的三个前提**（缺一不可）：

1. `architecture/0-system-overview.md` 存在且最新 — agent 才能理解 repo 边界
2. 每个代码 repo 的 `CLAUDE.md` 有 Cross-Repo Context 段落 — agent 才能发现跨服务 spec
3. `docs/specs/` 里的 requirements.md 包含验收标准 — agent 才能自我验证

> 瓶颈不在工具，在文档完整性。参见 [doc-structure-for-agents.md](/ai/factory/doc-structure-for-agents.md) 了解如何组织文档。

### 其他可用工具

| 工具                                                                                | Stars | 特点                                                  |
| --------------------------------------------------------------------------------- | ----- | --------------------------------------------------- |
| [ComposioHQ/agent-orchestrator](https://github.com/ComposioHQ/agent-orchestrator) | 4.1k  | 最接近你要的：读 issue/spec → 拆任务 → 并行 worktree → CI 失败自动路由 |
| [langchain-ai/open-swe](https://github.com/langchain-ai/open-swe)                 | —     | LangChain 出品，云端跑，内置 sandbox，支持 Slack/Linear 触发      |
| Claude Code 原生（实验性）                                                               | —     | `export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`     |

### 实际限制

| 限制    | 现实                                          |
| ----- | ------------------------------------------- |
| 并行上限  | 5-7 个 agent（再多 rate limit + merge conflict） |
| 适合的任务 | 独立模块，文件域不重叠                                 |
| 不适合的  | 强依赖顺序的任务（需要先 A 才能 B）                        |
| 成本    | Claude API token × N 个 agent                |

***

## 三、可靠性：出错了怎么办

出错有三种情况，处理方式完全不同。

### 情况 A：测试跑不过（最简单）

Stripe 的答案：**最多 2 次 retry，第 3 次直接 flag 给人类**。

```
测试失败 → Agent 自己修（第 1 次）
→ 还是失败 → 再修（第 2 次）
→ 还是失败 → 停止，开 Draft PR，写上卡点原因
→ 通知你
```

关键认知：Stripe 内部认为"一个 agent 花 20 分钟做了 80% 正确的工作，工程师再花 20 分钟 polish，仍然是巨大的净收益"。不需要追求 100% 自主。

### 情况 B：技术路线错了

解法：**Plan Checkpoint**（Devin 的核心设计）。睡前 5 分钟确认方向，不是睡醒后发现跑偏 3 小时。

```
你发任务
    ↓
Agent 先研究 codebase（不写代码）
    ↓
生成 Plan 给你看：
  "我准备这样做：Step 1... Step 2...
   ⚠️ 我发现：contacts 表没有按 phone 查询的索引
   你想要：A) 加索引  B) 换查询方式  C) 你决定"
    ↓
你 review Plan（5 分钟）→ 确认或修改
    ↓
晚上执行（方向已锁定，不会跑偏）
```

> **为什么 Devin 2.0 加了 Interactive Planning**：早期 Devin 会"花好几个小时追一个不可能的方案而不升级给人类"。解决方案不是更好的 AI，而是加 Plan Checkpoint——让人在 5 分钟内确认方向。

### 情况 C：遇到没想到的 edge case

生产系统做法：**分级处理 + 异步通知（Park & Notify）**。

```
Agent 遇到不确定情况
    ↓
能不能做合理决策？
  ├── 能 → 按 execution-policy.md 决定，继续，PR 里记录
  └── 不能（影响太大）→ Park & Notify
              ↓
         存为 Draft Branch
         发通知你（Slack/Discord/手机）：
         "Task #3 卡住了，需要你回答：
          当 phone 在多个 contacts 里出现时，用哪条？"
              ↓
         继续做其他并行任务（不浪费时间等你）
              ↓
         你醒来回答 → agent 继续
```

### 完整 Task 状态机

```
PENDING → PLANNING → [你 review Plan 5分钟]
                ↓
           EXECUTING
           /    |    \
       成功   卡住   超时/循环
        ↓      ↓       ↓
       PR   BLOCKED   ABORT
       ↓      ↓         ↓
    你review 通知你   Draft PR
              ↓         ↓
           你回答    你 polish
              ↓
           继续执行
```

### Circuit Breaker（防止烧钱循环）

```json
{
  "max_turns": 20,
  "cost_ceiling_usd": 5.0,
  "loop_detection": {
    "enabled": true,
    "window_size": 5,
    "similarity_threshold": 0.95
  }
}
```

***

## 四、验证：怎么知道代码真的能用

### Test 对 Agent 的作用与对人类完全不同

- 对人类：test 是"验证你写的代码是对的"（事后检查）
- 对 AI agent：test 是"agent 知道自己有没有完成任务的唯一方式"（执行引擎）

**没有 test = agent 写完代码不知道对不对 = 盲目提交 = 100% 需要你人工检查**

**有 test = agent 自己验证 → 自己修 → 你收到的已经是"跑通了的"代码**

### 三层验证体系

**层 1：Unit Test**（你已有）

```
Agent 写代码 → npm test → 失败 → 读错误 → 修 → 再跑 → 成功
```

**层 2：Integration Test**（你已有脚本，但 agent 不会自动跑）

在 execution-policy.md 里写清楚：

```markdown
## 验证步骤（必须全部通过才能开 PR）
1. npm test（unit tests）
2. npm run cdk:diff（无 replacement）
3. AWS_PROFILE=agent-test bun run integration-test \
   --base-url https://studio-api-test.retaintive.ai
```

**层 3：Digital Twin**（目标，2-3 周工程量）

完整 pipeline 在本地跑，不碰任何真实服务：

```
RingCentral Webhook  →  WireMock（录制真实响应一次，之后回放）
SQS                  →  LocalStack（AWS 本地模拟）
Deepgram             →  固定返回测试转录文本
Bedrock/Kimi         →  expected-outputs/（你已有）
DynamoDB             →  LocalStack
Neon PostgreSQL      →  pg Docker 容器 或 Neon Branch
```

你的 `test-data/fixtures/` 就是 Digital Twin 的雏形。

| 外部依赖                | 你现在的状态                | Digital Twin 需要什么  |
| ------------------- | --------------------- | ------------------ |
| AWS DynamoDB/S3/SQS | aws-sdk-client-mock ✅ | LocalStack         |
| Neon PostgreSQL     | test 环境真实连接 ⚠️        | pg Docker 容器       |
| Bedrock/Kimi K2     | expected-outputs/ ✅   | 已有，包装成 HTTP server |
| Deepgram            | 真实 audio 文件 ⚠️        | 固定转录结果 mock        |
| RingCentral         | 完全没有 mock ❌           | WireMock 录制回放      |

**从现在到 Digital Twin 的具体步骤：**

```bash
# Step 1（今天就能做）：LocalStack
docker run -p 4566:4566 localstack/localstack
# 测试时 AWS_ENDPOINT_URL=http://localhost:4566

# Step 2（中等难度）：录制 RingCentral 响应
npx wiremock --record-mappings --proxy-all=https://platform.ringcentral.com
# 跑一次真实 RC webhook，之后永远回放

# Step 3（你已 80% 完成）：把 expected-outputs/ 包装成本地 HTTP server
```

***

## 五、你现在的位置

| 已有（好的基础）                                                                                      | 缺的（待确认：需在代码 repo 验证）                         |
| --------------------------------------------------------------------------------------------- | -------------------------------------------- |
| 每个 repo 有 CLAUDE.md                                                                           | Agent 专属 IAM role（test env only）待确认          |
| 详细设计文档（GAP table）                                                                             | circuit breaker（max\_turns, cost ceiling）待确认 |
| GitHub Actions CI/CD 全套                                                                       | Langfuse 可观测性 待确认                            |
| Discord webhook                                                                               | Agent 自动触发 integration test 待确认              |
| test-data/fixtures/（Digital Twin 雏形）                                                          |                                              |
| Pre-commit hooks                                                                              |                                              |
| Integration test 脚本                                                                           |                                              |
| execution-policy.md（`.claude/rules/execution-policy.md`，每个 repo 均已有）                          |                                              |
| Agent-executable issue template（完整模板已在 playbook 中，保存为 `.github/ISSUE_TEMPLATE/agent-task.md`） |                                              |
| working-memory/ 文件夹（`.claude/working-memory/`，含 `_template.md`）                               |                                              |

**你和 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 真正能自主工作，文档体系需要满足三层：

```
docs repo（战略层）        = 跨 repo 设计 + 产品知识 + system-overview
代码 repo（战术层）        = feature spec（requirements.md + tasks.md）+ 本服务 ADR
CLAUDE.md（指针层）        = 精简，只存命令 + 指向文档的链接
execution-policy.md（决策层）= agent 遇到分叉时的判断规则
```

**product/changelog.md**（解决设计师的信息流断裂）：

```markdown
## 2026-03
- ✅ CUSTOMER_HISTORY 注入 — 历史通话数据已注入 AI 分析，相关 repo: callytics-infrastructure，PR: #123
- 🚧 客户温度分级 — 进行中
```

产品视角，不用 `feat/fix` 前缀，让设计师在 GitHub web UI 就能看到"最新实现了什么"。

**两类文档的区别**（决定放哪里）：

|          | 发布型            | 上下文型                                      |
| -------- | -------------- | ----------------------------------------- |
| **目的**   | 给人类读（设计师、新工程师） | 给 agent 读                                 |
| **内容状态** | 稳定、经过 review   | 可以是草稿、WIP                                 |
| **典型例子** | 产品功能设计、系统架构    | execution-policy、working-memory、prompt 草稿 |

> 详细的文档组织策略参见 [doc-structure-for-agents.md](/ai/factory/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：无限循环烧钱**

| 事故                             | 损失      |
| ------------------------------ | ------- |
| API 失败无限重试，一夜                  | $86     |
| 图片生成循环，3 天                     | $700    |
| K8s 为修语法错误无限开集群                | $12,000 |
| 4 个 LangChain agent 互相问对方，11 天 | $47,000 |

根本原因：没有 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）

| Bug 类型    | AI vs 人类 |
| --------- | -------- |
| 逻辑错误      | 1.75x 更多 |
| 安全漏洞      | 1.57x 更多 |
| 过多 I/O 操作 | 8x 更多    |
| XSS 漏洞    | 2.74x 更多 |

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 依赖是幻觉（不存在的库）。

最危险的形式：

```
Step 2：幻觉一个不存在的 method()
  → Step 7：写测试验证这个 method
    → Step 12：数据写入数据库
      → 你发现时，4 个系统已经被污染
```

额外风险：攻击者发现 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 / 安全漏洞**

| CVE            | 工具             | 后果                                |
| -------------- | -------------- | --------------------------------- |
| CVE-2025-49150 | Cursor         | 读 SSH key 后外泄                     |
| CVE-2025-53773 | GitHub Copilot | 修改 IDE 设置实现代码执行                   |
| CVE-2025-32711 | MS 365 Copilot | 收一封邮件就自动外泄 Google Drive（CVSS 9.3） |

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 快照，各自做合理但互相冲突的决定：

```
Agent A 实现 JWT auth
Agent B 不知道，独立实现 session auth
集成时：两套 auth 互相冲突
```

**问题 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 说"用 JWT"
→ Agent A 实现 JWT，发现已有 session context，接入了，但没更新 spec
→ Agent B 读旧 spec，实现第二套 JWT
→ 现在有两套 auth，两套都和 spec 不完全匹配
```

解法：spec 提交到 repo，agent 做了架构决策必须同一个 PR 更新 spec。

### 🟡 可观测性 & 基础设施

**问题 15：不知道 agent 做了什么**

过夜运行后最少需要记录：

- 哪个 agent 跑了哪个任务 + 改了哪些文件
- 每次迭代测试结果
- token 消耗和成本（每个 agent）
- 每步耗时（同一步突然 20x 时间 = 在循环）
- 退出原因（完成 / token 耗尽 / 错误上限 / 放弃）

推荐工具：[Langfuse](https://langfuse.com)（开源 MIT，自托管，任何框架）

**Langfuse 快速接入（Node.js / TypeScript）：**

```bash
npm install langfuse
```

```typescript
import { Langfuse } from "langfuse";

const langfuse = new Langfuse({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY,
  secretKey: process.env.LANGFUSE_SECRET_KEY,
  baseUrl: "https://cloud.langfuse.com", // 或自托管地址
});

// 每个 agent 任务开始时创建 trace
const trace = langfuse.trace({
  name: "agent-task",
  metadata: {
    taskId: "gap-3",
    repo: "callytics-infrastructure",
    agent: "worker-1",
  },
});

// 记录每一步
const span = trace.span({ name: "write-code", input: { file: "handler.ts" } });
span.end({ output: { linesChanged: 42 }, level: "DEFAULT" });

// 记录测试结果
trace.event({
  name: "test-result",
  metadata: { passed: true, coverage: 83, attempt: 1 },
});

// 任务结束
await langfuse.flushAsync();
```

**Claude Code 集成（在 `--enable-auto-mode` 下）：**

在 execution-policy.md 里加：

```markdown
## 可观测性
- 每个任务开始时记录 trace（taskId、repo、agent名）
- 每次测试运行记录结果（通过/失败、覆盖率、第几次重试）
- 每步耗时 > 5 分钟时记录 warning event
- 任务结束时记录退出原因
```

**自托管 Langfuse（推荐，数据不出去）：**

```bash
# docker-compose 一键起
git clone https://github.com/langfuse/langfuse
cd langfuse && docker compose up -d
# 访问 http://localhost:3000
```

**git-ai — 代码行级 AI 归因（任务级 vs 行级的区别）：**

Langfuse 追踪"这个任务跑了哪些步骤、用了多少 token"；git-ai 追踪"这行代码是哪个 AI session 写的"——两者互补：

- `git ai blame` — 显示每行代码的 AI model + session + 时间戳
- `/ask` skill — 查询原始 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**

三种形式：

1. Context window 满了 → 自动压缩 → 丢掉具体文件路径、错误码、架构决策
2. 信息在 context 中间 → LLM 注意力降权 → "看不见"（即使还在窗口里）
3. 任务太长（>30 分钟）→ 模型推理质量线性下降

解法：把关键信息外化到文件：

```
CLAUDE.md                  = 永久记忆（规范、约束）每次 session 自动加载
TodoWrite                  = 任务进度（做到哪了）
.claude/working-memory/    = 任务决策（发现了什么、决定了什么）
CHANGELOG.md               = 完成记录
```

context 可以丢，文件不会丢。

**问题 17：基础设施脆弱性**

每个新版本都带来新的基础设施 bug：tmux race condition、MCP server 连接失败、credential 过期、Docker socket 权限。不要完全依赖 orchestration 工具，要有手动 fallback。

***

## 七、优先行动清单

### 🔴 今天就做

| 行动                           | 工作量    | 效果                             |
| ---------------------------- | ------ | ------------------------------ |
| 开启 `--enable-auto-mode`      | 0 分钟   | 立刻减少 80% 权限询问                  |
| 写 `execution-policy.md`      | 1-2 小时 | 消除"应该用什么"类问题                   |
| 安装 `git-ai`（AI 代码行级归因）       | 5 分钟   | 过夜 agent 跑后能追踪每行代码来自哪个 session |
| 创建 agent-executable issue 模板 | 30 分钟  | 让 issue 本身驱动执行                 |
| PR 规则：测试文件改动 → 必须人工 review   | 10 分钟  | 防止 agent 作弊删测试                 |

### 🟡 下周做

| 行动                                        | 工作量   | 效果              |
| ----------------------------------------- | ----- | --------------- |
| 专属 agent IAM role（只有 test 权限）             | 2 小时  | 从根本上隔离 prod     |
| circuit breaker（max\_turns, cost ceiling） | 1 小时  | 防止烧钱循环          |
| Langfuse 接入                               | 半天    | 过夜 agent 需要可观测性 |
| working-memory/ 文件夹规范                     | 1 小时  | 对抗 context 丢失   |
| execution-policy.md 加 Park & Notify 规则    | 30 分钟 | agent 自己决定何时打断你 |

### 🟢 成熟后做

| 行动                                         | 工作量    | 效果               |
| ------------------------------------------ | ------ | ---------------- |
| LocalStack（DDB/S3/SQS 本地化）                 | 1 天    | Digital Twin 第一步 |
| WireMock 录制 RingCentral                    | 1 天    | 不依赖真实外部服务        |
| 分级 review 流程（15/70/15）                     | 设计 1 天 | PR 不再是瓶颈         |
| Orchestrator 并行 agent（ComposioHQ/Open SWE） | 1 周    | 真正实现隔夜批量 PR      |

***

## Sources

- [Stripe Minions Part 1](https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents)
- [Stripe Minions Part 2](https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents-part-2)
- [StrongDM Software Factory](https://factory.strongdm.ai/)
- [StrongDM Digital Twin Universe](https://factory.strongdm.ai/techniques/dtu)
- [Claude Code Sandboxing](https://www.anthropic.com/engineering/claude-code-sandboxing)
- [Claude Code Auto Mode](https://www.anthropic.com/news/enabling-claude-code-to-work-more-autonomously)
- [ComposioHQ Agent Orchestrator](https://github.com/ComposioHQ/agent-orchestrator)
- [LangChain Open SWE](https://github.com/langchain-ai/open-swe)
- [Devin Interactive Planning](https://docs.devin.ai/work-with-devin/interactive-planning)
- [git-ai](https://github.com/git-ai-project/git-ai)
- [CodeRabbit AI vs Human Code Report](https://www.coderabbit.ai/blog/state-of-ai-vs-human-code-generation-report)
- [MetalBear Self-Correcting AI](https://metalbear.com/blog/self-correcting-ai/)
- [Agentmaxxing](https://vibecoding.app/blog/agentmaxxing)
- [E2B Pricing](https://e2b.dev/pricing)
- [Langfuse](https://langfuse.com)