From sdd-mcp
Generates technical design documents for SDD workflow, covering architecture patterns, component specs, data models, and API interfaces from approved requirements. Invoke via /sdd-design <feature-name>.
npx claudepluginhub yi-john-huang/sdd-mcpThis skill uses the workspace's default tool permissions.
Generate comprehensive technical design documents that translate approved requirements into actionable architecture specifications.
Transforms approved requirements into technical design documents covering system architecture, components, data models, interfaces, error handling, and testing strategies.
Generates architecture/design documents from approved SRS docs when no prior design exists, proposing 2-3 approaches with trade-offs and securing section-by-section approval.
Collaboratively brainstorms architecture, approaches, and trade-offs from specs, proposes options, gets section-by-section approval, then writes design.md. Use for 'design this' or 'brainstorm approaches'.
Share bugs, ideas, or general feedback.
Generate comprehensive technical design documents that translate approved requirements into actionable architecture specifications.
Before generating design:
/sdd-requirementssdd-approve requirements MCP tool).spec/steering/tech.md and .spec/steering/structure.mdUse sdd-status MCP tool to verify:
requirements.generated: truerequirements.approved: true (recommended before design).spec/specs/{feature}/requirements.mdSelect appropriate patterns based on requirements:
| Pattern | Use When | Key Characteristics |
|---|---|---|
| Clean Architecture | Domain-heavy apps | Layers: Domain → Use Cases → Interface → Infrastructure |
| MVC/MVP | Web applications | Model-View-Controller separation |
| Microservices | Distributed systems | Independent deployable services |
| Event-Driven | Async processing | Event producers and consumers |
| Hexagonal | Testable business logic | Ports and Adapters pattern |
For each component, specify:
## Component: {ComponentName}
**Type:** Service | Controller | Repository | Adapter | Provider
**Purpose:** {Single responsibility description}
**Responsibilities:**
- {Responsibility 1}
- {Responsibility 2}
**Interface:**
```typescript
interface I{ComponentName} {
methodName(input: InputType): Promise<OutputType>;
}
Dependencies:
Error Handling:
### Step 5: Define Data Models
```markdown
## Data Models
### Model: {EntityName}
**Purpose:** {What this entity represents}
| Property | Type | Required | Description | Validation |
|----------|------|----------|-------------|------------|
| id | string | Yes | Unique identifier | UUID format |
| name | string | Yes | Display name | 1-100 chars |
| createdAt | Date | Yes | Creation timestamp | ISO 8601 |
**Relationships:**
- Has many: {RelatedEntity} (one-to-many)
- Belongs to: {ParentEntity} (many-to-one)
**Invariants:**
- {Business rule 1}
- {Business rule 2}
## API Interfaces
### REST Endpoints
| Method | Path | Description | Request | Response | Auth |
|--------|------|-------------|---------|----------|------|
| POST | /api/v1/resource | Create resource | CreateDTO | Resource | Bearer |
| GET | /api/v1/resource/:id | Get by ID | - | Resource | Bearer |
### Internal Service Interfaces
Following Interface Segregation Principle:
```typescript
// Read operations
interface IResourceReader {
getById(id: string): Promise<Resource>;
list(filter: Filter): Promise<Resource[]>;
}
// Write operations
interface IResourceWriter {
create(data: CreateDTO): Promise<Resource>;
update(id: string, data: UpdateDTO): Promise<Resource>;
delete(id: string): Promise<void>;
}
### Step 7: Document Error Handling
```markdown
## Error Handling Strategy
### Error Categories
| Category | HTTP Status | Retry | Log Level |
|----------|-------------|-------|-----------|
| Validation | 400 | No | WARN |
| Not Found | 404 | No | INFO |
| Conflict | 409 | No | WARN |
| Rate Limit | 429 | Yes (backoff) | WARN |
| Internal | 500 | Yes (limited) | ERROR |
### Error Response Format
```json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Human-readable message",
"details": [{ "field": "email", "issue": "Invalid format" }],
"requestId": "uuid-for-tracing"
}
}
### Step 8: Apply Linus-Style Quality Review
Before finalizing, validate against these principles:
#### 1. Taste - Is it elegant?
- Does the design feel natural and intuitive?
- Are there unnecessary complications?
#### 2. Complexity - Is it simple?
- Can any component be simplified?
- Are there too many abstractions?
#### 3. Special Cases - Are edge cases handled?
- What happens at boundaries?
- How does it fail gracefully?
#### 4. Data Structures - Are they optimal?
- Is the right data structure chosen?
- Does data flow make sense?
#### 5. Code Organization - Is it maintainable?
- Can new developers understand it?
- Is it easy to modify?
### Step 9: Save and Validate
1. Save design to `.spec/specs/{feature}/design.md`
2. Use `sdd-validate-design` MCP tool for GO/NO-GO review
3. If GO, use `sdd-approve design` MCP tool
## Design Document Template
```markdown
# Design: {Feature Name}
## Overview
{Brief summary of the design approach}
## Architecture Pattern
{Selected pattern and rationale}
## Component Diagram
[Component A] ──> [Component B] │ └──> [Component C]
## Components
### {Component 1}
{Component details as described above}
## Data Models
### {Entity 1}
{Model details as described above}
## Interfaces
### External APIs
{API specifications}
### Internal Interfaces
{Service interfaces}
## Error Handling
{Error strategy}
## Security Considerations
- Authentication: {approach}
- Authorization: {approach}
- Data protection: {approach}
## Testing Strategy
- Unit tests: {coverage target}
- Integration tests: {scope}
- E2E tests: {critical paths}
## Dependencies
- External: {list}
- Internal: {list}
| Tool | When to Use |
|---|---|
sdd-status | Verify requirements phase complete |
sdd-validate-design | Perform GO/NO-GO review |
sdd-approve | Mark design phase as approved |
Apply these steering documents during design:
| Document | Purpose | Key Application |
|---|---|---|
.spec/steering/principles.md | SOLID, DRY, KISS, YAGNI | Apply SOLID principles to component design, ensure interfaces follow ISP and DIP |
.spec/steering/linus-review.md | Code quality, data structures | Focus on data structures first, eliminate special cases, ensure backward compatibility |
Key Linus Principles for Design: