Harness 最佳实践:Java Spring Boot 项目落地 OpenSpec + Claude Code 的配置骨架与验证清单

发布时间:2026/11/18 7:41:59

Harness 最佳实践:Java Spring Boot 项目落地 OpenSpec + Claude Code 的配置骨架与验证清单 1. 为什么 Spring Boot 老项目需要 OpenSpec Claude Code如果你手上是一个跑了三五年的 Java Spring Boot 业务系统需求文档散在 Confluence、口头约定藏在老员工脑子里、SQL 脚本靠 DBA 手动执行那你大概已经体会过「AI 写代码很快但改错一行配置要排查半天」的滋味。OpenSpec 解决的是「改什么」的问题它把需求变成可审计的变更工件Claude Code 解决的是「怎么改」的问题它按工件执行代码改动。两者放进 Harness 流水线才能让 AI 编码从「玩具」变成「生产级工程能力」。这套方案适合谁有历史包袱的 Spring Boot 业务系统、以增量改造为主的团队、存在大量隐性契约比如「订单状态 3 不能直接改 5」这种口头规则的项目。不适合小型 demo 或一次性脚本因为配置成本高于收益。核心思路就四句话需求先工件化知识先显性化执行先加护栏评审与验证必须分离。下面我按落地顺序把配置骨架、TaoToken 接入位置、本地跑通和流水线校验的动作全部拆开。2. TaoToken 前置统一 Key 与 API 通道的接入位置Claude Code 在 Harness 流水线里跑最怕的是每个环境配一套 Key、每个开发者本地又一套最后审计时说不清谁调了什么。TaoToken 的作用是提供一个统一的 API 通道你只需要在项目级配置里写一次 base_url 和 Key本地和流水线共用同一套接入点。接入位置有三个按优先级排第一项目根目录的.claude/settings.local.json这是 Claude Code 读取项目级配置的地方适合放模型通道和权限规则。第二Harness 的 Secret Manager把 Key 存成TAOTOKEN_API_KEY环境变量流水线执行时注入。第三本地开发时用.env文件但记得加进.gitignore。API 地址统一用https://taotoken.net/api不要带任何查询参数。官网入口是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content第一次接入时从这里进控制台创建 Key。注意Key 只创建一次本地和流水线共用。如果团队成员各自创建审计时无法追溯调用来源护栏就形同虚设。创建 Key 的路径是控制台里的 API Keys 页面建议按项目命名比如springboot-order-svc。创建后立刻复制页面刷新就不再显示完整 Key。3. 可复制配置config.toml 与 settings.json 骨架这一章是全文最核心的部分配置写对了后面验证才有的放矢。我按「仓库结构 → config.toml → settings.json → hooks 脚本」的顺序给骨架。3.1 仓库目录结构先看整体布局配置文件放在哪一目了然repo/ ├─ AGENTS.md # OpenSpec 导航只写工作流和必读文件 ├─ CLAUDE.md # Claude 系统提示词 ├─ REVIEW.md # 只读评审代理提示词 ├─ docs/ │ ├─ architecture/ │ │ └─ implicit-contracts.md # 隐性约定联调必查 │ ├─ product/ │ └─ standards/ ├─ openspec/ │ ├─ changes/ # 进行中 归档的变更 │ └─ specs/ # 系统现有规范 ├─ .claude/ │ ├─ settings.local.json.example │ ├─ skills/ │ ├─ agents/ │ └─ hooks/ │ ├─ guard_write.py │ ├─ ensure_change_context.py │ └─ run_checks.sh ├─ src/ └─ pom.xml分层逻辑openspec/管改什么docs/管项目原本怎么工作配置文件管 AI 该怎么做hooks/permissions管哪些事不能做skills/agents管团队专用审查。3.2 config.toml 骨架Harness 流水线里用 config.toml 声明执行阶段和模型通道。下面这份可以直接复制改# .harness/config.toml [project] name springboot-order-svc language java build_tool maven [ai] provider taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model claude-sonnet-4-20250514 max_tokens 8192 [openspec] changes_dir openspec/changes specs_dir openspec/specs require_proposal true require_verify true [guardrails] protected_paths [ src/main/resources/application*.yml, db/, sql/, deploy/, infra/, secrets/ ] allowed_commands [ mvn compile, mvn test, mvn package, git status, git diff ] blocked_commands [ git push, kubectl, terraform, rm -rf ] [hooks] pre_write .claude/hooks/guard_write.py pre_command .claude/hooks/ensure_change_context.py post_write .claude/hooks/run_checks.sh关键参数说明api_key_env指向环境变量名而不是明文 Key这样流水线注入时不会泄露protected_paths里的目录 Claude Code 无法写入这是硬护栏blocked_commands拦截危险命令allowed_commands放行安全命令。3.3 settings.local.json 骨架Claude Code 读取的权限配置和 config.toml 配合使用{ permissions: { allow: [ Read, Glob, Grep, Bash(mvn compile), Bash(mvn test), Bash(mvn package), Bash(git status), Bash(git diff) ], deny: [ Write(src/main/resources/application*.yml), Write(db/**), Write(sql/**), Write(deploy/**), Write(infra/**), Write(secrets/**), Bash(git push), Bash(kubectl *), Bash(terraform *), Bash(rm -rf *) ] }, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: ${TAOTOKEN_API_KEY} } }deny列表里的路径和 config.toml 的protected_paths保持一致双重保险。env里用${TAOTOKEN_API_KEY}引用环境变量本地跑之前先export TAOTOKEN_API_KEY你的Key。3.4 hooks 脚本骨架三个钩子各司其职。guard_write.py在写入前检查路径是否在保护列表#!/usr/bin/env python3 import sys, os, fnmatch PROTECTED [ src/main/resources/application*.yml, db/*, sql/*, deploy/*, infra/*, secrets/* ] def is_protected(path): for pattern in PROTECTED: if fnmatch.fnmatch(path, pattern): return True return False if __name__ __main__: target sys.argv[1] if len(sys.argv) 1 else if is_protected(target): print(f[GUARD] 拒绝写入受保护路径: {target}) sys.exit(1) sys.exit(0)ensure_change_context.py在命令执行前校验是否有活跃变更#!/usr/bin/env python3 import sys, os CHANGES_DIR openspec/changes def has_active_change(): if not os.path.isdir(CHANGES_DIR): return False for name in os.listdir(CHANGES_DIR): if name ! archive and os.path.isdir(os.path.join(CHANGES_DIR, name)): return True return False if __name__ __main__: if not has_active_change(): print([CONTEXT] 无活跃变更禁止执行代码改动命令) sys.exit(1) sys.exit(0)run_checks.sh在写入后自动跑编译和测试#!/bin/bash set -e echo [CHECK] 开始编译... mvn compile -q echo [CHECK] 开始测试... mvn test -q echo [CHECK] 打包验证... mvn package -DskipTests -q echo [CHECK] 全部通过4. 验证请求本地跑通与流水线校验配置写完不算完得验证它真的生效。我分本地和流水线两步走。4.1 本地跑通第一步设置环境变量并确认通道可达export TAOTOKEN_API_KEY你的Key curl -s -o /dev/null -w %{http_code} \ https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY返回 200 说明 Key 和通道都正常。如果返回 401检查 Key 是否复制完整返回 404检查 base_url 是否多了斜杠。第二步在项目根目录启动 Claude Code执行一次 OpenSpec 提案claude # 在交互界面输入 /opsx:propose 新增订单超时自动取消功能预期结果openspec/changes/下生成一个以变更名命名的目录里面有proposal.md、design.md、tasks.md三个文件。如果目录没生成检查openspec/changes是否存在且可写。第三步验证护栏是否生效。尝试让 Claude Code 修改受保护文件# 在 Claude Code 交互界面输入 请修改 src/main/resources/application.yml 里的数据库连接预期结果被guard_write.py拦截输出[GUARD] 拒绝写入受保护路径。如果没拦截检查 hooks 路径是否配置正确、脚本是否有执行权限。第四步验证无变更时禁止改动# 先归档当前变更 /opsx:archive # 然后尝试改代码 请修改 OrderService.java 的取消逻辑预期结果被ensure_change_context.py拦截提示无活跃变更。4.2 流水线校验Harness 流水线里加一个校验阶段把上面四步自动化# .harness/pipeline.yaml stages: - name: openspec-validate steps: - script: - export TAOTOKEN_API_KEY$TAOTOKEN_API_KEY - test -d openspec/changes || exit 1 - test -f AGENTS.md || exit 1 - test -f CLAUDE.md || exit 1 - test -f docs/architecture/implicit-contracts.md || exit 1 - python3 .claude/hooks/guard_write.py src/main/resources/application.yml exit 1 || echo guard ok - bash .claude/hooks/run_checks.sh这段脚本做了三件事检查仓库骨架文件是否齐全、验证 guard_write 对受保护路径确实返回非零、跑一遍编译测试。任何一步失败流水线就红变更不允许合并。提示流水线里的TAOTOKEN_API_KEY从 Harness Secret Manager 注入不要写在 pipeline.yaml 里。本地和流水线共用同一个 Key审计时调用来源清晰。5. 本篇常见错排查配置落地过程中下面这几个坑我踩过你大概率也会遇到。错误一ANTHROPIC_BASE_URL没生效请求打到了默认地址。现象是 Claude Code 报连接超时或 401。原因是 settings.local.json 里的 env 没被读取或者环境变量名写错。排查方法在 Claude Code 里执行echo $ANTHROPIC_BASE_URL确认输出是https://taotoken.net/api。如果为空检查 settings.local.json 是否在.claude/目录下以及 JSON 格式是否合法。错误二hooks 脚本没有执行权限。现象是护栏完全不生效Claude Code 能随意改受保护文件。原因是脚本没有x权限。修复chmod x .claude/hooks/guard_write.py chmod x .claude/hooks/ensure_change_context.py chmod x .claude/hooks/run_checks.sh错误三/opsx:propose报「changes 目录不存在」。原因是 openspec 目录没初始化。修复mkdir -p openspec/changes openspec/specs touch openspec/changes/.gitkeep错误四流水线里mvn test失败但本地通过。大概率是流水线环境没有注入TAOTOKEN_API_KEY导致 Claude Code 生成的测试代码引用了不存在的配置。检查 Harness Secret Manager 里的变量名是否和 config.toml 的api_key_env一致。错误五guard_write.py 拦截了正常写入。现象是改src/main/java/下的文件也被拦。原因是 fnmatch 模式写得太宽比如*application*会匹配到Application.java。修复把模式收窄成src/main/resources/application*.yml只匹配资源目录下的配置文件。错误六变更归档后ensure_change_context.py仍然放行。原因是 archive 目录被当成了活跃变更。检查脚本里的if name ! archive判断是否生效或者归档时把变更移到openspec/changes/archive/子目录下。6. 下一步把评审和验证拆开配置跑通只是第一阶段。接下来你要做的是把「实现、评审、验证」彻底分离/opsx:verify只检查实现和变更工件是否一致/prepare-review生成人工评审摘要/spring-architecture-review检查 Spring 分层是否被破坏/sql-risk-review检查 SQL 风险。这些能力封装成 skills 和 subagents不塞进主提示词才能复用和演进。如果你还在验证模型通道阶段可以先到模型对话页面确认 Key 能正常调用如果准备把 Claude Code 长期接入日常编码和 Agent 流程Coding Plan 页面有更完整的配额和通道说明接入文档里有 settings.json 的完整字段解释。三个入口按你的当前阶段选不用一次全看完。最后留一个实操建议第一版 proposal 大概率不靠谱人工审计不能省。design 阶段修正的成本远低于 apply 之后返工。变更边界模糊时拆成多个小变更每个变更单独走 propose → apply → verify → archive比一个大变更塞进去再拆要省事得多。
延伸阅读

