AGENT SKILL

system-design

Produce a professional Software Design Description (SDD) compliant with IEEE 1016 standard, with strict requirement traceability, locked tech stack adherence, database ERD/DDL, OpenAPI specifications, and layered architecture design.

License 许可
MIT
最近更新
2026-09-15
Stars
★ 0
Forks
0

01 前言 Front Matter

name
system-design
author
Hermes Agent Team
license
MIT
version
2.0.0
metadata
{ "hermes": { "tags": [ "architecture", "sdd", "ieee-1016", "system-design", "database", "erd", "openapi", "adr" ], "related_skills": [ "srs-specifier", "test-planner", "delegate-software-engineering-team" ] } }
platforms
[ "linux", "macos", "windows" ]
description
Produce a professional Software Design Description (SDD) compliant with IEEE 1016 standard, with strict requirement traceability, locked tech stack adherence, database ERD/DDL, OpenAPI specifications, and layered architecture design.

03 SKILL.md 正文

Software Design Description (SDD) Skill (IEEE 1016)

Overview

Produce a comprehensive Software Design Description (SDD) document that translates requirements from docs/srs.md into concrete, implementable software blueprints.

Standards Compliance

  • IEEE 1016-2009: IEEE Standard for Information Technology — Systems Design — Software Design Descriptions.

When to Use

  • Phase 3 Architecture Design (dispatched by dev-pm to dev-architech).
  • Mid-development Tier 2 architectural revisions when database schema or cross-module boundaries change.
  • Replaces legacy lightweight system_design.md with an IEEE 1016 compliant specification.

Target Output Path

/opt/data/workspace/{project_name}/docs/sdd.md
/opt/data/workspace/{project_name}/docs/adr/ADR-XXX-{title}.md (for major architectural decisions)


🔒 Ironclad Tech Stack Adherence Rule

[!CAUTION] Strict Compliance with docs/srs.md Section 3: dev-architech MUST read docs/srs.md first. The architectural design MUST 100% follow the exact language, framework, database engine, and ORM specified in docs/srs.md Section 3. DO NOT switch tech stacks (e.g. never substitute TypeScript/Express for Python/FastAPI or vice-versa) unless explicitly authorized by the user via an approved ADR.


🛠️ Step-by-Step Procedure

Step 1: Ingest SRS Specification

  1. Read /opt/data/workspace/{project_name}/docs/srs.md.
  2. Extract all Use Cases (UC-001 ~ UC-NNN), Technical Constraints (TC), and Non-Functional Requirements (NFR).

Step 2: Design Layered Software Architecture

Establish a clean separation of concerns:

  • Presentation Layer (Frontend): React Components, Custom Hooks, Zustand/Context Stores, Axios/Fetch API Clients.
  • Interface Layer (Routers / Controllers): FastAPI APIRouter, request validation via Pydantic schemas, HTTP status mapping, dependency injection (DB sessions, current user).
  • Domain & Service Layer: Business logic, workflow validation, domain events, transaction orchestration.
  • Data Access Layer (Persistence & Repositories): SQLAlchemy 2.0 Async declarative models, async queries, transaction boundaries.

Step 3: Complete Data Architecture & ERD / DDL

  1. Provide a Mermaid ERD diagram showing all entities, cardinality (1:1, 1:N, N:M), foreign keys, and cascading rules.
  2. Provide complete, copy-paste ready SQL DDL statements for all tables with exact data types, constraints, default values, and indexes.

Step 4: Interface & API Specification (OpenAPI 3.0 Standard)

For every API endpoint:

  1. HTTP Method and Route Path (e.g. POST /api/v1/meetings).
  2. Authentication & Authorization requirements (e.g. Bearer JWT, required role).
  3. Request Headers, Query Parameters, Path Parameters.
  4. Request Body JSON schema with data types and validation rules.
  5. Response Body JSON schemas for HTTP 200/201 (Success) and HTTP 400/401/403/404/422/500 (Error).

Step 5: Requirement Traceability Matrix (RTM)

Construct an exhaustive bidirectional Traceability Matrix mapping: SRS Use Case ID $\rightarrow$ API Endpoints $\rightarrow$ Database Models $\rightarrow$ Service Functions $\rightarrow$ Frontend Views $\rightarrow$ Test Cases.

Step 6: Security & Cross-Cutting Architecture

  1. JWT lifecycle (Issuance, Expiration, Claims: sub, email, role, exp).
  2. Password hashing configuration (bcrypt with work factor 12).
  3. Global Exception Handler & Standard Error Response Envelope.
  4. CORS middleware configuration and allowed origins/methods.

Step 7: Output SDD & Report

  1. Write /opt/data/workspace/{project_name}/docs/sdd.md.
  2. If major architectural trade-offs occurred, write /opt/data/workspace/{project_name}/docs/adr/ADR-001-{title}.md.
  3. Commit and push to git: git add docs/ && git commit -m "docs(architecture): IEEE 1016 SDD specification (refs #{issue})" && git push origin main.
  4. Call kanban_complete() to notify PM.

📄 SDD Document Template Structure

