mcpField
D
designing-systems

designing-systems

github.com/dralgorhythmDevelopment12888 installsUpdated 14w ago
Repository

About designing-systems

designing-systems is a system-design skill for documenting architecture and technical decisions. It guides requirements gathering, diagramming, trade-off analysis, risk review, and validation through a proof of concept.

Key features

  1. 01Choose between ADRs and system design docs
  2. 02Gather functional and non-functional requirements
  3. 03Diagram components with Mermaid
  4. 04Define data models and API contracts
  5. 05Review trade-offs, risks, and validation

Use cases

  1. 01Plan a new system or component
  2. 02Document rationale for a technical choice
  3. 03Validate a risky component with a proof of concept

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/dralgorhythm/claude-agentic-framework --skill designing-systems

After installing, type/designing-systemsin Claude Code to confirm it loaded.

Bundled filesresources/adr.template.mdresources/system-design.template.md

Details

From the project README

Designing Systems

Artifact Selection

  • ADR (./artifacts/adr_[topic].md, template): one decision — a choice among alternatives with rationale and consequences.
  • System Design Doc (./artifacts/system_design_[component].md, template): a whole system or component — architecture, data model, API, NFRs, phased plan.

A new system usually needs both: the system design doc for the overall shape, plus an ADR for each decision worth justifying independently (e.g., "why Postgres over DynamoDB").

Workflow

  • Requirements: Gather functional and non-functional requirements
  • Diagram: Draft a Mermaid diagram showing components and their boundaries
  • Data & API: Define the data model, storage strategy, and interface contracts
  • Trade-offs: For each major decision, table Option A vs Option B — pros, cons, when to choose
  • Risks: Identify single points of failure
  • Tech Strategy: Confirm every technology choice matches .claude/rules/tech-strategy.md — no deviation without explicit instruction
  • Document: Fill in the matching template and save under ./artifacts/

Design-Validation Loop

  1. Draft the artifact from the template
  2. Review with stakeholders
  3. Build a POC for the riskiest component
  4. Refine the design from POC findings
  5. Finalize the artifact

Resources

Comments

Markdown supported