spring-boot-team-harness

Spring Boot team harness

The harness steers the agent in three places. AGENTS.md tells it how this repository works before it starts. Hooks check its work before a turn ends, so it fixes its own mistakes. ./mvnw verify in CI holds the same gates for every developer and every tool. Rules live in the build wherever they can: a gate holds whoever writes the code and costs no context.

Apply it

1. Run the script from the project root. Preview with --dry-run first:

   python3 ${CLAUDE_SKILL_DIR}/scripts/apply_harness.py . --dry-run
   python3 ${CLAUDE_SKILL_DIR}/scripts/apply_harness.py .
   

   Run it in the Maven project's folder. When that folder is inside a larger repository (for example backend/ next to frontend/), the CI workflow, .claude/settings.json, the hooks and .gitattributes go to the repository root, where GitHub and Claude Code read them, and the root AGENTS.md gets a line pointing to the project's own. The Stop hook then reacts only to changes in that folder.

   Pass --no-modules when the base package's subpackages are layers (controller, service, domain) rather than modules; Spring Modulith would report them as cycles. Rerunning with --no-modules after a run without it removes ModuleBoundariesTests and the add-module skill unless they were edited, and names what to remove from AGENTS.md by hand.

   It adds only what the project lacks. In the pom, it skips any property, dependency or plugin that is already declared, so an existing Spotless or Spring Modulith setup stays as it is. It adds CLAUDE.md (one line, @AGENTS.md), .claude/settings.json and its two hook scripts, .mvn/jvm.config, the three tests, a CI workflow, and project skills in both .claude/skills/ and .agents/skills/. It merges its permissions, hooks and plugin into an existing .claude/settings.json, adds its CI workflow only when no workflow runs Maven (as harness-verify.yml if verify.yml is taken), appends its gate section to an existing AGENTS.md, skips the boundary test when a test already calls ApplicationModules.of(...), and never overwrites a file the team has edited. Rerun it after updating this plugin: it adds the pieces the project is missing and updates the files it owns (hooks, tests, project skills, its workflow) that nobody has changed since, which it tracks in .claude/harness.lock. It reports each edited one so you can merge the new version by hand. If <build><plugins> already configures maven-compiler-plugin, it stops: merge that part of assets/pom/plugins.xml by hand and run it again.

2. Run ./mvnw spotless:apply and commit the result on its own, so the reformat stays out of later diffs. On an existing codebase, add that commit's hash to .git-blame-ignore-revs so git blame skips it.

3. Get ./mvnw verify green. New code must meet the gates; code that already fails them is recorded, not rewritten:

   • If there are only a few findings, fix them with the user. Each NullAway finding is a question about what a missing value means, so don't guess.
   • Otherwise run python3 ${CLAUDE_SKILL_DIR}/scripts/baseline.py .. It marks each class NullAway rejects today @NullUnmarked, and records today's CodeRulesTests violations in src/test/resources/archunit_store. New code is checked in full, and a fixed violation drops out of the record. Remove @NullUnmarked from a class once it's fixed. Don't suppress warnings or skip tests to get green. The Stop hook only blocks on problems in files the agent changed, but until verify is green it can't fully check those either.

4. Draft the Modules, Run and test and Team conventions sections of AGENTS.md from the code, then go through them with the user. Read the packages, the pom, compose files, the test setup, and repeated patterns such as error handling, DTO mapping and naming. Write only what an agent would get wrong without being told: one line per module, the commands and services the app needs, and the conventions the code follows. Mark each convention you inferred (inferred); the user confirms or deletes it. Leave out generic Spring advice and anything the code makes obvious, and keep the file short: every session reads all of it.

5. Commit everything, including .claude/settings.json, the marked classes and archunit_store.