Turning AI into a Controlled, Auditable Development Pipeline for Java Spring Boot

Why the focus is on controlling AI, not just making it write more code

In real production projects the biggest risk is not that AI can’t generate code, but that it operates without boundaries, ignores hidden project conventions, mixes implementation with review, and makes changes without clear risk communication.

Goal of the harness: Turn requirements into artifacts, keep code changes inside guardrails, separate review and verification, and let the repository become a knowledge base.

Core principles of the harness

OpenSpec change lifecycle – use

/opsx:propose → /opsx:apply → /opsx:verify → /opsx:archive

to manage a change from proposal to archiving.

AGENTS.md as navigation – only tells the AI where to look; actual knowledge lives in docs/.

Claude hard constraints – enforce rules with permissions and hooks instead of relying on prompt words.

Team‑specific actions – encapsulate repeatable capabilities in .claude/skills/ and .claude/agents/.

Projects that benefit most

Java Spring Boot services with legacy code

Incremental enhancements rather than full rewrites

Teams that have many oral or hidden contracts

Teams that want AI to be a process capability, not a personal trick

Recommended repository layout

repo/
├─ AGENTS.md               # navigation map
├─ CLAUDE.md               # Claude system prompts
├─ REVIEW.md               # read‑only review prompts
├─ docs/
│  ├─ architecture/
│  │   └─ implicit-contracts.md
│  ├─ product/
│  └─ standards/
│      ├─ testing.md
│      └─ database.md
├─ openspec/
│  └─ changes/
│      └─ my-change/
│          ├─ specs/
│          ├─ proposal.md
│          ├─ design.md
│          └─ task.md
├─ .claude/
│  ├─ settings.json
│  ├─ skills/
│  ├─ agents/
│  └─ hooks/
│      ├─ guard_write.py
│      ├─ ensure_change_context.py
│      └─ run_checks.sh
├─ src/
│  ├─ main/java/
│  └─ test/java/
├─ pom.xml
└─ .gitignore

The most important aspect is clear responsibility layering, not the number of files.

Directory responsibilities

openspec/

– manages the “what to change” lifecycle. docs/ – stores project knowledge and implicit contracts. AGENTS.md / CLAUDE.md / REVIEW.md – define how the AI should behave when it enters the repo. .claude/settings.json + hooks – enforce hard constraints and protect high‑risk paths. .claude/skills/ & .claude/agents/ – encapsulate team‑specific reusable abilities.

Best practice #1 – AGENTS.md only navigation

Keep AGENTS.md as a simple map that points the AI to the right documentation; never dump all rules there.

Best practice #2 – Document implicit contracts separately

Place hidden agreements such as status = null vs. status = 0 or UI‑dependent fields into docs/architecture/implicit-contracts.md and have OpenSpec design.md validate them.

Best practice #3 – OpenSpec only handles the change lifecycle

OpenSpec should not replace all governance; it only turns a requirement into a change artifact and drives its lifecycle.

Best practice #4 – Hard guardrails via permissions + hooks

Define high‑risk directories (e.g., src/main/resources/application*.yml, sql/, deploy/, secrets/) in permissions.deny and reinforce them with guard_write.py. Allow safe commands (e.g., mvn test) and forbid dangerous ones ( git push, kubectl, terraform, rm -rf).

Best practice #5 – Hooks also run automatic checks

After a write, run_checks.sh automatically performs compilation, unit tests, and packaging checks. Documentation changes can skip heavy checks.

Best practice #6 – Skills and sub‑agents for team‑specific capabilities

Encapsulate review summaries, Spring layer checks, SQL risk analysis, and read‑only reviewer agents in .claude/skills/ and .claude/agents/ so they are reusable, composable, and evolvable.

Standard workflow (illustrated with commands)

Initialize repository : openspec init --tools claude creates the skeleton and you add AGENTS.md, CLAUDE.md, REVIEW.md, docs/, and the .claude config.

Create a change : /opsx:propose generates proposal.md, design.md, tasks.md. If the first proposal is inaccurate, discard it and start a new change.

Human review of proposal/design/tasks : verify boundaries, hidden contracts, and task executability.

Apply the change : /opsx:apply implements the code.

Specialized reviews (run separately): /prepare-review, /spring-architecture-review, /sql-risk-review, and the reviewer agent.

Verify implementation : /opsx:verify checks that the code matches the OpenSpec artifacts.

Archive : /opsx:archive closes the change.

Additional practical insights

The first proposal is usually a draft; always treat it as mutable.

Human design review is far cheaper than fixing bugs after apply.

If a piece of logic remains ambiguous, split the change instead of forcing it into one large change.

Adoption roadmap

Phase 1 – Minimum viable harness : set up OpenSpec, AGENTS.md, CLAUDE.md, docs/architecture/implicit-contracts.md, and a basic reviewer agent.

Phase 2 – Add hard guardrails : configure permissions, guard_write.py, ensure_change_context.py, and automatic compile/test checks.

Phase 3 – Add team‑specific skills/agents : implement prepare-review, spring-architecture-review, sql-risk-review, and any other custom capabilities.

Checklist (repository, process, risk layers)

Repository: AGENTS.md, CLAUDE.md, REVIEW.md, docs/architecture/implicit-contracts.md, openspec/changes/, .claude/settings.json, hooks/skills/agents present.

Process: no change without a proposal, all artifacts reviewed by humans, automatic checks after apply, verification runs independently, change is archived after completion.

Risk: high‑risk directories denied, SQL/mapper risk reviews in place, test gaps documented, Spring layer reviews defined, implicit contracts recorded.

When most of these items are satisfied, the harness is ready for stable operation in a real project.

Conclusion

The harness is not a marketing buzzword but a concrete set of engineering practices that make AI a controlled, auditable, and reusable part of the development pipeline, especially for Java Spring Boot services.