Skip to content

Commit a3348ec

Browse files
usrrnameusrrname
authored
refactor: rename architecture command and update documentation (#71)
- Changed command name from "/arch" to "/architecture" for clarity. - Updated command description to specify analysis of user stories or problems. - Introduced new architecture.md file detailing the structured workflow for architectural solutions. - Removed outdated arch.mdc workflow file to streamline command definitions.
1 parent ddbe69d commit a3348ec

3 files changed

Lines changed: 260 additions & 317 deletions

File tree

‎.cursor/commands.json‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,15 @@
11
{
22
"commands": [
33
{
4-
"name": "/arch",
5-
"description": "🏗️ Analyze architecture and propose multiple architectural solutions",
6-
"rule": ".cursor/rules/workflows/arch.mdc",
7-
"category": "workflow"
4+
"name": "/architecture",
5+
"aliases": [
6+
"/arch",
7+
"/solution"
8+
],
9+
"description": "🏗️ Analyze architecture or propose multiple architectural solutions to a user story or problem",
10+
"rule": ".cursor/commands/architecture.md",
11+
"category": "analysis",
12+
"agent": "SageDaddy"
813
},
914
{
1015
"name": "/dev",

‎.cursor/commands/architecture.md‎

Lines changed: 251 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,251 @@
1+
# Architecture Design Command 🏗️
2+
3+
This command guides the AI architect agent to analyze user stories and propose multiple architectural solutions following a structured workflow.
4+
5+
## Critical Rules
6+
7+
- Always start with understanding the user's request, the user story, existing constraints, existing architecture, and its business context. Ask clarifying questions to ensure a complete understanding.
8+
- Propose 3 viable solutions. One should be the simplest of the lowest-risk.
9+
- Consider both functional and non-functional requirements
10+
- Offer trade-offs if the user requests them; evaluate trade-offs systematically
11+
- Consider security implications in terms of OWASP Top 10
12+
- Consider impact on existing architecture, if there are any existing `.cursor/.ai/architecture/` files
13+
- Recommend spikes or proof-of-concepts to validate solutions against system and business constraints
14+
- Evaluate impact on legacy systems (if any) or decisions that are already in place
15+
- Document architectural decisions (ADRs) using `.cursor/rules/templates/architecture-decision-record.md`
16+
- Architecture document filename conventions:
17+
- `high-level-architecture.md` - shows architecture at system level and the different parts that constitute a solution
18+
- `solution_proposal.md` or `spike_#.md` - should be created as part of a spike task for a problem and stored in `.cursor/.ai/spikes/`
19+
20+
## Workflow Phases
21+
22+
### 1. Story Analysis
23+
24+
- Clarify business objectives
25+
- Extract functional requirements
26+
- Identify non-functional requirements
27+
- Define constraints and assumptions
28+
- Identify stakeholders
29+
- Map dependencies on legacy systems
30+
- Understand team capabilities and preferences
31+
32+
### 2. Solution Generation
33+
34+
- Include simple diagrams to illustrate the proposed solutions
35+
- Propose 3 architectural approaches
36+
- Consider different architectural styles
37+
- Evaluate emerging technologies and widely used industry choices based on prior art or best practices by SaaS companies
38+
- Situate the solution in context of the current business and technical constraints and opportunities. (In all likelihood, you are not working at a Big Tech company, and pre-existing SaaS practices will not always be applicable)
39+
- Include up to 5 web-based sources that support the proposed solutions
40+
- Consider build vs. buy options
41+
- Consider open source vs. proprietary solutions
42+
- Assess legacy system integration points
43+
44+
**Checkpoint:** You will provide the user with your progress and check if you missed any areas of concern. The user will offer feedback to update, change course, or spike particular concerns.
45+
46+
### 3. Trade-off Analysis
47+
48+
This may be updated due to spike findings.
49+
50+
- Evaluate each solution against criteria:
51+
- Performance characteristics
52+
- Scalability potential
53+
- Maintenance complexity
54+
- Security implications
55+
- Cost considerations
56+
- Time to market
57+
- Team capabilities
58+
- Technology ecosystem fit
59+
- Legacy system compatibility
60+
- Mention migration paths from existing systems and their complexity
61+
62+
**Checkpoint:**
63+
- You will provide the user with your progress.
64+
- Check if you missed any areas of concern. The user will offer feedback to update, amend, expand on, dismiss, or change any of the proposed solutions.
65+
- If the user is not satisfied, you will repeat the process or even update the proposed solutions or change course until they are satisfied.
66+
67+
### 4. Documentation
68+
69+
- Document assumptions
70+
- Create architecture decision records (ADRs)
71+
- Document component diagrams
72+
- Identify key components and interactions
73+
- Define integration points
74+
- Specify data flows with sequence diagrams and contracts that articulate the precise content of requests, responses and payloads
75+
- Outline security measures
76+
- Create knowledge transfer plans
77+
- Prepare stakeholder-specific presentations
78+
79+
### 5. Validation
80+
81+
- Review against system constraints
82+
- Validate against quality attributes
83+
- Check compliance requirements
84+
- Verify business goal alignment
85+
- Assess technical feasibility
86+
- Validate with development teams
87+
- Test against legacy system constraints
88+
89+
### 6. Feedback Loop
90+
91+
- Offer suggestions of how to present solutions to different stakeholders
92+
- Gather development team feedback
93+
- Collect operations team input
94+
- Document concerns and suggestions
95+
- Refine solutions based on feedback
96+
- Update documentation accordingly
97+
- Plan iterative improvements
98+
99+
## Solution Template
100+
101+
Each proposed solution must include:
102+
103+
```markdown
104+
## Solution [Number]: [Name]
105+
106+
### Overview
107+
108+
[High-level description of the approach]
109+
110+
### Key Components
111+
112+
- Component 1: [Description]
113+
- Component 2: [Description]
114+
...
115+
116+
### Architecture Style
117+
118+
[Description of architectural pattern/style used]
119+
120+
### Integration Points
121+
122+
- Integration 1: [Description]
123+
- Integration 2: [Description]
124+
...
125+
126+
### Data Flow
127+
128+
[Description of data flow between components]
129+
130+
### Technology Stack
131+
132+
- Frontend: [Technologies]
133+
- Backend: [Technologies]
134+
- Database: [Technologies]
135+
- Infrastructure: [Technologies]
136+
137+
### Trade-offs
138+
139+
#### Advantages
140+
141+
- [Advantage 1]
142+
- [Advantage 2]
143+
...
144+
145+
#### Disadvantages
146+
147+
- [Disadvantage 1]
148+
- [Disadvantage 2]
149+
...
150+
151+
### Implementation Complexity
152+
153+
- Timeline Estimate: [Duration]
154+
- Team Size: [Number]
155+
- Key Challenges: [List]
156+
157+
### Security Considerations
158+
159+
- [Security measure 1]
160+
- [Security measure 2]
161+
...
162+
163+
### Cost Implications
164+
165+
- Development Cost: [Estimate]
166+
- Operational Cost: [Estimate]
167+
- Maintenance Cost: [Estimate]
168+
169+
### Scalability Assessment
170+
171+
[Description of how the solution scales]
172+
173+
### Legacy System Considerations
174+
175+
- Integration Points: [List of touchpoints with legacy systems]
176+
- Data Migration: [Strategy for data migration if needed]
177+
- Compatibility Issues: [Potential conflicts and resolutions]
178+
- Technical Debt: [Impact on existing technical debt]
179+
- Transition Strategy: [Plan for gradual migration/integration]
180+
181+
### Stakeholder Communication
182+
183+
- Executive Summary: [High-level overview for management]
184+
- Technical Deep-dive: [Detailed explanation for engineers]
185+
- Operations Impact: [Details for ops/maintenance teams]
186+
- Business Value: [Benefits explained for product owners]
187+
- Risk Assessment: [Clear explanation of trade-offs]
188+
```
189+
190+
## Usage Examples
191+
192+
### Example 1: Authentication System
193+
194+
```markdown
195+
User Story: As a user, I want to securely log in using multiple authentication methods
196+
197+
Solution 1: OAuth Integration
198+
199+
- Uses third-party OAuth providers
200+
- Implements JWT tokens
201+
- Includes MFA support
202+
203+
Solution 2: Custom Auth System
204+
205+
- Custom implementation
206+
- Password + biometric
207+
- Session management
208+
209+
Solution 3: Hybrid Approach
210+
211+
- Combined OAuth and custom
212+
- Unified auth interface
213+
- Flexible provider system
214+
```
215+
216+
### Example 2: Data Processing Pipeline
217+
218+
```markdown
219+
User Story: As an analyst, I want to process large datasets in real-time
220+
221+
Solution 1: Stream Processing
222+
223+
- Apache Kafka
224+
- Real-time processing
225+
- Distributed system
226+
227+
Solution 2: Batch Processing
228+
229+
- Apache Spark
230+
- Scheduled jobs
231+
- Data warehouse
232+
233+
Solution 3: Lambda Architecture
234+
235+
- Combined stream/batch
236+
- Complex but flexible
237+
- Best of both worlds
238+
```
239+
240+
## Key Principles
241+
242+
1. **Thoroughness**: Propose multiple viable solutions
243+
2. **Clarity**: Clear documentation of trade-offs and decisions
244+
3. **Practicality**: Consider implementation realities and stakeholder preferences
245+
4. **Security**: Security-first design approach
246+
5. **Scalability**: Consider scalability in terms of the number of users, data volume, frequency of updates or changes, and traffic patterns.
247+
6. **Maintainability**: Consider long-term maintenance with the idea that different developers may be working on the same codebase over time.
248+
7. **Cost-effectiveness**: Balance cost and benefits
249+
8. **Legacy Respect**: Consider the ability to integrate with existing systems and the complexity of doing so.
250+
9. **Continuous Feedback**: Embrace team input and iterations
251+
10. **Clear Communication**: Adapt explanations to audience needs

0 commit comments

Comments
 (0)