人设计系统，AI 在系统内可靠执行
2026年了，你每天打开 IDE 的第一件事是什么？
我猜是跟 AI 打招呼。
Cursor、Claude Code、Trae……这些工具已经从"尝鲜玩具"变成了日常开发的一部分。据统计，超过 80% 的开发者每天都在用 AI 辅助编程。
但有一个现象值得注意：
模型越来越强，可开发效率的提升似乎并没有那么明显。
回想一下过去一周的工作：
- AI 帮你生成的代码，看着没问题，跑起来却报错
- 改了一个接口字段，漏掉了几个引用的地方
- 前后端类型不同步，到运行时才发现
- 团队里每个人用 AI 生成的代码，风格不太一样
这些问题的原因可能不在 AI 本身。我在一个多 Repo 项目里折腾过一段时间之后，逐渐有了一个感受：
项目结构的方式，会直接影响 AI 能发挥多大的作用。
这篇文章想分享的，是两套在实践中被验证有效的方案：Monorepo 和 Harness Engineering。它们分别从"结构"和"执行"两个层面，帮助 AI 更好地融入开发流程。
原文地址
墨渊书肆/AI双层代码治理：Monorepo × Harness Engineering
一、AI 在多 Repo 项目中遇到的常见问题
1.1 上下文不完整
假设你的项目是这样组织的：
frontend-repo/ # 前端（Git仓库A）
admin-repo/ # 管理后台（Git仓库C）
backend-repo/ # 后端（Git仓库B）
这在很多团队中是很常见的做法。
现在你在 backend-repo 里，让 AI 帮你改一下 User 接口，加一个 role 字段。AI 打开文件——它只能看到 backend-repo 里的内容。前端的调用方式？不清楚。管理后台有没有用到？不相关。
于是 AI 改完了后端的 DTO。你去前端跑了一下——类型报错了。手动改了前端。去管理后台又跑了一下——又报了。再改后台。跑测试——用例挂了。
最后花了半小时，手动改了好几个地方才把这个字段加完整。
这不是 AI 的问题。是你把信息分散在了多个仓库里，而 AI 每次只能看到其中一部分。
1.2 规范难统一
再看项目根目录下散落的配置：
.cursor/rules/xxx.mdc # Cursor 的规则
CLAUDE.md # Claude Code 的规则
.trae/rules/xxx.md # Trae 的规则
三份配置，写的其实是同一类东西：技术栈约定、命名规范、禁用的写法……
维护起来比较麻烦：改一条规则要同步三个地方，漏掉一个就开始出现风格不一致。而且你在 Cursor 里调好的逻辑，切到命令行用 Claude Code 时，AI 可能就不知道那些规则了。
1.3 重构时心里没底
假设你要把整个项目里的 userId 重命名为 user_id。
在多 Repo 项目里，你的内心戏大概是这样的：
apps/web/user.tsx → 改了吗？
apps/api/user.service.ts → 这个呢？
libs/types/index.ts → 共享类型库肯定要改
libs/utils/format.ts — 这里有用到吗？
admin/src/pages/users.tsx — 还有管理后台
你不确定自己改全了。AI 也帮不上太多——它看不到其他 Repo 里的文件。最后只能靠全局搜索 + 人工检查。
这种不确定感积累多了，就会让人不太敢做重构。不是不想做，是成本比较高，不如先凑合着来。
二、第一层：Monorepo（解决结构问题）
2.1 什么是 Monorepo？
简单来说：把多个项目放在同一个 Git 仓库里管理。
传统多 Repo：
repo-frontend/ → Git 仓库 A
repo-backend/ → Git 仓库 B
repo-admin/ → Git 仓库 C
Monorepo：
monorepo/
├── apps/
│ ├── web/ # 前端应用
│ ├── api/ # 后端服务
│ └── admin/ # 管理后台
├── libs/
│ ├── shared/ # 共享类型
│ ├── auth/ # 认证模块
│ └── ui/ # UI 组件库
└── package.json # 统一的依赖管理
这个概念并不新。Google、Meta、Microsoft、字节跳动等公司很早就在用了。不过在 AI 辅助开发的场景下，Monorepo 有了一些新的价值。
2.2 Monorepo 对 AI 开发的帮助
上下文更完整
回到前面那个场景：修改 User 接口，新增 role 字段。
多 Repo 的情况：
你：帮我在 User DTO 里加个 role 字段
AI：（扫描 backend-repo）
已经改好了。
你：（前端跑一下）
...TypeScript Error: Property 'role' does not exist
AI：我只能看到 backend-repo 的文件。
Monorepo 的情况：
你：帮我在 User DTO 里加个 role 字段
AI：（索引整个项目）
这个改动可能会影响这些文件：
1. libs/shared/src/dto/user.dto.ts （源头）
2. apps/api/src/users/service.ts （后端逻辑）
3. apps/api/src/users/controller.ts （API响应）
4. apps/web/src/api/user.ts （前端请求）
5. apps/web/src/components/UserForm.tsx （表单组件）
6. apps/admin/src/pages/users.tsx （管理后台）
7. libs/auth/src/permissions.ts （权限判断）
要我帮你更新全部引用吗？
你：好
AI：已完成。建议检查下数据库 migration 是否需要更新。
体验上的差别是：前者你可能要来回改好几次，后者一次到位还附带了后续建议。
根据一些社区调研和工具报告（如 Cursor 年度报告），在 Monorepo 项目中，开发者对 AI 生成代码的接受率通常会更高一些——因为上下文更完整，生成的内容更贴合实际需求。
重构更放心
还是 userId → user_id 的例子。在 Monorepo 里，AI 可以跨模块追踪引用：
正在重命名: userId → user_id
✅ apps/web/src/components/UserCard.tsx (L23)
✅ apps/api/src/dto/user.response.ts (L15)
✅ apps/api/src/services/user.service.ts (L89)
✅ libs/shared/types/index.ts (L42)
✅ libs/shared/utils/format.ts (L18)
✅ apps/admin/src/hooks/useUser.ts (L31)
完成。共修改 6 处引用。
建议运行 pnpm test 验证。
不用再靠全局搜索和人工逐一确认了。
依赖版本一致
多 Repo 项目里偶尔会遇到这种情况：
前端 repo 用 TypeScript 5.3
后端 repo 用 TypeScript 4.9
共享类型库用 TypeScript 5.1
→ 同样的类型语法在不同 repo 表现可能不一致
Monorepo 里，依赖在根目录统一声明，所有子项目共享同一版本，pnpm workspace 自动去重。版本冲突的问题基本不会出现。
2.3 Monorepo 的适用范围
| 适合 | 不太适合 |
|---|---|
| 中大型团队（3人以上） | 个人独立小项目 |
| 前后端分离且需要类型同步 | 模块之间完全独立 |
| 有多个共享模块或组件库 | 只用 AI 做单文件补全 |
| 希望 AI 能理解全栈上下文 | 团队对 Monorepo 工具链不熟悉 |
2.4 Monorepo 小结
Monorepo 主要解决的是结构层面的问题：让 AI 能看到完整的代码上下文，跨模块追踪引用，统一管理依赖。
但它不能保证 AI 生成的代码一定符合你的规范，也不涉及如何连接外部工具等问题。
这就需要第二层方案：Harness Engineering。
三、第二层：Harness Engineering（解决执行问题）
3.1 核心思路
2025 年底开始，业界逐渐形成了一个叫 Harness Engineering 的理念。核心公式：
Agent = Model + Harness
- Model：大模型本身（GPT-4、Claude 等），能力强但需要引导
- Harness：约束和引导系统，包括上下文规范、执行规则、演进机制
- Agent：最终交付给你的、相对可靠的助手
打个比方：Model 是马，Harness 是缰绳和马鞍，Agent 是你可以骑着去目的地的马。
没有 Harness 的 Model，就像没有马绳的马——有劲，但方向不好控制。
3.2 三根支柱
Context：让 AI 知道该做什么
2026 年的一个变化是 AGENTS.md 标准逐渐被更多工具支持。以前 .cursorrules 给 Cursor 用，CLAUDE.md 给 Claude 用，copilot-instructions.md 给 Copilot 用——各管各的。现在一份 AGENTS.md，主流 AI 工具都能读取。
# AGENTS.md 示例
## 技术栈
- 前端：Next.js 15 + React 19 + TypeScript 5.4
- 后端：Node.js 22 + Fastify + Prisma ORM
- 包管理：pnpm workspace + Turborepo
## 绝对禁令
- ❌ 禁止使用 any 类型
- ❌ 禁止直接操作 DOM（必须使用 Ref）
## 目录约定
- apps/web/ → Next.js 前端应用
- apps/api/ → Fastify 后端服务
- libs/shared/ → 共享类型和工具
- libs/ui/ → UI 组件库
不过项目大了之后，如果把所有规则都塞进一份文件，AI 每次启动都要读一大堆无关内容，Token 消耗比较大。
所以有了 .spec/ 地方自治 的设计：
monorepo/
├── .agents/
│ └── AGENTS.md # 中央宪法（全局规范）
│
├── apps/web/
│ └── .spec/
│ ├── components.md # 组件写法
│ └── routing.md # 路由规则
│
├── apps/api/
│ └── .spec/
│ ├── endpoints.md # 接口定义
│ └── error-handling.md # 错误处理
│
└── libs/ui/
└── .spec/
└── props-naming.md # Props命名
对比一下：
| 角色 | AGENTS.md | .spec/ |
|---|---|---|
| 定位 | 全局架构师 | 业务分析师 |
| 内容 | 技术栈、禁令、目录索引 | 业务流程、边界案例 |
| 变动频率 | 季度级 | 随需求迭代 |
| Token 成本 | 中等（每次加载） | 极低（按需加载） |
实际效果：当你在 apps/web/ 工作时，AI 加载 AGENTS.md + apps/web/.spec/ 就够了，不用读后端的规范。精准、省 Token。
Enforcement：让 AI 不能做错事
Context 解决"知道做什么"，Enforcement 解决"不能做错事"。
以 Cursor 的 .mdc 规则为例：
---
description: TypeScript 代码规范
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: true
---
rules:
- pattern: "any"
message: "禁止使用 any，请使用具体类型"
severity: error
- pattern: "console\\.(log|warn)"
message: "生产环境禁止 console.log"
severity: warning
强制执行分几层：
- Lint 层：ESLint/Prettier 自动格式化
- Rule 层：AI 规则引擎实时拦截违规代码
- Test 层：自动生成测试验证正确性
意思是：AI 生成代码时如果触犯规则，在生成阶段就会被拦住，而不是等到人工 Review 才发现。
Evolution：让 AI 越用越好
通过 MCP（Model Context Protocol），AI 可以连接外部工具：
{
"mcpServers": {
"database": {
"command": "npx",
"args": ["@modelcontextprotocol/server-postgres"],
"env": { "DATABASE_URL": "postgresql://localhost/mydb" }
},
"github": {
"command": "npx",
"args": ["@modelcontextprotocol/server-github"],
"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }
}
}
}
接上 MCP 之后，AI 能做的事情变多了：查数据库表结构来生成准确的类型定义、读 GitHub Issues 来理解需求背景、执行命令行完成部署和测试。
再加上 Skills（技能库）（固化常用操作流程）和 Feedback Loop（反馈循环）（根据接受/拒绝记录持续优化），AI 会随着使用越来越适配你的项目。
3.3 Harness 解决什么
| 问题 | 传统方式 | Harness 方式 |
|---|---|---|
| 规范不一致 | 维护 N 份配置 | AGENTS.md 统一标准 |
| AI 不知道项目约定 | 每次 Prompt 手动提醒 | Context 自动加载 |
| 代码质量靠人 Review | 累且容易漏 | Enforcement 强制拦截 |
| AI 不能连外部工具 | 手动复制粘贴 | MCP 协议集成 |
四、两层结合：Monorepo × Harness Engineering
4.1 分工关系
┌─────────────────────────────────────┐
│ Monorepo（结构层） │
│ │
│ 提供"视野"： │
│ • 上下文完整 — AI 看得到全项目 │
│ • 类型自动同步 — 改一处全局感知 │
│ • 跨项目重构 — 追踪影响范围 │
│ • 依赖统一 — 版本冲突减少 │
│ │
└─────────────────┬───────────────────┘
↓ 完整上下文流入
┌─────────────────────────────────────┐
│ Harness Engineering（执行层） │
│ │
│ 确保"准确"： │
│ • Context — AGENTS.md + .spec/ │
│ • Enforcement — 规则引擎 │
│ • Evolution — MCP + Skills │
│ │
└─────────────────┬───────────────────┘
↓ 可靠代码输出
🤖 全栈 AI 助手
简单说：
- Monorepo 提供完整的上下文（让 AI 看得全）
- Harness 确保执行的规范性（让 AI 做得对）
- 两者配合，效果比单独使用任何一种都更好
4.2 效果对比
| 维度 | 多 Repo | 仅 Monorepo | 仅 Harness | 两者结合 |
|---|---|---|---|---|
| 上下文完整性 | 有限 | 较好 | 单 Repo 内 OK | 完整 + 精准 |
| 规范一致性 | 各自为政 | 靠人工保证 | 统一标准 | 全局 + 局部自治 |
| 重构安全性 | 人工追踪 | 跨项目分析 | 单 Repo 内追踪 | 自动 + 可追溯 |
| AI 代码接受率* | ~40-50% | ~65-70% | ~55-60% | ~70-75%+ |
*注：以上数据综合自社区调研和部分工具报告（Cursor 2025、GitHub Octoverse 2025 等），具体数值因项目和团队而异，仅供参考
4.3 结合后的目录结构
monorepo/
│
├── apps/ # 应用层
│ ├── web/ # Next.js 前端
│ │ ├── .spec/ # 前端业务规范
│ │ └── AGENTS.md # 覆盖全局的前端指令
│ ├── api/ # Fastify 后端
│ │ ├── .spec/ # 后端业务规范
│ │ └── AGENTS.md
│ └── admin/ # 管理后台
│
├── libs/ # 共享模块
│ ├── shared/ # 共享类型 & 工具
│ ├── auth/ # 认证模块
│ └── ui/ # UI 组件库
│
├── .agents/ # 中央 AI 配置中心
│ ├── AGENTS.md # 项目宪法
│ ├── skills/ # 可复用技能库
│ └── mcp.json # 外部工具连接配置
│
├── .cursor/ # Cursor 配置
│ ├── rules/conventions.mdc
│ └── mcp.json
│
├── turbo.json # 构建编排
└── package.json
关键点：
.agents/AGENTS.md替代原来分散的多份配置文件.spec/实现地方自治，各模块维护自己的业务规范skills/提供可复用的 AI 工作流模板mcp.json让 AI 连接外部工具
总结
回到开头的问题：
模型越来越强，可开发效率的提升并没有那么明显。
现在答案比较清晰了：
- 结构问题（信息分散、上下文不全）→ 用 Monorepo 改善
- 执行问题（规范不一致、容易犯错）→ 用 Harness Engineering 改善
- 两者结合，AI 能更好地融入开发流程
几点体会：
人设计系统，AI 在系统内可靠执行。
与其追求更强的模型，不如给模型一个清晰的结构和明确的约束。
结构即生产力。 项目结构的优劣，会影响 AI 能发挥多大作用。
参考
概念与标准
工具
数据来源
- GitHub Octoverse 2025
- Cursor 2025 年度报告
- ETH Zurich: AI Context File Effectiveness Study (2025)
