Generate Application Design Document
User Request: $ARGUMENTS
Context
- Project root: !
pwd
- Package.json: @package.json
- Existing design docs: !
ls -la .agents/rules/ 2>/dev/null || echo "No .claude/skills directory yet"
Goal
Create a comprehensive Application Design Document based on deep codebase analysis and user input. The document provides a high-level overview of the application's architecture, core features, user experience, and business logic while remaining technology-agnostic and focused on the "what" rather than the "how".
Process
1. Initial Analysis
- Analyze project structure and existing codebase
- Review package.json for project name and dependencies
- Check for existing documentation in .agents/rules/
- Identify key application features and patterns
- Think deeply about the application's purpose and architecture
2. Codebase Deep Dive
Think harder about the application's architecture and business logic.
Analyze the codebase to understand:
- Application Structure: Main modules, features, and components
- User Flows: Authentication, navigation, key user journeys
- Data Models: Conceptual relationships and entities
- Business Logic: Core rules, workflows, and processes
- Integrations: External services and APIs
- Security Patterns: Authentication and authorization approaches
Extended thinking helps identify non-obvious patterns, understand complex business rules from code, and make strategic decisions about what aspects are most important to document.
3. Interactive Q&A Session
CRITICAL: Ask project stage question FIRST, then 4-7 additional questions:
- Use lettered/numbered options for easy response
- Focus on business goals and user needs
- Gather context for proper documentation
4. Update Project Configuration
Based on project stage response:
- Update
.agents/rules/status.mdc with current stage
- Set appropriate DO/DON'T priorities for the stage
- Document stage-specific development guidelines in the Cursor rule
5. Generate Document
Create comprehensive app design document following the standard structure
6. Save and Organize
- Create
.agents/rules/ directory if needed
- Save as
1-app-design-document.mdc
- Suggest next steps (tech stack doc, PRD, etc.)
Required Questions Template
🎯 CRITICAL: Project Stage Assessment (Ask First!)
1. What stage is your application currently in?
a) Pre-MVP - Building initial version, not deployed to production yet
b) MVP - Basic version deployed and live with early users
c) Production - Mature application with established user base
d) Enterprise - Large scale deployment, multiple teams involved
2. Based on your selected stage, here are the development priorities:
Pre-MVP Priorities:
- ✅ DO: Core functionality, security basics, input validation, working features
- ❌ DON'T: Unit tests, performance optimization, accessibility polish, perfect code
- 🚀 Focus: Ship fast with security, iterate based on feedback
MVP Priorities:
- ✅ DO: Critical path testing, basic monitoring, user feedback loops
- ❌ DON'T: Comprehensive test coverage, advanced patterns, premature optimization
- 🚀 Focus: Stability for early users, rapid iteration
Production Priorities:
- ✅ DO: Testing, monitoring, performance, accessibility, documentation
- ❌ DON'T: Skip security reviews, ignore technical debt
- 🚀 Focus: Reliability, scalability, user experience
Enterprise Priorities:
- ✅ DO: Comprehensive testing, security audits, team coordination, compliance
- ❌ DON'T: Skip documentation, ignore code standards
- 🚀 Focus: Team efficiency, maintainability, compliance
📋 Context-Specific Questions (Ask 4-7 based on analysis)
3. Application Purpose & Users
- What is the primary problem your application solves?
- Who are your target users and what are their main goals?
4. Unique Value Proposition
- What makes your application unique compared to existing solutions?
- What's your competitive advantage?
5. User Roles & Permissions
- What different types of users interact with your system?
- Examples: end users, admins, moderators, content creators, viewers
6. Core User Journeys
- What are the 2-3 most critical user flows?
- Example: Sign up → Create content → Share → Get feedback
7. Business Model & Growth
- How does this application generate value?
- Options: SaaS subscription, marketplace, freemium, advertising, one-time purchase
8. Integration Ecosystem
- What external services must you integrate with?
- Examples: payment processors, email services, analytics, social platforms
9. Scale & Performance Goals
- What scale are you planning for in the next 12 months?
- Users: dozens, hundreds, thousands, millions?
- Geographic: local, national, global?
10. Success Metrics
- How will you measure if your application is successful?
- Examples: user retention, revenue, engagement, conversion rates
Document Structure
The generated document must follow this high-level structure:
Introduction
- Application overview and purpose
- Target audience and user base
- Core value proposition
- Business context and goals
Core Features
- Feature Category 1: (e.g., User Management)
- Purpose and user benefit
- Key functionalities
- User experience considerations
- Feature Category 2: (e.g., Content Creation)
- Purpose and user benefit
- Key functionalities
- User experience considerations
- [Additional feature categories as needed]
User Experience
- User personas and roles
- Key user journeys and flows
- Interface design principles
- Accessibility and usability considerations
System Architecture
- High-level system components
- Data flow and relationships
- Integration points and external services
- Security and privacy approach
Business Logic
- Core business rules and processes
- Data models and relationships (conceptual)
- Workflow and state management
- Validation and business constraints
Future Considerations
- Planned enhancements and features
- Scalability considerations
- Potential integrations
- Long-term vision and roadmap
Target Audience
The document should be accessible to:
- Business stakeholders who need to understand the application's purpose and capabilities
- Product managers planning features and roadmaps
- Designers creating user interfaces and experiences
- New developers joining the project who need a high-level understanding
- Technical leaders making architectural decisions
The language should be clear, business-focused, and avoid technical implementation details.
Writing Principles
DO:
- Business Focus: Describe WHAT the application does, not HOW
- User Value: Emphasize benefits and outcomes for users
- Clear Language: Write for non-technical stakeholders
- Visual Thinking: Use diagrams and flows where helpful
- Future Ready: Consider growth and evolution paths
DON'T:
- Technical Details: No code snippets or implementation specifics
- Technology Stack: Save for 2-tech-stack.mdc document
- Database Schemas: Keep data models conceptual
- API Specifications: Focus on capabilities, not endpoints
- Performance Metrics: Describe goals, not technical benchmarks
Output
- Format: Markdown (
.mdc)
- Location:
.agents/rules/
- Filename:
1-app-design-document.mdc
Execution Steps
1. Start with Analysis
- Use Read, Glob, and Grep to explore the codebase
- Identify key features and patterns
- Look for existing documentation
- Use extended thinking: "Think deeply about this codebase's architecture, business purpose, and how different components work together to serve users"
2. Interactive Q&A
- MUST ASK PROJECT STAGE FIRST
- Present questions with numbered/lettered options
- Wait for user responses before proceeding
3. Update Project Status in Cursor Rule
Update .agents/rules/status.mdc with the project stage information:
---
description: Project status and stage-specific development guidelines
globs:
alwaysApply: true
---
# Project Status Guidelines
## Current Project Stage: [Stage Name]
**Stage**: [Pre-MVP | MVP | Production | Enterprise]
### DO Care About (Current Stage Priorities)
[Stage-specific DO priorities from template below]
### DO NOT Care About (Skip for Velocity)
[Stage-specific DON'T priorities from template below]
### Development Approach
[Stage-specific development focus]
## Stage-Based Development Guidelines
[Keep existing stage categories and guidelines from the original file]
Stage-Specific Content:
Pre-MVP:
- ✅ DO: Core functionality, security basics, input validation, working features
- ❌ DON'T: Unit tests, performance optimization, accessibility polish, perfect code
- 🚀 Focus: Ship fast with security, iterate based on feedback
MVP:
- ✅ DO: Critical path testing, basic monitoring, user feedback loops
- ❌ DON'T: Comprehensive test coverage, advanced patterns, premature optimization
- 🚀 Focus: Stability for early users, rapid iteration
Production:
- ✅ DO: Testing, monitoring, performance, accessibility, documentation
- ❌ DON'T: Skip security reviews, ignore technical debt
- 🚀 Focus: Reliability, scalability, user experience
Enterprise:
- ✅ DO: Comprehensive testing, security audits, team coordination, compliance
- ❌ DON'T: Skip documentation, ignore code standards
- 🚀 Focus: Team efficiency, maintainability, compliance
4. Generate Document
- Follow the standard structure
- Tailor content to project stage
- Keep language accessible
5. Save and Next Steps
- Create directories:
mkdir -p docs .claude/skills
- Save design document:
.agents/rules/1-app-design-document.mdc
- Update Claude rule:
.agents/rules/status.mdc
- Suggest: "Would you like me to create a technical stack document next?"
1---
2allowed-tools: Read, Glob, Grep, Write, MultiEdit, TodoWrite
3description: Generate comprehensive app design document with project stage assessment
4name: create-app-design
5metadata:
6 skiller:
7 source: https://skillmd.com/skills/udecode/create-app-design
8 upstream: .agents/rules/create-app-design.mdc
9---
10
11# Generate Application Design Document
12
13**User Request:** $ARGUMENTS
14
15## Context
16
17- Project root: !`pwd`
18- Package.json: @package.json
19- Existing design docs: !`ls -la .agents/rules/ 2>/dev/null || echo "No .claude/skills directory yet"`
20
21## Goal
22
23Create a comprehensive Application Design Document based on deep codebase analysis and user input. The document provides a high-level overview of the application's architecture, core features, user experience, and business logic while remaining technology-agnostic and focused on the "what" rather than the "how".
24
25## Process
26
27### 1. Initial Analysis
28
29- Analyze project structure and existing codebase
30- Review package.json for project name and dependencies
31- Check for existing documentation in .agents/rules/
32- Identify key application features and patterns
33- **Think deeply** about the application's purpose and architecture
34
35### 2. Codebase Deep Dive
36
37**Think harder about the application's architecture and business logic.**
38
39Analyze the codebase to understand:
40
41- **Application Structure:** Main modules, features, and components
42- **User Flows:** Authentication, navigation, key user journeys
43- **Data Models:** Conceptual relationships and entities
44- **Business Logic:** Core rules, workflows, and processes
45- **Integrations:** External services and APIs
46- **Security Patterns:** Authentication and authorization approaches
47
48_Extended thinking helps identify non-obvious patterns, understand complex business rules from code, and make strategic decisions about what aspects are most important to document._
49
50### 3. Interactive Q&A Session
51
52**CRITICAL:** Ask project stage question FIRST, then 4-7 additional questions:
53
54- Use lettered/numbered options for easy response
55- Focus on business goals and user needs
56- Gather context for proper documentation
57
58### 4. Update Project Configuration
59
60Based on project stage response:
61
62- Update `.agents/rules/status.mdc` with current stage
63- Set appropriate DO/DON'T priorities for the stage
64- Document stage-specific development guidelines in the Cursor rule
65
66### 5. Generate Document
67
68Create comprehensive app design document following the standard structure
69
70### 6. Save and Organize
71
72- Create `.agents/rules/` directory if needed
73- Save as `1-app-design-document.mdc`
74- Suggest next steps (tech stack doc, PRD, etc.)
75
76## Required Questions Template
77
78### 🎯 CRITICAL: Project Stage Assessment (Ask First!)
79
80**1. What stage is your application currently in?**
81
82a) **Pre-MVP** - Building initial version, not deployed to production yet
83 b) **MVP** - Basic version deployed and live with early users
84 c) **Production** - Mature application with established user base
85 d) **Enterprise** - Large scale deployment, multiple teams involved
86
87**2. Based on your selected stage, here are the development priorities:**
88
89- **Pre-MVP Priorities:**
90
91 - ✅ DO: Core functionality, security basics, input validation, working features
92 - ❌ DON'T: Unit tests, performance optimization, accessibility polish, perfect code
93 - 🚀 Focus: Ship fast with security, iterate based on feedback
94
95- **MVP Priorities:**
96
97 - ✅ DO: Critical path testing, basic monitoring, user feedback loops
98 - ❌ DON'T: Comprehensive test coverage, advanced patterns, premature optimization
99 - 🚀 Focus: Stability for early users, rapid iteration
100
101- **Production Priorities:**
102
103 - ✅ DO: Testing, monitoring, performance, accessibility, documentation
104 - ❌ DON'T: Skip security reviews, ignore technical debt
105 - 🚀 Focus: Reliability, scalability, user experience
106
107- **Enterprise Priorities:**
108 - ✅ DO: Comprehensive testing, security audits, team coordination, compliance
109 - ❌ DON'T: Skip documentation, ignore code standards
110 - 🚀 Focus: Team efficiency, maintainability, compliance
111
112### 📋 Context-Specific Questions (Ask 4-7 based on analysis)
113
114**3. Application Purpose & Users**
115
116- What is the primary problem your application solves?
117- Who are your target users and what are their main goals?
118
119**4. Unique Value Proposition**
120
121- What makes your application unique compared to existing solutions?
122- What's your competitive advantage?
123
124**5. User Roles & Permissions**
125
126- What different types of users interact with your system?
127- Examples: end users, admins, moderators, content creators, viewers
128
129**6. Core User Journeys**
130
131- What are the 2-3 most critical user flows?
132- Example: Sign up → Create content → Share → Get feedback
133
134**7. Business Model & Growth**
135
136- How does this application generate value?
137- Options: SaaS subscription, marketplace, freemium, advertising, one-time purchase
138
139**8. Integration Ecosystem**
140
141- What external services must you integrate with?
142- Examples: payment processors, email services, analytics, social platforms
143
144**9. Scale & Performance Goals**
145
146- What scale are you planning for in the next 12 months?
147- Users: dozens, hundreds, thousands, millions?
148- Geographic: local, national, global?
149
150**10. Success Metrics**
151
152- How will you measure if your application is successful?
153- Examples: user retention, revenue, engagement, conversion rates
154
155## Document Structure
156
157The generated document must follow this high-level structure:
158
159### **Introduction**
160
161- Application overview and purpose
162- Target audience and user base
163- Core value proposition
164- Business context and goals
165
166### **Core Features**
167
168- **Feature Category 1:** (e.g., User Management)
169 - Purpose and user benefit
170 - Key functionalities
171 - User experience considerations
172- **Feature Category 2:** (e.g., Content Creation)
173 - Purpose and user benefit
174 - Key functionalities
175 - User experience considerations
176- **[Additional feature categories as needed]**
177
178### **User Experience**
179
180- User personas and roles
181- Key user journeys and flows
182- Interface design principles
183- Accessibility and usability considerations
184
185### **System Architecture**
186
187- High-level system components
188- Data flow and relationships
189- Integration points and external services
190- Security and privacy approach
191
192### **Business Logic**
193
194- Core business rules and processes
195- Data models and relationships (conceptual)
196- Workflow and state management
197- Validation and business constraints
198
199### **Future Considerations**
200
201- Planned enhancements and features
202- Scalability considerations
203- Potential integrations
204- Long-term vision and roadmap
205
206## Target Audience
207
208The document should be accessible to:
209
210- **Business stakeholders** who need to understand the application's purpose and capabilities
211- **Product managers** planning features and roadmaps
212- **Designers** creating user interfaces and experiences
213- **New developers** joining the project who need a high-level understanding
214- **Technical leaders** making architectural decisions
215
216The language should be clear, business-focused, and avoid technical implementation details.
217
218## Writing Principles
219
220### DO:
221
222- **Business Focus:** Describe WHAT the application does, not HOW
223- **User Value:** Emphasize benefits and outcomes for users
224- **Clear Language:** Write for non-technical stakeholders
225- **Visual Thinking:** Use diagrams and flows where helpful
226- **Future Ready:** Consider growth and evolution paths
227
228### DON'T:
229
230- **Technical Details:** No code snippets or implementation specifics
231- **Technology Stack:** Save for 2-tech-stack.mdc document
232- **Database Schemas:** Keep data models conceptual
233- **API Specifications:** Focus on capabilities, not endpoints
234- **Performance Metrics:** Describe goals, not technical benchmarks
235
236## Output
237
238- **Format:** Markdown (`.mdc`)
239- **Location:** `.agents/rules/`
240- **Filename:** `1-app-design-document.mdc`
241
242## Execution Steps
243
244### 1. Start with Analysis
245
246- Use Read, Glob, and Grep to explore the codebase
247- Identify key features and patterns
248- Look for existing documentation
249- **Use extended thinking:** "Think deeply about this codebase's architecture, business purpose, and how different components work together to serve users"
250
251### 2. Interactive Q&A
252
253- **MUST ASK PROJECT STAGE FIRST**
254- Present questions with numbered/lettered options
255- Wait for user responses before proceeding
256
257### 3. Update Project Status in Cursor Rule
258
259Update `.agents/rules/status.mdc` with the project stage information:
260
261```markdown
262---
263description: Project status and stage-specific development guidelines
264globs:
265alwaysApply: true
266---
267
268# Project Status Guidelines
269
270## Current Project Stage: [Stage Name]
271
272**Stage**: [Pre-MVP | MVP | Production | Enterprise]
273
274### DO Care About (Current Stage Priorities)
275
276[Stage-specific DO priorities from template below]
277
278### DO NOT Care About (Skip for Velocity)
279
280[Stage-specific DON'T priorities from template below]
281
282### Development Approach
283
284[Stage-specific development focus]
285
286## Stage-Based Development Guidelines
287
288[Keep existing stage categories and guidelines from the original file]
289```
290
291**Stage-Specific Content:**
292
293- **Pre-MVP**:
294
295 - ✅ DO: Core functionality, security basics, input validation, working features
296 - ❌ DON'T: Unit tests, performance optimization, accessibility polish, perfect code
297 - 🚀 Focus: Ship fast with security, iterate based on feedback
298
299- **MVP**:
300
301 - ✅ DO: Critical path testing, basic monitoring, user feedback loops
302 - ❌ DON'T: Comprehensive test coverage, advanced patterns, premature optimization
303 - 🚀 Focus: Stability for early users, rapid iteration
304
305- **Production**:
306
307 - ✅ DO: Testing, monitoring, performance, accessibility, documentation
308 - ❌ DON'T: Skip security reviews, ignore technical debt
309 - 🚀 Focus: Reliability, scalability, user experience
310
311- **Enterprise**:
312 - ✅ DO: Comprehensive testing, security audits, team coordination, compliance
313 - ❌ DON'T: Skip documentation, ignore code standards
314 - 🚀 Focus: Team efficiency, maintainability, compliance
315
316### 4. Generate Document
317
318- Follow the standard structure
319- Tailor content to project stage
320- Keep language accessible
321
322### 5. Save and Next Steps
323
324- Create directories: `mkdir -p docs .claude/skills`
325- Save design document: `.agents/rules/1-app-design-document.mdc`
326- Update Claude rule: `.agents/rules/status.mdc`
327- Suggest: "Would you like me to create a technical stack document next?"