system-design-architect

System Design Architect

A Claude Code plugin that researches the right architecture for your project and writes a reusable, decision-driven SYSTEMDESIGN.md — before you write code, so you avoid expensive rework later.

It doesn't design from memory. It:

1. Profiles the project — detects its archetype (chat, payments, marketplace, data pipeline, RAG, …) and scale/constraints.
2. Identifies the critical aspects that actually matter for that kind of project (not a generic checklist).
3. Researches each one — engineering blogs, specs, real GitHub reference repos, and current official docs (via context7) — fanning out parallel researcher agents.
4. Decides each aspect with explicit tradeoffs and citations.
5. Writes SYSTEMDESIGN.md from a battle-tested template.
6. Compounds — caches archetype research at ~/.claude/system-design/archetypes/ so the next project of the same kind starts from proven ground.

Why

Most architecture mistakes are discovered late, as rework. Researching the handful of decisions that are expensive to reverse — the data model, consistency model, fan-out strategy, tenant isolation — before coding is cheap insurance. And because the output is keyed to an archetype, the research is reusable by anyone building that same kind of system.

Install

/plugin marketplace add <your-org>/system-design-architect
/plugin install system-design-architect

Or point your marketplace at this repo's .claude-plugin/marketplace.json.

Use

• /systemdesign — in any project; infers context from the repo.
• /systemdesign a multi-tenant SaaS for scheduling with Stripe billing — greenfield, describe it.
• Or just ask: "design the system for X", "how should I architect X", "research the architecture before we build" — the system-design skill triggers automatically.

What's inside

.claude-plugin/
  plugin.json              # plugin manifest
  marketplace.json         # single-plugin marketplace listing
skills/system-design/
  SKILL.md                 # the workflow (profile → decompose → research → decide → write → compound)
  references/
    critical-aspects.md    # taxonomy of 16+ system-design dimensions + search terms
    archetypes.md          # project archetypes → critical aspects, reference systems, key tradeoff
    research-playbook.md    # how to search: per-aspect queries, GitHub mining, context7, quality bar
    template.md            # the SYSTEMDESIGN.md output structure
commands/systemdesign.md   # /systemdesign slash command
agents/system-design-researcher.md  # parallel per-aspect research subagent

Output

A SYSTEMDESIGN.md in your project root: project profile, ranked critical aspects, architecture diagram, one decision-with-tradeoffs-and-citations block per aspect, data model, API surface, non-functional plan, risks/open questions, and reuse notes.

Principles

• Researched, not recalled — every non-obvious decision is cited.
• Scale-matched — no hyperscale patterns on an MVP; each decision says when to revisit.
• Decisive — recommends, doesn't survey.
• Reusable — keyed to archetype so research compounds across projects.

License

MIT — see LICENSE.