system-design

System Design Architect

Turn a vague project idea into a researched, decision-driven SYSTEMDESIGN.md — before writing code — so the hard architectural choices are made against industry-standard, battle-tested approaches instead of discovered through rework.

Core principle

Don't design from memory. Identify what matters, then research it.

The value is not a generic doc template. It is: (1) correctly identifying the critical aspects for this specific kind of project, (2) finding how proven systems actually solved them, and (3) recommending a decision with explicit tradeoffs and citations. A good SYSTEMDESIGN.md is reusable by anyone building that same archetype.

When to use

• Starting a new project, service, or significant feature.
• User asks "how should I build X", "design the system for X", "research the architecture".
• Before committing to a stack/data model/scaling approach that is expensive to change later.

If the user just wants a quick code change, this is overkill — skip it.

Workflow

Run these phases in order. Phases 2–3 are where the real work is — do not skip research and write the doc from memory.

Phase 0 — Profile the project

Determine three things. Read the codebase/spec if one exists; otherwise ask the user only what you cannot infer.

1. Archetype — what kind of system is this? (chat/real-time, marketplace, payments ledger, data pipeline, ML/RAG serving, social feed, CRUD SaaS, search, booking/inventory, notification system, dev tool, etc.) See references/archetypes.md. A project can blend 2+ archetypes — note all.
2. Scale & constraints — expected users/QPS/data volume, latency targets, consistency needs, team size, budget, compliance (PCI/HIPAA/GDPR), deadline. Order-of-magnitude is enough; say so when estimating.
3. Hard requirements vs. nice-to-haves — what must be true on day one vs. later.

Write a one-paragraph project profile and confirm it with the user before researching. Getting the archetype wrong wastes all downstream research.

Phase 1 — Decompose into critical aspects

Using references/critical-aspects.md (the full taxonomy) and references/archetypes.md (which aspects matter per archetype), select the 5–9 aspects that genuinely drive this project's design. Resist listing all 16 — a payments app's critical aspects (idempotency, consistency, audit, reconciliation) differ sharply from a chat app's (fan-out, ordering, presence, delivery guarantees).

Output a short ranked list: aspect → why it's critical for this project. Confirm with the user; let them add/cut.

Phase 2 — Research each critical aspect

This is the core. For each selected aspect, follow references/research-playbook.md. Fan out: spawn one system-design-researcher subagent per aspect (or per 2–3 related aspects) so research runs in parallel. Each researcher must:

• WebSearch industry-standard approaches, naming the right terms (the playbook has query templates per aspect). Prefer primary engineering sources (Stripe/Uber/Discord/Figma/Netflix eng blogs, AWS/GCP architecture center, martinfowler.com, the relevant RFC/spec) over listicles.
• Mine GitHub for real reference implementations of this archetype: well-starred repos, awesome-* lists, the architecture/ADR docs inside mature OSS projects. Note what they actually did, not what a blog says they should.
• Pull official docs via context7 for any concrete framework/library/service in play (versions matter — your training data may be stale).
• Return: the 2–4 viable approaches, their tradeoffs, what scale each fits, and cited sources (URLs + repo links).

Sanity-check returned claims before trusting them: does the source actually support it? Is it current? Does it match the project's scale (don't bring hyperscale patterns to a 100-user app)?

Phase 3 — Decide with tradeoffs

For each aspect, recommend one approach with: the decision, why it fits this project's scale/constraints, the tradeoff accepted, the alternatives rejected and why, and citations. Be opinionated — a survey that picks nothing is not useful. Flag decisions that are cheap to reverse vs. one-way doors.

Phase 4 — Write SYSTEMDESIGN.md

Write SYSTEMDESIGN.md in the project root using references/template.md. Every recommendation carries its rationale + sources inline. Include a high-level architecture sketch (ASCII or mermaid), the data model, and an explicit "open questions / revisit later" section.

Phase 5 — Compound the knowledge (makes it reusable)

After writing, update the archetype cache so research compounds across projects and people:

• Cache distilled, project-agnostic findings per archetype at ~/.claude/system-design/archetypes/<archetype>.md (create the dir if missing). On the next project of the same archetype, read this cache first in Phase 1/2 and refresh it rather than starting cold.
• Keep the cache project-agnostic (patterns, tradeoffs, canonical sources) — not this project's specific numbers.

This is what makes a SYSTEMDESIGN.md reusable "for any project of that kind": the second time anyone designs that archetype, the baseline research already exists.

Quality bar

• Researched, not recalled. Every non-obvious decision cites a source. No uncited "best practice" claims.
• Scale-matched. Don't prescribe Kafka + sharding for an MVP. Match patterns to stated scale; note the threshold at which to revisit.
• Decisive. Recommend, don't survey. State the tradeoff you're accepting.
• Reusable. Someone building the same archetype should be able to lift 70% of the doc.

Reference files

• references/critical-aspects.md — full taxonomy of system-design dimensions, when each matters, standard approaches, and search terms.
• references/archetypes.md — catalog of project archetypes → their critical aspects, canonical reference systems, key tradeoffs.
• references/research-playbook.md — how to search: per-aspect query templates, where to look, how to mine GitHub, how to use context7, the source-quality bar.
• references/template.md — the SYSTEMDESIGN.md output structure.