夜雨聆风你是否遇到过：让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套上更好用的缰绳😂 有问题欢迎评论区交流～
欢迎关注
我知道你 “在看”
