AI双层代码治理：Monorepo × Harness Engineering

人设计系统，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 上下文不完整

假设你的项目是这样组织的：

bash 复制代码

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 规范难统一

再看项目根目录下散落的配置：

bash 复制代码

.cursor/rules/xxx.mdc              # Cursor 的规则
CLAUDE.md                 # Claude Code 的规则
.trae/rules/xxx.md               # Trae 的规则

三份配置，写的其实是同一类东西：技术栈约定、命名规范、禁用的写法......

维护起来比较麻烦：改一条规则要同步三个地方，漏掉一个就开始出现风格不一致。而且你在 Cursor 里调好的逻辑，切到命令行用 Claude Code 时，AI 可能就不知道那些规则了。

1.3 重构时心里没底

假设你要把整个项目里的 userId 重命名为 user_id。

在多 Repo 项目里，你的内心戏大概是这样的：

bash 复制代码

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 仓库里管理。

bash 复制代码

传统多 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 的情况：

md 复制代码

你：帮我在 User DTO 里加个 role 字段

AI：（扫描 backend-repo）
    已经改好了。

你：（前端跑一下）
    ...TypeScript Error: Property 'role' does not exist

AI：我只能看到 backend-repo 的文件。

Monorepo 的情况：

md 复制代码

你：帮我在 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 可以跨模块追踪引用：

md 复制代码

正在重命名: 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 项目里偶尔会遇到这种情况：

md 复制代码

前端 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 的理念。核心公式：

ini 复制代码

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 工具都能读取。

markdown 复制代码

# 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/ 地方自治 的设计：

bash 复制代码

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 规则为例：

yaml 复制代码

---
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 可以连接外部工具：

json 复制代码

{
  "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 分工关系

arduino 复制代码

┌─────────────────────────────────────┐
│         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 结合后的目录结构

bash 复制代码

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 能发挥多大作用。

参考

概念与标准

工具

Turborepo --- Monorepo 构建
Nx --- 内置 AI Agent Skills
Caliber --- AI 配置同步

数据来源

GitHub Octoverse 2025
Cursor 2025 年度报告
ETH Zurich: AI Context File Effectiveness Study (2025)