chore: Add initial architecture decision records and project documentation

2026-03-21 15:31:52 +01:00
parent 0d6935e184
commit 5ecc70f5a0
7 changed files with 234 additions and 0 deletions
@@ -0,0 +1,108 @@
+# Claude Code – Working Agreement
+
+## Workflow: Plan → 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. Implement
+Follow the plan. Do not add scope beyond what was agreed.
+
+### 3. 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`:
+
+```markdown
+## [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/`.
+- Tests must have `: Unit` return type (JUnit + Scala 3 requirement)
+- 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`