Design — Architecture, API & Data Models

Unified design guidance for feature implementation. Auto-detects context from project files or accepts explicit mode.

Usage

/design                    # Auto-detect from project, show summary
/design architecture       # Component architecture, SOLID, patterns
/design api                # REST API design, auth, rate limiting
/design data               # Pydantic schemas, validators, relationships
/design full               # All three in sequence (architecture → data → API)

Workflow

Step 1: Determine Mode

Parse $ARGUMENTS for explicit mode. If no arguments provided, detect context:

DETECTED=$(bash "$HOME/.claude/skills/design/lib/design-detector.sh")

Map detection results to recommended mode:

• pydantic,fastapi → suggest api + data
• pydantic only → suggest data
• fastapi or flask or django → suggest api
• Generic Python/Node → suggest architecture
• Unknown → show all summaries, let user choose

Step 2: Show Relevant Guidance

Based on detected or explicit mode, use progressive disclosure:

Level 1 — Summary (default, ~15 lines): Read and present the summary template for the chosen domain:

• templates/architecture/summary.md
• templates/api/summary.md
• templates/data/summary.md

Level 2 — Patterns (on request for more detail, ~50 lines): Read the patterns template with decision guidance and examples:

• templates/architecture/patterns.md
• templates/api/patterns.md
• templates/data/patterns.md

Level 3 — Full Reference (on request for complete SOP): Read the deep reference documents on demand:

• reference/architecture-patterns.md + reference/component-design-guide.md
• reference/api-design-guide.md + reference/function-design-patterns.md
• reference/data-model-guide.md + reference/pydantic-patterns.md

Step 3: Handle Multiple Domains

If context suggests multiple domains (e.g., new feature with API + data):

• Show summary for each detected domain
• Let user choose which to dive deeper into
• Or use /design full for the complete sequence

Step 4: No Context Detected

If detection returns "unknown" and no explicit mode:

• Show all three summaries as overview
• List available modes for user to choose

/design full Sequence

When running the full design workflow:

1. Architecture first: Component boundaries, layers, patterns, DI
2. Data models second: Pydantic schemas based on architecture components
3. API contracts third: Endpoints and schemas using data models

Output uses templates/architecture-doc.md as the final document template.

Output

Write documents to docs/architecture/ in the project root:

Subcommand	Output Path
/design architecture	docs/architecture/architecture-{feature}.md
/design api	docs/architecture/api-{feature}.md
/design data	docs/architecture/data-{feature}.md
/design full	docs/architecture/{feature}.md (combined)

Use templates/architecture-doc.md as the document template with sections:

• Overview, Architecture Pattern, Component Design, Data Model, API Specification
• Data Flows, Module Structure, Error Handling, Configuration
• Testing Strategy, Security Considerations, Performance Considerations

Create docs/architecture/ if it doesn't exist.

Integration

Invoked by: User directly (/design), /story prp workflow (design phase) Invokes: Nothing directly — produces architecture docs consumed by prp-generator Connected skills:

• /story create → requirements → /design → architecture doc → /story prp → PRP
• /implementation consumes design output

Progressive Disclosure Rules

• Never load reference/ docs unless user explicitly asks for full SOP or L3 detail
• Default to L1 summary — enough to orient and decide
• L2 patterns when user asks "how", "what pattern", "show me examples"
• L3 full when user asks for "complete guide", "full reference", or specific deep topic