💡 왼쪽 원문을 읽으면서 오른쪽에 따라 써보세요. Tab 키로 힌트를 받을 수 있습니다.

원문 렌더가 준비되기 전까지 텍스트 가이드로 표시합니다.

Introduction — The Era Where the Spec Is the Code

There is an old joke that a senior engineer's primary programming language is English. In 2026, the joke is no longer a joke. Malte Ubl's essay "Design Docs at Google" still gets periodically resurfaced on GeekNews and Hacker News, but the context of its latest revival has changed: with AI coding agents everywhere, a well-written spec or design doc now converts almost directly into working code.

Anyone who has delegated work to an agent like Claude Code or Codex has felt this. Give it a vague design and you get vague code; give it a crisp design doc and days of work come back in hours. The rise of CLAUDE.md and AGENTS.md as a standard engineering practice belongs to the same trend. Writing is no longer a "soft skill" — it is the execution interface that drives both humans and AI.

This post is not a sermon about the abstract importance of writing. It contains concrete templates for design docs and ADRs, section-by-section guidance, the craft of documents that pass review, before/after fixes for bad writing, and field-tested prompts for using AI in your writing — only things you can use starting tomorrow.

Why Writing Is the Senior Engineer Leverage

Code moves one system at a time; writing moves many minds at once. Concretely, there are three sources of leverage.

1. Bandwidth in an Async Organization

A meeting consumes time multiplied by attendee count; a document is written once and read infinitely. A one-hour design meeting with ten people costs ten person-hours. Spend two hours writing the same content as a doc and have each person read it for ten minutes, and the cost is about 3.7 person-hours. Better: the document still works for the new hire who joins six months later, and for the on-call engineer staring at an incident at 3 a.m. Meetings do not.

2. Quality Control for Thinking

Amazon famously banned PowerPoint and mandated six-page narratives for a reason: prose does not allow hand-waving. A design that felt complete in your head exposes its holes the moment you write it down. Thinking "we can just invalidate the cache here" and writing out the invalidation timing and its race conditions as full sentences are entirely different levels of thinking.

3. Amplification in the AI Era

This is the new variable in 2026. A well-written design doc is an execution plan you can feed directly to an AI agent. Now that "context engineering" has replaced prompt engineering as the keyword, the ability to write good documents and the ability to give AI good context are effectively the same skill. An engineer who cannot write documents also falls behind on AI leverage.

The Document Type Map — When to Write What

Each document type has a different purpose and lifespan. Pick the wrong type and the effort is wasted.

| --- | --- | --- | --- | --- |

The selection rule in one line: **design for upcoming work goes in a design doc, the record of a decision already made goes in an ADR, a proposal needing consensus goes in an RFC, lessons from an incident go in a postmortem, repeatable procedures go in a runbook.** The two most common mistakes are writing nothing where an ADR belongs, and running a full RFC process — exhausting everyone — where a design doc would have sufficed.

The Design Doc Template — Section-by-Section Guidance

A skeleton based on Google-style design docs, refined in practice. Feel free to copy it as is.

Design Doc: Order Event Pipeline v2

Status: In review | Author: Youngju Kim | Reviewers: A, B | Updated: 2026-06-12

1. Summary (3 sentences max)

Move order event processing from a single consumer to

partition-based parallel processing. Goal: reduce p99 processing

latency from 8s to under 500ms. Migrate gradually over 4 weeks

using dual writes.

2. Background and Problem

- Current structure, what hurts and why (with metrics)

- The minimum context needed to read this document

3. Goals / Non-Goals

Goals:

- p99 latency under 500ms

- Automatic reprocessing on consumer failure

Non-goals:

- Event schema changes (separate project)

- Real-time analytics support

4. Proposed Design

- Architecture overview (diagram)

- Data model, APIs, failure handling, security

- Key trade-offs and their rationale

5. Alternatives Considered

- Alternative A: current structure + vertical scaling (why rejected)

- Alternative B: brand-new system (why rejected)

- Comparison table required

6. Concerns and Open Questions

- Honest list of things without answers yet

7. Migration and Rollback Plan

8. Measurement Plan

- Which metrics decide success, and when

Section-by-section guidance:

1. **Summary**: the three most important sentences in the document. Busy reviewers read only this. It must contain what, why, and how. Write it last, after finishing the body.

