你是否遇到过：让AI写个功能，它却改了不该改的配置；让它修个bug，它把整个模块重写了一遍。问题不在AI不够聪明，而在于我们没给它套上缰绳。今天，我们就用一套叫做Harness的实战框架，让AI在你的项目里乖乖拉车，指哪打哪。

01 小白话简介：Harness是什么？

想象一下，AI是一匹千里马，跑得快、力气大，但性子也野。你直接撒手让它跑，它可能把你的田地踩得乱七八糟。而Harness（马具），就是那套缰绳、马鞍、嚼子——它不会限制马的能力，却能让你稳稳地驾驭方向，安全到达目的地。

在AI辅助编程里，Harness就是我们为项目搭建的一整套“规则+知识+流程”体系。它告诉AI：

✅ 哪些代码可以动，哪些是禁区

✅ 业务逻辑是怎么设计的，别再瞎猜

✅ 开发步骤按什么顺序走，别跳步

✅ 写完代码要怎么检查，别埋雷

下面这张图就是Harness的“物理形态”——我们项目里的目录结构。

repo/├─ AGENTS.md                             # 🗺️ OpenSpec全局导航├─ REVIEW.md                             # 🔍 只读评审标准├─ docs/                                 # 📚 项目知识库│  ├─ architecture/│  │  ├─ index.md                        # 🏛️ 架构总览│  │  └─ implicit-contracts.md           # ⚠️ 隐性约定/避坑指南│  ├─ product/│  │  └─ index.md                        # 📋 产品规则边界│  └─ standards/│     ├─ testing.md                      # 🧪 测试规范│     └─ database.md                     # 🗄️ 数据层规范├─ openspec/                             # 📖 OpenSpec执行区│  ├─ changes/│  │  ├─ <change_id>/                    # 🚀 当前变更│  │  │  ├─ specs/                       # 📐 工作原理│  │  │  ├─ proposal.md                  # 📝 需求拆解│  │  │  ├─ design.md                    # 🎨 技术方案│  │  │  └─ task.md                      # ✅ 任务清单│  │  └─ archive/                        # 📦 归档记录│  └─ specs/                             # 📘 系统现状说明├─ .trae/                                # 🔒 Trae约束核心│  ├─ settings.local.json.example        # ⚙️ 权限沙箱│  ├─ skills/                            # 🛠️ 专项能力集│  │  ├─ prepare-review/                 # 👀 预审审计│  │  ├─ spring-architecture-review/     # 🧱 分层合规│  │  └─ sql-risk-review/                # 🚨 SQL风控│  ├─ rules/│  │  └─ project_rules.md                # 🚦 AI行为准则│  ├─ agents/│  │  └─ reviewer.md                     # 🤖 独立审查代理│  └─ hooks/│     ├─ guard_write.py                  # 🛡️ 写入拦截│     ├─ ensure_change_context.py        # 🔗 上下文校验│     └─ run_checks.sh                   # ⚡ 自动化门禁├─ src/                                  # 💻 源代码├─ pom.xml                               # ⚙️ Maven配置└─ .gitignore                            # 🙈 Git过滤

别被它吓到，它其实是一张给AI看的藏宝图。

接下来我们就逐个拆解这些“零件”，看看它们怎么组成一套好用的马具。

02 基础铺垫：Harness核心组件详解

①AGENTS.md —— AI的导航地图

如果说 Harness 是一张城市交通网，AGENTS.md 就是立在市中心的巨型路牌。AI 进入项目后，第一眼就会寻找这个文件，它不负责讲细节，而是告诉你：谁在哪、往哪走、什么情况下找谁。

我们项目的 AGENTS.md 正是这样一个导航中枢：

项目结构导航：清晰标出前后端目录树——xxx_web/ 是 Vue3 前端项目，xxx_server/ 是多模块 Maven 后端项目。

关键文档导航：它不会把规则全塞进自己肚子里，而是充当“指路人”：想了解系统架构和隐性约定？docs/architecture/ 下应有尽有，按需自取。

规则与技能导航：它明确告诉 AI，项目级的硬性规则存放在 .trae/rules/project_rules.md，遇到拿不准的编码约束就去那里查。同时，.trae/skills/ 目录下挂载了多个“专项技能包”。

