4.1 KiB
name, description
| name | description |
|---|---|
| test-driven-development | Drive red-green-refactor implementation with tests written by someone other than the implementation agent, using public behavior and independent expected values. |
test-driven-development
Use test-driven development as process discipline for behavior-bearing changes. The result is working behavior plus useful tests, not a separate report artifact.
1. Establish roles and behavior backlog
Name the two functional roles before writing tests. The implementation agent changes production code and drives the loop. The test writer writes and edits tests. Tests are always written by someone other than the agent doing implementation.
Launch an independent test writer through whatever real context boundary the current harness provides. A separate agent, worker, subprocess, or documented headless session is sufficient when it cannot see the implementation agent's private backlog. If no real context boundary is available, stop before writing tests and report that test-driven development cannot be completed in the current runtime. Do not replace the independent test writer with an in-process role switch. Do not silently skip the independent-test-writer requirement.
The implementation agent may keep a private behavior backlog. Keep that backlog isolated from the test writer. The test writer receives one behavior at a time, not the whole backlog.
Done when roles are explicit and the implementation agent has the next behavior ready without exposing the whole backlog to the test writer.
2. Choose the public seam and source of truth
Test public behavior through the interface the code exposes or the task requires. When the seam is unclear, identify the smallest public seam that can prove the behavior. Do not test internals just to make RED easy.
Each test needs an independent source of truth for expected values. Acceptable sources include a spec, task, intent excerpt, worked example, known-good literal, existing behavior being preserved, user clarification, or external standard. The implementation agent's derived computation is not enough.
Done when the next behavior has a public seam, enough context for the test writer, and an independent expected-value source.
3. Run one red-green cycle
Give the test writer exactly one behavior, the public seam and context, the independent expected-value source, and any relevant project test conventions. The test writer writes or edits one test for that behavior and confirms it fails for the intended reason. A failing test should fail because the behavior is missing or wrong, not because of import, syntax, fixture, or collection errors.
The implementation agent writes the minimal production code needed to pass that test. The implementation agent must not edit test-writer-authored tests. If the test has a mechanical defect, send the error back to the test writer. If the implementation agent believes the test asserts the wrong semantics, pause for user or intent clarification.
Done when one behavior has a meaningful failing test and then passes through production-code changes made by the implementation agent.
4. Repeat behavior by behavior
Repeat the red-green cycle one behavior at a time. Do not bulk-write tests before implementation. Do not let the test writer see the behavior backlog. Do not add speculative behavior while making the current test pass.
Run focused verification as each behavior lands. Use broader verification when the repository or change warrants it.
Done when every selected behavior has passed through the one-behavior red-green loop or has been deliberately deferred by the implementation agent's judgment.
5. Refactor only after green
Never refactor while RED. After tests pass, the implementation agent may refactor production code. Refactoring means changing code structure without changing externally observable behavior.
The test writer updates tests only for deliberate public seam changes or test defects. A test failure during refactoring normally means production behavior broke. Fix production code unless the public seam changed deliberately.
Done when refactoring, if any, is complete and the relevant tests remain green.