Harness 最佳实践：Java Spring Boot 项目落地 OpenSpec + Claude Code

Harness 最佳实践：Java Spring Boot 项目落地 OpenSpec + Claude Code

核心结论

本文核心是将AI纳入可控、可审计、可复用的工程流程，通过需求工件化、知识显性化、执行加护栏、评审验证分离，让AI成为生产级研发流程的工程能力。

一、Harness 核心4原则

1. 1. OpenSpec 管变更生命周期 ：通过 /opsx:propose -> /opsx:apply -> /opsx:verify -> /opsx:archive 管控需求全流程
2. 2. AGENTS.md 只当地图 ：仅做导航，项目知识沉淀到 docs/ 目录
3. 3. Claude 硬约束靠权限+钩子：用 permissions + hooks 拦截危险操作，而非仅靠提示词
4. 4. 团队能力放skills/subagents：将评审、架构检查、SQL审查等封装为可复用能力

一句话总结：需求先工件化，知识先显性化，执行先加护栏，评审与验证必须分离

二、适用项目类型

• • 有历史包袱的Java Spring Boot业务系统

• • 以增量改造为主的项目

• • 存在口头/隐性契约的项目

• • 需将AI编码流程化、规范化的团队

• • 要拆分需求、实现、评审、校验的项目

不适合小型demo、一次性脚本、纯实验项目。

三、推荐仓库组织架构

repo/
├─ AGENTS.md        # 通用OpenSpec规则（导航用）
├─ CLAUDE.md        # Claude系统提示词
├─ REVIEW.md        # 只读评审代理提示词
├─ docs/            # 项目知识库
│  ├─ architecture/ # 架构知识+隐性约定
│  ├─ product/      # 产品规则
│  └─ standards/    # 测试、数据库等规范
├─ openspec/        # OpenSpec执行目录
│  ├─ changes/      # 变更文件（进行中+归档）
│  └─ specs/        # 系统现有规范
├─ .claude/         # Claude项目配置
│  ├─ settings.local.json.example # 权限配置
│  ├─ skills/       # 团队专用技能
│  ├─ agents/       # 子代理
│  └─ hooks/        # 拦截与自动检查脚本
├─ src/             # 业务代码
└─ pom.xml

核心分层：

• • openspec/：管理改什么

• • docs/：管理项目原本怎么工作

• • 配置文件：管理AI该怎么做

• • hooks/permissions：管理哪些事不能做

• • skills/agents：管理团队专用审查

四、7条核心最佳实践

1. AGENTS.md 只做导航，不做百科全书

• • 仅告诉AI工作流、必读文件、保护目录、命令入口

• • 所有知识、规则、隐性约定放入 docs/

2. 隐性约定单独文档化

将易导致联调出错的口头约定，写入 docs/architecture/implicit-contracts.md，并在设计、评审、验证阶段强制检查。

3. OpenSpec 只管变更生命周期

标准流程：

1. 1. /opsx:propose：生成提案、设计、任务文件
2. 2. /opsx:apply：按确认方案执行代码改动
3. 3. /opsx:verify：仅检查实现与变更工件是否一致
4. 4. /opsx:archive：归档变更，清理上下文

第一版proposal仅为草案，错误直接废弃重开。

4. 实现、评审、验证彻底分离

• • /opsx:verify：对齐变更工件

• • /prepare-review：生成人工评审摘要

• • /spring-architecture-review：检查Spring分层

• • /sql-risk-review：检查SQL风险

• • reviewer子代理：独立代码审计

5. 硬护栏：permissions + hooks

高风险目录禁止修改：

• • 配置文件、db/、sql/、deploy/、infra/、secrets/

  危险命令禁止执行：git push、kubectl、terraform、rm -rf等

  安全命令放行：mvn compile/test/package、git status/diff

6. Hooks 做拦截+自动检查

• • 写入前：guard_write.py 保护路径

• • 命令前：ensure_change_context.py 校验变更上下文

• • 写入后：run_checks.sh 自动跑编译、测试、打包

7. Skill/Subagent 封装团队私有能力

将评审摘要、架构检查、SQL审查等封装为可复用技能，不塞入主提示词，实现可复用、可组合、可演进。

五、标准工作流

1. 1. 初始化仓库：生成基础骨架+配置文件
2. 2. 创建变更：执行 /opsx:propose
3. 3. 人工审计：提案、设计、任务边界
4. 4. 修正变更：错误直接废弃重开
5. 5. 执行变更：/opsx:apply 落代码
6. 6. 专项审查：依次跑评审、架构、SQL检查
7. 7. 验证对齐：/opsx:verify
8. 8. 归档：/opsx:archive

六、Spring Boot 重点护栏场景

1. 1. Controller禁止写业务逻辑
2. 2. 禁止直接修改SQL、配置、数据库脚本
3. 3. 防止Service层过度臃肿
4. 4. 测试需覆盖非happy path，明确测试缺口
5. 5. 批量更新必须加WHERE限制

七、实战3条经验

1. 1. 第一版proposal大概率不靠谱，人工审计不可省
2. 2. design阶段修正成本远低于apply后返工
3. 3. 变更边界模糊时，拆分为多个小变更

八、团队落地顺序

第一阶段：最小可用版

• • OpenSpec + AGENTS.md + CLAUDE.md

• • 隐性约定文档 + reviewer子代理
  目标：变更工件化、知识显性化

第二阶段：补硬护栏

• • 权限配置 + 保护钩子

• • 自动编译/测试检查
  目标：高风险操作可控

第三阶段：补团队能力

• • 评审摘要、架构检查、SQL风险检查

• • 自定义skills/agents
  目标：流程工程化、可复用

九、落地检查清单

仓库层

• • AGENTS.md/CLAUDE.md/REVIEW.md齐全

• • 隐性约定文档存在

• • openspec/changes目录正常

• • .claude配置、hooks/skills/agents齐全

流程层

• • 无变更不允许开发

• • 提案/设计/任务经人工审计

• • 代码变更后自动检查

• • verify独立执行

• • 变更完成后归档

风险层

• • 高风险目录已禁止修改

• • SQL有专项风险检查

• • 测试缺口显式说明

• • Spring架构独立审查

• • 隐性约定已文档化

---