更多相关文章

2026/11/17 14:00:30

沈阳工伤保险做实网站避坑指南:3招搞定性能优化

沈阳工伤保险做实网站避坑指南:3招搞定性能优化 改个需求建站公司拖一周,后台报错没人管,这种憋屈感是不是让你想砸键盘?我干这行十年,见过太多沈阳本地老板被这种“半吊子”网站坑惨。特别是做【沈阳工伤保险做实网站】这类政务关联或企业内部申报系统…

2026/11/18 7:36:53

上岗必备!陕西省电工证网上查询流程全解析,手把手教你搞定

上岗必备!陕西省电工证网上查询流程全解析,手把手教你搞定 你还在为没证耽误工作发愁?特种作业证是很多行业上岗的 上岗必备 ,尤其是像电工这类高风险岗位,没有证根本没法干。今天我就从洛阳一名在职建筑工人的视角,详细说说怎么在陕西省电工证网上查…

2026/11/18 7:36:53

水电工证丢失怕报不上名?良心建议教你一步步处理

水电工证丢失怕报不上名?良心建议教你一步步处理 学历不高怕报不上名?别急,水电工证丢了真的不影响你报名和考试,只要你按照流程操作,照样能顺利拿到新证。今天咱们就来聊聊【水电工证丢失】这个情况,特别是像你这种在安阳本地干活的建筑工人,遇到证书…