有了这份导航地图，AI 不再是一头扎进代码海洋乱游，而是先抬头看路，知道何时该减速、何时该拐弯、何时该呼叫支援。一句话：AGENTS.md 让 AI 从迷路的新人，变成目的明确的向导。

②docs/ —— 项目知识库，把经验喂给AI

docs/目录下放着经过梳理的显性知识：

• architecture/index.md：系统整体架构、模块划分、数据流向。

• architecture/implicit-contracts.md：核心中的核心，记录那些“代码里看不出来，但一碰就炸”的隐性约定。比如：“订单金额字段是分，不是元，前端乘100时注意浮点精度”“用户注销后是逻辑删除，关联表必须同步更新status”。

• product/index.md：产品规则，比如“VIP用户订单满99包邮，和普通用户满199包邮的逻辑分支在OrderService.calcFreight()里”。

• standards/testing.md和database.md：测试规范（要求单元测试覆盖率80%）和SQL编写规范（禁止select *，复杂查询必须explain）。

这些文档就像给AI做的“岗前培训”，把它从一张白纸训练成“懂业务的老兵”。

③ openspec/ —— 变更管理，让AI按工序造车

传统的AI对话：你提需求→AI直接输出代码→你发现漏了边界条件→反复修改。

Harness式的玩法：我们把一次开发拆成三个步骤，放在openspec/changes/<变更名>/下：

• proposal.md（提案）：说清要做什么、影响范围、不做什么。比如：“实现用户手机号登录，不涉及微信登录，本次只改LoginController和UserService”。

• design.md（设计）：技术实现细节。“在UserService新增loginByPhone方法，调用Mapper查询user表，匹配密码后生成JWT，同时记录登录日志到login_log表”。

• task.md（任务）：拆解成可执行的具体步骤，每完成一步打个勾。

- [ ] 创建feature-login分支- [ ] 编写UserMapper.selectByPhone方法并添加单元测试- [ ] 实现UserService.loginByPhone- [ ] 修改LoginController，新增/sms-login接口- [ ] 集成测试

AI拿到这一套文件，就会按照你的工序一步步推进，而不是一股脑丢给你八百行代码。

④.trae/ —— 核心约束层，硬核护栏

在.trae/下，我们为AI配上了技能、规则、子代理和钩子。

skills/ ：专项能力包

比如：

prepare-review/SKILL.md：在发起code review前，AI自动统计本次变更的文件、方法、复杂度，生成一份“审查摘要”。

spring-architecture-review/SKILL.md：检查分层是否违规（Controller里有没有直接调Mapper）、依赖方向是否正确。

sql-risk-review/SKILL.md：检查新增SQL是否用了select *、批量更新是否加了事务、索引使用是否合理。

rules/project_rules.md：项目级规则

比AGENTS.md更偏向行为约束。比如“写入文件前必须经过guard_write.py检查”“代码生成后自动运行编译”。

agents/reviewer.md：独立只读评审代理

它像一位严格的老师傅，只读你的代码，然后输出评审意见，连AI自己写的代码也审，把“灯下黑”的概率降到最低。

hooks/ ：硬护栏

直接限制文件操作：

guard_write.py：拦截对application.yml、pom.xml等核心配置的直接写入，必须走特定流程。

ensure_change_context.py：如果你没创建openspec/changes/xxx就开始改代码，AI会提醒你：“先建个change，把提案写了。”

run_checks.sh：每次代码生成后自动执行mvn compile和测试，不通过就打回重写。

以上所有零件组合在一起，就是一套完整的Harness。接下来，我们跑一遍真实流程，感受一下它怎么驾驭AI。

03 应用实践：用Harness开发一个“手机号+验证码登录”

假设我们接了一个新需求：用户可以用手机号加验证码登录。下面就是用Harness带着AI从0到1的全过程。

Step 1：创建变更，画出疆域

在openspec/changes/下新建目录sms-login，编写三个文件：

proposal.md

