Code can't tell you why

The last post argued that the fast-changing, low-level parts of a system should be derived from code, and the slow-changing, high-level parts should be authored by hand. This post is about why the split has to exist at all — why you can't just generate everything from the source. The reason is short and permanent: code can tell you exactly what happens and how, but it can never tell you why you chose it that way. That "why" is the most valuable thing about an architecture and the first thing to evaporate. Capturing it is where a model stops being documentation and starts being leverage — including, increasingly, as the context you hand an AI.

The one thing you can't regenerate

Point a tool at a codebase and it will tell you a great deal, accurately: which components exist, what calls what, what input produces what output, in what order. What it cannot tell you is the reasoning. Why this boundary and not that one. Why we tolerate this coupling. Why we chose eventual consistency here and paid for strong consistency there. That knowledge lived in a design conversation, in a few people's heads, maybe in a document nobody can find. It was never in the code, so regenerating it from the code is not merely hard — it's impossible in principle.

Academics named this two decades ago. Jansen and Bosch reframed software architecture itself as a set of architectural design decisions, and pointed out that when you capture only the resulting design — the boxes, the code — and not the decisions and rationale behind it, that knowledge vaporizes: it's lost as soon as the people move on, and every later change is made blind to the reasoning it might be violating.¹ The industry's most practical response is the Architecture Decision Record — Michael Nygard's lightweight habit of writing down, per decision, the context, the choice, and its consequences, right next to the code in version control.² ADRs exist precisely because the code is silent about why, and because a decision you can't reconstruct is a decision your successors will accidentally undo.

Context, decision, consequences — linked to the element it's about, so the code and the reasoning behind it live in one place:

Two moving targets that must meet

So you have two things in motion, on different clocks. On one side, the high-level vision: intent, boundaries, the reasoning — changing slowly, impossible to derive from code. On the other, the code and its realisation — changing fast, and now faster than ever. The health of a system depends on those two staying connected. Let them drift and you get the architectural erosion the previous post described: the code implements one architecture while everyone believes in another.

Tooling that faces only one side can't hold them together. A diagramming tool that only lets you draw pretty pictures has no idea whether the code still matches. A pure code-extraction tool has no place to record the intent the code can't express. What you need is a model that carries both — the derived facts and the authored reasoning — as one artifact, so a change on either side can be checked against the other. That is the entire argument for keeping structure, intent, and rationale in a single model rather than scattering them across a wiki, a whiteboard photo, and the repo.

Architectural knowledge is the design plus the decisions and rationale that produced it. Capture only the design and the knowledge vaporizes; capture the decisions too and the model can outlive the people who made them.

The model as AI context

This is where it stops being a documentation argument and becomes an AI one. When you ask an AI to make a change, the quality of the result is bounded by the context you give it. Hand it a task with no architectural context and it will produce something that works locally and fits the system's intent only by luck. Hand it the model — the structure, the boundaries, the "why this is shaped this way" — and its change is far more likely to land inside the architecture rather than beside it.

A C4 model is unusually good context for this. It's compact, it's structured, it makes the boundaries and relationships explicit, and it can carry the rationale the code omits. Handing an AI the picture of how the systems cooperate and where the edges are lets it focus a change correctly — you turn "how the system is designed and why" into part of the prompt. The combination of a clear model plus a precise request produces results that fit the system far better than the request alone. In other words, the same model that keeps humans aligned is also the missing half of the context window.

AI flattened the roles — context is the new scarcity

There's a human shift underneath all this. We used to have a ladder: architect, designer, developer, and within that juniors, mediors, seniors, leads — each operating at their own level, each holding a slice of the knowledge. AI has largely collapsed that ladder. Everyone now has expert knowledge on tap, instantly, to make a choice. What AI does not hand you for free is the judgement to evaluate whether it's the right choice — and that judgement is entirely about consequences. To weigh a decision you have to foresee its consequences, and to foresee consequences you have to hold the full context of the system in view.

That's the catch, and it gets worse as systems grow. The bigger and more complex the system, the more context a sound decision requires — and the more information you must have established and kept accessible. This is why large AI-assisted efforts stall where small ones fly: a small, simple system can be changed almost instantly, while the same change in a large one demands so much context that it becomes unmanageable. The scarce resource is no longer knowledge — AI supplies that. It's context: the right information, current, and cheap to feed to whoever (or whatever) is making the change.

Which lands us back at the single model, now for a fourth reason. If the architect designing the system and the developer building it need the same information but keep it in separate places and rarely talk, you're paying for it twice and it's stale in both. The way out is one place where the fast-changing facts and the slow-changing rationale live together, no double bookkeeping, readable by a human or handed to an AI. That's the collaboration model the moment calls for: AI supplying knowledge, a shared model supplying context, and people supplying the judgement that weighs consequences. Not one of the three is optional.

Rules of thumb

1. Write down the why. Code records what and how; capture decisions and their consequences separately, or lose them — an ADR next to the code is enough.
2. Keep facts and rationale in one model. Derived structure and authored intent belong together, so each can be checked against the other.
3. Feed the model to the AI. Architectural context in the prompt is the difference between a change that fits and one that merely compiles.
4. Treat context as the scarce resource. AI supplies knowledge; your job is to keep the right context current and cheap to access.
5. Don't keep two sets of books. If the architect and the developer maintain separate documentation, both rot — one model, many readers, human and machine.

---

This closes the arc that began with "C4 is too much, and too little." The thread through all of it: one model — structure derived from code, intent authored by people, rationale captured deliberately — projected into whatever view, and whatever prompt, the moment needs. That's what CRAYON-C4 is for.

References

Footnotes

1. Anton Jansen and Jan Bosch, "Software Architecture as a Set of Architectural Design Decisions," 5th Working IEEE/IFIP Conference on Software Architecture (WICSA 2005), pp. 109–120 — architecture as decisions, and the "vaporization" of architectural knowledge when only the resulting design is recorded. DOI: 10.1109/WICSA.2005.61 ↩

2. Michael Nygard, "Documenting Architecture Decisions," 2011 — the Architecture Decision Record (ADR): context, decision, consequences, versioned with the code. Original post · adr.github.io ↩