Spec Anti-Patterns and Constraint Language

Most failed Autobuild runs trace back to a spec problem, not a code problem. The agent writes exactly what you describe — which means how you write the spec determines what gets built. This article covers the five most common spec mistakes and the language conventions that help agents interpret your intent accurately.

Common Failure Modes

"Just build it" specs

What goes wrong: A one-line request forces the agent to make every decision—product, UX, and technical—during implementation.

What to do instead: Provide a product spec with the user problem, desired outcome, and success criteria.

Product specs that are feature lists

What goes wrong: A feature list tells the agent what to build, but not why or what success looks like. The agent builds faithfully but may not solve the underlying problem.

What to do instead: Lead with the outcome — an observable change in user behavior — then list features that serve it.

UX specs that describe instead of show

What goes wrong: Prose like "The notification panel should appear on the right side" is insufficient. Agents interpret literally, inventing missing details like edge states and error handling.

What to do instead: Build actual prototype components. A prototype artifact with real data, states, and edge cases serves as a spec.

Technical specs grounded in assumptions, not code

What goes wrong: Assumptions like "The WebSocket service probably lives in the API layer" lead to PRs targeting wrong files and CI failures.

What to do instead: Read the code. Name actual files, services, schemas, and routes. Cite evidence, not expectations.

Monolithic specs

What goes wrong: A single document mixing product intent, UX decisions, and technical architecture is hard to review and forces the agent to parse all three phases simultaneously.

What to do instead: Keep each phase in its own document. Separate files let specs evolve independently and let the agent load only relevant context.

Writing for the Agent

Autobuild agents read specs literally — they implement what's written, not what you intended. These conventions close the gap.

Use the constraint language spectrum

Your word choice binds the agent's behavior:

Tier	Words	How the agent treats it
Hard constraint	must, must not, always, never	Hard acceptance criterion; agent will not deviate.
Soft guidance	should, prefer, ideally	Treated as guidance; agent may deviate if simpler.
Dangerous	could, consider, might, probably	Treated as optional; agent often skips entirely.

When something matters, use "must." When something is genuinely flexible, "should" is fine. Avoid "could" and "consider" for anything you actually care about.

Name things consistently

Call it a "notification" in the product spec, UX spec, and technical spec. Don't switch between "notification," "alert," "message," and "update."

Reference artifacts by ID

Use art_xyz, not "the notification panel design." The agent opens artifacts by ID directly.

State negative requirements explicitly

'Do not persist notifications to localStorage' is more useful than assuming the agent will avoid it. Agents optimize for the simplest solution.

Keep each phase in its own document

Three focused documents let the agent load only context relevant to the current phase. A single monolithic spec increases misinterpretation risk.