Decision 0056 · Accepted
Contract-first tests, no UI tests
by default
Principle 8, "Agent-first, API-first", has products define capabilities as contracts before interfaces, and to-spec writes API shapes and MCP tool definitions before any UI.
- Status
- Accepted
- Built from:
- da88c48
Status: Accepted (2026-10-31). Amends 0042 items 1 and 5 (test order), for contracts only. Preserves 0023, 0044, and 0045. Spec: 047. Amended by 0065 (items 1 and 3: test-first is targeted at consequential contracts; other behavior needs evidence, not necessarily a test).
Context
Principle 8, "Agent-first, API-first", has products define capabilities as contracts before interfaces, and to-spec writes API shapes and MCP tool definitions before any UI. 0042 left test order to the agent: a check must fail if a named behavior is missing, and writing it first is "allowed and not required". In practice, agents ship MCP tools and routes whose errors and permissions were never exercised, while early UI collects brittle tests that churn with each design change.
Decision
- Contracts are test-first. When a change adds or changes an API route, an MCP tool, or the domain function behind them,
buildwrites a focused check of the contract first, sees it fail, then implements. The check covers input, result, actionable errors, and permissions, one check per behavior. - No UI tests by default. UI is verified in the running preview. A UI test is added only on request, when a spec names one, or when the same UI regression returns.
- Order stays free elsewhere. Other behavior keeps 0042 item 5: a check that fails without the change, written in any order.
- Projects may differ. A testing policy stated in the project's
ARCHITECTURE.mdoverrides items 1 and 2.
Alternatives
- Stay order-neutral everywhere (0042 as is). Rejected: contracts are what agents depend on, and a test written after the code tends to confirm the code rather than the contract.
- Test-first for all behavior. Rejected: more ceremony than the risk warrants; internal logic and early UI change too often to pay for it.
- Put the policy in
PRODUCT.md. Rejected:PRODUCT.mdowns outcomes; system contracts belong toARCHITECTURE.md.
Consequences
build gains a short Tests section that owns this rule; review checks that a changed contract has a failing-without-change check and does not expect UI tests. The templates' bundled TDD skill overlaps build and is theirs to drop. Evidence of order comes from the session log (the focused check failing before the implementation), so a squashed history alone cannot show it.