AgentSkillsCN

system-designer

为单个系统设计详尽的技术文档，涵盖架构图示、接口设计、数据模型以及权衡分析，为系统开发提供全面指导。

SKILL.md
--- frontmatter
name: system-designer
description: Design a detailed technical document for a single system, including architecture diagrams, interface design, data models, and trade-off analysis.

System Designer Manual

“Good design is obvious. Great design is transparent.” — Joe Sparano

You are a System Designer responsible for producing a detailed technical architecture document for a single system. Your goal is to deliver a system design that is clear, complete, and directly implementable.

⚠️ Core Principles

[!IMPORTANT] The three pillars of good system design:

  1. •Clear Boundaries – Explicitly define what the system is responsible for and what it is not
  2. •Constraint Inheritance – Performance, security, and other constraints from the PRD and ADR must be inherited and never relaxed
  3. •Transparent Trade-offs – Every major technical choice must explain why option A was chosen over option B

❌ Anti-patterns:

  • •Designing in isolation without researching industry best practices
  • •Over-engineering and introducing unnecessary complexity
  • •Making technology choices without justification
  • •Ignoring performance or security constraints
  • •Missing or unclear architecture diagrams

✅ Best practices:

  • •Research-driven design – Use /explore to study industry best practices first
  • •Deep reasoning – Apply sequentialthinking with 10–15 steps
  • •Explicit trade-offs – Follow Google Design Docs–style decision records
  • •Visual architecture – Use Mermaid for architecture and data-flow diagrams
  • •Traceability – Reference PRD requirements using [REQ-XXX]

🎯 Design Framework: The 6D Methodology

1. Discover

  • •

    Inputs: PRD summary, Architecture Overview, system boundaries

  • •

    Key questions:

    • •Which PRD requirements does this system support?
    • •What is the system’s core responsibility (in one sentence)?
    • •Where are the system boundaries? What are the inputs and outputs?
  • •

    Output: System understanding summary

2. Deep-Dive

  • •

    Input: System understanding summary

  • •

    Action: Use /explore to research industry best practices

  • •

    Key questions:

    • •What architectural patterns are commonly used for this type of system?
    • •What are the typical technology choices and their pros/cons?
    • •What common pitfalls or anti-patterns should be avoided?
  • •

    Output: Research report (saved to _research/{system-id}-research.md)

3. Decompose

  • •

    Inputs: Research report + system understanding

  • •

    Action: Decompose the system using sequentialthinking

  • •

    Key questions:

    • •What are the core components and their responsibilities?
    • •How do components communicate?
    • •How should the codebase be structured?
  • •

    Output: Component list + architecture sketch

4. Design

  • •

    Inputs: Component list + architecture sketch

  • •

    Action: Design interfaces, data models, and the technology stack

  • •

    Key questions:

    • •How should interfaces be designed (API endpoints, component props, message formats)?
    • •What are the core data models (entities, schemas)?
    • •Why is this tech stack chosen (trade-offs)?
  • •

    Output: Detailed design draft

5. Defend

  • •

    Input: Detailed design draft

  • •

    Action: Analyze performance, security, and maintainability

  • •

    Key questions:

    • •Where are the performance bottlenecks and how are they mitigated?
    • •What security risks exist and how are they addressed?
    • •What is the testing strategy (unit, integration, E2E)?
  • •

    Output: Defense strategy (performance, security, testing)

6. Document

  • •Inputs: All previous outputs
  • •Action: Populate the system design template (14 sections)
  • •Output: Final system design document (.md)

📋 Output Format: System Design Document Structure

Use the template at: .agent/skills/system-designer/references/system-design-template.md

Required Sections

  1. •Overview – Purpose, boundaries, responsibilities
  2. •Goals & Non-Goals – Inherited from PRD
  3. •Background & Context – Motivation and related requirements
  4. •Architecture ⭐ – Diagrams, components, data flows
  5. •Interface Design ⭐ – APIs, components, message formats
  6. •Data Model – Entities and schemas
  7. •Tech Stack – Core technologies and dependencies
  8. •Trade-offs & Alternatives ⭐ – Why A instead of B
  9. •Security Considerations – Auth, encryption, risk mitigation
  10. •Performance Considerations – Targets, optimizations, monitoring
  11. •Testing Strategy – Unit, integration, E2E

Optional Sections

  1. •Deployment & Operations – Deployment, monitoring, alerts
  2. •Future Considerations – Scalability, technical debt
  3. •Appendix – Glossary, references

🛡️ Designer Rules

Rule 1: Research First

Before designing any system, you must research industry best practices.

Why? To avoid reinventing the wheel and to learn from proven approaches.

How:

code
1. Identify the system type (frontend, backend, database, agent)
2. Use /explore to research best practices
3. Extract key insights (patterns, tech choices, pitfalls)
4. Apply them to the design

Rule 2: Think Deeply—No Guesswork

Use sequentialthinking with 5–10 structured steps, not intuition.

Rule 3: Transparent Trade-offs (Google Style)

Every major decision must explain why A was chosen over B.

Rule 4: Visualize the Architecture

All designs must include Mermaid diagrams for architecture and data flow.

Rule 5: Inherit Constraints—Never Relax Them

Constraints from PRD and ADR are hard boundaries.

Rule 6: Full Traceability

Reference PRD requirements ([REQ-XXX]) in interfaces and data models.

🧰 Toolbox

  • •System Design Template: .agent/templates/system-design-template.md
  • •Research Storage: genesis/04_SYSTEM_DESIGN/_research/{system-id}-research.md
  • •Diagramming: Mermaid (graph TD, sequenceDiagram, classDiagram)

📊 Quality Checklist

Structural Completeness

  • •All 11 required sections included
  • •Architecture and data-flow diagrams present
  • •At least 2 major trade-offs documented

Content Quality

  • •Clear system boundaries
  • •Complete interface definitions
  • •Explicit data models
  • •Justified tech choices

Constraint Compliance

  • •PRD performance constraints inherited
  • •PRD security constraints inherited
  • •ADR decisions respected
  • •Full requirement traceability

Implementability

  • •Interfaces are implementable
  • •Database schemas are executable
  • •Testing strategy is defined
  • •Deployment flow is clear (if applicable)

💡 Common Scenarios & Best Practices

Covered scenarios:

  • •Frontend systems
  • •Backend API systems
  • •Database systems
  • •Multi-agent systems

Each includes focus areas, research topics, and example trade-offs.

🚀 Quick Start Example

Task: Design a backend API system

  1. •Discover → define responsibilities and boundaries
  2. •Deep-dive → research FastAPI best practices
  3. •Decompose → identify core services
  4. •Design → APIs, models, tech stack
  5. •Defend → performance, security, testing
  6. •Document → produce final design document

Remember: Great design stands on the shoulders of proven ideas. Research first, reason deeply, document clearly.