How to Build Features With TDD

TDD feature building is the practice of turning a feature spec into tests before production code, then using those tests to drive the smallest implementation that satisfies the acceptance criteria. The important part is not that tests exist by the end. The important part is that each test failed for the right reason before the code was written.

That order protects the team from the most common failure in agent-assisted development: code appears quickly, tests are added afterward, and nobody knows whether the tests prove the behavior or mirror the implementation. A test-first loop makes the spec, edge cases, and review evidence visible.

Why feature work quietly drifts without TDD

Feature specs usually look clear until implementation starts. Acceptance criteria hide edge cases. Existing code has conventions the spec does not name. A coding agent can produce a plausible patch fast, but speed creates risk when no one saw a failing test describe the behavior first.

The drift shows up late: a PR with broad changes, tests that passed immediately, missing error cases, and a description that says what changed without proving why it is correct. Reviewers then have to reverse-engineer the spec from the diff. That is slow work, and it misses regressions.

What the manual process looks like

A disciplined human TDD loop has a clear ritual:

1. Read the feature brief and acceptance criteria.
2. Map the files and conventions before writing code.
3. Break the feature into bite-sized steps, each with its own behavior and test.
4. Write one minimal failing test and run it.
5. Confirm the failure is the expected failure, not a setup error.
6. Write the smallest code that makes it pass, then refactor only while green.
7. Repeat for error and boundary cases, run the full suite once, and draft the PR.

The ritual is not glamorous, but it is the difference between a patch that looks done and a patch whose behavior is locked in.

What an agent can automate

The TDD feature builder playbook turns that ritual into a controlled workflow:

• Plan from the spec. The agent scope-checks the feature, maps the touched files, and turns the spec into a bite-sized plan with no placeholder steps.
• Translate criteria into tests. Each acceptance criterion becomes a behavioral test, including important error and boundary cases.
• Verify red before green. The agent runs each new test and confirms it fails for the right reason before touching production code.
• Implement minimally. It writes the smallest code that passes, avoids speculative options, and refactors only after the tests are green.
• Prepare review evidence. It runs the full suite once at the end, self-reviews against the spec, and drafts a PR that names the tests covering each criterion.

The agent is doing engineering labor, not making the merge decision. The workflow stops at approval.

The guardrails that make it safe

The hard rule is simple: no production code without a failing test first. If production code appears ahead of its test, the agent must delete it and re-implement from the test. Exceptions such as generated code, config, or throwaway prototypes require a human decision.

The second guardrail is failure verification. A test that passes instantly proves nothing. A test that errors because the setup is broken also proves nothing. The workflow forces the agent to watch the test fail for the behavior it is meant to protect.

The final guardrail is the PR approval step. The agent drafts the PR and lists the coverage, but a human reviews the feature, the tests, and the proof that the suite is green before anything merges.

Set it up in Task Machine

The TDD feature builder playbook installs the coding agent, the TDD feature workflow, and the standing goal that keeps features shipping test-first. Setup takes a few minutes. You need a Task Machine workspace and permission to install playbooks (workspace owners have it). Repository access can be connected after install. Until then, the agent works from code and context attached to the run and drafts the PR for you to open.

1. Find the playbook

Open Playbooks and search for "TDD feature builder", or browse the Engineering category. The card shows the coding agent, workflow, goal, and TDD skills the install creates.

2. Preview what it installs

Preview & install opens the full contents before anything is created: the TDD Coding Agent, the TDD feature workflow, the Features shipped test-first goal, and the skills for test-driven development, planning, and implementation.

3. Describe the feature context

Start setup asks for the repository, feature brief, acceptance criteria, and verification command. The repository can stay empty during capture or early setup if you plan to connect it later, but the feature brief and acceptance criteria should be concrete enough for tests.

4. Generate and review

Generate customized playbook bakes the feature context into the agent instructions and workflow prompts. Review the generated playbook for the iron law, failure verification, edge-case coverage, full-suite check, PR draft, and human approval gate.

5. Install

Install customized playbook creates the agent, workflow, goal, and skills in your workspace. One follow-up lands in your inbox: start the TDD feature workflow. The first run asks you to confirm the acceptance criteria, repo conventions, check commands, and PR handoff, then the agent starts at the failing-test step and stops at approval.

What good looks like

The workflow is healthy when these are true:

• Every acceptance criterion has a behavioral test. The PR description maps criteria to tests instead of saying "tests added" in bulk.
• Each new test was seen red first. The failure reason matches the behavior being protected.
• The suite is green once at the end. Short loops run during the work, and the full test suite runs before the PR is handed off.

Common questions

Can this run without repository access? Yes. The agent can work from attached code and context, then draft the PR for you to open. Connecting repository access lets it read the codebase and prepare the PR in place.

What if a test passes as soon as it is written? That usually means the test describes existing behavior or the wrong behavior. The agent should revise the test until it fails for the intended reason before implementing.

Does the agent merge the PR? No. The workflow drafts the PR and waits for human approval. Merge remains a human decision.

Does TDD slow down small features? It adds a visible test loop, but it removes review ambiguity. For agent-built features, that tradeoff is usually worth it because the reviewer gets behavior evidence instead of only a diff.