title: Test-First Agent slug: test-first-agent category: workflow-pattern status: proven difficulty: intermediate tags: [TDD, testing, test-driven, quality, verification] prerequisites: [basic-cli-usage, testing-basics] estimated_time: 10min to learn, varies per task cost_per_use: "$0.15-$1.00"

Test-First Agent

Problem

When an agent writes code and tests together, the tests tend to validate what the code does rather than what it should do. The agent unconsciously writes tests that pass, not tests that verify correctness. If there is a bug in the implementation, the test enshrines it. You need the tests to be an independent specification that the implementation must satisfy.

Solution

Write tests first with the agent, lock them in, then implement code to pass them. The test suite becomes a contract that constrains the implementation.

Step-by-Step

1. Specify behavior: Describe the desired behavior in plain language.
2. Generate tests: Ask the agent to write tests based on the specification, with no implementation.
3. Review tests: Verify the tests capture your intended behavior and edge cases.
4. Lock tests: Commit the tests. They are now the acceptance criteria.
5. Implement: Ask the agent to write code that makes all tests pass.
6. Verify: Run the test suite. If tests fail, the agent fixes the implementation (not the tests).

When to Use

• Building new features with clear behavioral requirements
• Replacing or rewriting existing functionality
• When correctness matters more than speed
• When you can articulate the expected behavior but not the implementation
• Fixing bugs (write a failing test first, then fix the code)

When NOT to Use

• Exploratory prototyping where requirements are unclear
• UI/visual work where tests are hard to write meaningfully
• Performance optimization (behavior tests already exist, you need benchmarks)
• Trivial CRUD with no business logic

Example: Claude Code

# Step 1: Generate tests from a specification
claude -p "Write Jest tests for a new PricingCalculator class with these rules:
  - Base price comes from the product catalog
  - 10% discount for orders over \$100
  - 20% discount for premium members
  - Discounts do not stack (use the higher one)
  - Tax is applied after discounts (rate varies by state)
  - Minimum final price is \$1.00

  Write thorough tests covering all rules and edge cases.
  Create the test file at tests/pricing-calculator.test.ts.
  Do NOT create the implementation file."

# Step 2: Review and commit the tests
cat tests/pricing-calculator.test.ts
git add tests/pricing-calculator.test.ts
git commit -m "test: add PricingCalculator specification tests"

# Step 3: Verify tests fail (no implementation yet)
npm test -- tests/pricing-calculator.test.ts
# Expected: all tests fail

# Step 4: Implement to pass the tests
claude -p "Implement src/pricing-calculator.ts to make all tests in \
  tests/pricing-calculator.test.ts pass. \
  Do NOT modify the test file. \
  Run 'npm test -- tests/pricing-calculator.test.ts' after implementation \
  to verify all tests pass."

# Bug fix workflow: test-first
claude -p "There's a bug: premium members are charged full price on orders \
  over \$100. Write a failing test in tests/pricing-calculator.test.ts that \
  demonstrates this bug. Do NOT fix the implementation yet."

# Verify the test fails
npm test -- tests/pricing-calculator.test.ts

# Now fix
claude -p "Fix src/pricing-calculator.ts so the new failing test passes. \
  Do not modify any tests. All existing tests must continue to pass."

Example: Codex CLI

# Generate tests first
codex -q "Write Jest tests for a PricingCalculator class. Rules:
  - 10% discount over \$100, 20% for premium, no stacking.
  - Tax after discounts, minimum \$1.00.
  Save to tests/pricing-calculator.test.ts. Do NOT create implementation."

# Lock the tests
git add tests/pricing-calculator.test.ts && git commit -m "test: pricing spec"

# Implement
codex -q "Implement src/pricing-calculator.ts to pass all tests in \
  tests/pricing-calculator.test.ts. Do not modify the tests."

Cost Estimate

Maturity Notes

Status: Proven. This pattern produces the highest-quality agent-generated code. The main challenge is writing good test specifications — vague specs produce vague tests. Be explicit about edge cases, error conditions, and boundary values. Some practitioners write the test descriptions (test names and comments) by hand and let the agent fill in assertions. Works best with well-established test frameworks where the agent can follow patterns.

Related

• Pattern: Review Then Fix
• Pattern: Checkpoint Commit
• Module: Hooks & Commands