8.6 KiB
8.6 KiB
Clarify Design
Clarifies technical design and architecture based on requirements.
Initial Setup
Respond with:
I'm ready to help clarify the technical design.
I'll read your requirements from spec/requirements.md to understand what needs to be built.
Please describe your tech stack and design preferences.
Wait for user input.
Workflow
- Read
spec/requirements.mdFULLY - Receive user's tech preferences
- Ask clarifying questions (3-5 at a time) about:
- Specific technologies and versions
- Architecture patterns and structure
- Data storage and management
- UI/interface approach
- Integration points and dependencies
- Testing approach and preferences
- Continue asking until no more questions remain
- Generate design document at
spec/design.md
Guidelines
- Each bullet with a clarifying question should be numbered
- Be specific: name actual technologies with versions, not placeholders
- Align with requirements: every design decision should trace back to requirements
- If user doesn't mention UI approach and requirements need one, ask or suggest
- If user has no testing preferences, create appropriate strategy based on tech stack
- Include concrete file/folder structures
- Match complexity to project scope - don't over-engineer
- Design for both happy path and error cases
Chat Output Format
After completing design:
I've created a design document at spec/design.md.
The design includes:
- Complete tech stack with rationale
- Component breakdown with responsibilities
- Data model and UI structure
- Key user flows and interactions
- File structure and development approach
Please review and let me know if you'd like any adjustments.
File Output Format
Create spec/design.md:
# Design: [Project Name]
## Design Overview
[2-3 sentences describing the technical approach and key architectural decisions]
## Tech Stack
### Languages & Frameworks
- **Language**: [e.g., JavaScript/TypeScript]
- **Framework**: [e.g., React 18]
- **Build Tool**: [e.g., Vite]
- **Styling**: [e.g., Tailwind CSS]
### Data & State
- **Data Storage**: [e.g., localStorage, PostgreSQL, MongoDB]
- **State Management**: [e.g., React Context, Redux, Zustand]
- **Data Format**: [e.g., JSON, structured data model]
### Dependencies
- [Library 1]: [Purpose]
- [Library 2]: [Purpose]
**Rationale**: [Why this tech stack? How does it fit the requirements?]
## System Architecture
### High-Level Architecture
[Diagram or description of system layers]
Example: ┌─────────────────────────────┐ │ Presentation Layer │ ← UI Components ├─────────────────────────────┤ │ Business Logic Layer │ ← State Management ├─────────────────────────────┤ │ Data Layer │ ← Storage/API └─────────────────────────────┘
### Component Breakdown
#### Component: [Name]
**Purpose**: [What this component does]
**Location**: `src/components/ComponentName.tsx`
**Responsibilities**:
- [Responsibility 1]
- [Responsibility 2]
**Props/Interface**:
```typescript
interface ComponentProps {
prop1: string;
prop2: number;
onAction: () => void;
}
State:
Data Model
Entity: [EntityName]
interface EntityName {
id: string;
field1: string;
field2: number;
field3: Date;
}
Purpose: [What this represents]
Relationships: [How it relates to other entities]
User Interface Design
Screen: [ScreenName]
Purpose: [What user accomplishes here]
Layout:
┌─────────────────────────┐
│ Header │
├─────────────────────────┤
│ Main Content │
│ - Element 1 │
│ - Element 2 │
├─────────────────────────┤
│ Footer/Actions │
└─────────────────────────┘
Key Elements:
- [Element 1]: [Purpose and behavior]
- [Element 2]: [Purpose and behavior]
User Interactions:
- [Action 1] → [Result]
- [Action 2] → [Result]
Key Interactions & Flows
Flow: [FlowName]
Scenario: [User story this implements]
- User [action]
- System [response]
- System [next step]
- User sees [result]
Error Handling:
- If [error condition] → [behavior]
- If [error condition] → [behavior]
File Structure
project-root/
├── src/
│ ├── components/
│ │ ├── ComponentA.tsx
│ │ └── ComponentB.tsx
│ ├── hooks/
│ │ └── useCustomHook.ts
│ ├── utils/
│ │ └── helpers.ts
│ ├── types/
│ │ └── index.ts
│ ├── App.tsx
│ └── main.tsx
├── spec/
│ ├── requirements.md
│ └── design.md
├── package.json
└── README.md
Design Decisions & Tradeoffs
Decision: [DecisionName]
Choice: [What we decided]
Alternatives Considered: [What else we could do]
Rationale: [Why we chose this]
Tradeoffs: [What we gain/lose]
Non-Functional Considerations
Performance
- [Performance approach, e.g., "Lazy load components"]
- [Optimization strategy, e.g., "Memoize expensive calculations"]
Scalability
- [How design handles growth]
- [What needs to change if requirements scale]
Accessibility
- [Accessibility approach, e.g., "ARIA labels on all interactive elements"]
- [Keyboard navigation strategy]
Error Handling
- [Error handling strategy]
- [User feedback approach]
Testing Strategy
Philosophy: Every task must be verified before moving to the next. Testing is incremental and continuous.
Testing Tools & Framework
- Testing Framework: [e.g., Jest, pytest, Vitest, etc.]
- Testing Library: [e.g., React Testing Library, unittest, etc.]
- Test Runner Command:
[e.g., npm test, pytest, etc.] - Coverage Tool (if applicable): [e.g., Jest coverage, coverage.py]
Verification Approach for Each Task Type
Code/Logic Tasks
- Verification Method: Automated tests
- When to Test: [After each task / TDD / as you go]
- What to Test:
- Function behavior with valid inputs
- Edge cases and error handling
- Integration with other components
UI/Component Tasks
- Verification Method: [Automated tests + manual verification / manual only]
- Automated Tests: Component rendering, props, interactions
- Manual Verification: Visual appearance, responsiveness, UX flow
Configuration/Setup Tasks
- Verification Method: [e.g., "Run build command", "Run dev server"]
- Success Criteria: No errors, expected output
Test Writing Approach
[Describe when tests should be written:]
- Test-Driven Development (TDD): Write tests before implementation
- Test-After: Implement feature, then write tests
- Incremental: Write tests as you implement
Critical Testing Rules
- Every task must have clear verification steps
- Tests must pass before moving to next task
- If tests fail repeatedly (3+ times), stop and reassess
- Document any tasks that cannot be automated (manual verification)
Unit Tests
- What: Test individual components/functions in isolation
- Where:
src/__tests__/or alongside source files - Key areas: [List critical functions to test]
- Run Command:
[command to run unit tests]
Integration Tests
- What: Test component interactions and data flow
- Key flows: [List important user flows to test]
- Run Command:
[command to run integration tests]
Manual Testing Scenarios
- What: UI/UX verification that requires human judgment
- Key scenarios: [List scenarios to manually verify]
- When: After completing each phase with UI changes
Development Approach
Phase Breakdown
[High-level phases - detailed breakdown happens in plan.md]
- Phase 1: [e.g., "Setup & Core Structure"]
- Phase 2: [e.g., "Data Layer"]
- Phase 3: [e.g., "UI Components"]
- Phase 4: [e.g., "Integration & Polish"]
Development Standards
- [Coding conventions]
- [Naming conventions]
- [Documentation requirements]
Open Questions
[Any remaining technical uncertainties - resolve before planning]
- [Question 1]
- [Question 2]
References
- Requirements:
spec/requirements.md - [Any relevant documentation or resources]