From f99e114770452d96bbdbcb9822f022aed1894343 Mon Sep 17 00:00:00 2001
From: Jef Roosens <jefroosens@outlook.com>
Date: Thu, 28 May 2026 12:51:57 +0200
Subject: [PATCH] docs: require TDD workflow in AGENTS.md

New functionality must follow the red-green-refactor cycle:
1. Write failing tests first
2. Confirm they fail before implementing
3. Implement until tests pass
4. Run full suite to check for regressions
---
 AGENTS.md | 28 +++++++++++++++++-----------
 1 file changed, 17 insertions(+), 11 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index e4224d8..2add69f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -72,15 +72,23 @@ uv run pytest tests/test_parser.py::TestParseTable::test_empty_input
 
 ### Rules for adding or changing functionality
 
-1. **Always update or add tests** when introducing new behaviour or modifying
-   existing behaviour. Tests live in the `tests/` file that corresponds to the
-   module being changed (e.g. changes to `parser.py` → `tests/test_parser.py`).
+1. **Use test-driven development (TDD) for new functionality.** The workflow is:
+   1. Write the tests first, based on the expected behaviour.
+   2. Confirm the new tests *fail* before writing any implementation:
+      ```sh
+      uv run pytest tests/test_<module>.py
+      ```
+   3. Implement the functionality until all tests pass.
+   4. Run the full suite to confirm nothing regressed:
+      ```sh
+      uv run pytest --cov
+      ```
+   Skipping the "confirm it fails" step defeats the purpose of TDD — a test
+   that never fails gives no confidence.
 
-2. **Run the full test suite before finishing** and confirm it passes with no
-   failures:
-   ```sh
-   uv run pytest --cov
-   ```
+2. **Always update or add tests** when modifying existing behaviour. Tests live
+   in the `tests/` file that corresponds to the module being changed
+   (e.g. changes to `parser.py` → `tests/test_parser.py`).
 
 3. **Do not reduce coverage.** Every new function or branch should have at
    least one test covering the happy path. Edge cases and error paths should be
@@ -92,9 +100,7 @@ uv run pytest tests/test_parser.py::TestParseTable::test_empty_input
 5. Joplin integration tests in `test_joplin.py` must mock `ClientApi` — do not
    require a live Joplin instance.
 
-# Development Guidelines
-
-# CLAUDE.md
+# Behavioral Guidelines
 
 Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.