Design Docs and RFCs skill for Claude Code

A design doc is done when reviewers can disagree with specific, numbered claims, the alternatives section would convince a skeptic that the obvious options were weighed, the rollout can be reversed, and the review ended with a recorded decision. A doc that only describes the chosen solution is an announcement, not a design review.

When to write one

Write a design doc when any is true: more than ~2 engineer-weeks of work, more than one team affected, a new datastore/service/vendor/language, a public API or data model change, a migration of production data, or a decision hard to reverse. Otherwise a PR description or an ADR (see adr-records) is enough.

Ground rules

• Lead with the decision you need and by when. Busy reviewers read the first screen.
• Write the problem so someone outside the team understands why now.
• Show alternatives, including “do nothing”, with the same rigor as the proposal.
• Put numbers in: request rates, data sizes, latency budgets, cost per month. Rough estimates with stated assumptions beat adjectives.
• Separate facts, assumptions, and opinions. Label assumptions.
• Keep the core doc to ~3–8 pages; push detail into appendices.

Workflow

- [ ] 1. Write the summary and the decision requested (before anything else)
- [ ] 2. Context, problem, goals, non-goals
- [ ] 3. Estimate scale and constraints
- [ ] 4. Proposal: overview diagram, then components, data, APIs
- [ ] 5. Alternatives and trade-offs
- [ ] 6. Cross-cutting: security, privacy, reliability, observability, cost
- [ ] 7. Migration, rollout, rollback, testing
- [ ] 8. Open questions; circulate; time-boxed review; record decision

1. Summary block

**Decision requested:** Approve moving job scheduling from cron on app servers to a
dedicated queue (SQS + worker service) by Nov 7.
**Why now:** Duplicate job runs caused 3 double-billing incidents in Q3; app servers
are being moved to autoscaling, which breaks host-local cron.
**Recommendation:** Option B (SQS + idempotent workers). Cost +$140/month.

3. Back-of-envelope estimates

Jobs/day: 1.2M today, 3M projected in 12 months (assumption: 2.5× customer growth)
Peak: 15% of daily volume in the 00:00–01:00 UTC hour → ~125 jobs/s at peak in 12 months
Payload: ≤ 4 KB → peak throughput ~0.5 MB/s
Latency budget: job start within 60 s of schedule (current SLO)

4. Proposal

• Start with one diagram of the system after the change (C4 container level is usually right; see c4-diagrams or mermaid-diagrams).
• Walk the main flow as numbered steps that reference the diagram.
• Specify interfaces precisely: API shapes, events, schema changes (with migration), configuration.
• Call out what does not change.

flowchart LR
  Scheduler[Scheduler service] -->|enqueue| Q[(SQS queue)]
  Q --> W[Worker pool]
  W -->|idempotency key| DB[(Postgres)]
  Q -.->|after 5 failures| DLQ[(Dead-letter queue)]

5. Alternatives

Criterion	A: Keep cron + leader lock	B: SQS + workers (proposed)	C: Temporal
Fixes duplicate runs	Partly (lock expiry races)	Yes (idempotency keys + visibility timeout)	Yes
Works with autoscaling	Needs lock service	Yes	Yes
Ops burden	Low	Low (managed)	High (new cluster) or vendor cost
Cost / month	$0	~$140	~$1,200 (cloud)
Migration effort	1 week	3 weeks	6+ weeks
Team familiarity	High	Medium	Low

Then a short paragraph per alternative: why it was rejected, and under what conditions you would revisit it. Include “do nothing” and its cost.

6. Cross-cutting concerns (answer each, even if “N/A because…”)

• Security: authn/authz changes, secrets, new attack surface, input validation.
• Privacy/compliance: PII stored or moved, retention, residency.
• Reliability: failure modes and what happens in each (dependency down, slow, returns garbage), timeouts, retries, idempotency, back-pressure.
• Observability: metrics, logs, traces, alerts, dashboards added; SLO impact.
• Performance: latency and throughput vs. the estimates.
• Cost: monthly run cost and engineering cost.
• Developer experience: local dev, testing, on-call burden.

7. Migration and rollout

1. Ship worker service behind flag `queue_jobs` (no traffic).
2. Dual-run: enqueue + cron for read-only jobs; compare outputs for 7 days.
3. Move write jobs per job type, 10% → 50% → 100%, watching duplicate-run metric.
4. Remove cron entries after 14 days at 100%.
Rollback: flip `queue_jobs` off; cron entries remain until step 4. Data written by
workers is identical in shape, so no data rollback needed.
Point of no return: step 4 (document who approves it).

8. Review process

• Circulate with a deadline (typically 3–5 working days) and named required reviewers (owners of affected systems, security if relevant).
• Resolve comments in the doc; unresolved disagreements go to a 30-minute meeting with a decider named in advance.
• Record the outcome at the top: Status Accepted | Rejected | Superseded by …, date, decider, and key conditions.
• Significant decisions also get an ADR entry linking to the doc.

Writing style

Before	After
“The new system will be much more scalable.”	“Workers scale horizontally; at the 12-month peak of ~125 jobs/s we need 6 workers at 25 jobs/s each (measured).”
“We considered other options.”	Alternatives table with criteria and costs
“There may be some risk during migration.”	“Risk: a job type runs on both paths during step 3. Mitigation: idempotency key per (job_type, scheduled_at).”
“Should be fine for security.”	“No new external endpoints. Workers use an IAM role scoped to the queue and the jobs schema.”

Gotchas

• Writing the doc after building it; the review then only rubber-stamps. Write it when the decision is still open.
• Straw-man alternatives make reviewers distrust the whole doc.
• Missing non-goals invite scope creep in comments.
• No rollback plan, or a rollback that requires restoring a database backup, is a red flag for reviewers.
• Docs that never record a final status leave teams relitigating the decision months later.

Output contract

# <Title>: <short description of the change>
Status: Draft | In review | Accepted | Rejected | Superseded   Author(s):   Reviewers:
Decision needed by: <date>   Decider: <name>

## Summary (decision requested, why now, recommendation)
## Context
## Problem
## Goals / Non-goals
## Estimates and constraints
## Proposal (diagram, flow, components, data model, APIs)
## Alternatives considered (table + rationale, including do nothing)
## Security, privacy, reliability, observability, cost
## Migration, rollout, rollback
## Testing plan
## Open questions (owner, due)
## Decision record (date, outcome, conditions)
## Appendix