Tdd With Llm Agents

REFACTOR — clean up under green

1. Improve structure: remove duplication, improve naming, simplify logic.
2. Do NOT add new behavior.
3. Run tests after every change. All must stay green.
4. Refactor implementation first (tests are the fixed reference), then optionally refactor tests (implementation is the fixed reference). Never both simultaneously.

Repeat

Return to RED with the next behavior. Continue until the feature is complete.

Hard constraints

• NEVER modify or delete a test to make it pass.
• NEVER write implementation without a corresponding failing test.
• NEVER skip the red phase (running the test to see it fail).
• NEVER add functionality beyond what the current test requires.
• NEVER proceed to the next test until the current cycle is complete.
• If you believe a test is wrong, explain why — but do not change it without explicit approval.

Test quality

• Test the public interface, not implementation details.
• One behavior per test — single, unambiguous target.
• Use concrete input/output values, not abstract descriptions.
• Each test must be independent and self-contained.
• Start with happy-path behavior, then add edge cases in later cycles.

Generating a TDD plan

For larger features, generate a plan before starting cycles:

1. Produce a numbered checklist of test descriptions, ordered simplest to most complex. One behavior per item.
2. Do not write any code yet.
3. Get approval, then execute one test at a time via red/green/refactor.

Recovering from mistakes

• Agent wrote implementation before test: Stop. Delete the implementation. Write the failing test first.
• Agent modified a test to pass: Revert the test change. Fix the implementation instead.
• Test passes unexpectedly (no red): The test does not exercise new behavior. Rewrite or discard it.
• Context window getting large: Summarize completed work. Re-run the full test suite to re-anchor.

Reference material

• Principles and context: references/01-principles-and-context.md — why TDD fits agents, structural biases, foundational principles
• Workflow and test specifications: references/02-workflow-and-test-specifications.md — detailed phase descriptions, tests-as-prompts patterns, TDD plan generation
• Prompt templates and enforcement: references/03-prompt-templates-and-enforcement.md — AGENTS.md rules template, prompt templates, hooks, guards, git safety nets
• Anti-patterns and pitfalls: references/04-anti-patterns-and-pitfalls.md — ten common failure modes and their fixes