Harness实战指南：在Java Spring Boot项目中落地OpenSpec+Claude Code
最近，Harness这个词在开发者社区中频繁出现，让人不禁思考：它究竟是什么？其实，Harness并非凭空出现的黑科技，而是将我们早已熟悉的工程实践——如需求拆分、代码审查、自动化校验——系统化、工具化，并融入AI能力，形成一套可控、可审计、可复用的工程流程。本文基于一次真实的Java Spring Boot项目实践，分享如何将Harness思想落地，让AI从“不受控的高效助手”转变为“稳定融入生产的工程能力”。这套思想同样适用于Python、Go、JavaScript、C++等项目，核心逻辑完全通用。
一、核心原则：Harness落地的4条关键原则
将Harness实践浓缩为四条原则，它们是整个落地的指导思想：
- OpenSpec管变更生命周期：用
/opsx:propose -> /opsx:apply -> /opsx:verify -> /opsx:archive这套流程，管住“需求从提出到归档”的全过程，让每一次变更都有迹可循。 - AGENTS.md只当地图，不当百科全书：AGENTS.md的核心作用是告诉AI“先看什么、按什么流程做”，相当于入口导航；真正的项目知识应统一放在
docs/目录下。 - Claude的硬约束靠permissions + hooks：规则写在提示词里只是“软约束”，真正能拦住危险动作的是权限配置和钩子函数，这才是Harness的硬护栏。
- 团队专用动作放到skills和subagents：高频动作如代码评审摘要生成、Spring分层架构检查、SQL风险审查，应沉淀为可重复调用的能力，提升复用性和一致性。
再压缩成一句话：需求先工件化，知识先显性化，执行先加护栏，评审与验证必须分离。这十六个字贯穿了整个落地过程。
二、明确边界：这套方案适合哪些项目
Harness并非万能，它有自己的适用场景：
- 适合：有历史包袱的Java Spring Boot项目；需求以增量改造为主；存在隐性口头约定；团队希望将AI编码变成流程能力；需要明确区分“需求、实现、评审、校验”环节。
- 不适合：小型demo仓库、一次性脚本、纯实验性项目或全新的从0到1项目。这类项目更注重灵活性，可考虑与Superpowers、ecc、omc等框架搭配使用。
⚠️ Harness的核心是“可控”，而非“僵化”，目标是在约束与效率之间找到平衡。
三、基础铺垫：适合Harness的仓库组织方式
一个合理的仓库结构是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/ # │ ├─ 变更目录，存放当前和历史变更
│ │ ├─ # │ ├─ 当前正在执行的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/：管理“这次改什么”，驱动变更生命周期。docs/：存放项目知识、规则和隐性约定。AGENTS.md / CLAUDE.md / REVIEW.md：AI的基础行为规范。.claude/settings.json + hooks：硬护栏，定义“哪些事不能做”。skills / agents：沉淀团队专用审查能力。
四、核心实践：7个关键落地技巧
实践一：AGENTS.md只做导航，不做知识库
很多团队习惯把所有规则塞进AGENTS.md，导致臃肿不堪。正确做法是：AGENTS.md只负责告诉AI“去哪里看、按什么流程做”，真正的知识放在docs/目录下。AGENTS.md应包含：工作流说明、必须先读的文件、是否允许无change开发、受保护目录、主要命令入口（如 /opsx:propose、/opsx:apply）。判断标准：如果AGENTS.md越来越长，说明没有正确拆分知识。
实践二：把“隐性约定”单独文档化 ✅
对于有历史包袱的项目，最危险的是“大家都知道但没人写下来”的隐性约定。例如：status = null 和 status = 0 语义不等价；前端依赖contentResponse字段回显。最佳实践是：将所有口头约定沉淀到docs/architecture/implicit-contracts.md中，并在OpenSpec的design阶段显式检查，在reviewer和verify阶段作为对齐依据。
实践三：OpenSpec只管“变更生命周期”
OpenSpec的定位很明确：只负责把需求变成change工件，并驱动change生命周期。推荐主流程：/opsx:propose -> /opsx:apply -> /opsx:verify -> /opsx:archive。四个步骤职责严格区分：
/opsx:propose：产出proposal.md、design.md、tasks.md。第一版proposal往往不靠谱，拆错了宁可废弃重来。/opsx:apply：只做tasks.md范围内的事，不允许扩展需求。/opsx:verify：核对实现与change工件是否一致，不负责代码质量。/opsx:archive：归档当前change，保持上下文干净。
实践四：把“实现、评审、验证”彻底拆开 ⚠️
这是Harness与普通AI编码最大的区别。需求拆解、代码实现、OpenSpec对齐校验、架构审查、SQL风险审查、PR摘要生成，必须拆成不同职责：
/opsx:verify：只检查OpenSpec对齐。/prepare-review：整理变更摘要。/spring-architecture-review：检查Spring分层架构。/sql-risk-review：检查SQL和数据层风险。- reviewer子代理：做只读代码审查。
这样出问题时更容易定位，不会互相覆盖又互相遗漏。
实践五：真正的硬护栏，落在permissions + hooks ️
规则写在提示词里是“软约束”，AI难免失误。最佳实践是：能通过权限和hook强制拦住的，就不要只靠提示词。例如，以下高风险目录应禁止修改：
src/main/resources/application*.ymlsrc/main/resources/db/deploy/secrets/
在permissions.deny中禁止，同时在guard_write.py做双重防护。Bash命令也应分层控制：安全命令如 mvn test、mvn -q -DskipTests compile 可允许；危险命令如 git push、kubectl 默认禁止。
实践六：Hooks不只做拦截，还要做自动检查
在Claude Code场景下，hooks最有价值的是自动补上执行后校验。我们配置了三个核心功能：
- 写入前校验：
guard_write.py拦截受保护路径写入。 - 命令前检查上下文：
ensure_change_context.py检查是否存在OpenSpec change，无change时对高风险操作提示确认。 - 写入后自动跑检查：
run_checks.sh自动执行编译、测试、打包，确保代码可运行。
关键点是：把“被动检查”变成“主动触发”，减少人工干预。
实践七：Skill和Subagent只做团队专用能力
团队专用能力应沉淀到.claude/skills/和.claude/agents/目录下，如PR摘要生成、Spring架构检查、SQL风险审查等。这样可复用、可组合、可演进，主流程负责通用约束，skills/agents负责团队私有经验，分工明确。
[AFFILIATE_SLOT_1]
五、标准工作流：从初始化到归档的完整流程
结合实战，整理出7步标准工作流：
- 第0步：初始化仓库：通过
openspec init --tools claude生成基础目录，补齐AGENTS.md、CLAUDE.md、REVIEW.md、docs/等文件。 - 第1步：创建change：执行
/opsx:propose命令，生成proposal.md、design.md、tasks.md。 - 第2步：人工审proposal/design/tasks：检查需求边界、隐性约定、change是否过大、tasks是否可执行。
- 第3步：必要时废弃change重来：如果proposal拆错，直接废弃重生成。
- 第4步：实施开发：按tasks.md范围编码，不扩展需求。
- 第5步：执行verify + reviewer：检查OpenSpec对齐和代码质量。
- 第6步：归档change：清理上下文，保持目录干净。
六、落地顺序建议：从易到难，逐步推进
不要试图一次性落地所有实践，建议按以下顺序推进：
- 第一阶段：搭建仓库结构，配置AGENTS.md和permissions，建立基本护栏。
- 第二阶段：引入OpenSpec，规范change生命周期，让需求工件化。
- 第三阶段：沉淀隐性约定到docs/，减少联调问题。
- 第四阶段：开发skills/agents，自动化团队专用审查。
- 第五阶段：持续优化，根据团队反馈调整流程。
[AFFILIATE_SLOT_2]
结语
Harness的核心不是“用AI多写代码”，而是把AI装进可控、可审计、可复用的工程流程里。通过OpenSpec管理变更、AGENTS.md导航知识、permissions + hooks提供硬护栏、skills/agents沉淀团队能力，我们能让AI稳定融入生产研发。这套思想不仅适用于Java Spring Boot，也适用于Python、Go、JavaScript、C++等语言。记住：需求先工件化，知识先显性化，执行先加护栏，评审与验证必须分离——这十六字，就是Harness落地的精髓。
浙公网安备 33010602011771号