The traditional software development project accumulates scope creep, technical debt and complexity over time. The usual advice for a new developer joining a project - Read the Code - tells the developer what a system does, but not why it was built that way. That gap only widens with legacy code and complex, long-drawn projects.
AI makes this gap sharper. The quality of AI-assisted code depends significantly on how the request is defined.
A vague prompt eg. “Add a new feature to my app to allow users to upload files” forces the AI to make assumptions about essential details: what type of files (PDF, PPT, DOCX .etc.)? How many files can a user upload? Should the files be stored locally or in the cloud?
This is where Specs-Driven Development (SDD) comes in. Instead of giving an agent a one-line request, the developer provides a more specific requirement, as follows:
“Add a new feature to my app that allows users to upload PDF documents, with a maximum of 5 files per account and a maximum file size of 2 MB. The files should be analyzed for encoded content and then securely stored in an S3 bucket.”
With these details clearly defined, the agent has the necessary context to produce code that implements the intended functionality and addresses the required compliance considerations.
The fundamental principle of SDD is: Specs act as intent, and Code is the realisation of the intent.
Types
With AI advancements over the past four years, almost all AI-generated code could be considered “prompt-based,” and to some extent, maintaining an agents.md file moves a team toward SDD. But not all approaches are equal. The 3 approaches below differ in one main way: how much you rely on the spec vs the code as the “real” record of what the system does.
Specs-First [Best for: new projects, prototypes, one-off features] Write a quick spec to gain clarity before you start, then let the code take over. Once built, the code becomes the record, and the spec doesn’t need to be kept up to date. For example, “create a static application using HTML and QRCode.JS that allows users to enter their LinkedIn URL and generate a QR code for it”. Good enough for the developer to build a prototype from, enhance the code as needed, and no one needs to maintain the spec after launch. Now the major artefact here will be code. This approach is best for projects where speed, experimentation, and rapid validation are more important than maintaining extensive specifications throughout the development lifecycle.
Specs-Anchored [Best for : production environments where an established engineering baseline and development process already exist] Spec and code are both kept accurate. If a requirement or functionality is changed, you update both. The spec first, then the code to match. For example, consider an application where the file upload limit is currently defined as 5 files per user, and a new requirement increases this limit to 10 files per user. In a Specs-Anchored approach, the specification is first updated to reflect the new limit of 10 files. The corresponding code is then modified or generated to implement this change. This is useful for production systems where traceability, maintainability, consistency, and long-term evolution are important.
Specs-as-Source [Best for: Teams with heavy tooling investment] The spec is the primary artefact, and the code is the by-product. In this approach, the code is generated from the specification rather than being manually changed. Whenever there is a change, the specification is first updated, and the code is then regenerated based on the updated specification. This creates a clear relationship between the intended behaviour described in the specification and the resulting implementation. However, this can be engineering-intensive and resource-intensive. It requires complex tooling and processes to ensure that the generated code can be trusted and consistently meets the intended requirements, which is why few teams use it at the moment.
Want to dive deeper? Check out additional resources here:
We will also be producing more articles on SDDs in coming issues. Keep a look out!