Awesome Design Doc

Design Doc / ADR

Turn a feature request or architectural question into a decision a team can execute and a future reader can retrace. The core discipline: requirements and numbers before components, real alternatives before a recommendation, and a recommendation before the end — a document that tours options without choosing is a meeting agenda, not a design.

When to Activate

• "Design X", "how should we build Y", "write a design doc / ADR / RFC".
• A reviewer flagged a load-bearing decision that needs an ADR (awesome-code-review hands the format here).
• Two credible approaches exist and the choice is expensive to reverse.

Do not activate for reversible everyday choices (naming, a helper's location) — an ADR for those is noise; the three-condition test below decides.

When an ADR is warranted

All three, or don't write one:

1. Expensive to reverse — schema, public API shape, persisted format, event name, framework/storage choice, service boundary.
2. Crosses a boundary — more than one module, team, or service must honor it.
3. The context would be lost — six months from now, the "why" is not recoverable from the code.

One-page ADR for a single decision; full design doc when the feature needs a data model, API surface, and rollout plan together.

Work Process

1. Requirements before components — functional requirements as testable statements, then the constraints that shape the design: expected scale (users, QPS, data volume and growth), latency targets, consistency needs (what must be read-your-write, what can lag), availability expectations, compliance boundaries. Getting the scope wrong makes a technically impressive design solve the wrong problem — clarify with the user before designing, not after.
2. Back-of-envelope the load — requests/sec, storage/year, working-set size, fan-out per action. Three lines of arithmetic kill more bad designs than any diagram; a design without numbers is a vibe. State the assumptions so a reader can re-run the math when the assumptions age.
3. Sketch the contract before the internals — the API endpoints or events in/out, and the data model's core entities with their invariants. The contract exposes scope errors while they are still cheap (awesome-api-design for HTTP resource detail).
4. Generate 2–3 genuine alternatives — including the simplest thing that could work ("do nothing" or "a cron job and a table" is often a legitimate contender). An alternative added only to be knocked down is padding; each one gets its honest best case.
5. Evaluate on the trade-off axes the requirements activate — not a fixed rubric: consistency vs availability, sync vs async, SQL vs NoSQL, monolith-extension vs new service, build vs buy, latency vs cost. For each active axis, say which side the requirements favor and why. Skip axes with no tension — padding dilutes the load-bearing analysis.
6. Recommend, grounded in requirements — one recommendation, tied by name to the requirements that drove it ("eventual consistency suffices because the feed tolerates 30s lag — that unlocks the cheaper fan-out-on-read"). State what new information would flip the decision.
7. Name non-goals, risks, and the path — explicit non-goals (what this deliberately does not solve, so scope creep has to argue with a sentence), the top risks with their mitigations, the migration/rollout order for existing data and consumers, and the rollback story (rules-level deploy discipline applies; a design that cannot roll out incrementally gets that called out here, not discovered in the PR).

ADR format

# ADR-: 
Status: proposed | accepted | superseded by ADR-
Date: 

Context: 
Decision: 
Alternatives considered: 
Consequences: 
Non-goals: 

Output Format

Full design doc: Title → Problem & requirements (with numbers) → Proposed design (contract first, then internals) → Alternatives & trade-offs → Recommendation → Non-goals → Risks & mitigations → Rollout & rollback → Open questions (marked, not hidden). Deliver as a Markdown file in the repo's docs convention (docs/adr/, docs/design/, or where existing docs live — discover, don't invent).

Self-check before delivering

• The three-condition test verdict is stated in one line — why this decision earned a document at all.
• Every scale number traces to a stated assumption a reader can re-run; a number with no assumption is a vibe with digits.
• A recommendation exists, cites the requirements that drove it by name, and states what new information would flip it.
• Re-read each alternative as its advocate: if one collapses under its own best case, it was a straw man — replace it or drop it.
• Non-goals, rollback, and marked open questions are present; any requirement you invented rather than confirmed is moved to Open questions or deleted.

Anti-patterns

| Anti-pattern | Instead | |---|---| | Component shopping — naming technologies before requirements | Requirements and numbers first; technology falls out of them | | Trade-off tour with no recommendation | End every comparison in a recommendation tied to a requirement | | Straw-man alternatives | Each alternative argued at its honest best before it loses | | Invented requirements ("we might need multi-region") | Only stated or confirmed requirements; speculation goes to Non-goals | | ADR spam — a document per reversible choice | The three-condition test; reversible choices get a code comment | | Design without a rollout | Migration order, backward compatibility, and rollback in the doc | | Open questions silently resolved by omission | An explicit Open questions section the reader can answer |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: khasky
• Source: khasky/awesome-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.