Which Artifacts and Why

Overview

An architecture practice is a small set of documents and the habits around them. Choosing the set is the first decision, and the usual failure is introducing all of it at once.

The organising property is not importance. It is lifespan — because lifespan determines maintenance cost, and maintenance cost determines whether an artifact survives contact with a busy quarter.

The six

Artifact	What it is for	Who reads it	How long it lives
Strategy	The sequence of bets and their reasoning	Leadership	A year, revised deliberately
Roadmap	Order, displacement, dates	Leadership and engineering	A quarter to a year
ADR	Why one decision was made	Future engineers, mostly	Permanently — superseded, never deleted
HLD	How the system works, at container level	Anyone joining or integrating	The system’s life, revised continuously
LLD	The internals of one component	That component’s team	Short, and usually should not exist
Proposal	A decision being requested	Whoever decides	Until decided, then archived

Modules 3 and 8 already produced two of these: the strategy as a sequence of bets, and the proposal as a justification pack. This module adds the rest and the practice around them.

Lifespan decides everything

graph LR
  A["<b>Proposal</b><br/>weeks<br/><i>archived after</i>"] --> B["<b>Roadmap</b><br/>months<br/><i>revised often</i>"]
  B --> C["<b>HLD</b><br/>system's life<br/><i>must be revised<br/>or it lies</i>"]
  C --> D["<b>ADR</b><br/>permanent<br/><i>never edited,<br/>only superseded</i>"]

  classDef short fill:#7D9A4E,stroke:#5F7A38,stroke-width:2px,color:#ffffff
  classDef mid fill:#E8A33D,stroke:#C4832A,stroke-width:2px,color:#ffffff
  classDef long fill:#D9695B,stroke:#B4483A,stroke-width:2px,color:#ffffff
  classDef perm fill:#5B8FB9,stroke:#4A7A9E,stroke-width:2px,color:#ffffff
  class A short
  class B mid
  class C long
  class D perm

Four lifespans, four different maintenance obligations. The terracotta one is the dangerous artifact: an HLD that is not revised becomes actively misleading, where an un-revised proposal is merely old.

The consequence for each artifact:

An ADR is cheap to maintain because you never maintain it. It records a decision at a moment, and that record does not go out of date — the world changes around it, which is why it stays useful. This is the artifact with the best ratio of value to upkeep, which is why the next topic argues for it first.

An HLD is expensive because it must be revised. A description of how the system works is wrong the moment the system changes, and a wrong HLD is worse than no HLD — it costs a reader hours of misdirection they would not have spent on an honest blank. So it needs an owner and a trigger for revision, or it should not be started.

An LLD usually should not exist. The code is more accurate, self-updating and closer to the truth. A separate low-level document is a second source of truth that diverges, and it will lose. Two exceptions: a component being built by a team that cannot read your code yet, and an algorithm whose correctness needs reviewing before anyone implements it.

The minimum viable set

For an organisation with no existing practice, three artifacts:

ADRs. Highest leverage, lowest maintenance, immediately useful for onboarding.
One HLD. So that somebody joining can understand the system without an archaeology phase.
A proposal template. So that the next decision arrives in a reviewable shape.

That is the whole starter set. Each is cheap, each is immediately useful, and none requires anyone’s permission to begin.

What not to introduce yet

Naming the deferrals is as important as the set, and the rubric for this module asks for an explicit deferral with a reason.

An architecture board. A board approves things. With no recorded decisions and no shared description of the system, it would be a meeting that approves undocumented proposals — ceremony without substance. Module 8’s size argument applies: boards solve the problem of a single architect becoming a bottleneck, which happens several hundred engineers from now.

A technology radar. A radar communicates a portfolio position to many teams. With no practice to anchor it, it reads as an edict from someone with no mandate.

A standards catalogue. Standards enforce consistency, and nothing enforces them yet. Writing them first produces a document everyone ignores, which then makes the second attempt harder.

A mandatory review gate. The fastest way to be routed around, and Module 8 established what that costs.

Each of these is right eventually. The deferral is about sequence, not value — and the sequence is governed by the cheap-now-expensive-to-retrofit test from Module 8.

The question to ask of every artifact

Before introducing anything: who will update this, and when?

If the answer is “I will, when I remember”, the artifact will be stale within two quarters and will then mislead someone. An artifact with no named owner and no revision trigger is a liability with a title page.

The three to start, and the four to refuse

The organisation has no architecture board, no practice of recording decisions, and no mandate. About 140 engineers, two years into a strangler migration, with roughly twenty Go services whose boundaries nobody wrote down.

Start with three:

ADRs for the decisions already made. Modules 3 through 7 produced perhaps eight decisions worth recording — the two-service split, hosted in-region inference, retrieval over fine-tuning, the action boundary and its tiers, the bounds on the agent loop, the eval gate and its corrected threshold. All made in the last few weeks, all with reasoning that will evaporate. This is the next topic but one.

One HLD at container level, with a named owner and a revision trigger: it is updated whenever a container is added or a boundary moves. Without that trigger it becomes the misleading-document case within a quarter.

A proposal template, because the Module 8 justification pack already has the shape and formalising it costs an afternoon.

Refuse four, with reasons:

An architecture board — nothing to approve yet, and at this headcount it would add ceremony to an organisation whose problem is that nothing is written down. An LLD requirement — the Go services’ code is the better record. A standards catalogue — no mandate to enforce it, and Module 8’s remit topic says occupying contested territory early costs credibility that has not been earned. A mandatory review gate — the fastest route to being bypassed.

The one that is tempting and still wrong: a decision record for the twenty existing Go services. The reasoning is genuinely lost, reconstructing it would take weeks of Ivan Petrov’s time, and Module 8’s Conway analysis suggests the honest finding would be “shaped by whichever team extracted it” — which is worth knowing and not worth twenty documents. The next topic but one handles what to recover and what to leave.

Feeds the workbook

This topic shapes two artifacts: the documentation structure and the process proposal. The rubric requires something explicitly deferred with a reason — the four refusals above are the shape of that, and the reason should be about sequence and size rather than value.

→ Three artifacts to start, and one of them earns its place first. — ADRs in practice