Specs, design documents, RFCs, ADRs, and code ownership

Some decisions are bigger than a ticket.

A new architecture, a build-versus-buy call, a database migration — anything expensive to reverse.

For these, mature engineering cultures do something that surprises outsiders. They write essays at each other.

This lesson is the field guide to those documents: what each one looks like, when it gets written, and who reads it.

Why write instead of meet?

Before meeting the documents one by one, consider why the culture exists at all.

Start with the physical facts because “document” can sound grander than it is. These are ordinary written pages, usually a Google Doc or a wiki page, sometimes a file in the repo itself, and typically two to six pages long. Teammates read them on their own time and leave comments in the margins; the author replies and revises. If you have ever commented on a shared doc at work, you already know the mechanics.

Writing is where fuzzy thinking goes to be discovered. A plan that sounds convincing in a meeting must, on paper, name its assumptions, count its costs, and survive being reread slowly by a skeptic.

Meetings and documents also reward different things:

• Meetings favor the quick and confident. Documents favor the correct.
• Documents can be reviewed by anyone, in any time zone, at their own pace, exactly like a PR review of prose.
• A meeting evaporates. A document remains, and becomes the record.

A design that survives being written down and reviewed by five skeptics is a design with its edge cases already found. This is the PR ritual from lesson 11.3, scaled up from code to decisions.

What is a technical specification?

A technical specificationConcept · lights on your maptechnical specificationThe blueprint written before building: which endpoints, which fields, which failure behaviors. Its secret purpose is discovery, since half the hard problems surface during the writing, when a fix still costs a sentence. pins down exactly what will be built, before anyone builds it. In conversation it is a “spec.”

The logistics:

• Who writes it: the engineer who will build the thing; writing the spec is the first part of building it.
• When: after the decision to build, before the first line of code.
• Who reads it: teammates, reviewing it like code (comments, replies, revisions), usually over a few days.

Here is a slice of one, pinning the details tickets leave open:

The point is timing. Problems found in a spec cost a comment, while the same problems found mid-build cost a rewrite. A reviewer asking “what if the slot fills mid-checkout?” in the margin costs the author one added line. The same question, first asked by a confused customer in production, costs a very bad week.

What is a design document?

The spec’s broader sibling, the design documentConcept · lights on your mapdesign documentProse for a decision big enough to argue about: the problem, the options that lost, and the reason the winner won. Passing one around before building lets teams disagree in writing instead of in production., argues the why.

Where a spec assumes the decision is made and pins the details, a design document exists to make the decision well. Its skeleton is nearly universal: the problem, the constraints, the options considered, the tradeoffs of each, and a recommendation. That is Module 10’s nine words, now in paragraph form.

One famous version of the culture comes from Amazon, where meetings about big decisions begin with twenty minutes of everyone silently reading the document, a six-page narrative memo. There are no slides. The writing is the thinking, and everyone confronts it directly.

Before the next two names, note that companies use all of these labels loosely. One team’s “design doc” is another’s “RFC,” another’s “one-pager,” another’s “tech spec.” Don’t memorize the boundaries, recognize the shape: problem, options, tradeoffs, recommendation.

What is an RFC?

When a design document is explicitly circulated for structured feedback, it is called an RFCConcept · lights on your mapRFCA design document published to collect objections before the decision closes. The name honors the internet’s founding papers (HTTP itself is defined in one), and reaching for it signals a choice too consequential to settle in a hallway., a request for comments.

Here is the shape of one, compressed to a sketch:

The process around the document is the point.

1. The author drafts and shares it with the team, and often adjacent teams too.
2. A comment period follows, typically a week or two: skeptics probe the margins, and the author responds and revises. It is a structured argument, carried out in writing.
3. A decision gets made, then recorded, which is the next document’s job.

What “structured argument, in writing” looks like on the page:

The name is borrowed from the internet’s own tradition. Since 1969, the documents that define its protocols, including Module 4’s HTTP, have been published as numbered RFCs. The habit of deciding-by-written-argument is older than the web.

Culturally, “I’ll write an RFC” means: this idea is big enough to deserve the team’s written attention before anyone commits code to it.

What is an ADR?

The ADRConcept · lights on your mapADROne page per settled decision: what the situation was, what was chosen, what it costs. A codebase with a folder of these can explain itself years after everyone involved has moved on. (architecture decision record) is filed after the decision, and it is deliberately short:

Why bother, once the decision is made? Because of a question you can now hear coming. Two years later, a new engineer asks, “wait, why is notifications built this way?”

Without the ADR, the answer is a shrug. Or worse, nobody remembers why the old way failed, so the team confidently rebuilds a mistake it already made once.

ADRs live where the curious will actually look. They are short numbered files, usually checked into the repo alongside the code they explain. That is why the example is “ADR-017.” The sixteen before it are the team’s decision history, readable in an afternoon.

The division of memory is precise. Git remembers what changed, and ADRs remember why.

What is code ownership?

Attached to all of this is code ownershipConcept · lights on your mapcode ownershipThe rule that no file is orphaned: each directory maps to one owning team, whose approval gates changes there and whose on-call answers for it at 3 a.m. Tooling reads the map and summons the right reviewers automatically., meaning every part of the codebase has an owning team.

Ownership means two concrete things:

• Their review is required. Changing owned code needs the owner’s approval (remember branch protection from lesson 11.3).
• Their responsibility when it breaks. Module 13 will make this literal: the owner’s pager is the one that rings.

This is not tribal knowledge; tooling enforces it. GitHub reads a file literally named CODEOWNERS, checked into the repo like any other file:

“Who owns checkout?” is one of the first questions in a cross-team project because it names whose review, whose roadmap, and whose pager the work will involve.

The failure mode is worth knowing too: code with no owner. Orphaned code is nobody’s job, unreviewed by experts, unmaintained, and unclaimed when it breaks. Mature organizations treat unowned code as a bug in the ownership map.

The documents, in order

The catalog assembles into a lifecycle around every big decision:

Not every change runs the full gauntlet. A bug fix is a ticket and a PR, nothing more. The documents scale with the decision, so the more expensive the reversal, the more writing it earns first.

The mental model to remember

A spec pins the what and how before building, reviewed like code, finding problems while they cost comments.

A design document argues the why: problem, options, tradeoffs, recommendation.

An RFC is a design document circulated for structured written argument before the decision. It is the PR ritual, scaled to ideas. (The three labels blur from company to company; the shape is what to recognize.)

An ADR is the short record filed after: context, decision, consequences. Git remembers what; ADRs remember why.

Code ownership maps every part of the codebase to a team whose review is required and whose pager rings, enforced by a file, not folklore.

The deeper pattern: writing is the thinking. Decisions that are expensive to reverse earn documents, and documents turn five skeptical readers into cheap insurance.

You should now be able to receive an RFC with your name on the reviewer list and know exactly what is being asked of you: read slowly, probe the margins, and help find the expensive problems while they are still words.