2. **Background and problem**: the bar is "a new hire can follow it" — but keep it short. Replace any background that can be a link with a link. The key is quantifying the pain: not "it is slow" but "p99 is 8 seconds, generating 40 support tickets a week."

3. **Goals/non-goals**: the non-goals are the real substance. Without explicit non-goals, review derails into scope debates and the scope balloons during implementation. Nailing down "what we are not doing this time" is the greatest peace a document can give.

4. **Proposed design**: one diagram beats ten paragraphs. Do not hide trade-offs — reviewers will find them anyway. Stating them first builds trust; being caught hiding them destroys it.

5. **Alternatives considered**: a design doc without this section is not a design doc, it is an announcement. More on this below.

6. **Open questions**: a document that can say "we do not know" is a good document. It also channels reviewer energy to exactly the right places.

Writing ADRs — Context, Decision, Consequences

An ADR (Architecture Decision Record) is the lightest format for recording "why." Following Michael Nygard's original shape, three parts suffice: context (the situation and constraints at decision time), decision (what we chose to do), and consequences (what we gain and what we accept).

Two real-style examples:

ADR-014: Use SQS instead of Kafka for the message queue

Status: Accepted (2026-05-20)

Context

The order event pipeline needs a message queue. About 2M events

per day, 300 per second at peak. Nobody on the team has Kafka

operations experience, and dedicated infra capacity is 0.5 of a

person. Event ordering is required only per order ID.

Decision

Use SQS FIFO queues. Use the order ID as the message group ID

to guarantee partial ordering.

Consequences

- (+) Zero ops burden; reuses existing AWS IAM setup

- (+) Absorbs 10x peak traffic with no extra work

- (-) Throughput ceiling exists. Redesign needed past 3,000/sec

- (-) Replay is less convenient than Kafka. Operate a separate

archive bucket

- Revisit trigger: when daily events reach 20M

ADR-021: No additional state management library on the frontend

Status: Accepted (2026-06-02)

Context

New admin dashboard. Server state is 95 percent of the data;

client-only state is roughly modal-open flags and filters. The

team already uses React Query. In a past project we spent about

2 weeks per quarter maintaining Redux boilerplate.

Decision

Do not add a global state library. Handle server state with

React Query, and client state with URL query parameters and

component-local state.

Consequences

- (+) Zero dependency and learning cost; clear source of truth

- (-) Risk of prop drilling if complex client state grows

- Revisit trigger: when 3-plus-level prop passing appears in

5 or more places

Three principles to keep for ADRs:

1. **Write it right after the decision.** Two weeks later, half of the "why" has evaporated. An ADR is a field record, not a memory exercise.

2. **Write for the future skeptic.** The ADR reader is the person six months from now following git blame and muttering "why on earth did they pick SQS?" The goal is sparing that person from re-litigating the same debate.

3. **State a revisit trigger.** Writing down "when this condition holds, this decision goes back on the table" prevents the ADR from hardening into dogma.

The Craft of Documents That Get Reviewed — Design the Reader's Ten Minutes

Writing is half the job; being read is the other half. Techniques for designing the reviewer's ten minutes:

1. **Enforce conclusion-first writing**: the first sentence of every section must be that section's conclusion. A good document is one where a reviewer who reads only first sentences still gets the whole argument.

2. **Scope your review request**: "please take a look at the whole thing" is the worst possible ask. Allocate reviewer energy: "I need opinions on two things — the failure handling in section 4 and the rejection rationale for alternative B in section 5."

3. **State the reading time**: put "estimated reading time: 8 minutes" at the top. It looks trivial but it is remarkably effective at pulling your document out of the read-it-later queue.

4. **Set a comment deadline**: "if there are no comments by June 19, I will treat this as approved and proceed" is not rude — it is considerate. A review request without a deadline never ends.

5. **Plant questions inline**: at points where you need input, embed "Open question: which is better, X or Y?" Reviewers engage far more easily than when asked to critique from a blank slate.

Fixing Bad Writing — Before and After

A real edit beats abstract advice. Here is a typical bad paragraph, repaired.

Before:

The current system has various problems and needs improvement.

Performance is not good and maintenance is difficult. Therefore,

introducing a new architecture is expected to bring many benefits

in several aspects.

The problems: no quantification ("not good"), no agent ("is expected"), an unsupported conclusion ("therefore"), and every word vague ("various", "several aspects").