2026/11/18 7:36:53

电工证报名需要户口本,真实经历告诉你别再走弯路了

电工证报名需要户口本,真实经历告诉你别再走弯路了 工地太忙根本没时间复习考试,这几乎是所有一线施工人员的真实写照。尤其是刚从其他岗位转岗过来的电工,一边要适应新的工作节奏,一边还得抽出时间准备电工证考试。很多人第一次报考时,都被“电工证报名…

2026/11/18 7:36:53

电工证报名需要户口本?真实经历告诉你别怕考不过白交培训费

电工证报名需要户口本?真实经历告诉你别怕考不过白交培训费 怕考不过白交培训费?我见过太多人因为材料没准备全,报名被拒,培训费打水漂。电工证报名需要户口本这事,说白了就是材料门槛问题,很多人被卡在第一步。今天我以驻马店一家中小型施工企业的负责…

2026/11/18 7:36:53

玉林考电工证哪里好考 2026河南最新政策如何影响你

玉林考电工证哪里好考 2026河南最新政策如何影响你 之前考的证在外省能不能转过来?这个问题困扰了不少在玉林的建筑工人和想要转行的从业者。尤其是在2026年河南最新政策出台之后,各地对于特种作业证书的要求也在不断升级,…

2026/11/18 7:31:52

高压电工证可以登高么?值不值得考?实操考试心里没底怕挂科

高压电工证可以登高么?值不值得考?实操考试心里没底怕挂科 你是不是也在纠结: 高压电工证可以登高么? 考这个证值不值得?实操考试心里没底怕挂科,怕浪费时间、精力和钱。我以前也是这样,现在在商丘做培训机构,带过上百个学员,今天就用咱们同行的经…

2026/11/17 17:09:16

电工证考试口诉怎么准备值不值得考

电工证考试口诉怎么准备值不值得考 实操考试心里没底怕挂科,这是大多数准备考电工证的人心里最真实的感受。尤其是面对【电工证考试口诉】环节,很多人不知道该怎么准备,甚至担心自己说不好就被淘汰。其实,只要掌握方法, 值不值得考…

2026/11/17 21:35:12

桑植县考电工证千万别踩坑!报名全流程教你避坑

桑植县考电工证千万别踩坑!报名全流程教你避坑 你是不是也遇到过这种情况:想考个电工证,但不知道从哪儿下手,怕被中介坑,怕花冤枉钱,更怕考了证还不能用?别急,这正是你该看这篇文章的原因。在桑植县考电工证,确实有很多人被坑过,但只要你知道流程、…

2026/11/18 0:00:18

小型汽车电工证怎么考通过率揭秘

小型汽车电工证怎么考通过率揭秘 你是不是也担心,花了几千块培训费,最后考不过,钱就白花了?别急,今天我就从安阳在职建筑工人的角度,给你讲讲【小型汽车电工证怎么考】的真相,特别是【通过率揭秘】,帮你避坑、避雷、少走弯路。…

2026/11/18 0:00:18

青浦区电工证在哪考内部消息曝光了,学历不高也能考!

青浦区电工证在哪考内部消息曝光了,学历不高也能考! 你是不是也担心自己学历不高,报不了电工证?别急, 青浦区电工证在哪考 其实有“内部消息”能让你轻松搞定,而且门槛并不高。今天我就从一个过来人的角度,给你讲清楚电工证报考的真相,以及你真正需…

2026/11/18 0:00:18

你别再被中介坑了!登高证和电工证相片保姆级教程来了

你别再被中介坑了!登高证和电工证相片保姆级教程来了 你是不是正为 登高证和电工证相片 的事情发愁?不知道去哪儿报名,怕被中介忽悠,花了不少冤枉钱却还没拿到证?其实,这事儿你不是一个人在战斗,很多人都在为这事头疼。别急,今天这波 保姆级教程…

2026/11/17 0:49:41

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

在智慧养宠时代,基于视觉的宠物身份识别技术正逐步从实验室走向家庭应用。然而,与配合度高的人类不同,宠物是典型的“非合作生物识别对象”——它们不会主动配合摄像头调整姿态,更无法控制光照环境。实际应用中,我们常…

2026/11/18 1:15:04

SSM电子书店源码全解析:结构、原理、部署与排错实战

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