How to write an architecture doc with AI: a six-section template, where AI helps, and where it invents constraints
An architecture document template (context, constraints, components, data flow, decisions, risks).
On this page
An architecture document has six sections: context, constraints, components, data flow, decisions and risks. AI is useful for the first draft of components and data flow from a PRD, for listing alternatives under each decision, and for a risk list you then prune; it is harmful when it fills the constraints section, because it invents limits you never had and then designs around them. Write constraints and decisions yourself, let the agent draft the rest, and keep the whole thing under two pages.
This is the template we use at Atrix for every feature larger than one cycle, with the division of labour between the agent and the engineer that we have settled on after a year of using both.
What an architecture doc is for
It answers one question for the next person: why is the system shaped this way? Not how to run it (that is the runbook), not what it does for users (that is the PRD), but which pieces exist, how data moves between them, and which choices were made on purpose rather than by accident.
The reader is an engineer joining in six months, or you after a long break. If the doc cannot be read in ten minutes, it will not be read. Two pages, one diagram, a decisions table.
The six-section template
| Section | What goes in it | Who drafts it |
|---|---|---|
| Context | The feature in two sentences; link to the PRD; what exists today | Agent, from the PRD |
| Constraints | Hard limits: data residency, latency, budget, existing contracts, team size | Human only |
| Components | The pieces touched and the pieces deliberately not touched | Agent drafts, human cuts |
| Data flow | How a request or record moves through the components, in order | Agent drafts, human verifies against the code |
| Decisions | Each significant choice: options considered, the one taken, why | Human decides; agent lists alternatives |
| Risks | What could go wrong, likelihood, what we would do | Agent lists, human prunes to five |
The "who drafts" column is the point of this post. The template itself is ordinary; the division is what makes AI useful rather than dangerous.
Context
Two sentences and a link. The agent does this well because it is summarising a document it was given. Make it name what exists today: "Reminders do not exist; the calendar sync and the email sender do."
Constraints
The hard limits that the design must respect. "Customer data stays in the EU region." "The email provider rate-limits to 100 a minute." "Two engineers, one cycle." "Must not change the sync layer, which is being replaced next quarter."
Write this section yourself, before the agent sees the doc. An agent asked to draft constraints will produce plausible ones: "must support 10,000 concurrent users", "must be horizontally scalable", "must support multi-region failover". None of these are yours. Once they are in the doc, the components section designs for them, and you end up with a queue, a cache and a fallback region for a feature that sends forty emails a day.
Components
The agent's first draft is usually a reasonable list of pieces touched. Your job is to cut: remove components it added to satisfy invented constraints, and add the line "not touched: X, Y" for the parts you are deliberately leaving alone. The "not touched" list is more useful to a reviewer than the touched list.
Data flow
A numbered sequence: "1. Cron fires at :00. 2. Query bookings in the next 24h without a sent flag. 3. Render template. 4. Send via provider. 5. Mark sent." The agent drafts this from the PRD and the components; you verify each step against the code that exists. Step 2 is where most bugs live, and the agent will not know that the bookings table has a soft-delete column.
Decisions
One row per choice that someone might question later: options, chosen, why. The agent is good at listing options you did not think of; it is bad at choosing, because it does not know your team or your history. Ask it for alternatives, then write the "chosen" and "why" cells yourself. Three to six rows is normal. If you have twelve, the doc is for two features.
Risks
The agent will list fifteen. Keep five, each with a one-line mitigation. A risk without a mitigation is a worry, not a risk.
Where AI helps and where it hurts
Helps:
- First draft of context, components and data flow from a PRD. It is reading a document and restating it structurally, which it does well.
- Alternatives under each decision. "What else could we do here?" reliably produces one option you had not considered.
- Consistency checks. "Does every component in the data flow appear in the components section?" catches the omissions a tired human makes.
- Risk brainstorming, as long as you prune.
Hurts:
- Constraints. Invented, plausible, and load-bearing. Covered above.
- Choosing between options. It picks the textbook answer, not the one that fits a two-person team with a deadline.
- Current-state claims. "The existing sync layer exposes a webhook" when it does not. Anything the agent says about today's system must be checked against the code.
- Scale. Left alone it designs for the scale in its training data, not yours.
The rule we use: the agent may write anything that restates an input it was given; a human writes anything that is a fact about the world or a choice.
Doing it in Atrix
Our own AI agent produces an architecture document as one of the three outputs of a Develop run, alongside requirements and planned issues, from the brief and the PRD you give it. It follows the division above because we brief it that way: the run's brief names the constraints as input, and the agent is told not to add to them. The doc lands as a page in Docs, where it has version history, comments and live co-editing, so the engineer's edits to components and decisions are visible as a diff against the agent's draft.
The block diagram is drawn on the whiteboard inside the page. Whiteboards in Atrix are Excalidraw boards: you draw the boxes and arrows by hand, and the drawing stays editable next to the text. There is no text-to-diagram generation; if you want the agent to produce a diagram, ask it for a numbered data flow and draw from that, which takes about ten minutes for a six-component feature. Tools that do generate diagrams from text, such as Miro's AI and Eraser's DiagramGPT, are covered in a separate post.
A worked example, abridged
Context: booking reminders; PRD v3; today there are no reminders, the calendar sync and the email sender exist.
Constraints (human): no changes to the sync layer; provider limit 100 emails a minute; one engineer, one cycle; EU data only.
Components (agent drafted, human cut): reminder scheduler (new), reminder template (new), bookings query (existing, read only), email sender (existing). Not touched: sync layer, calendar UI.
Data flow: the five steps listed earlier, with step 2 corrected to exclude soft-deleted bookings after checking the table.
Decisions: cron vs queue (cron; volume is forty a day, a queue is a second system to run); per-booking vs batch send (batch, to stay under the provider limit); template storage (page in Docs, not a new table).
Risks: duplicate sends on cron overlap (mitigation: sent flag written before send); provider outage (mitigation: retry next hour, no alert under one hour); time-zone mistakes (mitigation: store and compare in UTC, render in booking's zone).
The agent's draft had added a Redis queue and a "notification service" to satisfy a scalability constraint it had written itself. Both were cut, and the doc fits on a page and a half.
FAQ
What should an architecture document include?
Six sections: context, constraints, components (touched and not touched), data flow as a numbered sequence, a decisions table with options and reasons, and five risks with mitigations. Two pages and one diagram is the target.
Can AI write a software architecture document?
It can draft context, components, data flow and alternatives from a PRD, and it does that well. It should not write constraints or make decisions, because it invents constraints and picks textbook options. Treat it as a drafting tool with a human owner for every fact and choice.
What is the difference between an architecture doc and an ADR?
An architecture decision record covers one decision: context, options, choice, consequences. The architecture doc for a feature contains several decisions in a table plus the components and data flow around them. Small teams usually keep the table in the doc and promote a row to its own ADR only when it affects more than one feature.
How long should an architecture doc be?
Two pages, read in ten minutes. If it is longer, it describes two features or it has absorbed the runbook. Move operational detail out.
Should the architecture doc include a diagram?
Yes, one block diagram of the components with arrows for the main data flow. Draw it by hand from the numbered data flow; it takes ten minutes and the act of drawing finds missing arrows.
When should the architecture doc be written?
After the PRD is frozen and before issues are created, because the components section determines how the work splits. Writing it after the issues exist turns it into a description of what was done, which is a different document.
Next step
Take your current feature, write the constraints section by hand in five minutes, then hand the PRD and those constraints to whatever agent you use and ask for the other five sections. The PRD template gives the agent the numbered requirements it needs, and in Atrix a Develop run from the AI agent returns the architecture doc as a page you can edit with the team.