最近这段时间Harness这个词突然火了起来铺天盖地的营销文章让人看得眼花缭乱不少研发同学难免会慌这又是什么新风口我是不是又落后了其实大可不必焦虑Harness从来不是什么凭空出现的“黑科技”它更像是我们研发人早就一直在做的工程实践只是现在被正式定义、系统梳理有了一个统一的名字而已。很多人提到Harness第一反应就是“用AI多写点代码”但这其实是对它最大的误解。真正的Harness核心不是解放AI的生产力而是把AI装进一套可控、可审计、可复用的工程流程里让AI从“一个不受控的高效助手”变成“能稳定融入生产研发的工程能力”。对于我们日常开发的Java Spring Boot业务项目来说尤其是那些有一定历史包袱、需求以增量改造为主的系统最可怕的从来不是AI写不出代码而是AI在没有边界的情况下乱改代码不懂项目里的历史隐性约定把需求拆解、代码实现、评审验证混为一谈改完代码却不明确风险甚至触碰SQL、配置这类高风险区域而没有任何阻拦。基于一次真实的Java Spring Boot项目实践我整理出了这套Harness最佳实践从核心原则、适用场景、仓库组织到具体实践、流程复盘、落地顺序全方位拆解如何把Harness思想落地到实际项目中。需要说明的是Harness思想本身和编程语言无关弄懂了这套逻辑不管是Python、Go还是其他语言都能灵活复用。一、先抓核心Harness落地的4条关键原则如果把Harness的所有实践浓缩成最关键的几条原则我总结为4点这也是我们整个项目落地的核心指导思想记牢这4点就不会偏离Harness的本质。第一OpenSpec管变更生命周期。用/opsx:propose - /opsx:apply - /opsx:verify - /opsx:archive这一套流程管住“需求从提出到归档”的全过程让每一次变更都有迹可循、有章可依。第二AGENTS.md只当地图不当百科全书。AGENTS.md的核心作用是告诉AI“先看什么、按什么流程做”相当于一个入口导航而真正的项目知识比如架构设计、业务规则、隐性约定应该统一放在docs/目录下避免AGENTS.md变得臃肿失控。第三Claude的硬约束靠permissions hooks。把规则写在提示词里只是“软约束”AI难免会有判断失误的时候真正能拦住危险动作的是权限配置和钩子函数这才是Harness的“硬护栏”。第四团队专用动作放到skills和subagents。比如代码评审摘要生成、Spring分层架构检查、SQL风险审查这些高频动作应该沉淀成可重复调用的能力而不是每次靠人临时提醒AI这样才能提升流程的复用性和一致性。如果再压缩成一句话就是需求先工件化知识先显性化执行先加护栏评审与验证必须分离。这十六个字贯穿了我们整个Harness落地的全过程。二、明确边界这套Harness方案适合哪些项目不是所有项目都适合照搬这套Harness配置它有自己的适用场景找对场景才能发挥它的最大价值避免画蛇添足。这套Harness最适合的是这类Java Spring Boot项目有一定的历史包袱不是全新的从0到1项目需求以增量改造为主比如迭代新功能、修复老bug、优化现有逻辑而不是整体重写前后端之间存在一些口头约定或隐性契约这些约定没有写进文档新人或AI很难快速掌握团队希望把AI编码变成团队的“流程能力”而不是某个人的个人技巧需要把“需求、实现、评审、校验”这几个环节明确拆开避免混在一起导致风险失控。反之如果你的项目是一个很小的demo仓库、一次性脚本仓库或者是纯实验性质的项目甚至是全新的从0到1项目就没必要照搬这套配置。这类项目更注重灵活性约束太多反而会降低效率可以考虑和Superpowers、ecc、omc等框架搭配使用根据项目实际情况调整约束强度。这里要强调一点Harness的核心是“可控”但不是“僵化”。我们的目标是在约束和效率之间找到平衡而不是为了约束而约束。三、基础铺垫适合Harness的仓库组织方式要落地Harness首先要搭建一个合理的仓库结构让每个目录、每个文件都有明确的职责避免混乱。一个适合Java Spring Boot项目的Harness仓库结构建议如下按目录层级依次说明重点标注核心文件和目录的作用repo/ ├─ AGENTS.md # 通用OpenSpec规则AI的导航地图 ├─ CLAUDE.md # Claude系统提示词定义AI的基础行为 ├─ REVIEW.md # 只读评审代理提示词规范评审标准 ├─ docs/ # 项目知识库目录存放所有项目知识 │ ├─ architecture/ # │ ├─ 整体架构知识 │ │ └─ index.md # │ │ └─ 项目架构总览让AI快速了解系统整体设计 │ │ └─ implicit-contracts.md # │ │ └─ 隐性业务约定/项目坑点核心中的核心 │ ├─ product/ # │ ├─ 产品知识 │ │ └─ index.md # │ │ └─ 产品规则明确业务逻辑边界 │ ├─ standards/ # │ ├─ 相关规范 │ │ ├─ testing.md # │ │ ├─ 测试规范明确测试要求和标准 │ │ └─ database.md # │ │ └─ 数据库与SQL规范规避数据层风险 ├─ openspec/ # OpenSpec执行目录管理变更生命周期 │ ├─ changes/ # │ ├─ 变更目录存放当前和历史变更 │ │ ├─ changes名 # │ ├─ 当前正在执行的change每个change对应一个需求 │ │ │ ├─ specs/ # │ │ │ ├─ 该change的工作原理说明 │ │ │ ├─ proposal.md # │ │ │ ├─ 需求实现提案拆解需求边界 │ │ │ ├─ design.md # │ │ │ ├─ 具体执行方案明确技术实现细节 │ │ │ └─ task.md # │ │ │ └─ 执行步骤节点拆解具体工作内容 │ │ └─ archive/ # │ │ └─ 归档文件存放已完成的change │ └─ specs/ # │ └─ 当前系统工作原理说明让AI了解系统现状 ├─ .claude/ # Claude项目级配置目录核心约束层 │ ├─ settings.local.json.example # │ ├─ 项目级权限设置定义AI可操作范围 │ ├─ skills/ # │ ├─ 项目级Skills团队专用能力沉淀 │ │ ├─ prepare-review/ # │ │ ├─ review前变更审计生成评审摘要 │ │ │ └─ SKILL.md # │ │ │ └─ 该skill的具体执行逻辑 │ │ ├─ spring-architecture-review/ # │ │ ├─ Springboot分层架构检查避免分层混乱 │ │ │ └─ SKILL.md # │ │ │ └─ 架构检查的具体规则 │ │ └─ sql-risk-review/ # │ │ └─ SQL、Mapper、批量更新等风险检查 │ │ └─ SKILL.md # │ │ └─ SQL风险检查的具体规则 │ ├─ agents/ # │ ├─ 子代理承担专项审查职责 │ │ └─ reviewer.md # │ │ └─ 只读评审代理做独立代码审查 │ └─ hooks/ # │ └─ Hook硬护栏的核心实现 │ ├─ guard_write.py # │ ├─ 文件写入保护拦截高风险路径写入 │ ├─ ensure_change_context.py # │ ├─ 上下文变更保护检查change是否存在 │ └─ run_checks.sh # │ └─ 编译检查自动执行编译、测试等 ├─ src/ # 项目源代码目录和常规Spring Boot项目一致 │ ├─ main/ │ │ ├─ java/ │ │ └─ resources/ │ └─ test/ │ ├─ java/ │ └─ resources/ ├─ pom.xml # Maven配置文件 └─ .gitignore # Git忽略文件这套结构的核心不是“文件多”而是“职责分层清晰”每个目录和文件都有明确的定位不会出现职责交叉或遗漏。简单来说各核心目录的职责可以总结为openspec/管理“这次改什么”负责把需求变成change工件驱动变更生命周期docs/管理“这个项目本来是怎么工作的”存放所有项目知识、规则和隐性约定AGENTS.md / CLAUDE.md / REVIEW.md管理“AI进入仓库后应该怎么做”是AI的基础行为规范.claude/settings.json hooks管理“哪些事不能做、哪些检查必须跑”是Harness的硬护栏skills / agents管理“团队专用的审查动作”沉淀可复用的团队经验和能力。搭建好这个仓库结构就为Harness的落地做好了基础铺垫后续的所有实践都将围绕这个结构展开。四、核心实践7个关键落地技巧附实战细节仓库结构搭好之后就进入了核心实践环节。这7个最佳实践是我们从真实项目中总结出来的经验每一个都解决了实际落地中的痛点也是确保Harness能稳定发挥作用的关键。实践一AGENTS.md只做导航不做知识库这是整个Harness落地过程中最容易踩坑的一点很多团队一开始会本能地把所有规则、知识都塞进AGENTS.md觉得这样AI能一次性看到所有内容效率更高。但实际上这样做很快就会导致AGENTS.md臃肿不堪后续维护困难而且AI在读取时也会抓不住重点反而降低效率。正确的做法是AGENTS.md只负责告诉AI“去哪里看、按什么流程做”相当于一个入口导航而真正的知识、规则、隐性约定全部放进docs/目录下对应的文件中。具体来说AGENTS.md至少应该包含这几部分内容仓库采用的工作流是什么AI进入仓库后必须先读哪些文件没有change是否允许开始开发哪些目录是受保护的主要的命令入口是什么比如/opsx:propose、/opsx:apply等。这里有一个判断标准如果你的AGENTS.md变得越来越长通常不是因为规则变多了而是因为你没有把知识正确拆分到docs目录下。这时候就需要及时整理把属于项目知识的内容迁移到docs/让AGENTS.md始终保持简洁只做导航作用。实践二把“隐性约定”单独文档化避免踩坑对于有历史包袱的Java Spring Boot项目来说最危险的往往不是那些写在文档里的显式规则而是那些“大家都知道但没人写下来”的隐性约定。比如在我们这次实践中就遇到了两个典型的隐性约定status null 和 status 0 在历史语义上并不等价前端在单元详情接口中依赖contentResponse字段做回显。这些隐性约定如果只存在于口头沟通中AI基本不可能稳定推断出来很容易在编码时出错导致“本地能跑、联调出错”的问题。所以最佳实践是把所有容易导致联调失败的口头约定单独沉淀到docs/architecture/implicit-contracts.md文件中。而且要做到两件事一是在OpenSpec的design.md阶段就显式检查这些隐性约定确保设计方案符合约定二是在reviewer和verify阶段把这些约定作为对齐依据避免实现时偏离约定。这一步做得好不好几乎直接决定了AI产出代码的可落地程度。很多团队用AI编码时经常出现“代码能跑但不符合业务逻辑”的问题核心原因就是没有把隐性约定显性化AI不懂项目的历史包袱和业务潜规则。实践三OpenSpec只管“变更生命周期”不代替全部治理很多人对OpenSpec的定位有误解觉得它可以包揽所有的项目治理工作但实际上OpenSpec的定位非常明确它只负责把需求变成change工件并驱动change的生命周期不负责代替其他的治理工作。在Java Spring Boot项目中我们推荐使用下面这条主流程来管理change的生命周期/opsx:propose - /opsx:apply - /opsx:verify - /opsx:archive。这四个步骤的职责的必须严格区分不能混为一谈。第一步/opsx:propose把需求拆成一个change产出proposal.md、design.md、tasks.md三个核心文件。这里有一个非常重要的实战经验第一版proposal往往不靠谱不要急着执行。它更像第一轮工作草案而不是最终方案。如果proposal拆错了宁可废弃当前change重新生成新的change也不要硬着头皮继续做否则后续会出现更多问题返工成本更高。第二步/opsx:apply根据已经确认过的design.md和tasks.md实施代码改动。这一步的重点不是“让AI尽量多写代码”而是“只做tasks.md范围内的事”不允许AI自行扩展需求每完成一个里程碑就自动跑一次检查确保代码没有偏离设计方案。第三步/opsx:verify核对“实现有没有和OpenSpec工件对上”。这里要特别注意verify的作用非常重要但也非常有限它不是代码评审也不是架构评审只负责检查实现与change工件proposal.md、design.md、tasks.md是否一致不负责检查代码质量、架构合理性等内容。第四步/opsx:archive把当前change归档保持openspec/changes/目录下的进行中上下文干净方便后续进入下一个change。很多团队会忽略这一步导致openspec/changes/目录下堆满了已完成的change后续查找和管理非常麻烦。实践四把“实现、评审、验证”彻底拆开各司其职这是Harness和普通AI编码方式最大的区别之一也是确保AI编码可控的核心。在真实的项目开发中下面这几件事绝对不能混在一起需求拆解、代码实现、OpenSpec对齐校验、架构审查、SQL风险审查、面向PR的人工阅读摘要。最佳实践是把它们拆成不同的职责让每个环节只专注于自己的核心任务/opsx:verify只负责检查“实现有没有和OpenSpec对上”确保代码实现没有偏离需求拆解和设计方案/prepare-review只负责整理“这次到底改了什么”生成PR前的评审摘要方便人工快速了解变更内容提高评审效率/spring-architecture-review只负责检查Spring分层架构有没有乱比如Controller里写业务逻辑、Service职责混乱等问题/sql-risk-review只负责检查SQL、Mapper、批量更新、索引和扫描范围等数据层风险比如批量更新没有where限制、索引缺失等问题reviewer子代理只负责做一轮独立、只读、偏代码审查视角的检查重点关注代码质量、逻辑合理性等。这样拆开的好处有两个一是每种审查都有明确的目标不会互相覆盖又互相遗漏比如不会出现“检查了架构却忽略了SQL风险”的情况二是出问题时更容易定位到底是proposal有问题、实现有问题还是架构/SQL有风险不用在一堆混乱的流程中找原因。实践五真正的硬护栏必须落在permissions hooks很多团队喜欢把规则写进提示词然后默认AI会严格遵守但在实际工程实践中这种做法并不可靠。AI难免会有判断失误的时候一旦提示词中的规则没有被遵守就可能触碰高风险区域导致线上事故。最佳实践是能通过权限系统和hook强制拦住的就不要只靠提示词约束。提示词是“软约束”权限和hook才是“硬护栏”两者结合才能确保风险可控。比如下面这些目录在Java Spring Boot项目中属于高风险区域一旦被误改很可能导致线上故障src/main/resources/application*.yml、src/main/resources/bootstrap*.yml配置文件直接影响系统运行src/main/resources/db/、sql/数据库脚本误改可能导致数据丢失或错乱deploy/、infra/部署相关文件误改可能导致部署失败secrets/密钥文件泄露会导致安全风险。对于这些路径我们建议直接在permissions.deny中禁止修改同时在guard_write.py里再做一层路径校验双重防护确保即使AI判断失误也无法修改这些高风险目录下的文件。同理对于Bash执行命令也应该分层控制。像mvn test、mvn -q -DskipTests compile、mvn -DskipTests package、git status、git diff这类安全命令可以放入permissions.allow中允许AI执行但像git push、kubectl、terraform、helm、rm -rf以及任何生产部署相关的命令都应该默认禁止避免AI误操作导致严重后果。实践六Hooks不只做拦截还要做自动检查在Claude Code场景下hooks最有价值的地方不只是阻止危险动作还包括自动补上执行后校验让“检查会不会跑”不再依赖模型自觉而变成流程自动发生减少人工干预。我们在实践中给hooks配置了三个核心功能覆盖了“写入前、命令前、写入后”三个关键节点写入前校验通过guard_write.py拦截受保护路径写入一旦AI试图修改高风险目录下的文件直接拦截并提示不允许继续操作命令前检查上下文通过ensure_change_context.py检查当前是否存在OpenSpec change如果没有change对高风险Bash动作直接提示确认而不是默认放行避免AI在没有需求拆解的情况下乱执行命令写入后自动跑检查通过run_checks.sh在代码变更后自动执行编译检查、单元测试、打包检查确保代码能正常编译、测试通过避免出现“代码能写但无法运行”的问题。同时对于文档类变更比如修改docs/目录下的文件可以跳过重检查避免无谓的资源消耗。这套设计的关键点是把“被动检查”变成“主动触发”不管AI有没有意识到需要检查流程都会自动执行确保每一次变更都经过必要的校验降低风险。实践七Skill和Subagent只做团队专用能力很多团队会把所有能力都硬塞进主提示词里导致主提示词越来越长维护困难而且不同团队的需求不一样很多能力并不通用强行塞进主提示词会造成冗余。最佳实践是把团队专用的能力沉淀到.claude/skills/和.claude/agents/目录下比如生成PR前的review摘要、检查Spring Boot分层架构、检查SQL风险、做一轮只读视角的reviewer审计等这些能力都是团队在日常开发中高频使用的而且具有团队特殊性适合单独沉淀。这样做有三个好处一是可复用以后每个change都可以重复调用这些能力不用每次都重新写提示词二是可组合不同类型的需求可以只调用需要的能力比如不需要SQL变更的需求就可以不调用sql-risk-review这个skill提高效率三是可演进团队后续可以持续补充自己的审查能力比如新增“接口参数校验”“异常处理规范检查”等skill而不必频繁修改系统提示词降低维护成本。简单来说主流程负责通用约束skills/agents负责团队私有经验两者分工明确才能让Harness既规范又灵活。五、标准工作流从初始化到归档的完整流程结合我们的实战经验整理出了一套适合Java Spring Boot项目的Harness标准工作流共7个步骤从仓库初始化到change归档形成完整闭环团队可以直接复用也可以根据自身项目情况微调。第0步初始化仓库基础准备先通过openspec init --tools claude生成OpenSpec对应的基础目录结构然后再补齐以下核心文件和目录确保仓库结构符合Harness的要求AGENTS.md、CLAUDE.md、REVIEW.md、docs/目录重点补齐implicit-contracts.md、.claude/settings.json、.claude/hooks/、.claude/skills/、.claude/agents/。这一阶段的目标不是“立刻开始写代码”而是先把change生命周期、项目知识入口、权限和hook的承载位置搭好。如果这个骨架没立起来后面的流程就很容易重新滑回“想到哪改到哪”的无序状态。第1步创建change需求工件化执行/opsx:propose命令让需求先变成change工件生成proposal.md、design.md、tasks.md三个核心文件。这一步的核心是“需求拆解”把模糊的需求变成清晰、可执行的方案避免后续开发偏离需求。第2步人工审proposal/design/tasks关键把关这一步绝对不能省是控制风险的关键。人工重点检查三个方面一是需求边界是不是对的有没有遗漏或多余的内容二是是否遗漏了项目中的隐性约定确保设计方案符合项目历史包袱三是是否把多个问题错误混成一个change避免change过大、边界不清四是tasks.md是否足够可执行每个任务节点都要明确、具体让AI知道该做什么。第3步必要时废弃change重来及时止损如果proposal拆错了或者design方案不符合需求不要勉强修补。直接废弃当前change重新生成新的change往往更省成本。我们在实战中就遇到过多次第一版proposal不符合需求的情况及时废弃重来避免了后续更大的返工。第4步执行/opsx:apply代码落地基于已确认的proposal.md、design.md和tasks.md执行/opsx:apply命令让AI实施代码变更。这一步要注意AI只能做tasks.md范围内的事不允许自行扩展需求每完成一个任务节点就自动跑一次检查确保代码符合设计方案。第5步跑专项审查风险排查代码落地后依次执行专项审查不建议一次性打包调用分开执行更清晰、更可控/prepare-review生成PR前的评审摘要整理本次变更的核心内容方便人工评审/spring-architecture-review进行Spring分层架构审计检查分层是否混乱比如Controller写业务逻辑、Service职责过重等问题/sql-risk-review进行数据层和SQL风险审计检查SQL语句是否有风险、Mapper配置是否合理、批量更新是否有where限制等reviewer (agent)让reviewer子代理做一轮独立、只读的代码审查重点关注代码质量、逻辑合理性等。第6步执行/opsx:verify对齐校验专项审查完成后执行/opsx:verify命令确认代码实现是否和OpenSpec change工件proposal.md、design.md、tasks.md对齐确保没有偏离需求和设计方案。如果发现不一致及时修改代码重新执行verify直到对齐为止。第7步归档闭环收尾所有检查都通过后执行/opsx:archive命令对当前change进行归档将其移动到openspec/changes/archive/目录下保持进行中change目录的干净。到了这一步这个change才算从“提出需求”走到了“完成闭环”。六、实战复盘一次真实change的完整执行过程前面讲的都是方法论下面把我们这次Harness落地中的真实执行过程保留下来方便大家更直观地理解一条change在项目里到底是怎么从初始化、拆解、修正、执行、审查一路跑完的。这些细节比单纯的方法论更有参考价值因为它能让你看到实际落地中会遇到的问题和解决方式。1. 初始化仓库先搭骨架再填内容首先通过openspec init --tools claude生成OpenSpec对应的基础目录结构然后我们开始补齐AGENTS.md、CLAUDE.md、REVIEW.md这三个核心文件明确AI的导航规则和行为规范。接着我们重点完善了docs/目录尤其是docs/architecture/implicit-contracts.md把项目中所有的隐性约定都整理进去比如前面提到的status字段语义、前端依赖的contentResponse字段等。最后我们配置了.claude/settings.json、hooks、skills和agents搭建好硬护栏和团队专用能力。这一阶段我们花了大概1天时间没有急于写代码而是先把仓库骨架搭好。事实证明这一步的投入是值得的后续的所有流程都能顺畅推进没有出现因为结构混乱导致的效率低下问题。2. 第一轮propose快速成形及时推翻需求进入后我们先执行/opsx:propose让AI拆解对应change。很快proposal.md、design.md、tasks.md等相关文件就生成了但我们仔细审查后发现第一版拆解并不符合真实需求——AI误解了部分业务逻辑把两个不同的需求混在了一个change里而且没有考虑到项目中的隐性约定。这时候我们没有勉强继续而是直接废弃了这个change。这也是Harness很重要的一条经验proposal不是生成出来就要执行第一版不对就应该及时推翻避免后续返工。3. 第二轮propose重新拆解持续细化第一版废弃之后我们重新执行/opsx:propose生成新的change。但第一次生成后仍然不满足需求AI还是没有完全理解业务边界。于是我们开始持续补充上下文把项目的业务逻辑、隐性约定、需求边界一一告诉AI让它修正理解偏差。随后AI生成了新的proposal.md我们再次审查发现还是有部分细节遗漏于是继续补充业务信息让AI进一步修正。这一阶段反复调整了3次才最终确定了符合需求的proposal。这个过程非常能体现Harness的现实意义AI可以很快把change搭出一个骨架但proposal的质量高度依赖你有没有把真实业务边界和上下文交代清楚。AI不是万能的它需要明确的指引才能产出符合需求的方案。4. 进入design自动生成是起点人审是关键在确认了proposal的边界和逻辑之后我们让AI继续生成design.md明确具体的技术实现细节。design.md生成后我们开始人工审计发现其中存在一些错误和遗漏比如部分SQL语句的逻辑不符合数据库规范Spring分层设计有问题没有考虑到异常处理场景。于是我们开始修正design.md补充异常处理逻辑调整SQL语句优化Spring分层设计。这不是一次就结束的而是多轮审计、持续修正前后调整了2次才最终确定了符合要求的design方案。这里出现了一个非常典型的问题由于proposal中已经把范围限定在adunit/save、adunit/update两个接口AI始终无法稳定判定到素材相关的逻辑无论我们怎么补充上下文AI都容易偏离范围。最后的处理方式是当前change先只处理adunit/save、adunit/update范围内的逻辑素材相关的逻辑后续再单独开一个change。这样一来change的边界变得清晰AI也能准确理解需求后续的执行过程也顺利了很多。这一段过程正好印证了一条非常重要的最佳实践当模型始终无法稳定理解某块逻辑时优先怀疑的往往不是模型能力而是change边界定义得不够清楚。这时候拆分change比强行让AI理解更高效。5. verify、apply和专项审查分开执行各司其职在任务边界清晰、design方案确认之后我们先让子代理reviewer (agent)通过/opsx:verify做了一轮验证确认design方案符合OpenSpec约定没有偏离需求。随后我们正式执行/opsx:apply让AI开始落地代码。代码落地之后我们没有把所有审查动作一次性打包调用而是依次跑专项审查首先执行/prepare-review生成PR前的评审摘要整理出本次变更的核心内容、修改的文件、新增的功能方便后续人工评审然后执行/spring-architecture-review进行Spring分层架构审计发现AI在Controller里写了少量业务逻辑我们及时修正把业务逻辑迁移到Service层接着执行/sql-risk-review进行数据层和SQL风险审计发现一个批量更新语句没有where限制这是典型的事故隐患我们立即补充where条件避免后续出现数据错乱问题之后让reviewer (agent)再做一轮只读审计重点检查代码质量和逻辑合理性发现部分异常处理不完整我们补充了异常捕获和返回逻辑最后我们再执行一次/opsx:verify检查代码实现是否仍然和OpenSpec工件一致确保所有修改都没有偏离需求和设计方案。这一步最值得强调的是verify、review、架构审查、SQL审查不是一回事它们有各自的职责分开编排更清晰、更可控也更方便定位到底是哪一个环节出了问题。如果把所有动作混在一起一旦出现问题很难快速找到原因会浪费大量时间。6. 最后归档完成闭环所有审查都通过代码也已经提交测试确认没有问题后我们执行/opsx:archive命令对当前change进行归档将其移动到openspec/changes/archive/目录下。到这一步这个change才算真正完成从需求提出到代码落地、审查归档形成了完整的闭环。7. 实战过程的核心感悟把这段过程保留下来比只讲方法论更有价值因为它更直观地说明了几件事第一第一版proposal往往只是草案不能盲目执行人工审查必不可少而且要敢于废弃错误的change及时止损第二design阶段的人审通常比apply后返工便宜得多在design阶段发现并修正问题能节省大量的后续返工成本第三/opsx:verify不是万能审查它必须和review、架构审查、SQL审查分开各司其职才能全面覆盖风险第四当某块逻辑始终解释不清时宁可拆change也不要把所有问题硬塞进一个change清晰的边界是高效执行的前提。换句话说Harness的价值不只是“让AI参与开发”而是让整个开发过程变成可拆解、可回退、可审计、可复用、可沉淀的流程这才是它能真正融入生产研发的核心原因。七、重点关注Java Spring Boot项目最值得加护栏的5个地方并不是所有限制都无脑加越多越好约束太多会降低效率约束太少会增加风险。我们始终认为在限制中保持简洁AI才能更好地工作。结合Java Spring Boot项目的特点下面这些坑最值得优先考虑加护栏也是我们在实战中遇到的高频问题。1. Controller写业务逻辑这是Java Spring Boot项目中最常见的“脏问题”很多开发人员包括AI都会习惯性地在Controller里写业务逻辑导致分层混乱、代码复用性差、维护困难。所以我们需要在CLAUDE.md、REVIEW.md、reviewer子代理、spring-architecture-review这个skill中同时卡住明确规定Controller只能负责接收请求、返回响应不能包含任何业务逻辑业务逻辑必须放在Service层。2. 直接改SQL/配置/数据库脚本这类改动往往“本地能跑线上出事”比如修改配置文件导致系统启动失败修改SQL脚本导致数据丢失修改数据库脚本导致表结构异常。所以我们应该通过permissions.deny、guard_write.py、database.md、sql-risk-review这个skill多层保护禁止AI直接修改这些高风险文件如需修改必须经过人工审批重新生成change按流程执行。3. Service过胖职责混乱这类问题很容易在AI连续补代码时越滚越大一个Service负责多个不相关的业务逻辑导致代码臃肿、逻辑混乱、难以维护。我们需要靠reviewer子代理和spring-architecture-review这个skill持续盯住一旦发现Service职责混乱及时拆分Service明确每个Service的核心职责。4. 测试只跑happy path这是很多项目的通病AI在写测试用例时也容易只考虑正常场景忽略异常场景、边界场景导致测试覆盖率不足潜在bug无法被发现。所以我们至少要在testing.md和review摘要里明确本次变更跑了哪些测试哪些场景没有测为什么当前可以接受避免测试流于形式。5. 批量更新没有where限制这类问题不是bug而是事故预告。一旦批量更新没有where限制会导致全表数据被修改造成严重的数据错乱甚至无法恢复。所以在数据库规范database.md和SQL风险审查sql-risk-review里必须把它作为显式检查项一旦发现直接拦截不允许执行。八、实战补充3条千金难买的落地经验除了前面讲的结构设计和最佳实践这次Harness落地还有3条很重要的经验这些经验不是来自理论而是来自实际操作中的踩坑和总结对后续团队落地Harness非常有帮助。1. 第一版proposal通常只是草案人工审查不能省AI很容易先产出一个“结构看起来合理、业务边界其实不对”的proposal尤其是对于有历史包袱、业务逻辑复杂的项目AI很难一次性理解所有细节。因此proposal阶段的人工审查绝对不能省而且要仔细审查重点关注需求边界、隐性约定、change拆分是否合理避免后续出现更大的问题。2. design阶段修正比apply后返工便宜得多一旦进入apply阶段错误就开始变成代码、测试和联调成本此时再修正错误需要修改代码、重新测试、重新联调耗时耗力。而在design阶段错误还只是“方案上的问题”修正起来只需要调整设计方案成本低、效率高。所以最值得花时间的地方其实是design阶段多花一点时间审查和修正design方案能节省大量的后续返工成本。3. change边界不清时宁可拆成多个change如果模型始终无法稳定理解某块逻辑通常不是因为它“再多想一轮就会懂”而是因为当前change边界定义得不够好包含了太多不相关的内容导致AI无法抓住重点。这时候最佳实践不是继续硬压AI理解而是把复杂问题拆开先让change边界变清晰一个change只负责一个明确的需求这样AI能更准确地理解需求执行效率也会更高。九、团队落地推荐的3阶段实施顺序如果团队想逐步引入这套Harness不建议一次性全部落地那样成本太高也容易出现混乱。我们建议按下面3个阶段落地循序渐进逐步完善让团队有一个适应的过程。第一阶段最小可用版1-2周先上最核心的几个组件把“变更工件化”和“隐性约定显性化”跑通OpenSpec搭建openspec/目录使用/opsx:propose - /opsx:apply - /opsx:verify - /opsx:archive流程管理changeAGENTS.md编写AI导航地图明确AI的基础流程和入口CLAUDE.md编写Claude系统提示词规范AI的基础行为docs/architecture/implicit-contracts.md整理项目中的隐性约定让AI了解项目历史包袱reviewer子代理实现基础的只读评审能力辅助人工审查。这个阶段的目标是让每一次需求变更都能变成change工件有明确的拆解和记录AI能了解项目的隐性约定避免出现“联调出错”的问题。第二阶段补硬护栏2-3周在第一阶段的基础上增加硬护栏让高风险动作可控permissions配置权限禁止AI修改高风险目录和文件guard_write.py实现文件写入保护拦截高风险路径写入ensure_change_context.py实现上下文变更保护检查change是否存在自动检查配置run_checks.sh实现代码变更后自动执行编译、测试、打包检查。这个阶段的目标是通过权限和hook强制拦住危险动作让AI的操作始终在安全范围内减少人工干预的成本。第三阶段补团队专用能力持续迭代最后补充团队专用的skills和agents让流程真正变成可复用的工程能力prepare-review实现PR前评审摘要生成能力spring-architecture-review实现Spring分层架构检查能力sql-risk-review实现SQL风险审查能力其他团队私有skills/agents根据团队需求新增接口参数校验、异常处理规范检查等能力。这个阶段的目标是沉淀团队的私有经验让Harness更贴合团队的实际需求进一步提高开发效率和代码质量减少人工审查的工作量。十、附录可直接复用的Harness检查清单为了方便团队落地和自查我们整理了一份可直接复用的检查清单涵盖仓库层、流程层、风险层三个维度对照这份清单就能快速判断你的Harness是否具备了在真实项目里稳定运行的基础。仓库层检查清单⬜ 是否有AGENTS.md⬜ 是否有CLAUDE.md⬜ 是否有REVIEW.md⬜ 是否有docs/architecture/implicit-contracts.md⬜ 是否有openspec/changes/目录⬜ 是否有.claude/settings.json⬜ 是否有hooks、skills、agents目录流程层检查清单⬜ 没有change时不允许直接开始开发⬜ proposal/design/tasks是否经人工审计⬜ apply后是否自动跑检查⬜ verify是否独立执行⬜ change完成后是否archive风险层检查清单⬜ 高风险目录是否已deny⬜ SQL/Mapper是否有专项风险检查⬜ 测试缺口是否被显式说明⬜ Spring分层是否有独立审查⬜ 隐性约定是否在docs中显性记录如果这些项大部分都能满足说明你的Harness基本已经具备了在真实项目里稳定运行的基础。如果有遗漏可以对照清单逐步完善。另外我们这次实践的相关配置文件也已经打包好了大家可以用于参考公众号后台回复「20260401」即可获取。最后别被新词吓到Harness的本质是工程实践的沉淀说实话最近Harness这个词一出来营销号铺天盖地的宣传导致很多人都会有点慌觉得这又是一个新的风口自己如果不跟上就会被淘汰。但其实Harness真的没那么吓人。因为我们以前做项目的时候也一直在做差不多的事。我们会定开发规则会加权限限制会做代码审查会留回退方案会告诉工具什么能做什么不能做什么可以自动跑什么一定要人来拍板。这些事我们以前就在做只是那时候没有一个很统一的名字把它们都组织到一起。所以我想说别被新词吓到。Harness不是突然从天上掉下来的东西它更像是我们早就懂、早就在做的一些工程经验现在终于被定义出了名字被系统梳理成了一套可复用的流程。只是到了AI coding时代这件事反而更重要了。因为AI很像一个特别能干的小帮手做事快写东西也快但它快不代表它每次都对它能做很多事也不代表它知道哪条线不能碰。所以我们要给它规则给它边界给它检查也给它刹车。这其实就是Harness思想最有价值的地方不是让AI随便冲而是让它在可控的路上跑让AI真正成为提升团队效率的工具而不是增加风险的隐患。