CORE GUIDE
Test-first AI coding
AI coding is safer when executable expectations exist before generation, because tests give the agent and reviewer an external contract that does not depend on the generated code explaining itself.
Mental model
Test-first AI turns desired behavior into independent executable evidence before implementation. The model may choose the code, but it does not get to redefine what success means after seeing its own solution.
Why it matters
Coding agents can create large plausible diffs quickly and then produce equally plausible explanations for why they are correct. Existing or newly written failing tests anchor the task in observable behavior, constrain regressions and make iteration faster because the agent can receive deterministic feedback instead of relying on self-review.
01
Create the smallest failing contract first
Translate acceptance criteria into tests at the most stable interface available. Confirm the test fails for the intended reason before asking the agent to implement. Let the agent iterate until the targeted test and relevant regression suite pass, then still review whether the test itself is sufficient, whether implementation widened scope and whether non-testable requirements need additional evidence.
02
Example: retry fix must not duplicate payment
Before changing retry logic, a test simulates timeout ambiguity and asserts that two deliveries with the same operation key cause one settlement. The agent can refactor clients or state handling, but it cannot declare success until the invariant holds. Review then checks logging and migration concerns that the test does not cover.
Common failure modes
- Writing tests after the generated implementation and unconsciously matching its behavior.
- Using snapshots that prove output stayed the same without proving the important invariant.
- Treating green tests as proof that requirements not represented by tests are satisfied.
Engineering heuristics
- Make the first test express the consequential behavior, not an internal implementation detail.
- Run the relevant regression suite, not only the newly added test.
- Review test adequacy separately from implementation correctness.
Takeaways
- 01Tests provide evidence independent of model confidence.
- 02Test-first constrains generation before code exists.
- 03Green tests are necessary evidence, not complete proof.
Reading evidence
This records actions you actually took; it does not claim mastery, proficiency, or certification.
Used in
This Concept is reused across these canonical learning paths.
Related concepts from the Knowledge Graph
These relationships come from the canonical graph, not a separate Guide taxonomy.