design-first

# Design First Methodology You are following a design-first approach. Before writing any code, design the solution. ## Core Principle **Think first, code second.** ## When to Use Design First Apply this methodology when: - Building a new feature or component - Making significant architectural changes - The task involves multiple components or systems - Requirements are complex or ambiguous - Multiple valid approaches exist Skip for trivial changes (typos, simple bug fixes, config changes). ## Design Process ### Phase 1: Understand the Problem Before designing, ensure clarity on: **Requirements Checklist:** - [ ] What is the user/business need? - [ ] What are the inputs and outputs? - [ ] What are the constraints (performance, security, compatibility)? - [ ] What are the edge cases? - [ ] What are the non-requirements (out of scope)? **Questions to Ask:** - What exactly should this do? - What should it NOT do? - How will users interact with it? - How will it integrate with existing systems? - What happens when things go wrong? ### Phase 2: Explore Options Generate multiple approaches before choosing: ```markdown ## Option A: [Approach Name] **Description:** [Brief explanation] **Pros:** - [Advantage 1] - [Advantage 2] **Cons:** - [Disadvantage 1] - [Disadvantage 2] **Complexity:** Low/Medium/High --- ## Option B: [Approach Name] ... ``` Evaluate options against: - Requirements fit - Implementation complexity - Maintenance burden - Performance characteristics - Team familiarity ### Phase 3: Design the Solution Create a design document covering: #### System Overview ``` ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Client │───▶│ Service │───▶│ Database │ └─────────────┘ └─────────────┘ └─────────────┘ ``` #### Data Model ```typescript interface Order { id: string; customerId: string; items: OrderItem[]; status: OrderStatus; createdAt: Date; total: Money; } ``` #### API/Interface Design ```typescript // Public interface interface OrderService { createOrder(customerId: string, items: OrderItem[]): Promise<Order>; getOrder(orderId: string): Promise<Order | null>; cancelOrder(orderId: string): Promise<void>; } ``` #### Key Algorithms/Logic ``` Order Total Calculation: 1. Sum item prices (price × quantity) 2. Apply discounts (percentage-based first, then fixed) 3. Calculate tax (rate based on customer location) 4. Add shipping (free over threshold, otherwise flat rate) ``` #### Error Handling - What errors can occur? - How should they be handled? - What should users see? ### Phase 4: Validate the Design Before implementing, validate: **Self-Review:** - Does it meet all requirements? - Are there simpler alternatives? - What could go wrong? - Is it testable? **External Validation:** - Rubber duck explanation (explain to yourself/others) - Quick review with teammate - Check against similar patterns in codebase ## Design Document Template Use `DESIGN_TEMPLATE.md` as the standard artifact for each feature. It covers: - **Overview** — one-paragraph summary of what is being built and why - **Requirements** — functional and non-functional (performance, security) - **Architecture** — component diagram and explanation - **Data Model** — entity definitions and relationships - **API Design** — interface definitions - **Key Decisions** — decision table with options considered, choice made, and rationale - **Implementation Plan** — ordered steps - **Testing Strategy** — unit and integration test scope - **Open Questions** — unresolved items Create this file at the start of each design session and keep it updated as the design evolves. ## Design Levels ### High-Level Design (Architecture) - System components and their interactions - Data flow between systems - Technology choices - Deployment architecture ### Mid-Level Design (Module/Component) - Class/module structure - Interfaces and contracts - State management - Error handling strategy ### Low-Level Design (Implementation) - Algorithm details - Data structures - Method signatures - Edge case handling ## Anti-Patterns to Avoid | Anti-Pattern | Mitigation | |---|---| | Big Design Up Front (BDUF) | Design enough to start; refine as you learn | | Analysis Paralysis | Time-box the design phase; decide at 70% confidence | | Design in Isolation | Align with existing codebase patterns and team conventions | ## Integration with Implementation After design is approved: 1. **Review the design** one more time before coding 2. **Break into tasks** using task-decomposition skill 3. **Implement incrementally** - verify design assumptions as you code 4. **Update design** if you discover issues during implementation The design document is living — update it as you learn. ## Signals You Need More Design - "I'm not sure where to start" - "This is getting complicated" - "I keep refactoring" - "The requirements are unclear" - "Multiple approaches seem valid" Stop and design before proceeding.