From 0918e758030e1d21a5e831c72079553a07811721 Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Thu, 19 Mar 2026 12:03:50 +0100
Subject: [PATCH] docs: add Red/Green TDD workflow to COLLABORATING.md

---
 COLLABORATING.md | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/COLLABORATING.md b/COLLABORATING.md
index 871d70a9..60f32798 100644
--- a/COLLABORATING.md
+++ b/COLLABORATING.md
@@ -12,11 +12,37 @@ Every non-trivial feature or bug fix follows this sequence:
 
 1. **Research** — Read the relevant code. Understand existing patterns before touching anything.
 2. **Plan** — Write a plan to `/.agent/current-plan.md` and align with the user before writing code. Update the plan as work progresses.
-3. **Implement** — Build with tests and error handling. Use pure functions where possible.
+3. **Implement** — Use Red/Green TDD (see below).
 4. **Validate** — Run formatters, linters, and tests after every implementation step.
 
 Never start writing code without having read the relevant files first.
 
+## Red/Green TDD
+
+All new behavior is driven by tests written **before** the implementation. The cycle is:
+
+1. **Red** — Write a test that captures the requirement. Run it and confirm it fails. A test that passes before the implementation is written is not testing anything real.
+2. **Green** — Write the minimum production code needed to make the test pass. No more.
+3. **Refactor** — Clean up the implementation (names, structure, duplication) while keeping the test green.
+4. **Commit** — The test and implementation ship together in a single logical commit.
+
+Repeat for each new behavior.
+
+### What level of test to write
+
+| Scenario | Test type |
+|---|---|
+| Business logic, calculations, service rules | Unit test (`DocumentServiceTest`, etc.) |
+| HTTP contract, request validation, error codes | Controller slice test (`@WebMvcTest`) |
+| Full user-facing behavior, navigation, forms | E2E Playwright spec |
+
+### Rules
+
+- Never write production code without a failing test that requires it.
+- Keep the Green step minimal — resist adding "obvious" extras that have no test yet.
+- The Refactor step must not change behavior — if a test breaks, the refactor introduced a bug.
+- If a bug is reported with no test, write the failing test first, then fix it.
+
 ## Issue Tracking (Gitea)
 
 All work is tracked in **Gitea** at `http://192.168.178.71:3005` (repo `marcel/familienarchiv`). Never use todo files or CLAUDE.md notes as a substitute.