A software design specification (SDS) is a document that describes how a software system will be built to meet its requirements: the components, the data, the interfaces, the key workflows and the decisions behind them. It sits between the requirements, which say what the system must do, and the code, which is the system. Engineers write it, and the people who build, review and later maintain the system read it. You will also see it called a software design document (SDD) or a software design description. In practice these mean the same thing.
This guide covers what goes in one, how it differs from a PRD and an SRS, a template you can copy, and a short example. If you came looking for the document that comes before this one, start with what a PRD is.
What is a software design specification?
The one-line version: requirements say what, the design specification says how.
A PRD or SRS might say "a client can comment on a project through a link, with no signup." The design specification answers the questions that sentence leaves open. Which component creates the link? What table stores it, and what stops someone guessing another client's link? What happens when it expires? Where does the comment go, and which service sends the designer an email about it?
The thing that makes a design spec worth writing is that it records decisions while they are still cheap to change. Choosing a database, an auth model or a sync-versus-async boundary is easy on a page and expensive after six weeks of code. The document's job is to make those choices visible, argued and agreed before anyone builds on them.
SDS, SDD, SRS, PRD: what is the difference?
These documents overlap and teams use the names loosely. The usual distinctions:
| Document | Answers | Typical author | Written |
|---|---|---|---|
| PRD (product requirements document) | What should we build for users, and how will we know it worked? | Product manager | First |
| SRS (software requirements specification) | What exactly must the system do, in testable detail? | Business analyst or systems engineer | After the PRD |
| SDS or SDD (software design specification, description or document) | How will the system be built to meet those requirements? | Engineer or architect | Before and during the build |
| Test plan | How will we show it works? | QA or engineering | Alongside the design |
Requirements and design are separate on purpose. Requirements describe the problem from the outside, so a product manager and a customer can both read them. Design describes the solution from the inside, so it can mention databases and queues. Mixing them is the usual way a requirements document turns into an unreadable one.
Many teams skip the formal names. A "tech spec," "design doc" or "RFC" at a software company is usually an SDS under another label. The label matters less than whether the content is there.
What goes in a software design specification?
There is a formal answer and a practical one.
The formal answer is IEEE 1016, the standard for software design descriptions. It organises a design into views, each written from a viewpoint such as context, composition, logical structure, dependencies, information (data), interfaces, interaction and state dynamics. The idea is useful even if you never read the standard: no single diagram shows a whole system, so you describe it from several angles, each answering a different question.
The practical answer, for a small team or a solo builder, is a short set of sections. These cover most of what a reader needs:
| Section | What it answers |
|---|---|
| 1. System overview and context | What is the system, who and what does it talk to, and what is out of scope? |
| 2. Architecture overview | What style is it (monolith, serverless, client plus backend-as-a-service), and why does that fit? |
| 3. Component design | What are the major modules and what is each responsible for? |
| 4. Data architecture | What are the core entities and how do they relate? Where is the data stored? |
| 5. API and integration design | What is the interface between components, and with outside services? |
| 6. Key workflows | How does the system behave in the two or three journeys that matter most, including failures? |
| 7. Non-functional requirements | How fast, how available, how secure, how observable, with numbers? |
| 8. Security and access control | Who can reach what, and how is that enforced? |
| 9. Deployment and infrastructure | Where does it run, and how does a change reach production? |
| 10. Architecture decision records | Which decisions would be expensive to reverse, and what did we trade away? |
| 11. Risks and mitigations | What could go wrong technically, and what is the plan? |
| 12. Open questions and assumptions | What is still undecided, and what did we assume? |
You will not need every section every time. A small feature might need only components, data, interface and one workflow. The test is whether a new engineer could build the thing, or review someone else's attempt at it, without asking you to explain the architecture out loud.
Three sections tend to be missing from weak design specs, and they are the most valuable ones.
Decisions with their alternatives. Michael Nygard's widely used format for an architecture decision record has a title, context, decision, status and consequences. Add "alternatives considered" and you have the part of the document that future maintainers actually come back for. Code shows what was chosen. Only the record shows what was rejected and why.
Numbers in the non-functional requirements. "The system should be fast" cannot be tested or disputed. "p95 API latency under 300 ms at 10,000 rows per project" can be both.
An explicit list of assumptions. Every design rests on guesses about volume, users and third-party behaviour. Writing them down is how you find out which one was wrong before it hurts.
How is it different from an architecture document?
An architecture document describes the system at the highest level: the major structure and the principles that shape it. A design specification includes that and goes further down, into components, data and interfaces detailed enough to build from. In a small project they are one document. In a large organisation the architecture document is the map and several design specifications are the street-level detail for each part.
A short software design specification example
Here is a deliberately small excerpt, continuing the "client share links" feature from the PRD example. It shows the shape and level of detail, not a complete document.
# Design: Client share links
## 1. Context
A signed-in designer creates a read-and-comment link for a project.
A client opens it without an account. Out of scope for v1: client
accounts, file uploads, real-time updates.
## 3. Components
| Component | Responsibility | Depends on |
|---|---|---|
| Share-link service | Create, validate and revoke links | Database |
| Board view | Render a project's comments for a link holder | Share-link service |
| Comment service | Store comments, attribute them to a link | Database |
| Notifier | Email the designer when a client comments | Email provider |
## 4. Data
- share_links: id, project_id, token_hash, expires_at, revoked_at
- comments: id, project_id, share_link_id (nullable), author_label, body
The token is random and stored only as a hash, so a database leak does
not expose working links. [ASSUMPTION] about 50 links per designer.
## 7. Non-functional requirements
- Link validation p95 under 200 ms
- A link stops working within 60 seconds of expiry or revocation
## 10. Decision record
### ADR-1: Opaque tokens, not signed URLs
Context: links must expire and be revocable before expiry.
Decision: store a hashed random token and check it on every request.
Consequences: revocation is instant. Every view costs one lookup.
Alternatives considered: signed URLs (stateless, but cannot be revoked
before they expire without a deny-list).
## 12. Open questions
- Can a client edit or delete their own comment?
Read it with the questions above in mind. The data section explains a security choice instead of just listing columns. The non-functional requirements are numbers. The decision record shows the alternative that lost and the reason, and the assumption is labelled so someone can challenge it.
How to write a software design specification
A process that works for most teams:
- Start from agreed requirements. If the user stories and acceptance criteria are still moving, the design will move with them. A rough PRD is enough to start. A missing one is not.
- Draw the boundary first. Write down who and what the system talks to, and what is out of scope. Most disputes later are disagreements about the boundary.
- Derive components from features. Each major feature area maps to one or more components. Then list the shared ones, such as auth, logging and billing, separately.
- Design the data before the endpoints. Entities and relationships constrain everything else. A database schema built from your user stories is a good starting point.
- Walk two or three journeys end to end, including the failure path. A sequence diagram per journey, plus a few sentences on what happens when a step fails.
- Record the expensive decisions. Anything hard to reverse gets a decision record. Cheap decisions do not.
- Put numbers on quality. Latency, volume, uptime, recovery time.
- List risks and open questions last, honestly. This section is where you earn trust. A design that claims no risks has not been looked at hard.
- Keep it next to the requirements. Link each component back to the requirement it serves. That link is what requirements traceability is, and it is what lets you answer "if this requirement changes, which parts of the design move?"
Keep diagrams simple. The C4 model, with its context, container, component and code levels, is a good vocabulary for deciding how much to draw. And write the prose so it stands alone: a diagram that fails to render, or that a reader cannot parse, should not take the meaning with it.
Why a design specification matters more with AI coding agents
An AI coding agent given only a feature list will invent an architecture, and it will do so confidently and differently in each session. Data models drift between files, an auth approach in one module contradicts the one in another, and nothing records why. A design specification fixes this the same way it helps a new human engineer: it is the written answer to "how is this system put together," available at the start of every session.
The same goes for review. Checking generated code against a stated design is a much easier job than inferring the design from the code. This is the reason design specifications belong in spec-driven development: the requirements, the design and the tasks are written down before the code, so an agent builds against something fixed and you can tell when it has deviated.
Generating a first draft with VibeMap
I build VibeMap, so weigh this accordingly. VibeMap generates a system design specification from the spec you have already built in it: your project description, personas, features, database schema and the API endpoints implied by your pages. It writes the twelve sections listed above, with diagrams, decision records for the major choices, and a risk register. Where your spec is thin, it marks the guess as an assumption instead of presenting it as fact, and you can add notes such as "must run on Cloudflare Workers" that override its choices.
Two limits worth knowing. It is grounded only in your own project's artifacts and does no web research, so it will not know about a library released last week. And it is a first draft for an engineer to challenge, not a substitute for one: the section on open questions and assumptions is where to start reading. The generation step is on the Pro plan.
You can write a good one by hand with the template above. The generator is for when you already have the spec and do not want to retype it as architecture.
FAQ
What is a software design specification?
A software design specification (SDS) is a document describing how a software system will be built to meet its requirements. It covers the components, data model, interfaces, key workflows, quality targets and the major design decisions. It is also called a software design document (SDD) or software design description.
Are requirements and specs the same?
No. Requirements describe what the system must do and why, from the user's side. A design specification describes how it will be built. Both are called "specs" casually, which causes confusion. A good habit is to name which one you mean: requirements spec or design spec.
What is software design in simple terms?
Software design is deciding how a program will be organised before and while you write it: what the parts are, what each part is responsible for, how they talk to each other and where the data lives. A design specification is the written record of those decisions.
How do you write a design specification?
Start from agreed requirements, define the system boundary, break the features into components, design the data, walk the key workflows including failures, record the hard-to-reverse decisions with their alternatives, set numeric quality targets, and finish with risks and open questions. The steps above go through each in order.
What is the difference between an SDS and an SRS?
An SRS (software requirements specification) states what the system must do in testable detail. An SDS states how the system will be built to do it. The SRS is written first and is largely independent of technology. The SDS is where technology choices appear.
How long should a design specification be?
As long as the system needs, and no longer. A small feature can be one or two pages. A new product might run ten to twenty. If a section would be fewer than a hundred words, it may not need to exist for this project. Length is a poor measure. A reader being able to build from it is the right one.
Who writes a software design specification?
Usually the engineer or architect who will lead the build, with review from the rest of the team. Product managers contribute the requirements it traces back to. In a solo project the same person does both, and it is still worth writing the design down.
Related reading
- What is a PRD?, the requirements document this one builds on.
- Spec-driven development, for how requirements, design and tasks fit together before an AI agent writes code.
- Requirements traceability matrix, for linking each part of the design back to a requirement and forward to a test.
- Database schema from user stories, for the data architecture section.
- GitHub Spec Kit guide, for a workflow that puts a plan between the spec and the code.
Sources and further reading
- IEEE, 1016: Standard for Information Technology, Systems Design, Software Design Descriptions; overview of its design views and viewpoints on Wikipedia.
- Michael Nygard, Documenting Architecture Decisions (2011): the decision record format used above.
- Simon Brown, The C4 model for visualising software architecture: context, container, component and code diagrams.
- ISO/IEC/IEEE, 29148:2018 Systems and software engineering: Requirements engineering: the standard behind the requirements documents a design specification builds on.
