CORE GUIDE
Specify before you generate
AI-assisted implementation becomes controllable when the intended behavior and acceptance evidence are defined before code is generated.
Mental model
A specification is an executable boundary around generation: it states the problem, constraints, non-goals, affected interfaces and observable acceptance criteria that generated work must satisfy.
Why it matters
Coding agents are very good at filling ambiguity with plausible implementation choices. If the task is underspecified, successful-looking code may solve the wrong problem, widen scope or introduce architecture that nobody requested. A strong spec reduces rework because it gives the agent a target and gives reviewers evidence that is independent of the agent's own claim of completion.
01
Convert intent into observable contracts
Before generation, write the desired user or system behavior, relevant repository constraints, interfaces that may change, explicit non-goals and acceptance checks. Link each important requirement to evidence such as a test, type check, migration verification or manual review criterion. Then let the agent plan against those constraints before editing files.
02
Example: add sorting to a media downloader
Instead of asking an agent to 'improve filtering', the spec defines sortable fields, default order, pagination behavior, backward compatibility and the tests that must pass. The agent can choose implementation details, but it cannot silently reinterpret the feature as a new search system or change unrelated download behavior.
Common failure modes
- Starting generation from a vague feature sentence and clarifying only after code appears.
- Writing acceptance criteria that merely restate 'works correctly'.
- Letting the generated implementation redefine the original requirement.
Engineering heuristics
- State non-goals to prevent attractive but unnecessary scope expansion.
- Attach at least one observable acceptance check to every consequential requirement.
- Ask for a plan when the change crosses multiple files, boundaries or migrations.
Takeaways
- 01Specification reduces ambiguity before it becomes code.
- 02Acceptance evidence should exist independently of model confidence.
- 03Good specs constrain outcomes while leaving room for implementation choices.
Related concepts from the Knowledge Graph
These relationships come from the canonical graph, not a separate Guide taxonomy.