ARCHITECTURE STUDY · Consistency
Using AI as a consistency engine for architecture work
The examples use Salesforce Commerce Cloud mechanics. The reasoning applies to any commerce platform of this size. The TSD Generator on this site is this idea, built as a tool you can use.
Why this matters
Architecture decisions get written down so a team can build to them. When many people write those documents by hand, they come out different every time, and sections quietly go missing. A missing section is not a writing problem. It is how a risk reaches production without anyone noticing.
The decision — Fix the structure of the document, not the words. Let an assistant produce a first draft in that fixed shape, and keep every judgement with the architect.
What it gives you — Every design considers the same questions: payments, consent, failure cases, integration contracts. The slow part — the blank page — becomes the quick part.
The risk it removes — A design that silently skips the section that would have caught the problem, because nobody prompted the author to think about it.
In one sentence: a template cannot be talked out of asking the difficult question, so encode the questions and let the assistant fill the shape — but never let it make the call.
The problem
A technical design document records how something will be built, and why. Written by many people over time, these documents drift apart. Different structure, different depth, and sometimes an important section — payments, consent, what happens when a system fails — is simply absent.
The inconsistency is the real issue, and it is easy to misdiagnose. If one design considers failure cases and the next one does not, the second team is usually not being careless. They had no prompt to think about it. Nothing in front of them asked the question.
That makes it a governance problem rather than a writing problem. You cannot fix it by asking people to try harder, because the failure is silent: nobody notices the section that is not there.
The question that shapes the design
Ask what is actually safe to automate.
Structure is safe. It is the same every time. A design for a loyalty feature and a design for a payment integration need the same questions asked, even though the answers differ completely. Nothing is lost by fixing it.
Judgement is not safe. Whether to keep a call synchronous, which market goes first, what to do when a partner system is down — these are decisions with consequences, and they belong to a person who can be held to them.
So the design follows: automate the first, refuse to automate the second.
The approach
A reusable template in Markdown that sets out every section a design must cover. A single requirement can then produce a complete first draft in that shape, using an assistant such as GitHub Copilot.
The mechanism that makes it work is small: every section the author has not written carries a visible note saying what belongs there. Not a heading with blank space under it — a specific instruction, in the file, that an assistant can act on and a human can read.
## Caching
> **What to write here.** Describe the caching strategy for "Loyalty enrolment
> at checkout". State what is cached, for how long, and what must never be
> cached because it is personalised.
That note does two jobs. It tells the assistant precisely what to draft, and — if nobody ever runs an assistant over it — it tells the next human what the section is for. The document is useful either way.
It is deliberately visible rather than hidden in a comment. A hidden instruction disappears from every preview, so the file looks empty to anyone browsing it, and a section nobody wrote looks exactly like a section nobody needed. Left in the finished document, a visible note says plainly that this part has not been written yet.
The limit that matters most
An assistant asked to fill thirty sections will fill thirty sections. It will produce confident, fluent text for every one of them, including the ones where it has no idea.
That is the failure mode this approach creates, and it has to be named rather than hidden. The structure being automatic makes the output look uniformly considered, which is exactly what makes an unreviewed section dangerous: it reads like the others.
So the discipline is: every section an assistant expands is reviewed by the author before it counts as written. The tool states this in the generated document itself, at the bottom of every file it produces, because a caution that lives only on a web page is a caution nobody sees at the moment it matters.
Options considered
| Option | Decision | Reasoning |
|---|---|---|
| Fixed template, assistant drafts, author reviews | Chosen | The structure cannot be argued out of asking a hard question, and the first draft is cheap. Accepts that reviewing generated text is real work, and that some sections will be wrong. |
| Ask people to write more carefully | Rejected | Treats a systemic problem as a discipline problem. It fails in exactly the case that matters — the section nobody thought of — because trying harder does not surface an unknown unknown. |
| Let the assistant decide the trade-offs too | Rejected | The seductive version. It produces a document that reads well and commits to positions nobody owns. A design nobody can defend in review is worse than no design. |
| A rigid form that must be completed before work starts | Rejected | Front-loads the whole document at the point of least knowledge. Some sections genuinely cannot be answered until the build has started; forcing them produces filler, which is worse than an honest gap. |
What I would watch in practice
- Fluent text that says nothing. The characteristic failure is a section that is grammatical, on topic, and empty of decisions. Review for whether a call was made, not whether it reads well.
- The template growing without limit. Every incident tempts you to add a section. A template that asks eighty questions gets skipped entirely, so size it to the change — a small fix and a major integration should not get the same document.
- Sections marked not applicable without a reason. "Not applicable" is a useful, honest answer. "Not applicable" with no reason is an unexamined one, so the reason should be required.
- The comment drifting from reality. The guidance is the asset. If a comment describes a concern the platform no longer has, it teaches the wrong thing to everyone who uses it afterwards.
- Adoption, which is the hard part. The technology is the easy half. Getting people to start from the template rather than the last document they wrote is the actual problem, and it is won by making the template the fastest route, not the mandated one.
What it gives you
- Every design considers the same questions, so the ones that catch production problems stop being optional.
- The blank page — reliably the slowest part — becomes a review, which is faster and easier to do well.
- A team can use these tools without every output looking different, because the shape is shared.
- The judgement stays visible and owned, because the parts that need a decision are the parts the tool refuses to fill.
The template is not the clever part. The clever part is being honest about which half of the work is safe to automate — and building the tool so the other half cannot be skipped by accident.
The tool: the TSD Generator is this study made usable. Write the requirement once and it produces the full scaffold, guidance comments and all, in your browser.