Software design record template
By Kivrelune Studio

Software design record
Document the internal design of a component so maintainers can understand its boundaries and trade-offs.
Architecture
Component responsibility: [purpose]. Inputs and outputs: [contracts]. Upstream and downstream dependencies: [services]. Draw or link the flow from [event] to [result].
Data and failure behavior
State model: [states and transitions]. Persistent data: [storage and ownership]. For [failure], define [retry or recovery] and [observable signal]. Note ordering and concurrent use if relevant.
Design review
Alternative considered: [design and trade-off]. Validate with [test or prototype]. Operational owner, rollout plan and decision date: [details].
Using this template
Trace a real event through the component and describe the contracts, state changes and failure behavior along the way. Have a maintainer use the record to explain a retry or recovery case before the design review closes.
Questions & answers
Looking for more help? Visit the Help center.
How much internal detail belongs in a software design record?
Include decisions that affect contracts, state, failure recovery or future maintenance. Link implementation-specific details separately and explain the assumptions a later maintainer needs to understand the design.
What is included in this template?
Architecture · Data and failure behavior · Design review. Each section includes prompts you can adapt to your team.
How do we handle a change in scope?
Record the new evidence, identify the affected decision and name the person who will settle it. Keep the previous reasoning available to the next reader.
How do I use my own copy?
Choose “Start with this doc” to open an editable copy on this device. You can also copy the Markdown or download the file and use it in your own editor.

