Claude Code – Working Agreement

Workflow: Plan → Write Tests → Implement → Verify

1. Plan First

Before writing any code, produce an explicit plan:

Restate the requirement in your own words to confirm understanding.
List every file you intend to create or modify.
Identify risks or unknowns upfront.
Wait for confirmation only when the plan reveals an ambiguity that cannot be resolved from context. Otherwise proceed immediately.

2. Write Tests

Before implementing, write tests that should cover the new behaviour. Only write tests for the new behaviour.

3. Implement

Follow the plan. Do not add scope beyond what was agreed.

4. Verify Every Requirement

After implementation, go through each requirement one-by-one and confirm it is satisfied:

Run the relevant tests (unit, integration, or build check) for every changed module.
If a requirement cannot be fulfilled, do not silently skip it — document it immediately (see Unresolved Requirements below).

No Code Without Verification (Testing)

Every new behaviour must be covered by at least one automated test before the task is considered done.
Every bug fix must be accompanied by a regression test that fails before the fix and passes after.
Run ./gradlew :modules:<module>:test (or the appropriate Gradle task) and confirm a green build before marking work complete.
If a test cannot be written for a legitimate reason, document it in docs/unresolved.md with an explanation.

Automatic Bug Fixing

When a test or build step fails, attempt to fix the root cause immediately — do not ask for permission.
Apply the fix, re-run the verification, and continue until green.
If the same failure persists after three fix attempts, stop, log the issue in docs/unresolved.md, and surface a concise summary.

Unresolved Requirements → `docs/unresolved.md`

When a requirement or bug cannot be resolved, append an entry to docs/unresolved.md:

## [YYYY-MM-DD] <Short title>

**Requirement / Bug:**
<What was requested or what failed>

**Root Cause (if known):**
<Why it cannot be resolved right now>

**Attempted Fixes:**
1. <What was tried>
2. …

**Suggested Next Step:**
<What a human engineer should investigate>

Create the file if it does not exist. Never delete existing entries.

Project Structure

.                        ← Repository root (multi-project Gradle setup)
├── build.gradle.kts     ← Root build file (shared plugins, dependency versions)
├── settings.gradle.kts  ← Gradle settings (declares all subprojects)
├── modules/             ← One subdirectory per microservice
│   └── <service>/
│       ├── build.gradle.kts
│       └── src/
└── docs/                ← Architecture Decision Records, API docs, unresolved issues
    └── unresolved.md

Conventions

All microservices live under modules/{service-name}. Never place service code in the root.
Shared configuration (dependency versions, plugin setup) belongs in the root build.gradle.kts or in buildSrc / a version catalog.
settings.gradle.kts must include every module via include(":modules:<service>").
Architecture decisions go in docs/adr/ as numbered Markdown files (ADR-001-<title>.md).
API contracts live in /docs/api/.
Unit tests extend AnyFunSuite with Matchers with JUnitSuiteLike — no @Test annotations, no : Unit requirement
Integration tests use @QuarkusTest with JUnit 5 — @Test methods must be explicitly typed : Unit
Always exclude scala-library from Quarkus deps to avoid Scala 2 conflicts

Agent Routing Rules

Use agents in PARALLEL when:

Tasks touch different, independent microservices
No shared files or state between tasks
Example: "implement service-user AND service-orders simultaneously"

Use agents SEQUENTIALLY when:

Tasks have dependencies (architect → implementer → test-writer)
Shared API contracts are involved
Example: design API first, then implement, then test

Quick-Reference Checklist

Before considering any task done, confirm:

Plan was written and requirements restated
All planned files were created / modified
Automated tests cover the new behaviour
./gradlew build (or scoped task) is green
Each requirement has been explicitly verified
Any unresolved items are logged in docs/unresolved.md

4.4 KiB Raw Blame History Unescape Escape