Principle
AI increases throughput of code; tests and types increase trust in revision. Maintainability is the ability to change the product next month without fear — especially when you did not write every line yourself.
The goal is not maximum coverage. The goal is confidence at the boundaries that hurt users: money, auth, data loss, and the core workflow you validated in Discover.
The decision
DEC_013
┌─────────────┐
│ E2E (few) │ critical user paths
├─────────────┤
│ Integration │ API + DB, webhooks
├─────────────┤
│ Unit (many)│ pure logic, parsers
└─────────────┘What to test first
| Priority | Examples | Why |
|---|---|---|
| P0 | Sign up, pay, delete account, core workflow | User trust |
| P1 | Permissions, idempotency on webhooks | Security + money |
| P2 | Edge cases from support tickets | Regression fuel |
| P3 | Snapshot everything | False confidence |
Ask agents to write tests with the feature, not in a later “test sprint” that never ships.
Maintainability habits
- CI on every PR — build + lint + test; agents do not merge around it.
- Types or schemas — inputs validated at boundaries; models hallucinate shapes.
- Small modules — files you can delete without archaeology.
- Fix flukes immediately — flaky tests train you to ignore red.
- Delete dead code — agents add; humans prune.
Working with AI on tests
- Prompt: “Implement X and add tests for acceptance criteria A, B, C.”
- Reject tests that only assert mocks or mirror implementation line-for-line.
- Require one failure test — prove the test can catch a break.
- For UI: prefer few Playwright paths over hundred component snapshots.
Workflow
- Acceptance criteria in ticket → map 1:1 to test descriptions.
- Implement feature + tests in same PR.
- CI green before review; human reads test names for intent.
- On bug: regression test first, then fix.
- Quarterly: delete tests that no longer encode a decision.
Tooling
Vitest, Jest, pytest — pick what your stack uses. Playwright or Cypress for thin E2E. TypeScript, Zod, or DB constraints for shape. GitHub Actions or similar for CI.
Common mistakes
- 100% coverage vanity while P0 paths untested.
- Letting agents disable CI “temporarily.”
- No test for webhooks — production surprises at 2am.
- Testing implementation details — refactors become impossible.
Artifacts
templates/test-plan.md— P0/P1 map per feature.- Regression rule: no bug fix without a test unless explicitly documented why.
Further reading
- Chapter 09 — AI pair programming
- Chapter 11 — Architecture decisions
- Chapter 13 — Deployment