A specification is a structured, durable artifact that turns software intent into a target humans can review and coding agents can implement. It records what should happen, the constraints that shape the solution, and how to verify the outcome. A saved prompt or task list alone is not a specification: it may direct one session without preserving the decisions needed for later changes. section 2.1 section 2.6
The central problem is not whether an agent can generate code from a brief request; it is how much the agent must guess. Author the specification through dialogue: state the purpose, let the agent probe ambiguities, review its proposed decisions, and retain only the detail needed to prevent consequential assumptions. The result should be a primary reference for behavior, organized so relevant context can be retrieved without reconstructing intent from chat history or code. section 2.1.2 section 2.1.1
Separate the conversations before implementation, then revisit them as the feature evolves:
- Discover what the feature is for, who needs it, its scope, and its observable outcomes. section 2.2.1
- Design the technical approach and constraints; derive tasks for execution rather than mixing every decision into one prompt. section 2.2.1 section 2.6
- Use the reviewed artifacts to guide implementation and validation. Specify features incrementally; revise earlier decisions when implementation exposes a gap. section 2.2 section 2.5.1
A URL shortener’s first slice
A bounded proposal asks the agent to clarify scope before drafting: anonymous users submit a long URL, receive a short URL, and follow it to the original. The artifacts distinguish purpose and exclusions, design choices, requirements with valid- and invalid-URL scenarios, and implementation tasks. Initially, links remain permanent and features such as accounts, custom aliases, and click tracking stay out of scope. A later request for 90-day expiry modifies existing behavior; reviewing the prior specification exposes decisions that a code-only change might miss. section 2.4.4 section 2.4.6
Keep the specification authoritative after code generation. If testing reveals that malformed URLs cause a server error, a direct code patch fixes the symptom but leaves future agents with the same vague instruction to “validate input.” Clarify the rejection rule and expected response in the specification, then bring implementation back into line. If the rule was discussed but lost when written down, improve the artifact’s format; if it was never discussed, improve the questions asked. section 3.1.1 section 3.2.2 section 3.1
Listing 3.2 Capturing malformed URL validation in Gherkin format
Feature: Shorten URL
Scenario: Reject malformed URL
Given the user submits a malformed URL
When the shorten URL request is processed
Then the service returns the expected validation status
And the response explains the validation failure
And no short link is storedThe validation scenario makes the expected response and absence of a stored link explicit, rather than leaving “return an error” open to interpretation. section 3.2.2











