From 69ea7dfa50f431fd205b2adb18b04d41c92443f2 Mon Sep 17 00:00:00 2001
From: Andras Bacsai <5845193+andrasbacsai@users.noreply.github.com>
Date: Wed, 25 Mar 2026 14:08:48 +0100
Subject: [PATCH] docs(tdd): add bug fix workflow section with TDD requirements

Add a new "Bug Fix Workflow (TDD)" section that establishes the strict
test-driven development process for bug fixes. Clarify that every bug fix
must follow TDD: write a failing test, fix the bug, verify the test passes
without modification. Update the Key Conventions to reference this workflow.
---
 CLAUDE.md | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 8e398586b..5dc2f7eee 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -73,7 +73,7 @@ ## Key Conventions
 - PHP 8.4: constructor property promotion, explicit return types, type hints
 - Always create Form Request classes for validation
 - Run `vendor/bin/pint --dirty --format agent` before finalizing changes
-- Every change must have tests — write or update tests, then run them
+- Every change must have tests — write or update tests, then run them. For bug fixes, follow TDD: write a failing test first, then fix the bug (see Test Enforcement below)
 - Check sibling files for conventions before creating new files
 
 ## Git Workflow
@@ -231,6 +231,16 @@ # Test Enforcement
 - Every change must be programmatically tested. Write a new test or update an existing test, then run the affected tests to make sure they pass.
 - Run the minimum number of tests needed to ensure code quality and speed. Use `php artisan test --compact` with a specific filename or filter.
 
+## Bug Fix Workflow (TDD)
+
+When fixing a bug, follow this strict test-driven workflow:
+
+1. **Write a test first** that asserts the correct (expected) behavior — this test should reproduce the bug.
+2. **Run the test** and confirm it **fails**. If it passes, the test does not cover the bug — rewrite it.
+3. **Fix the bug** in the source code.
+4. **Re-run the exact same test without any modifications** and confirm it **passes**.
+5. **Never modify the test between steps 2 and 4.** The same test must go from red to green purely from the bug fix.
+
 === laravel/core rules ===
 
 # Do Things the Laravel Way