Agent Skills Framework Extension
Software Design Document Patterns Skill
When to Use This Skill
Use this skill when implementing software design document patterns patterns in your codebase.
How to Use This Skill
- Review the patterns and examples below
- Apply the relevant patterns to your implementation
- Follow the best practices outlined in this skill
SDD specifications, technical requirements documentation, architecture documentation, and comprehensive system design documentation.
Core Capabilities
- SDD Templates - Complete software design document structure
- Requirements Documentation - Functional, non-functional, constraints
- Architecture Documentation - System architecture, component diagrams, data flow
- API Specifications - REST API, GraphQL, WebSocket documentation
- Database Schema - ERD, table specifications, relationships
- Deployment Architecture - Infrastructure, deployment diagrams, CI/CD
SDD Template Generator
# scripts/sdd_generator.py
from typing import List, Dict, Optional
from dataclasses import dataclass
from datetime import datetime
@dataclass
class SDDSection:
"""SDD document section."""
title: str
content: str
subsections: List['SDDSection'] = None
class SoftwareDesignDocumentGenerator:
"""Generate comprehensive Software Design Document."""
def __init__(self, project_name: str, version: str = "1.0"):
self.project_name = project_name
self.version = version
self.sections: List[SDDSection] = []
def generate(self) -> str:
"""Generate complete SDD in Markdown."""
doc = self._generate_header()
doc += self._generate_toc()
# Core sections
doc += self._section_1_introduction()
doc += self._section_2_system_overview()
doc += self._section_3_architecture()
doc += self._section_4_detailed_design()
doc += self._section_5_data_design()
doc += self._section_6_interface_design()
doc += self._section_7_security()
doc += self._section_8_deployment()
doc += self._section_9_testing()
doc += self._section_10_appendices()
return doc
def _generate_header(self) -> str:
"""Generate document header."""
return f"""# Software Design Document
## {self.project_name}
**Version:** {self.version}
**Date:** {datetime.now().strftime('%Y-%m-%d')}
**Status:** Draft
---
"""
def _generate_toc(self) -> str:
"""Generate table of contents."""
return """## Table of Contents
1. [Introduction](#1-introduction)
- 1.1 [Purpose](#11-purpose)
- 1.2 [Scope](#12-scope)
- 1.3 [Definitions, Acronyms, and Abbreviations](#13-definitions-acronyms-and-abbreviations)
- 1.4 [References](#14-references)
- 1.5 [Overview](#15-overview)
2. [System Overview](#2-system-overview)
- 2.1 [System Context](#21-system-context)
- 2.2 [System Architecture](#22-system-architecture)
- 2.3 [Design Constraints](#23-design-constraints)
3. [Architectural Design](#3-architectural-design)
- 3.1 [Architectural Patterns](#31-architectural-patterns)
- 3.2 [Component Diagram](#32-component-diagram)
- 3.3 [Deployment Architecture](#33-deployment-architecture)
4. [Detailed Design](#4-detailed-design)
- 4.1 [Component Specifications](#41-component-specifications)
- 4.2 [Class Diagrams](#42-class-diagrams)
- 4.3 [Sequence Diagrams](#43-sequence-diagrams)
5. [Data Design](#5-data-design)
- 5.1 [Database Schema](#51-database-schema)
- 5.2 [Data Models](#52-data-models)
- 5.3 [Data Flow](#53-data-flow)
6. [Interface Design](#6-interface-design)
- 6.1 [External Interfaces](#61-external-interfaces)
- 6.2 [Internal Interfaces](#62-internal-interfaces)
- 6.3 [API Specifications](#63-api-specifications)
7. [Security Design](#7-security-design)
- 7.1 [Authentication](#71-authentication)
- 7.2 [Authorization](#72-authorization)
- 7.3 [Data Protection](#73-data-protection)
8. [Deployment Design](#8-deployment-design)
- 8.1 [Infrastructure](#81-infrastructure)
- 8.2 [CI/CD Pipeline](#82-cicd-pipeline)
- 8.3 [Monitoring and Logging](#83-monitoring-and-logging)
9. [Testing Strategy](#9-testing-strategy)
- 9.1 [Unit Testing](#91-unit-testing)
- 9.2 [Integration Testing](#92-integration-testing)
- 9.3 [End-to-End Testing](#93-end-to-end-testing)
10. [Appendices](#10-appendices)
---
"""
def _section_1_introduction(self) -> str:
"""Generate Introduction section."""
return """## 1. Introduction
### 1.1 Purpose
This Software Design Document (SDD) provides a comprehensive architectural overview of the system, using a number of different architectural views to depict different aspects of the system. It is intended to capture and convey the significant architectural decisions which have been made on the system.
**Target Audience:**
- Software architects and developers
- QA engineers and testers
- Project managers
- Technical stakeholders
### 1.2 Scope
This document describes the software architecture and detailed design for **{project_name}**. It includes:
- System architecture and design patterns
- Component specifications and interactions
- Data models and database schema
- API specifications and interfaces
- Security architecture
- Deployment and infrastructure design
### 1.3 Definitions, Acronyms, and Abbreviations
| Term | Definition |
|------|------------|
| API | Application Programming Interface |
| REST | Representational State Transfer |
| SDD | Software Design Document |
| CRUD | Create, Read, Update, Delete |
| ORM | Object-Relational Mapping |
### 1.4 References
- IEEE 1016-2009 Software Design Descriptions
- C4 Model for Visualizing Software Architecture
- Clean Architecture by Robert C. Martin
### 1.5 Overview
This document is organized as follows:
- Section 2 provides a high-level overview of the system
- Section 3 describes the architectural design
- Section 4 details the component-level design
- Sections 5-10 cover data, interfaces, security, deployment, and testing
---
"""
def _section_3_architecture(self) -> str:
"""Generate Architectural Design section."""
return """## 3. Architectural Design
### 3.1 Architectural Patterns
The system follows a **Layered Architecture** pattern with the following layers:
┌─────────────────────────────────────┐ │ Presentation Layer │ <- React SPA ├─────────────────────────────────────┤ │ Application Layer │ <- Business Logic, Use Cases ├─────────────────────────────────────┤ │ Domain Layer │ <- Domain Models, Entities ├─────────────────────────────────────┤ │ Infrastructure Layer │ <- Database, External Services └─────────────────────────────────────┘
**Key Architectural Decisions:**
1. **Layered Architecture:** Clear separation of concerns, improved maintainability
2. **Repository Pattern:** Abstract data access, enable testing
3. **Dependency Injection:** Loose coupling, improved testability
4. **Event-Driven:** Asynchronous processing, scalability
### 3.2 Component Diagram
```mermaid
graph TB
subgraph "Client"
Web[Web Application]
Mobile[Mobile App]
end
subgraph "API Gateway"
Gateway[API Gateway]
end
subgraph "Services"
Auth[Auth Service]
User[User Service]
Order[Order Service]
Payment[Payment Service]
end
subgraph "Data"
UserDB[(User DB)]
OrderDB[(Order DB)]
Cache[(Redis Cache)]
end
subgraph "External"
PaymentGW[Payment Gateway]
Email[Email Service]
end
Web --> Gateway
Mobile --> Gateway
Gateway --> Auth
Gateway --> User
Gateway --> Order
Gateway --> Payment
User --> UserDB
Order --> OrderDB
Payment --> PaymentGW
Auth --> Cache
Order --> Email
3.3 Deployment Architecture
Production Environment:
┌──────────────────────────────────────────────────┐
│ Load Balancer │
└──────────────────┬───────────────────────────────┘
│
┌──────────────┼──────────────┐
│ │ │
┌───▼───┐ ┌───▼───┐ ┌───▼───┐
│ API 1 │ │ API 2 │ │ API 3 │
└───┬───┘ └───┬───┘ └───┬───┘
│ │ │
└─────────────┼─────────────┘
│
┌─────────▼─────────┐
│ PostgreSQL │
│ (Primary) │
└─────────┬─────────┘
│
┌─────────▼─────────┐
│ PostgreSQL │
│ (Replica) │
└───────────────────┘
"""
def _section_5_data_design(self) -> str:
"""Generate Data Design section."""
return """## 5. Data Design
5.1 Database Schema
Entity Relationship Diagram:
5.2 Data Models
User Model:
from dataclasses import dataclass
from datetime import datetime
from uuid import UUID
@dataclass
class User:
id: UUID
email: str
first_name: str
last_name: str
password_hash: str
created_at: datetime
updated_at: datetime
def full_name(self) -> str:
return f"{self.first_name} {self.last_name}"
5.3 Data Flow
Order Processing Flow:
User Action → API Gateway → Order Service → Validation
↓
Create Order
↓
┌───────────┴───────────┐
│ │
Reserve Stock Process Payment
│ │
└───────────┬───────────┘
↓
Update Order Status
↓
Send Confirmation
"""
Usage
generator = SoftwareDesignDocumentGenerator("E-Commerce Platform", "1.0") sdd = generator.generate()
Save to file
with open('docs/SDD.md', 'w') as f: f.write(sdd)
print("Software Design Document generated: docs/SDD.md")
## API Specification Generator
```typescript
// tools/api-spec-generator.ts
interface APISpecification {
openapi: string;
info: {
title: string;
version: string;
description: string;
};
servers: Server[];
paths: Record<string, PathItem>;
components: Components;
}
class APISpecificationGenerator {
generate(service_name: string): APISpecification {
return {
openapi: "3.0.0",
info: {
title: `${service_name} API`,
version: "1.0.0",
description: `REST API for ${service_name}`
},
servers: [
{
url: "https://api.example.com/v1",
description: "Production server"
},
{
url: "https://staging-api.example.com/v1",
description: "Staging server"
}
],
paths: this.generatePaths(),
components: this.generateComponents()
};
}
private generatePaths(): Record<string, PathItem> {
return {
"/users": {
get: {
summary: "List all users",
operationId: "listUsers",
tags: ["users"],
parameters: [
{
name: "page",
in: "query",
schema: { type: "integer", default: 1 }
},
{
name: "limit",
in: "query",
schema: { type: "integer", default: 20 }
}
],
responses: {
"200": {
description: "Successful response",
content: {
"application/json": {
schema: {
type: "object",
properties: {
data: {
type: "array",
items: { $ref: "#/components/schemas/User" }
},
pagination: { $ref: "#/components/schemas/Pagination" }
}
}
}
}
}
}
},
post: {
summary: "Create a new user",
operationId: "createUser",
tags: ["users"],
requestBody: {
required: true,
content: {
"application/json": {
schema: { $ref: "#/components/schemas/CreateUserRequest" }
}
}
},
responses: {
"201": {
description: "User created",
content: {
"application/json": {
schema: { $ref: "#/components/schemas/User" }
}
}
}
}
}
}
};
}
private generateComponents(): Components {
return {
schemas: {
User: {
type: "object",
required: ["id", "email", "firstName", "lastName"],
properties: {
id: { type: "string", format: "uuid" },
email: { type: "string", format: "email" },
firstName: { type: "string" },
lastName: { type: "string" },
createdAt: { type: "string", format: "date-time" },
updatedAt: { type: "string", format: "date-time" }
}
},
CreateUserRequest: {
type: "object",
required: ["email", "password", "firstName", "lastName"],
properties: {
email: { type: "string", format: "email" },
password: { type: "string", minLength: 8 },
firstName: { type: "string" },
lastName: { type: "string" }
}
},
Pagination: {
type: "object",
properties: {
page: { type: "integer" },
limit: { type: "integer" },
total: { type: "integer" },
totalPages: { type: "integer" }
}
}
},
securitySchemes: {
bearerAuth: {
type: "http",
scheme: "bearer",
bearerFormat: "JWT"
}
}
};
}
}
Requirements Documentation
# scripts/requirements_doc.py
from typing import List
from dataclasses import dataclass
@dataclass
class Requirement:
"""Single system requirement."""
id: str
type: str # Functional, Non-Functional
priority: str # Must, Should, Could, Won't
description: str
acceptance_criteria: List[str]
class RequirementsDocument:
"""Generate requirements documentation."""
def __init__(self, project_name: str):
self.project_name = project_name
self.functional: List[Requirement] = []
self.non_functional: List[Requirement] = []
def add_functional(self, req: Requirement):
"""Add functional requirement."""
self.functional.append(req)
def add_non_functional(self, req: Requirement):
"""Add non-functional requirement."""
self.non_functional.append(req)
def generate(self) -> str:
"""Generate requirements document."""
doc = f"# Requirements Specification\n## {self.project_name}\n\n"
doc += "## Functional Requirements\n\n"
for req in self.functional:
doc += f"### {req.id}: {req.description}\n\n"
doc += f"**Priority:** {req.priority}\n\n"
doc += "**Acceptance Criteria:**\n"
for criterion in req.acceptance_criteria:
doc += f"- {criterion}\n"
doc += "\n"
doc += "## Non-Functional Requirements\n\n"
for req in self.non_functional:
doc += f"### {req.id}: {req.description}\n\n"
doc += f"**Priority:** {req.priority}\n\n"
doc += "**Acceptance Criteria:**\n"
for criterion in req.acceptance_criteria:
doc += f"- {criterion}\n"
doc += "\n"
return doc
# Usage
requirements = RequirementsDocument("E-Commerce Platform")
requirements.add_functional(Requirement(
id="FR-001",
type="Functional",
priority="Must",
description="User Registration",
acceptance_criteria=[
"Users can register with email and password",
"Email validation is performed",
"Password must meet complexity requirements (8+ chars, uppercase, lowercase, number)",
"Confirmation email is sent after registration"
]
))
requirements.add_non_functional(Requirement(
id="NFR-001",
type="Non-Functional",
priority="Must",
description="Performance - Response Time",
acceptance_criteria=[
"API response time < 200ms for 95th percentile",
"Page load time < 2 seconds",
"Database query time < 100ms"
]
))
print(requirements.generate())
Usage Examples
Generate Complete SDD
Apply software-design-document-patterns skill to generate comprehensive Software Design Document with all sections
Generate API Specification
Apply software-design-document-patterns skill to create OpenAPI 3.0 specification for REST API
Document Requirements
Apply software-design-document-patterns skill to document functional and non-functional requirements with acceptance criteria
Integration Points
- software-design-patterns - Design patterns and C4 diagrams
- code-documentation-patterns - API documentation and code examples
- documentation-quality - Quality validation and standards
Success Output
When successful, this skill MUST output:
✅ SKILL COMPLETE: software-design-document-patterns
Completed:
- [x] SDD template generated with all 10 sections
- [x] Architecture diagrams created (component, deployment, data flow)
- [x] API specification generated (OpenAPI 3.0)
- [x] Requirements documented (functional + non-functional)
- [x] Database schema with ERD documented
Outputs:
- docs/SDD.md (complete Software Design Document)
- docs/api-spec.yaml (OpenAPI specification)
- docs/requirements.md (requirements specification)
- docs/architecture/component-diagram.mmd (Mermaid)
- docs/architecture/erd.mmd (Entity Relationship Diagram)
Sections Complete: 10/10
- 1. Introduction ✓
- 2. System Overview ✓
- 3. Architectural Design ✓
- 4. Detailed Design ✓
- 5. Data Design ✓
- 6. Interface Design ✓
- 7. Security Design ✓
- 8. Deployment Design ✓
- 9. Testing Strategy ✓
- 10. Appendices ✓
Completion Checklist
Before marking this skill as complete, verify:
- SDD document includes all 10 sections (no placeholders)
- Table of contents generated with working links
- System architecture diagram present (layered/microservices/etc.)
- Component diagram shows major components and relationships
- Deployment diagram shows infrastructure and scaling
- Database ERD shows all entities and relationships
- Data models defined with types and validation rules
- API specification includes all endpoints (GET/POST/PUT/DELETE)
- Functional requirements have acceptance criteria
- Non-functional requirements quantified (response time <200ms, etc.)
- Security section covers auth, authz, data protection
- Testing strategy includes unit, integration, E2E
Failure Indicators
This skill has FAILED if:
- ❌ SDD missing required sections (incomplete template)
- ❌ Architecture diagrams not rendering (syntax errors in Mermaid)
- ❌ API specification invalid (fails OpenAPI validation)
- ❌ Requirements lack acceptance criteria
- ❌ ERD missing foreign key relationships
- ❌ No quantifiable metrics in non-functional requirements
- ❌ Deployment diagram doesn't match actual infrastructure
- ❌ Security section generic/boilerplate (not project-specific)
When NOT to Use
Do NOT use this skill when:
- Project in early prototype/spike phase (premature documentation)
- Simple CRUD app with no architectural complexity (overkill)
- Design still highly volatile (document will be outdated immediately)
- Agile team prefers lightweight documentation (use ADRs instead)
- Existing SDD just needs updates (use targeted editing, not regeneration)
- Time-sensitive delivery (defer comprehensive SDD to post-launch)
Use alternatives:
- adr-decision-workflow - For lightweight architectural decisions
- api-first-design - For API-only documentation
- readme-driven-development - For simple project documentation
- architecture-sketch - For quick architecture diagrams only
Anti-Patterns (Avoid)
| Anti-Pattern | Problem | Solution |
|---|---|---|
| Copy-paste from template | Generic SDD, no project specifics | Customize every section with actual design |
| Outdated diagrams | Diagrams don't match implementation | Generate diagrams from code where possible |
| No versioning | Can't track design evolution | Include version, date, and changelog |
| Missing decisions rationale | Team doesn't understand "why" | Document decision drivers and alternatives |
| Over-specification | Design too rigid, prevents iteration | Balance detail with flexibility |
| No audience adaptation | Same SDD for devs and executives | Create targeted views (technical vs executive summary) |
| Diagrams without legends | Ambiguous symbols/colors | Always include diagram keys and notations |
| Requirements without priority | Everything is "must have" | Use MoSCoW (Must/Should/Could/Won't) prioritization |
Principles
This skill embodies:
- #1 Search Before Create - Uses IEEE 1016-2009 and C4 model standards
- #2 First Principles - Architecture derived from fundamental requirements
- #5 Eliminate Ambiguity - Precise specifications with diagrams and examples
- #6 Clear, Understandable, Explainable - Progressive disclosure (overview → detail)
- #8 No Assumptions - Explicit documentation of constraints and decisions
- Separation of Concerns - Layered documentation (system → component → implementation)
- Single Source of Truth - SDD as authoritative design reference
Standard: CODITECT-STANDARD-AUTOMATION.md
Version: 1.1.0 | Updated: 2026-01-04 | Quality Standard Applied