# Software Design Description (SDD)
## Project: {Project Name}
**Standard**: IEEE 1016-2009  
**Version**: 1.0.0  
**Status**: Baseline  
**SRS Reference**: `docs/srs.md` (v1.0.0)  

---

## 1. System Overview & Architectural Style
### 1.1 Architectural Pattern
- **Style**: Layered Clean Architecture (Client-Server over REST API)
- **Frontend Architecture**: SPA with React, TypeScript, Component-Driven Design.
- **Backend Architecture**: Layered Modular Architecture (Routers -> Services -> Repositories/Models).

### 1.2 System Topology Diagram
```mermaid
graph TD
    Client[React Frontend / Browser] -->|HTTP REST / JSON| Gateway[FastAPI Backend Application]
    Gateway --> Router[API Routers / Controllers]
    Router --> Service[Domain Business Services]
    Service --> Repo[Data Access / Repositories]
    Repo --> DB[(PostgreSQL 16 Database)]

2. Requirement Traceability Matrix (RTM)

SRS UC ID Description API Endpoint(s) Database Tables Backend Service / Model Frontend Component Test Suite Ref
UC-001 User Registration POST /api/v1/auth/register users AuthService.register / User RegisterPage, AuthForm tests/unit/test_auth.py
UC-002 User Login POST /api/v1/auth/login users AuthService.login / User LoginPage tests/unit/test_auth.py

3. Data Architecture & Database Design

3.1 Entity Relationship Diagram (ERD)

erDiagram
    USERS ||--o{ MEETINGS : creates
    MEETINGS ||--o{ MINUTES : contains
    MEETINGS ||--o{ ACTION_ITEMS : assigns
    
    USERS {
        uuid id PK
        string email UK
        string hashed_password
        string full_name
        string role
        timestamp created_at
    }

3.2 SQL DDL Schema

CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    email VARCHAR(255) UNIQUE NOT NULL,
    hashed_password VARCHAR(255) NOT NULL,
    full_name VARCHAR(100) NOT NULL,
    role VARCHAR(50) NOT NULL DEFAULT 'member',
    is_active BOOLEAN NOT NULL DEFAULT TRUE,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_users_email ON users(email);

4. API & Interface Specifications

4.1 Authentication & Base URL

  • Base URL: /api/v1
  • Security Scheme: Authorization: Bearer <JWT_TOKEN>

4.2 Endpoint Specifications

POST /api/v1/auth/register

  • Description: Registers a new user account.
  • Request Body:
    {
      "email": "user@example.com",
      "password": "SecurePassword123!",
      "full_name": "Roy Shao"
    }
    
  • Responses:
    • 201 Created: {"id": "uuid", "email": "user@example.com", "full_name": "Roy Shao"}
    • 400 Bad Request: {"detail": "Email already registered", "code": "EMAIL_EXISTS"}
    • 422 Unprocessable Entity: Field validation error.

5. Security & Session Architecture

  1. Password Hashing: Passlib bcrypt context with rounds=12.
  2. JWT Issuance: jwt.encode({"sub": str(user.id), "email": user.email, "role": user.role, "exp": ...}, SECRET_KEY, algorithm="HS256").
  3. CORS Configuration: Allowed origins configured via CORS_ORIGINS environment variable.

6. Architecture Decision Records (ADRs)

  • docs/adr/ADR-001-postgresql-async-orm.md
  • docs/adr/ADR-002-jwt-stateless-authentication.md

04 同仓库更多 Skills

roychshao
roychshao/hermes-multi-agent-sdlc

srs-specifier

Generate professional Software Requirements Specification (SRS) compliant with ISO/IEC/IEEE 29148 and IEEE 830 standards, focusing purely on requirements (WHAT the system does) with granular use-case decomposition, high-level technology constraints, non-functional requirements, and strict exclusion of design details (no API routes, no ERD/DDL, no response envelopes).

★ 0
roychshao
roychshao/hermes-multi-agent-sdlc

test-planner

Author comprehensive Test Plan specifications compliant with ISO/IEC/IEEE 29119-3 standard (superseding IEEE 829) and E2E Testing Patterns, establishing testing pyramid ratios, fixture strategies, boundary edge cases, headless containerized E2E acceptance suites, and triple-gate quality metrics.

★ 0
roychshao
roychshao/hermes-multi-agent-sdlc

writing-plans

Write a markdown plan to .hermes/plans/; no execution.

★ 0
roychshao
roychshao/hermes-multi-agent-sdlc

system-design

Produce a comprehensive system design document for a software project.

★ 0
roychshao
roychshao/hermes-multi-agent-sdlc

srs-specifier

Generate professional Software Requirements Specification (SRS) compliant with ISO/IEC/IEEE 29148 and IEEE 830 standards, focusing purely on requirements (WHAT the system does) with granular use-case decomposition, high-level technology constraints, non-functional requirements, and strict exclusion of design details (no API routes, no ERD/DDL, no response envelopes).

★ 0
roychshao
roychshao/hermes-multi-agent-sdlc

sdd-architect

Author comprehensive Software Design Description (SDD) specifications compliant with IEEE 1016-2009 standard, translating SRS requirements into layered clean architectures, explicit Business Service method signatures, domain exceptions, ERDs, REST APIs, and ADRs.

★ 0