System Design
Intents
Draft a system design for our payments serviceUpdate the system design — we switched from PostgreSQL to DynamoDBWe're adding a message queue between the API and worker — update the architectureHow should we architect the notification system?Use the scaling knowledge from our load tests to update the designReferences
Read references/system-design-conventions.md for placement rules and references/system-design-template.md for section structure.
Scope
System design captures the technical "how" at architecture level. Product requirements belong in the PRD; implementation detail in feature specs. System-wide decisions should reference or create ADRs.
Input
Synthesize from whatever the user provides: conversation context, existing PRD (docs/PRD.md), local docs, external links, direct prompts, or docs/knowledge/ entries (when explicitly referenced).
Workflow: Create
- Normalize input into architecture context: mission, design principles, tech stack, components, dependencies, cross-cutting concerns, constraints.
- Map into template sections from
references/system-design-template.md. Align to local convention if one exists. - Place at the repository's existing path, or fallback:
docs/system-design.md. - Mark unknowns in
Open Points— don't guess. - Link upstream PRD in
Related Documentswhen one exists. - Set status to
draft.
Workflow: Iterate
- Read the existing system design in full.
- Upstream check: If
docs/PRD.mdexists, scan its scope, success criteria, and status. Warn the user if the update conflicts with upstream PRD. - Identify what changed and why.
- Update affected sections in place. Preserve unchanged content.
- Update
Last updateddate. - Transition status when appropriate:
draft→active→shipped, or any →deprecated.
Output
- Create: complete system design at
docs/system-design.md - Iterate: targeted updates to affected sections only
- Unresolved decisions go in
Open Points - Design principles are opinionated and system-specific
- Architecture diagram matches component descriptions
- Security section is always present — includes assumptions, gaps, and controls
- No feature-level implementation detail