AGENT SKILL

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.

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

01 前言 Front Matter

name
sdd-architect
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
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.

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 1 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.


🌐 System Boundary, Network Topology & Infrastructure Architecture Law

[!IMPORTANT] Mandatory Network Topology, CORS & DevOps Containerization Specifications: In addition to Domain Models and Business Services, dev-architech MUST explicitly author a dedicated Network Topology & Infrastructure Blueprint section in docs/sdd.md:

  1. System Boundary & Network Topology: Mermaid diagram depicting Client Browser, Reverse Proxy / Ingress (Nginx), Application Server (FastAPI / Uvicorn), Database (PostgreSQL 16), and Background Schedulers.
  2. Cross-Origin Resource Sharing (CORS) Specification: Explicit specification of CORS policy, configurable via CORS_ORIGINS environment variable, including allow_origins, allow_credentials, allow_methods, and allow_headers.
  3. Gateway & Routing Contracts: Standard path prefix (/api/v1), trailing slash rules, and reverse proxy forwarding headers (X-Forwarded-For, X-Forwarded-Proto, Host).
  4. DevOps Multi-Container Topology: Complete blueprint for dev-ops containerization in Phase 5, defining container service names, internal network bridges, exposed host ports, volume persistence mounts, Required Environment Variables Specification (categorized by Backend, Frontend, and Database container), and container healthchecks.

⚖️ SDD Service Contract Law

[!IMPORTANT] Explicit Business Service Layer & Domain Exception Contracts: In Phase 1 SDD authoring, dev-architech MUST explicitly specify:

  1. Domain Business Service Layer: Full class definitions, method signatures (async def method_name(...) -> ReturnType), exact parameter types, and return models.
  2. Domain Exception Hierarchy: Explicit domain Exception classes (e.g. MeetingNotFoundError, DuplicateTranscriptError, InvalidMeetingStateError) with their HTTP status mappings and error codes.
  3. Repository Interfaces: Data access contracts and async session boundaries. This provides an unambiguous blueprint so that dev-backend and dev-tester never guess or diverge on method contracts.

🛠️ 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 & Domain Services

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: Explicit Business Service classes, typed method signatures, domain exception raises, business logic workflows.
  • 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 -> API Endpoints -> Database Models -> Service Functions -> Frontend Views -> 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" && git push origin main.
  4. Call kanban_complete() to notify PM.

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