# 手机号验证码登录## 目标- 新增接口 POST /api/login/sms- 接收参数：phone, code- 校验验证码后，返回JWT token- 不涉及：注册、修改绑定手机号## 影响范围- LoginController.java- UserService.java- SmsCodeService.java（新增）- 新增login_log表记录

design.md

## 技术方案1. 新增SmsCodeService，提供sendCode()和verifyCode()，验证码5分钟有效。2. UserService新增loginBySms(phone, code)：   - 先verifyCode，失败抛BizException("验证码错误或过期")   - 根据phone查询user表，不存在抛BizException("用户未注册")   - 生成JWT返回3. LoginController新增/sms接口，调用service。4. 登录成功异步写入login_log。

task.md

- [ ] 创建sms-login分支- [ ] 新增SmsCodeService及实现- [ ] UserService补充loginBySms方法- [ ] LoginController添加接口- [ ] 更新login_log表相关逻辑- [ ] 编写单元测试（覆盖正常、验证码错误、用户不存在）- [ ] 运行sql-risk-review检查SQL

Step 2：AI动工，技能和护栏开始运作

在Trae（或其他AI IDE）中，我告诉AI：“请根据sms-login下的提案和设计，开始实现第1项任务”。

AI首先会读AGENTS.md和docs/architecture/下的文档，知道要用R<T>返回、遵循分层架构。

ensure_change_context.py钩子检测到当前有一个活跃的change，放行。

AI创建SmsCodeService接口和实现，写到src/main/java/.../service/下。guard_write.py检查写入路径，未命中核心配置文件，放行。

在UserService里写loginBySms方法时，AI从docs/product/index.md里查到“登录日志要记录IP和终端类型”，于是自动从Header里取了X-Forwarded-For和User-Agent填充到日志对象里。这归功于知识库的喂养。

代码写完，run_checks.sh自动执行mvn test，发现一个单元测试红色（因为mock的验证码返回了null），AI立刻收到失败信号，重新修正。

Step 3：发起Review，子代理上场

我需要为这次变更做代码审查。执行prepare-review技能（或在Trae中触发指令），AI会：

1. 扫描openspec/changes/sms-login/specs/下的实际变更文件（AI生成时自动记录了修改文件清单）。

2. 统计出：新增3个文件，修改2个文件，新增方法4个，SQL语句1条。

3. 生成审查摘要：“本次变更主要围绕手机验证码登录，核心逻辑在SmsCodeService.verifyCode，建议重点检查验证码有效期判断和防暴力破解。”

然后，我要求独立的reviewer代理（只读）对代码进行审查。它会基于REVIEW.md的标准：

4. 检查分层依赖：Controller → Service → Mapper，没有反向引用，通过。

5. 运行sql-risk-review技能：发现login_log表的INSERT语句没写列名，违反了standards/database.md的规范。代理给出建议：“请显式指定字段列表，避免后续表结构变更受影响”。

6. 指出UserService中的loginBySms方法过长（45行），建议抽取出组装JWT的私有方法。

AI根据评审意见二次修改，直到Review通过。

Step 4：归档与知识沉淀

开发测试完毕，代码合并。我们把sms-login整个change移动到openspec/archive/下。同时，把开发过程中踩的坑（比如：“验证码存储用Redis，key设计为sms:code:phone，要设置过期时间300秒”）更新到docs/architecture/implicit-contracts.md里，供后续AI参考。

到此，一次被Harness全程驾驭的AI编程圆满结束。

结语：AI时代，驾驭比放任更重要

很多人担心AI会取代程序员，其实工具越强，驾驭工具的能力就越值钱。Harness这样一套“知识+流程+规则+护栏”的体系，正是让我们从“用嘴喊AI干活”升级到“用系统指挥AI干活”。

无论是Trae、Claude还是Cursor，你都可以围绕自己的项目，逐渐沉淀出这样一套马具。当团队的新人、新AI助手进入项目时，它看到的不再是一堆散乱的文件，而是一张清晰的作战地图和一套标准化的作业流程。那时候你会发现，AI这匹千里马，真的能日行千里，还不乱踢人。

如果你也有自己的Harness故事，欢迎留言分享，我们一起给AI套上更好用的缰绳😂 有问题欢迎评论区交流～

欢迎关注

我知道你 “在看”