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/