Designing Systems¶
Artifact Selection¶
- ADR (
docs/adr/NNNN-<topic>.md, template): one decision — a choice among alternatives with rationale and consequences. - System Design Doc (
docs/architecture/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
docs/
Design-Validation Loop¶
- Draft the artifact from the template
- Review with stakeholders
- Build a POC for the riskiest component
- Refine the design from POC findings
- Finalize the artifact