Spec writing
Spec writing is a core skill of the product builder and one of the most effective ways to reduce hallucinations and inconsistent outputs from AI agents.
The spec as a co-created artifact
The spec "is born within the team that builds" (Yeret): it is a step forward when it is written by those who will build, and a step backward when someone hands it over from outside.
It is not a document that the human hands over to the agent, but one that is built collaboratively. The human contributes the what and the why (the strategic direction, the business requirements, and the constraints), and the agent proposes the how in detail. The human validates, corrects, and approves.
This collaboration leverages the strengths of each party: language models excel at working out details when they have a clear high-level directive, but they get lost when they lack a defined mission. The human provides the direction; the agent provides the thoroughness.
The six areas of an effective spec
GitHub analyzed more than 2,500 agent configuration files in public repositories and found a clear pattern: the most effective specs cover six areas (published on the GitHub Blog in 2025):
- Commands: not just tool names but complete commands with parameters. Not "use npm" but "npm run build to compile, npm test to run tests, npm run lint --fix to fix style."
- Testing: how to run the tests, which framework is used, where the test files live, and what coverage is expected.
- Project structure: where the source code, the tests, and the documentation live. Be explicit: "src/ for application code, tests/ for unit tests."
- Code style: one real code snippet that shows the project's style is worth more than three paragraphs describing it. Naming conventions, formatting rules, and examples of expected output.
- Git workflow: branch naming, commit message format, and pull request requirements.
- Boundaries: what the agent must never touch. Secrets, dependency directories, and production configurations. The Always / Ask First / Never system formalizes these restrictions.
Living specs versus static specs
A key decision in spec writing is whether the spec is kept alive after implementation (spec-anchored) or used as a build guide and then discarded (spec-first):
- Spec-anchored specs are kept in sync with the code and serve as living documentation of the system. They require an active maintenance process.
- Spec-first specs guide the build and are then archived or discarded. They are lighter, but lack the benefit of persistent documentation.
Not every spec is worth maintaining. The rule of thumb is: if the spec answers questions the team will keep having in the future, maintain it. If it only answers questions from the initial build, discard it.
Spec writing antipatterns
The Scrum Manager guide Spec Driven Development en equipos ágiles [Spec Driven Development in agile teams, in Spanish] (September 2026 edition) catalogs four failure modes of the method when it is misapplied:
- Overspecification: the team spends more time perfecting the spec than producing working software; its extreme form is applying the same intensity to a trivial defect as to a complex feature.
- Gates as bottlenecks: an approval stalls because the person who must approve it is unavailable or overloaded. The answer is to delegate, allow asynchronous approval, and shorten the specs, not to remove the gate.
- Specification theater: specs are written that nobody really reviews, and the process is carried out mechanically. A gate that never rejects anything, or a spec that never changes after review, does not mean everything is fine: it means nobody is looking.
- Zombie documentation: specs that nobody consults or updates. Deciding which specs to keep alive and which to let die is part of management.
All four share the same remedy: the principle of proportionality, and someone (the agile enabler) who looks at the process as well as at the people carrying it out.
Common mistake
Writing specs as free-form prose instead of as structured documents. Agents process structured information better than free-form prose. A spec with clear sections, consistent headings, and predictable formatting lets the agent quickly locate the information relevant to each task. A spec written as a narrative text document produces more variable and inconsistent outputs than a structured spec with the same content.
Resources
📊 Guía didáctica SDD [SDD Study Guide, in Spanish]Resources · Scrum Manager
🏦 SDD en equipos ágiles [SDD in Agile Teams, in Spanish]Skill Arena · Scrum Manager
See also
Want to advance in agility? You can search for course and exam calls or go at your own pace by becoming a member of the Agile Club. This membership includes exclusive resources, e-learning classrooms, and access to Skill Arena: a space to practice and measure your agile skills at your own pace.