AI Coding Agent 的天花板：不是模型，是你的代码库

我在一个开源自动化平台工作。我们有 12 个工程师，花了几个月时间试图回答一个问题：

为什么 Claude Code 在我笔记本上的空白 Next.js 项目里表现炸裂，但在我们自己的代码库里像个刚入职的实习生？

答案不是模型不够强。不是。

是我们的代码库没有给 AI 配备"马鞍"。

这个概念，海外社区叫 AI Harness——AI 马具。我觉得翻译成"AI 配套体系"更直观：它是让你的 AI 从 raw power 变成靠谱助手的全套基础设施。

这篇文章是我们团队摸出来的经验，不是什么"10 倍效率提升"的 hype，是踩坑记录。

Part 1：大家都忽略的脏秘密

每次有新一代模型发布，Twitter 就炸锅。基准测试涨了 3%，然后有人说 Claude 死了，GPT 回来了。六小时后反转。一周后继续反转。

但真正在工程团队里用这些工具的人，看到的是另一个画面：

工程师说："加一个 webhook 日志功能。"

AI：新建了一个 entity
AI：忘了在 getEntities() 里注册
AI：写查询时没加 projectId 过滤
AI：从 src/app/ee/ 导入了企业版代码到社区版
AI：用了 PUT 而不是 POST
AI：编了一个不存在的 safeFetch 函数

工程师："不不不，不是这样的……记得用我们的品牌色……"

这是模型的错吗？

一部分是。但大部分不是。

模型不知道你的代码库有多租户规则。它不知道你们用 TypeORM 但不自发现 entity，必须手动注册。它不知道 src/app/ee/ 是企业版，从社区版导入会破坏自托管用户的构建。它不知道你们三年前因为 PATCH 语义出过 bug，所以所有 create 和 update 接口都统一用 POST。

它不知道这些，是因为你没告诉它。

你把一个顶级大脑扔进一个 20 万文件的鬼屋，不给地图，不给规则，不给词汇表，然后它踩到耙子，你还生气。

这不是模型的问题。这是马鞍的问题。

Part 2：什么是 AI Harness？

AI Harness（AI 配套体系）：让 AI agent 从"通用强大"变成"在你的代码库里靠谱输出"所需要的全部文件、目录结构、约定和基础设施。

类比：马本来就很强壮。马鞍才让你真的能骑上去并且去你想去的地方。

一个完整的 AI Harness 包括这些部分：

1. 始终加载的指令（Always-On Instructions）

每个 session 启动时自动加载的架构规则、约定、坑点说明。

不是 README 里的一行"用 TypeScript"就完了，是：
- 项目架构是什么（CE 和 EE 分离原则）
- 什么是 piece，什么是 plugin，为什么不能混用
- 哪些目录是企业版专用，社区版不能 import
- 你们的 API 风格（为什么用 POST 不用 PATCH）

2. 安全反射（Safety Reflexes）

一些小的、具体的规则，用来catch 最贵的错误。

比如：
- "任何数据库查询必须有 projectId 过滤，否则会泄露跨租户数据"
- "不允许从 ee/ 目录向 CE 代码 import"
- "创建 entity 后必须在 getEntities() 里注册"

这些是你们团队用血泪教训换来的，AI 每次都会踩的坑。

3. 按需上下文（On-Demand Context）

AI 需要时再获取的文档、词汇表、Schema。

不是把所有东西都塞进 system prompt（会塞不下），而是让 AI 知道"需要的时候去哪找"。

比如：
- docs/pieces-api.md - Piece 开发规范
- docs/auth-flow.md - 认证流程详解
- docs/db-schema.md - 数据库 Schema 说明

4. 成文的 Workflow（Codified Workflows）

把"做这个需要五步"变成一个命令。

Slash commands 或 skills：
- /new-piece - 创建一个新 Piece 的完整流程
- /add-endpoint - 添加 API endpoint 的标准步骤
- /write-test - 写测试的正确方式

5. 范围化的子 Agent（Scoped Subagents）

专门的 Agent 待在各自的 lane 里。

比如：
- 专门处理数据库的 Agent
- 专门处理前端的 Agent
- 专门处理第三方集成的 Agent

好处：不会让通用 Agent 跨域乱改，最后改出一堆冲突。

6. 外部集成（MCPs）

Model Context Protocol，让 Agent 能访问你的工具：Linear、Postgres、浏览器等。

Agent 可以直接查 Linear 看当前 sprint，可以直接跑 SQL 验证数据，而不是让你手动复制粘贴。

7. Session 卫生（Session Hygiene）

清 context 的时机、并行工作方式、以及知道什么时候该放弃重来。

Part 3：真正的解锁——先计划，再执行

在我们找到 AI Harness 之后，发现真正的解锁是另一件事：

计划先行，执行在后。

AI 最擅长的不是写代码，是写计划。

给你们看一个真实的转变过程——我们让 AI 实现一个"凭证管理器"功能：

第一次尝试（直接执行）：

用户：实现凭证管理器
AI：*开始写代码*
结果：Claude Code 创建了一个不存在的 entity，忘了注册，导入路径错误，第一次冲刺结束后发现生产环境有 bug。

第二次尝试（先计划）：

用户：实现凭证管理器，先给我一个计划
AI：*花 5 分钟写出详细计划，包括：*
  - 需要新建哪些文件
  - 需要修改哪些现有文件
  - 数据库迁移步骤
  - 需要注册的 entity 列表
  - 潜在的冲突点