After:

The order lookup API has a p99 latency of 3.2s (target: 500ms).

The cause is the triple join across the order, payment, and

shipping tables (execution plan in Appendix A). Splitting out a

read model removes the join and brings p99 under 400ms. The cost

is about 2 weeks of event synchronization code and up to 1 second

of staleness, which the order lookup screen tolerates (confirmed

with PM, link).

What changed: a number behind every claim, evidence behind every causal link, and a confirmed acceptability behind every trade-off. The sentence count is similar; the information density is five times higher. Good technical writing is not elegant prose — it is **verifiable prose**.

Handling Disagreement — Make the Alternatives Comparison Table Mandatory

If I had to name one secret of persuasive documents, it is this: **say what your opponents would say, before they say it.** Mandating a comparison table in the alternatives section makes this happen naturally.

| --- | --- | --- | --- |

The table forces two things. First, it makes you acknowledge the strengths of rejected alternatives (alternative B costing only two days is genuinely attractive — hide that, and a reviewer will find it and the credibility of the entire document collapses). Second, it makes criteria and weights explicit, moving the debate from a clash of tastes to a negotiation over criteria. Even if a reviewer disagrees with the conclusion, narrowing the disagreement to "we weight things differently" makes the argument productive.

Introducing a Documentation Culture — Start Light

Pushing a full-blown process onto a team with no documentation culture fails every time. A staged adoption path:

1. **Stage 1 (solo, this week)**: when the next hard-to-reverse decision happens, write one ADR. Do not ask permission. Just write it and attach it to the PR. ADRs are one page; nobody objects to one page.

2. **Stage 2 (team, one month)**: create an ADR directory in the repo (docs/adr/) with a template inside. Form only one light agreement: "decisions that take more than a week to reverse get an ADR."

3. **Stage 3 (team, one quarter)**: pilot a design doc on one new project. Measure the effect: number of direction changes during implementation, number of design flaws caught in review.

4. **Stage 4 (organization)**: make design doc reviews routine, but never mandate "a design doc for everything." Example threshold: work above two person-weeks, or changes crossing team boundaries.

The core principle: **the felt experience of documents helping must come before any mandate.** The moment your first ADR answers a new hire's "why is it built this way?" with a single link six months later, the culture spreads on its own.

Using AI for Writing — Patterns and Limits

In 2026, few people write design docs from a blank page. But AI usage splits sharply into patterns that work and patterns that fail.

Three patterns that work:

1. **Structure generation, not draft generation**: "write me a design doc about X" produces plausible documents with no substance. Instead, dump your own thinking into a raw note and have AI structure it.

Prompt example 1 — structuring:

Below is my raw brain-dump about a new event pipeline.

Rearrange it into design doc structure (summary/background/

goals/design/alternatives/risks), but do not invent content.

Mark anything missing from the notes as

[TODO: author input needed].

[paste notes]

2. **Requesting critique — the most underrated usage**: AI delivers more value as an adversarial reviewer than as a drafter.

Prompt example 2 — adversarial review:

You are a demanding staff engineer trying to get this design

doc rejected. Produce the 5 most painful questions from these

angles: 1) claims without quantitative evidence 2) failure

scenarios not considered 3) scope risks hidden in the non-goals

4) bias in the alternatives comparison.

For each question, also state which part of the document to fix

so the question is defensible.

3. **Reader simulation**: a request like "assume a junior backend engineer with no infra context reads this document; list, in order, the points where comprehension breaks" substitutes for the round-two rehearsal reader.

The limits are equally clear. First, **decisions cannot be delegated.** AI can enumerate alternatives and lay out trade-offs, but assigning weights belongs to someone who knows the organizational context — team skills, politics, budget. Second, there is the **plausibility trap**: AI-written documents read smoothly and therefore pass review easily, but smoothness and correctness are unrelated. Numbers, links, and system names must be verified by a human. Third, starting from an AI draft before forming your own view causes **anchoring**. Ten minutes of blank-page thinking first; AI second.

A Writing Training Routine

Writing is a muscle, so the routine is everything. In order of increasing commitment:

1. **One ADR per week from a real decision** (15 min): the best value-for-effort training there is. The fixed format removes blank-page fear.

2. **PR descriptions in a three-paragraph structure** (5 min each): what / why / how it was verified. PR descriptions are the technical writing you do most often.

3. **Comment on other people's design docs** (30 min/week): read before you write. When you meet a good document, jot one line on why it was easy to read.

4. **One full-size design doc per quarter** (half a day): the real thing. With the routines above accumulated, it comes out more easily than you expect.

5. **Compression practice** (anytime): summarize a technical article you read into three sentences and share it in the team channel. Compression is the core muscle of technical writing.

Postmortems and Runbooks — Mini Templates

After design docs and ADRs, these are the two formats you write most often — and having skeletons ready cuts writing time in half.

For postmortems, the blameless principle matters more than the format, but the format is what protects the principle. A template that forces roles and systems — not people's names — into the subject position is that protective device.

Postmortem: Order API outage (2026-06-08)

Severity: SEV-2 | Impact: ~1,200 failed order creations over 23 min

Author: on-call engineer | Review: whole team (June 10 meeting)

Timeline (all times KST)

- 14:02 Deploy completed (PR 1077)

- 14:05 Error rate alarm fired

- 14:11 On-call confirmed deploy correlation, started rollback

- 14:25 Error rate normalized

Root cause

Connection pool setting fell back to default (5) due to a missing

environment variable. Staging traffic was too low to reproduce it.

What went well / what hurt

- (+) 9 minutes from alarm to rollback decision

- (-) No environment variable validation in the deploy pipeline

Action items (owner/deadline mandatory)

- Add required env var schema validation — A, 6/15, INFRA-310

- Make staging load tests recurring — B, 6/22, PERF-20

For runbooks, remember only one thing: the reader is "you at 3 a.m." Do not demand judgment; provide commands that can be copy-pasted, with expected outputs.

Runbook: Restart the order event consumer

When to use: consumer lag alarm (metric link) persists over 10 min

1. Check current lag (expected: under 1,000 when healthy)

kubectl exec -it consumer-0 -- ./check-lag.sh

2. Restart the consumer

kubectl rollout restart deployment/order-consumer

3. Re-check lag after 5 min. Not dropping -> escalate: data team on-call

Warning: never run the partition reset command first (data loss)

The Craft of Answering Review Comments

Half the craft of writing documents is the craft of answering comments. I often see well-written documents collapse at the comment-response stage. Five principles:

1. **Answer every comment**: a single ignored comment kills the motivation of every reviewer. Even when you do not adopt a suggestion, write down why not.

2. **Accept fast, push back politely**: handle correct observations immediately with "good catch — addressed in section 4 (diff link)." When you disagree, answer with evidence; if two round-trips stay parallel, take it out of the document (a call).

3. **Convert comments into document fixes**: if a reviewer got confused, that confusion is itself a document defect. Do not settle for "I explained it in the comment thread" — fix the body text. The next reader will not read the comment thread.

4. **Do not blur decision authority**: process every comment by majority vote and the document becomes a camel. You must be able to say "thank you for the input — after weighing the trade-offs I am keeping the original; here is the reasoning."

5. **Declare review closure**: when the changes are in, announce explicitly: "comments addressed, moving status to approved." A document that never ends loses trust.

A Case — How One Document Eliminated Five Meetings

For a concrete picture, consider a fictional (but very common) scenario. Backend, infra, and PM held five meetings over three weeks about splitting out the payment module, with no conclusion. The same arguments repeated each time — because attendance shifted slightly, each meeting invalidated the previous meeting's consensus.

Instead of a sixth meeting, one person wrote a design doc: three alternatives in a comparison table, each team's worries listed as open questions, a one-week comment deadline. The result: 19 comments, asynchronous consensus, and a single 30-minute meeting for the final decision. What the document did was not magic. **It persisted the state of the argument.** Meetings are volatile memory — every session recomputed from scratch; the document was disk, so the computation could resume where it left off.

Sentence-Level Rules — A Quick Editing Guide

Once the structure is in place, it comes down to sentences. Seven sentence-level rules that pay off immediately in technical writing, with corrections:

1. **Passive to active**: "it was decided" → "the backend team decided." A sentence without a subject is a sentence without accountability.

2. **No double negatives**: "not impossible" → "possible." Reduce the reader's parsing cost.

3. **One claim per sentence**: a three-line sentence chained with conjunctions becomes three sentences. Technical prose reads best at modest sentence lengths.

