00 Design docs · New
The whole story of a change, in one place
A design doc keeps the spec written before the work, the implementation plan, and the evidence of what shipped. Every service it mentions links to your catalog, so six months later you can still see why it changed.
- Decision
- Add a Refunds Service that reads booking status and asks Billing to refund the charge.
- Touches
- Refunds ServiceBookings DBBilling Service
Brief
Plan versus actual
| Refunds Service | Planned, changed |
| Billing Service | Planned, changed |
| Bookings DB | Planned, changed |
| Ledger DB | Changed, not planned |
01 Lifecycle
The page always says what you are reading
A draft, an approved plan and a shipped record look different, and the status is never a guess.
01
Draft
Where every design doc starts.
02
In review
A variation is waiting for approval.
03
Approved
Every variation the change needs before the work is ready, and approved where your team requires it.
04
Shipped
A person or agent marks it shipped once evidence exists. Nothing ships on its own.
A design doc can also be superseded by a newer one, or abandoned with a reason. Each gets a number, like DD-0007, that is never reused.
02 Variations
Spec, plan and evidence, in one doc
Each design doc has variations. The change size, small, standard or large, decides which ones it needs.
| Variation | When | Required for | Brief fields |
|---|---|---|---|
| Spec | Before the work | Standard and large | Decision, touches, risks, open questions, rejected alternatives |
| Implementation plan | Before the work | Small, standard and large | Approach, touches, risks |
| Evidence of work | After the work | Small, standard and large | Outcome, deviations, not done, touches |
02.1
Your own types
Add a variation type with its own instructions, outline and brief fields. A security review example is ready to start from.
02.2
Room for real documents
Full markdown with tables, task lists and code blocks, plus images and short videos.
02.3
Diagrams inside
Embed a living canvas doc or a diagram the design doc owns. Both open the full canvas to edit.
03 Briefs
A short version a reviewer reads in a minute
Every variation has a brief whose fields come from its type. Readers and agents get the brief first and the full text when they ask.
- 03.1The "Touches" field is built from mentions, never typed
- 03.2Marked out of date when the full text moves past it, with what changed
- 03.3Shows who wrote it
- 03.4ArchDocs AI can draft one from the full text; it condenses and never adds decisions
Plan · AI brief drafting on Team and above, using AI credits.
Spec · brief
- Decision
- Add a Refunds Service
- Touches
- Refunds ServiceBookings DBBilling Service
- Risks
- Double refunds on retry
04 Mentions
Every service named is a live reference
Mention a service with the @ picker and it links to the catalog object. The object page gets a Design docs tab that lists every design doc that touches it.
- 04.1Mention catalog objects and other docs
- 04.2Name a service that does not exist yet as a proposed object
- 04.3Proposed objects become real catalog entries only when a person accepts them at ship time
- 04.4Plain text names are left alone; only real mentions link
05 Open questions
Undecided points stay visible until someone decides
Raise each open point as a question on the doc. A person answers it, or it stays open, so a guess never passes for a decision.
- 05.1Questions have their own discussion thread
- 05.2Agents raise questions instead of inventing answers
- 05.3Your organization chooses whether open questions allow, warn or block shipping
- Q1
Retry refunds from a queue or inline?
Open - Q2
Who owns the refund ledger entry?
AnsweredAnswered by a person
Ship check · 1 open question · Warn
06 Review
Approval where your team needs it, and nowhere else
Each variation type sets the change sizes that need approval and who approves: named people or a team. One approval is enough.
- 06.1An approved variation is frozen
- 06.2Editing it later is an amendment with a reason, and goes back to review
- 06.3Comments anchored to a variation
- 06.4History for every human session and agent write, with a diff between any two versions
Plan · Design docs on Team and Business. Review and approvals on Business.
v4 · Approved by the Platform team
ApprovedAmendment · Refund window changed to 30 days · back in review
In review- v3 to v4 · 2 sections changed · agent write from Claude Code
07 Plan versus actual
See what shipped, and what nobody planned
The plan lists the objects and docs it expects to change. Evidence compares that list with the changes recorded for the design doc.
- 07.1Planned and changed, planned and not changed, changed without a plan
- 07.2Linked pull requests with their state and CI results, read from GitHub
- 07.3Shows "Ready to ship" when the last linked pull request merges
- 07.4Without GitHub, a person marks it shipped by hand
- Decision
- Add a Refunds Service that reads booking status and asks Billing to refund the charge.
- Touches
- Refunds ServiceBookings DBBilling Service
Brief
Plan versus actual
| Refunds Service | Planned, changed |
| Billing Service | Planned, changed |
| Bookings DB | Planned, changed |
| Ledger DB | Changed, not planned |
08 Agents
Agents write to your standard. People decide.
Design docs work fully without AI. When an agent writes one over MCP, it gets each type’s instructions word for word and has to send a brief with every write.
- 08.1Import a Claude Code plan, a Spec Kit plan.md, a Kiro tasks.md or plain markdown as the plan
- 08.2Attach screenshots, link pull requests and record architecture changes
- 08.3Every write records the person, the client and an optional session link
- 08.4No agent can approve a variation or accept a proposed object
09 Decisions
Record the decisions that outlive a change
A design doc records one change. An architecture decision record keeps a choice the team lives with, linked to the objects it affects.
- 09.1MADR template for every decision
- 09.2Considered options and tradeoffs
- 09.3Supersede chains show how decisions evolve
10 Findable
Easy to find later
10.1
Search
Every variation is indexed, and results show the design doc status.
10.2
Export
Export a whole design doc or one variation as markdown.
10.3
Private to your organization
Visible across the org, never in share links, public spaces or embeds.
11 Architecture docs
Mentions point at the living system
The services a design doc mentions are the same objects your architecture docs draw. When the change ships, those docs show the result.
12 Start
Start your first design doc
Design docs are included on Team and Business.