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

Harness 最佳实践Java Spring Boot 项目落地 OpenSpec Claude Code核心结论本文核心是将AI纳入可控、可审计、可复用的工程流程通过需求工件化、知识显性化、执行加护栏、评审验证分离让AI成为生产级研发流程的工程能力。一、Harness 核心4原则1.OpenSpec 管变更生命周期通过/opsx:propose - /opsx:apply - /opsx:verify - /opsx:archive管控需求全流程2.AGENTS.md 只当地图仅做导航项目知识沉淀到docs/目录3.Claude 硬约束靠权限钩子用 permissions hooks 拦截危险操作而非仅靠提示词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./opsx:propose生成提案、设计、任务文件2./opsx:apply按确认方案执行代码改动3./opsx:verify仅检查实现与变更工件是否一致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/diff6. Hooks 做拦截自动检查• 写入前guard_write.py保护路径• 命令前ensure_change_context.py校验变更上下文• 写入后run_checks.sh自动跑编译、测试、打包7. Skill/Subagent 封装团队私有能力将评审摘要、架构检查、SQL审查等封装为可复用技能不塞入主提示词实现可复用、可组合、可演进。五、标准工作流1. 初始化仓库生成基础骨架配置文件2. 创建变更执行/opsx:propose3. 人工审计提案、设计、任务边界4. 修正变更错误直接废弃重开5. 执行变更/opsx:apply落代码6. 专项审查依次跑评审、架构、SQL检查7. 验证对齐/opsx:verify8. 归档/opsx:archive六、Spring Boot 重点护栏场景1. Controller禁止写业务逻辑2. 禁止直接修改SQL、配置、数据库脚本3. 防止Service层过度臃肿4. 测试需覆盖非happy path明确测试缺口5. 批量更新必须加WHERE限制七、实战3条经验1. 第一版proposal大概率不靠谱人工审计不可省2. design阶段修正成本远低于apply后返工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架构独立审查• 隐性约定已文档化