反框架宣言：AI Agent 的 12 条军规

格帕文士 · 深度解读 项目：humanlayer/12-factor-agents | 21.7k Stars 作者：Dex Horthy，YC 创业者，HumanLayer CEO

一个 Markdown 仓库，凭什么两万星？

打开这个仓库，你会看到什么？

没有 npm install。没有 pip install。没有一行可运行的框架代码。只有 Markdown 文件，十二篇短文，每篇讲一条原则。

而它的 Star 数已经超过两万。

Dex Horthy，HumanLayer 的创始人，YC 校友。他访谈了超过一百个 AI 创业者，发现一个反直觉的共性：市面上自称"AI Agent"的产品，大多不怎么 agentic。它们不是"给模型一个目标、一袋工具、让它自己循环直到完成"的自主系统。相反，它们是确定性代码为主体，只在关键决策点撒上几粒 LLM 的魔法粉末。

这套原则不是教你造一个更聪明的 Agent。它是教你：别造 Agent。造可靠的软件，让 LLM 在正确的位置做正确的事。

12 条军规速览

核心洞察一：Dumb Zone——上下文的 40% 诅咒

Dex Horthy 分析了 10 万次开发者会话，发现一个 empiric 规律：

上下文窗口填满约 40% 后，模型的指令跟随能力断崖式下跌。

他管这叫"Dumb Zone"（笨蛋区）。过了这条线，模型开始漂移、幻觉、忘记自己的任务。不是模型变笨了，是注意力被稀释了——Transformer 的 softmax 注意力是零和游戏，token 越多，每个 token 分到的注意力越少。

Stanford 的"Lost in the Middle"研究（2023）已经证实：LLM 对上下文中间位置的信息 recall 显著低于开头和结尾。20 个文档放在上下文中，答案埋在中部，准确率暴跌 20 分以上。

这意味着什么？

• 上下文窗口不是越大越好。100 万 token 的窗口，真正可靠的只有前 40 万。
• 每塞一个 MCP 定义、每一行工具文档，都在消耗注意力预算。CLAUDE.md 写得越长，模型理解你代码的能力就越弱。
• 子 Agent 的真正价值不是分工，是隔离上下文。让研究 Agent 去读 50 个文件，主 Agent 只看它的 500 字总结。各用各的窗口，互不污染。

Claude Code 的实践验证了这个阈值：新手会话控制在 40% 以下，老手 aggressively 压到 30%。超过 60% 必须 /clear 或 /compact。

核心洞察二：最好的 AI 产品，根本不"Agentic"

Dex 访谈了 100+ 创业者，发现成功的 AI 产品有一个共同模式：

大部分是确定性代码，只在关键决策点插入 LLM。

不是"给模型一个目标、一袋工具、让它自己循环"。是"代码走流程，走到不确定的分叉口，问一句 LLM 该怎么走，然后继续走代码"。

这颠覆了 Agent 框架的叙事。LangChain、CrewAI、AutoGPT 的愿景是"让 LLM 接管一切"。Dex 说：别接管。协作。LLM 做它擅长的（理解意图、处理歧义、生成创意），代码做它擅长的（精确执行、状态管理、错误处理）。

Agent 循环的伪代码看起来很美：

while not done:
    next_step = llm.determine_next_step(context)
    context.append(next_step)
    result = execute(next_step)
    context.append(result)

实际生产中，这个循环会：累积错误、上下文膨胀、状态漂移、无限循环。Dex 自己试遍了所有框架，从 plug-and-play 的 Crew/LangChain 到"生产级"的 LangGraph，结论是——80% 容易做到，最后 20% 必须把框架拆了自己重写。

核心洞察三："无框架"不是裸奔，是拿回控制权

12-Factor Agents 最叛逆的一点：它拒绝成为框架。

没有 npm install。没有抽象层。没有替你管提示词的黑盒。每条原则都是一句断言，你自己决定怎么实现。