4. **Numbers instead of adjectives**: "significant improvement" → "62 percent improvement at p99." If there is no number, the claim has not been verified yet.

5. **Banish pronouns**: "this" and "that approach" become unidentifiable two paragraphs later. Repeat the noun, even if it feels tedious.

6. **Expand acronyms on first use**: internal team acronyms are a foreign language to new hires and to yourself six months from now.

7. **Mark uncertainty honestly**: instead of vague hedges like "it should probably work," write when the uncertainty resolves: "unmeasured; will confirm after the June 20 benchmark."

These rules can be applied mechanically at editing time — put "find violations of the seven rules above" into your AI review prompt and you have a self-correcting loop.

A Side Effect — Documents Are Onboarding Assets

The most underrated return on documentation culture is onboarding. A new hire joining a team with accumulated design docs and ADRs can read the history of "why it was built this way" in chronological order — context transfer faster than ten code tours.

Three practical tips:

1. **An onboarding reading list**: pick the ten key decisions from the ADR directory and turn them into a "first week reading list." Ten minutes to create; saves days for every new hire.

2. **New hires as document testers**: have new joiners record where they got stuck while reading, and you get a defect map of your documentation for free. "I got lost here" is the best document review there is.

3. **A document as the first contribution**: in the first week, have them open a "documentation improvements discovered during onboarding" PR instead of code. It starts the contribution cycle with no psychological pressure.

Pitfalls and Counterarguments

For balance, the dark side of documentation culture deserves attention.

**Organizations where documents replace work** are a real pathology: places where design doc approval takes six weeks and no energy remains for implementation, or where writing documents itself becomes the deliverable and unread documents pile up. A document is a tool for making decisions faster, not a ritual for postponing them. If you cannot answer "what goes wrong without this document?", do not write it.

The counterargument that **"the code is the documentation"** has merit too. When code and documents diverge, the document becomes a lie, and a lying document is worse than none. The answer is separating lifespans. Documents about "why" (ADRs, design docs) are snapshots of decision time, so they retain value even when the code moves on. Documents about "how" (runbooks, API docs) must live close to the code — ideally in the same repo — and be updated in code review alongside it.

Finally, **the shadow of writing meritocracy**. In document-heavy organizations, the opinions of fluent writers can be over-represented — a real issue in global teams that mix native and non-native speakers. Practical mitigations: review norms that grade the quality of reasoning rather than the polish of prose, and an explicit policy of welcoming AI writing assistance.

Checklists

Before publishing a design doc:

1. Does reading only the 3-sentence summary convey what/why/how

2. Does every "slow/many/hard" have a number attached

3. Is there a non-goals section

4. Does the alternatives table state the strengths of rejected options

5. Are open questions listed honestly

6. Does the review request state scope and deadline

7. If estimated reading time exceeds 10 minutes, can it be cut

Before publishing an ADR:

1. Does the context capture the constraints of the moment (people, time, tech)

2. Do the consequences include at least one downside being accepted

3. Is a revisit trigger stated

4. Is it one page or less

Closing

Code persuades computers; documents persuade people. And in 2026, documents — through AI — produce code as well. Time spent writing is not a tax on coding time; it is the highest-yield investment available, the one that sets the direction of the coding and eliminates rework.

If you made one technical decision this week, leave one ADR behind today. It takes fifteen minutes. Someone six months from now — possibly future you — will be grateful for that single page.

References

- Design Docs at Google (Malte Ubl): https://www.industrialempathy.com/posts/design-docs-at-google/

- ADR official home — Architectural Decision Records: https://adr.github.io/

- Michael Nygard — Documenting Architecture Decisions: https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions

- Google Technical Writing Courses: https://developers.google.com/tech-writing

- GeekNews — design doc discussions: https://news.hada.io/

- Hacker News — Design Docs at Google discussion: https://news.ycombinator.com/

- AWS — Architecture Decision Records guidance: https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/welcome.html

- GitHub — adr/madr template repository: https://github.com/adr/madr

- Anthropic — Claude Code memory (CLAUDE.md) docs: https://docs.anthropic.com/en/docs/claude-code/memory

- Write the Docs — technical writing community and guides: https://www.writethedocs.org/

- Diátaxis — a framework for classifying documentation types: https://diataxis.fr/

- 37signals — Shape Up (how to write a pitch): https://basecamp.com/shapeup