From 05fc1c60f4c65e3b0efdb1bb6b9669be1fbc479d Mon Sep 17 00:00:00 2001
From: Jason Woltje <jason.woltje@uscllc.com>
Date: Wed, 28 Jan 2026 17:51:55 -0600
Subject: [PATCH] docs: Add comprehensive TDD requirements to CLAUDE.md

- Add detailed TDD workflow (Red-Green-Refactor)
- Specify test-first approach as non-negotiable
- Include testing requirements (85% coverage minimum)
- Add test types and running instructions
- List TDD anti-patterns to avoid
- Provide example TDD session workflow

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 CLAUDE.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 90 insertions(+), 3 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 135c8bf..5327753 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -267,11 +267,98 @@
   Fixes #123
   Types: feat, fix, docs, test, refactor, chore
 
+  Test-Driven Development (TDD) - REQUIRED
+
+  **All code must follow TDD principles. This is non-negotiable.**
+
+  TDD Workflow (Red-Green-Refactor)
+
+  1. **RED** — Write a failing test first
+     - Write the test for new functionality BEFORE writing any implementation code
+     - Run the test to verify it fails (proves the test works)
+     - Commit message: `test(#issue): add test for [feature]`
+
+  2. **GREEN** — Write minimal code to make the test pass
+     - Implement only enough code to pass the test
+     - Run tests to verify they pass
+     - Commit message: `feat(#issue): implement [feature]`
+
+  3. **REFACTOR** — Clean up the code while keeping tests green
+     - Improve code quality, remove duplication, enhance readability
+     - Ensure all tests still pass after refactoring
+     - Commit message: `refactor(#issue): improve [component]`
+
   Testing Requirements
 
-  - Minimum 85% coverage for new code
-  - Write tests before implementation (TDD)
-  - All tests must pass before PR merge
+  - **Minimum 85% code coverage** for all new code
+  - **Write tests BEFORE implementation** — no exceptions
+  - Test files must be co-located with source files:
+    - `feature.service.ts` → `feature.service.spec.ts`
+    - `component.tsx` → `component.test.tsx`
+  - All tests must pass before creating a PR
+  - Use descriptive test names: `it("should return user when valid token provided")`
+  - Group related tests with `describe()` blocks
+  - Mock external dependencies (database, APIs, file system)
+
+  Test Types
+
+  - **Unit Tests** — Test individual functions/methods in isolation
+  - **Integration Tests** — Test module interactions (e.g., service + database)
+  - **E2E Tests** — Test complete user workflows with Playwright
+
+  Running Tests
+
+  ```bash
+  pnpm test              # Run all tests
+  pnpm test:watch        # Watch mode for active development
+  pnpm test:coverage     # Generate coverage report
+  pnpm test:api          # API tests only
+  pnpm test:web          # Web tests only
+  pnpm test:e2e          # Playwright E2E tests
+  ```
+
+  Coverage Verification
+
+  After implementing a feature, verify coverage meets requirements:
+  ```bash
+  pnpm test:coverage
+  # Check the coverage report in coverage/index.html
+  # Ensure your files show ≥85% coverage
+  ```
+
+  TDD Anti-Patterns to Avoid
+
+  ❌ Writing implementation code before tests
+  ❌ Writing tests after implementation is complete
+  ❌ Skipping tests for "simple" code
+  ❌ Testing implementation details instead of behavior
+  ❌ Writing tests that don't fail when they should
+  ❌ Committing code with failing tests
+
+  Example TDD Session
+
+  ```bash
+  # 1. RED - Write failing test
+  # Edit: feature.service.spec.ts
+  # Add test for getUserById()
+  pnpm test:watch  # Watch it fail
+  git add feature.service.spec.ts
+  git commit -m "test(#42): add test for getUserById"
+
+  # 2. GREEN - Implement minimal code
+  # Edit: feature.service.ts
+  # Add getUserById() method
+  pnpm test:watch  # Watch it pass
+  git add feature.service.ts
+  git commit -m "feat(#42): implement getUserById"
+
+  # 3. REFACTOR - Improve code quality
+  # Edit: feature.service.ts
+  # Extract helper, improve naming
+  pnpm test:watch  # Ensure still passing
+  git add feature.service.ts
+  git commit -m "refactor(#42): extract user mapping logic"
+  ```
 
   Docker Deployment