这和 Heroku 的 12-Factor Apps 一脉相承。Heroku 也没给你框架，它给了 12 条原则——无状态进程、配置存环境变量、端口绑定——这些原则变成了云原生时代的共同语言。

Dex 想对 AI Agent 做同样的事。他不卖工具，他在命名和归类已经存在的好实践。当你说"Factor 3：Own Your Context Window"，团队立刻知道你在谈什么。

Anthropic 已经在产品里默默实践这些原则：

• Plan Mode = Factors 2, 3, 8：你自己控制提示词、上下文保持聚焦计划而非执行产物、你自己决定何时开始编码
• 并行子 Agent = Factor 10：Claude Code spawn 轻量级 Haiku Agent 并行探索代码库，各拿隔离上下文，返回浓缩发现后销毁
• CLAUDE.md = Factor 3：项目级指令文件，精心挑选的上下文，每个 token 都是为 Claude 的注意力付费

实操建议：从哪条开始？

Dex 的建议：不必 12 条全上。挑最痛的点。

1. 如果你只有一小时：做 Factor 3。打开 Claude Code，敲 /context，看看你塞了多少垃圾。删掉 MCP 定义里用不到的工具。把 CLAUDE.md 砍到 500 字以内。

2. 如果你有一周：加 Factor 10。把一个臃肿的"万能 Agent"拆成三个：一个分类意图，一个检索数据，一个执行操作。中间用结构化 JSON 传话。

3. 如果你有一个月：加 Factor 5 和 6。把 Agent 的状态和业务系统的状态合并到同一个数据库表。给每个不可逆操作加 HUMAN_APPROVAL_REQUIRED 暂停点。

4. 如果你重构一个现有产品：Factor 1 和 8。把"让 LLM 直接操作数据库"改成"LLM 输出 JSON，代码执行 SQL"。把框架控制的 Agent 循环改成你自己写的显式状态机。

一个微妙的信号

发布当天，这个仓库涨了 700+ Stars，霸占 Hacker News 首页一整天。

为什么火了？

因为开发者受够了框架的魔法承诺。"你只需要写 prompt，剩下的框架帮你搞定"——这句话在 demo 里成立，在生产里破产。12-Factor Agents 没有承诺魔法，它说：你自己管。但我会告诉你管什么、为什么。

另一个信号：Dex 在 Talk 里提到，Manus AI（那个一度很火的通用 Agent）重写了四次框架才学会这些原则。Anthropic 的"Building Effective Agents"官方指南也在讲同样的故事——小 Agent、显式编排、人在回路。

行业正在收敛。不是往"更自主的 Agent"收敛，是往"更可控的 LLM 增强软件"收敛。

结语

12-Factor Agents 的价值不在技术新颖性。每条原则都似曾相识——状态分离、错误压缩、小服务、人在回路——这是软件工程几十年的老智慧。

它的价值在命名和归类。当 Dex 说"Dumb Zone"，团队立刻理解上下文管理的紧迫性。当他说"Factor 10：Small, Focused Agents"，架构评审有了共同语言。

两万 Star 投给的不是一个仓库。投的是一种态度：别被框架绑架，别被 Agent 叙事催眠。LLM 是强大的工具，但工具要在人的手里，按人的意图，做可靠的事。

Dex Horthy 在自己的 Talk 里说了句话，可以作为这 12 条军规的注脚：

"Do not outsource the thinking. AI can only amplify the thinking you've already done."

参考来源：

• 12-Factor Agents 官方仓库：https://github.com/humanlayer/12-factor-agents
• 项目主页：https://www.humanlayer.dev/12-factor-agents
• Dex Horthy AI Engineer Summit 演讲 "No Vibes Allowed"（2025-11）
• Anthropic "Building Effective Agents" 官方指南
• Stanford "Lost in the Middle"（TACL 2024）
• Chroma Research "Context Rot: How Increasing Input Tokens Impacts LLM Performance"

#AI #Agent #软件工程 #LLM #深度解读 #格帕文士