用户：确认后继续
AI：*按计划执行，两轮迭代后生产就绪*

区别在哪？

第一次，AI 在黑暗里摸象。
第二次，AI 有了地图。

我们现在的流程是：任何功能开发，AI 第一步永远是出计划，人 review 确认，第二步才开始写代码。

这听起来慢，但其实快。因为省去了来回修改错误的时间。

Part 4：我们是怎么从零开始搭这套体系的

第一步：audit 你们现有的 tribal knowledge

很多团队意识不到自己有多少"隐式规则"。

我们的方法是：故意让 AI 犯错，然后记录下来。

连续一周，每次 AI 犯错了，就记下来：
- 犯的什么错
- 为什么这个错是错的（你们团队的特定原因）
- 怎么避免

一周后，我们有了一个"AI 踩坑清单"。然后把这些坑变成安全反射规则。

第二步：把 tribal knowledge 变成文档

清单有了，下一步是结构化。

docs/
├── architecture/
│   ├── ce-vs-ee.md          # 社区版vs企业版分离原则
│   ├── pieces-vs-plugins.md # Piece vs Plugin 区别
│   └── api-conventions.md   # API 设计约定
├── database/
│   ├── schema.md            # 数据库Schema
│   └── entity-rules.md      # Entity注册规则
├── frontend/
│   └── component-library.md # 组件库使用规范
└── workflows/
    ├── new-piece.md         # 新建Piece流程
    ├── add-endpoint.md      # 添加API流程
    └── run-tests.md         # 测试流程

每个文档不需要长，核心是：把这个团队"想当然"的东西写出来。

第三步：建立 Slash Commands

我们用 Cline，内置支持 custom commands。

// .cline/commands.json
{
  "new-piece": {
    "description": "创建一个新的 Piece",
    "prompt": "按照 docs/architecture/pieces-vs-plugins.md 和 docs/workflows/new-piece.md 的规范，创建一个新的 Piece。确认以下信息：1) Piece类型 2) 需要的权限 3) 认证方式"
  }
}

这样每次说 /new-piece，AI 就会按你们的标准流程走，而不是自己想当然。

第四步：选对 MCPs

MCPs = Model Context Protocols，让 AI 能真正操作你的工具。

我们配的：
- Postgres MCP：让 AI 直接跑 SQL，验证数据模型
- Linear MCP：让 AI 查 issue 状态，更新 sprint
- File System MCP：让 AI 读写文件（本来就有，但配置了权限边界）

配 MCP 的原则：不要配太多。只配 AI 真正需要用来完成工作的。多了会乱。

Part 5：这套体系的天花板在哪

说完了这套体系怎么搭，必须说它的局限。

模型能力还是有上限的。

Harness 能让 AI 少犯蠢，但不能让 AI 变聪明。

我们发现：
- 500 行以内的任务，AI 几乎总能搞定
- 1000 行以上的任务，需要拆成多个子任务，否则 AI 会迷路
- 涉及架构决策的任务，AI 只能给建议，最终还是要人拍板

Harness 不是银弹，它是基础设施。模型还是那个模型，基础设施好了，模型的潜力才能发挥出来。

另一个局限：维护成本。

Harness 不是一次性搭建完就完了。代码库在变，流程在变，Harness 也得跟着变。

我们现在的做法是：每次代码审查，发现新的"AI 又踩这个坑了"，就同步更新 docs/ 里的对应文档。文档即代码审查的副产物。

这其实也是好事——它强迫你把 tribal knowledge 外化，新人加入时也能看到这些知识。

Part 6：落地建议

如果你想在自己团队试这套体系，从哪开始？

最小可行版本：CLAUDE.md

不用一上来搭整套体系。先建一个 CLAUDE.md（或者叫 AGENTS.md，看你们用哪个工具），内容只要包含：

项目架构概述（一段话）
关键约定（bullet points，不要超过 20 条）
最大的坑（AI 最容易犯的错误 top 3）
常用的 workflow（新建功能的标准步骤）

这四条能解决 50% 的"AI 在代码库里发疯"问题。

之后根据需要再扩展。

指标怎么定？

我们内部不追"AI 完成了多少 story points"，追的是：

AI 出品的代码，一轮 review 能过的比例
AI 产生的 bug，需要回滚的比例
每个工程师每天 review AI 代码花的时间

这三个指标在 AI 配套体系不完善时很高，完善后应该显著下降。

我们目前的状态：AI 出品代码一轮 review 通过率约 70%，比三个月前的 20% 好多了，但还没到 90% 的目标。

总结

AI coding agent 的瓶颈，90% 不是模型能力，是上下文工程。

你的代码库就是 AI 的工作环境。你不会把一个新员工扔进一个没有文档、没有交接、没有 onboarding 流程的代码库，然后期待他第一周就产出对吧？

AI 也是一样。

这不是"AI 不够好"，是"我们没有给 AI 准备好它需要的东西"。

搭好 AI Harness，模型还是那个模型，但你会有一个真正能用的 AI 助手，而不是一个会编不存在函数的玩具。

本文是对 The AI Harness: why your AI coding agent is only as smart as the repo you put it in 的深度解读，结合了我在团队中实践 AI coding 工具的经验。

你也在用 AI coding 工具吗？遇到了什么问题？欢迎留言交流。

📑 目录