Notes
What breaks specifications, and how to keep them true — for teams building with AI coding agents, and for agencies whose clients have to sign off. The free templates are under Templates.
Spec-driven development
What spec-driven development is, the tools, existing codebases, and who reviews the spec.
-
How to write a spec for an AI coding agent
Spec-driven development best practices, each with its evidence: keep the spec small, make acceptance runnable, say must, clarify first, review the plan.
-
Plan mode vs spec-driven development: when a plan is enough
Plan mode or a spec? What each one keeps, where Claude Code, Cursor, Copilot and Kiro save plans, what the research shows, and when a plan is enough.
-
Spec-driven development for product managers
What spec-driven development changes for product managers and owners: intent before the spec, reviewing an agent-written spec, approving changes, acceptance.
-
Spec-driven development with Claude Code
Spec-driven development in Claude Code: a spec file, plan mode and a fresh session without a framework, or with Spec Kit, OpenSpec, Superpowers, BMAD or GSD.
-
What is spec-driven development?
Spec-driven development (SDD) means writing the spec before an AI coding agent writes the code: how it works, an example, the tools, and the criticism.
-
Does spec-driven development work?
What studies of spec-driven development have found: how teams use it, defects, agent results, token and review costs, and what nobody has tested yet.
-
Spec Kit vs OpenSpec vs BMAD: what each leaves out
Spec Kit, OpenSpec and BMAD compared, with Superpowers, Kiro and GSD: how each works, what users say about it, and the gaps all of them share.
-
Spec-driven development on an existing codebase
How Spec Kit, OpenSpec, Kiro and BMAD work on an existing codebase: specify the change, not the system. What that leaves out, and how to start.
-
Spec-driven development: who reviews the spec?
Spec-driven development makes the spec the source of truth for coding agents, and assumes a developer approves it. What changes when someone else has to.
Keeping specs current
Where specifications live — git, Confluence, a baseline — and why they drift from the work.
-
How to track changes to requirements: versions and history
How to track changes to requirements: requirement, document and baseline versions, what a history needs, and how to keep it in Word, Confluence, Jira and git.
-
Managing requirements in Jira
Can Jira be used for requirements management? How to write and track requirements in Jira, link them to work and tests, and where it breaks.
-
Requirements volatility: definition, formula and metrics
Requirements volatility is how much agreed requirements change. The formula, a worked example, what is normal, the metrics to track, and how to use them.
-
Managing requirements in Confluence: where it breaks
How to manage requirements in Confluence and Jira, and where it breaks: versions of the whole set, sign-off from outside the team, traceability and drift.
-
Requirements baseline: what it is, with an example
A requirements baseline is the agreed version of the requirements every later change is measured against. Definition, example, scope baseline, re-baselining.
-
Requirements in git: what version control does not track
Keeping specs and requirements in git gives you history, diffs and review. What it does not give you, and how to make requirements in GitHub or GitLab work.
-
What is spec drift?
Spec drift is the gap between what a specification says and what was built, planned or agreed from it. Why it happens, how to detect it, how to stop it.
Sign-off, scope and change
Getting the requirements agreed, and handling what changes after.
-
Change control vs change management
Change control vs change management in projects, IT operations and organisations, plus configuration management, with one software change through all four.
-
How to handle changing requirements
How to handle changing requirements: why they keep changing, what to do mid-sprint and after sign-off, clients who keep changing their minds, and what to say.
-
Informal requirements changes: the work nobody wrote down
Informal requirements changes skip the change request: tweaks agreed on calls, small favours, UI changes. What research found, what they cost, how to log them.
-
Requirements change management: the process, with an example
Requirements change management step by step: request, impact analysis, decision, updating every document and test, and closing — with a worked example.
-
Scope creep in software projects
Scope creep is work added to a project without a decision about what it costs. Examples from software projects, what causes it, and how to stop it.
-
Change request vs pull request
A change request changes what was agreed; a pull request changes the code. Scope creep vs change requests, change orders, and the change request process.
-
Discovery phase in software development: what the client should sign off
What the discovery phase of a software project is, what it produces, the questions to ask, and what the client should sign off before development starts.
Research
What developers and agencies say about specs, counted.
-
We went through 20,000 comments about specs. Here is what breaks.
Developers say their specs drift from the code; agencies say the client's sign-off does not hold. What 20,000 comments and issues from 2025–2026 show.