Agentic Software 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，把所有常见分叉的答案预先写死：

# 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：

---
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

# 启动时开启
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/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/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 了解如何组织文档。

其他可用工具

工具	Stars	特点
ComposioHQ/agent-orchestrator	4.1k	最接近你要的：读 issue/spec → 拆任务 → 并行 worktree → CI 失败自动路由
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（防止烧钱循环）

{
  "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 里写清楚：

## 验证步骤（必须全部通过才能开 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 的具体步骤：

# 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（解决设计师的信息流断裂）：

## 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。

真实公司案例对比

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（开源 MIT，自托管，任何框架）

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

npm install langfuse

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 里加：

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

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

# 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
• 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