tdd

Test-Driven Development

Use TDD to implement one observable behavior at a time.

The loop is:

one failing test -> smallest implementation -> refactor -> next test

Do not write all tests first. Do not implement the whole feature before the first failing test proves the path.

Read First

Before editing code, inspect:

• docs/agents/test-commands.md
• docs/agents/domain.md
• CONTEXT.md
• relevant ADRs under docs/adr/
• existing tests near the behavior
• package scripts or equivalent task definitions

If setup docs are missing, infer commands from the repo. Ask only if the verification command or behavior target is unclear.

Workflow

1. Clarify Behavior

Identify public behavior before test shape.

Capture:

• User-visible outcome.
• Acceptance criteria.
• Public interface or entry point.
• Existing behavior that must not regress.
• Out-of-scope behavior.

Ask the user only for product or acceptance decisions that cannot be answered from files or code.

2. Choose The First Vertical Slice

Pick the thinnest end-to-end behavior that proves the feature direction.

A vertical slice should:

• Be independently verifiable.
• Touch real integration points when reasonable.
• Avoid layer-only work with no observable outcome.
• Produce a small but meaningful behavior.

If the requested work is large, list slices and start with the smallest useful one.

3. Select Test Level

Prefer tests through public interfaces.

Good targets:

• Public function or module API.
• HTTP endpoint.
• CLI command.
• UI behavior through user interaction.
• Integration boundary already used by the repo.

Avoid:

• Private methods.
• Internal call counts.
• Mocking the unit that owns the behavior.
• Tests that break when implementation changes but behavior stays the same.

See references/test-quality-guide.md for examples.

4. Red

Write exactly one failing test for one behavior.

Then run the focused test command.

Confirm:

• The test fails.
• The failure is expected.
• The test would pass only if the desired behavior exists.