C4 Architecture

作者 softaworks3027f20f3181无许可证2.5K 个星标收录于 2026年10月8日更新于 2026年10月8日仓库7个月前更新

Generate architecture documentation using C4 model Mermaid diagrams. Use when asked to create architecture diagrams, document system architecture, visualize software structure, create C4 diagrams, or generate context/container/component/deployment diagrams. Triggers include "architecture diagram", "C4 diagram", "system context", "container diagram", "component diagram", "deployment diagram", "document architecture", "visualize architecture".

仅含说明Software DevelopmentDocuments & Office
AI 生成的概览

使用 Mermaid 图生成 C4 模型架构文档。

功能
该技能指导智能体使用 Mermaid 语法编写 C4 模型图，从而产出软件架构文档。内容涵盖上下文、容器、组件、动态和部署等图级别，并提供元素、关系、边界与样式语法参考。输出以固定命名约定写入 docs/architecture/ 下的 markdown 文件。
适用场景
当被要求创建架构图、记录系统架构、可视化软件结构，或生成上下文图、容器图、组件图、部署图时使用。适合需要面向不同受众的架构文档的团队。
运行要求
无需脚本，仅包含说明与参考 markdown 文件。智能体需要能够读取代码库并将 markdown 文件写入 docs/architecture/。

C4 Architecture Documentation

Generate software architecture documentation using C4 model diagrams in Mermaid syntax.

Workflow

  1. Understand scope - Determine which C4 level(s) are needed based on audience
  2. Analyze codebase - Explore the system to identify components, containers, and relationships
  3. Generate diagrams - Create Mermaid C4 diagrams at appropriate abstraction levels
  4. Document - Write diagrams to markdown files with explanatory context

C4 Diagram Levels

Select the appropriate level based on the documentation need:

LevelDiagram TypeAudienceShowsWhen to Create
1C4ContextEveryoneSystem + external actorsAlways (required)
2C4ContainerTechnicalApps, databases, servicesAlways (required)
3C4ComponentDevelopersInternal componentsOnly if adds value
4C4DeploymentDevOpsInfrastructure nodesFor production systems
-C4DynamicTechnicalRequest flows (numbered)For complex workflows

Key Insight: "Context + Container diagrams are sufficient for most software development teams." Only create Component/Code diagrams when they genuinely add value.

Quick Start Examples

System Context (Level 1)

mermaid
C4Context  title System Context - Workout Tracker
  Person(user, "User", "Tracks workouts and exercises")  System(app, "Workout Tracker", "Vue PWA for tracking strength and CrossFit workouts")  System_Ext(browser, "Web Browser", "Stores data in IndexedDB")
  Rel(user, app, "Uses")  Rel(app, browser, "Persists data to", "IndexedDB")

Container Diagram (Level 2)

mermaid
C4Container  title Container Diagram - Workout Tracker
  Person(user, "User", "Tracks workouts")
  Container_Boundary(app, "Workout Tracker PWA") {    Container(spa, "SPA", "Vue 3, TypeScript", "Single-page application")    Container(pinia, "State Management", "Pinia", "Manages application state")    ContainerDb(indexeddb, "IndexedDB", "Dexie", "Local workout storage")  }
  Rel(user, spa, "Uses")  Rel(spa, pinia, "Reads/writes state")  Rel(pinia, indexeddb, "Persists", "Dexie ORM")

Component Diagram (Level 3)

mermaid
C4Component  title Component Diagram - Workout Feature
  Container(views, "Views", "Vue Router pages")
  Container_Boundary(workout, "Workout Feature") {    Component(useWorkout, "useWorkout", "Composable", "Workout execution state")    Component(useTimer, "useTimer", "Composable", "Timer state machine")    Component(workoutRepo, "WorkoutRepository", "Dexie", "Workout persistence")  }
  Rel(views, useWorkout, "Uses")  Rel(useWorkout, useTimer, "Controls")  Rel(useWorkout, workoutRepo, "Saves to")

Dynamic Diagram (Request Flow)

mermaid
C4Dynamic  title Dynamic Diagram - User Sign In Flow
  ContainerDb(db, "Database", "PostgreSQL", "User credentials")  Container(spa, "Single-Page App", "React", "Banking UI")
  Container_Boundary(api, "API Application") {    Component(signIn, "Sign In Controller", "Express", "Auth endpoint")    Component(security, "Security Service", "JWT", "Validates credentials")  }
  Rel(spa, signIn, "1. Submit credentials", "JSON/HTTPS")  Rel(signIn, security, "2. Validate")  Rel(security, db, "3. Query user", "SQL")
  UpdateRelStyle(spa, signIn, $textColor="blue", $offsetY="-30")

Deployment Diagram

mermaid
C4Deployment  title Deployment Diagram - Production
  Deployment_Node(browser, "Customer Browser", "Chrome/Firefox") {    Container(spa, "SPA", "React", "Web application")  }
  Deployment_Node(aws, "AWS Cloud", "us-east-1") {    Deployment_Node(ecs, "ECS Cluster", "Fargate") {      Container(api, "API Service", "Node.js", "REST API")    }    Deployment_Node(rds, "RDS", "db.r5.large") {      ContainerDb(db, "Database", "PostgreSQL", "Application data")    }  }
  Rel(spa, api, "API calls", "HTTPS")  Rel(api, db, "Reads/writes", "JDBC")

Element Syntax

People and Systems

Person(alias, "Label", "Description")Person_Ext(alias, "Label", "Description")       # External personSystem(alias, "Label", "Description")System_Ext(alias, "Label", "Description")       # External systemSystemDb(alias, "Label", "Description")         # Database systemSystemQueue(alias, "Label", "Description")      # Queue system

Containers

Container(alias, "Label", "Technology", "Description")Container_Ext(alias, "Label", "Technology", "Description")ContainerDb(alias, "Label", "Technology", "Description")ContainerQueue(alias, "Label", "Technology", "Description")

Components

Component(alias, "Label", "Technology", "Description")Component_Ext(alias, "Label", "Technology", "Description")ComponentDb(alias, "Label", "Technology", "Description")

Boundaries

Enterprise_Boundary(alias, "Label") { ... }System_Boundary(alias, "Label") { ... }Container_Boundary(alias, "Label") { ... }Boundary(alias, "Label", "type") { ... }

Relationships

Rel(from, to, "Label")Rel(from, to, "Label", "Technology")BiRel(from, to, "Label")                        # BidirectionalRel_U(from, to, "Label")                        # UpwardRel_D(from, to, "Label")                        # DownwardRel_L(from, to, "Label")                        # LeftwardRel_R(from, to, "Label")                        # Rightward

Deployment Nodes

Deployment_Node(alias, "Label", "Type", "Description") { ... }Node(alias, "Label", "Type", "Description") { ... }  # Shorthand

Styling and Layout

Layout Configuration

UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
  • $c4ShapeInRow - Number of shapes per row (default: 4)
  • $c4BoundaryInRow - Number of boundaries per row (default: 2)

Element Styling

UpdateElementStyle(alias, $fontColor="red", $bgColor="grey", $borderColor="red")

Relationship Styling

UpdateRelStyle(from, to, $textColor="blue", $lineColor="blue", $offsetX="5", $offsetY="-10")

Use $offsetX and $offsetY to fix overlapping relationship labels.

Best Practices

Essential Rules

  1. Every element must have: Name, Type, Technology (where applicable), and Description
  2. Use unidirectional arrows only - Bidirectional arrows create ambiguity
  3. Label arrows with action verbs - "Sends email using", "Reads from", not just "uses"
  4. Include technology labels - "JSON/HTTPS", "JDBC", "gRPC"
  5. Stay under 20 elements per diagram - Split complex systems into multiple diagrams

Clarity Guidelines

  1. Start at Level 1 - Context diagrams help frame the system scope
  2. One diagram per file - Keep diagrams focused on a single abstraction level
  3. Meaningful aliases - Use descriptive aliases (e.g., orderService not s1)
  4. Concise descriptions - Keep descriptions under 50 characters when possible
  5. Always include a title - "System Context diagram for [System Name]"

What to Avoid

See references/common-mistakes.md [blocked] for detailed anti-patterns:

  • Confusing containers (deployable) vs components (non-deployable)
  • Modeling shared libraries as containers
  • Showing message brokers as single containers instead of individual topics
  • Adding undefined abstraction levels like "subcomponents"
  • Removing type labels to "simplify" diagrams

Microservices Guidelines

Single Team Ownership

Model each microservice as a container (or container group):

mermaid
C4Container  title Microservices - Single Team
  System_Boundary(platform, "E-commerce Platform") {    Container(orderApi, "Order Service", "Spring Boot", "Order processing")    ContainerDb(orderDb, "Order DB", "PostgreSQL", "Order data")    Container(inventoryApi, "Inventory Service", "Node.js", "Stock management")    ContainerDb(inventoryDb, "Inventory DB", "MongoDB", "Stock data")  }

Multi-Team Ownership

Promote microservices to software systems when owned by separate teams:

mermaid
C4Context  title Microservices - Multi-Team
  Person(customer, "Customer", "Places orders")  System(orderSystem, "Order System", "Team Alpha")  System(inventorySystem, "Inventory System", "Team Beta")  System(paymentSystem, "Payment System", "Team Gamma")
  Rel(customer, orderSystem, "Places orders")  Rel(orderSystem, inventorySystem, "Checks stock")  Rel(orderSystem, paymentSystem, "Processes payment")

Event-Driven Architecture

Show individual topics/queues as containers, NOT a single "Kafka" box:

mermaid
C4Container  title Event-Driven Architecture
  Container(orderService, "Order Service", "Java", "Creates orders")  Container(stockService, "Stock Service", "Java", "Manages inventory")  ContainerQueue(orderTopic, "order.created", "Kafka", "Order events")  ContainerQueue(stockTopic, "stock.reserved", "Kafka", "Stock events")
  Rel(orderService, orderTopic, "Publishes to")  Rel(stockService, orderTopic, "Subscribes to")  Rel(stockService, stockTopic, "Publishes to")  Rel(orderService, stockTopic, "Subscribes to")

Output Location

Write architecture documentation to docs/architecture/ with naming convention:

  • c4-context.md - System context diagram
  • c4-containers.md - Container diagram
  • c4-components-{feature}.md - Component diagrams per feature
  • c4-deployment.md - Deployment diagram
  • c4-dynamic-{flow}.md - Dynamic diagrams for specific flows

Audience-Appropriate Detail

AudienceRecommended Diagrams
ExecutivesSystem Context only
Product ManagersContext + Container
ArchitectsContext + Container + key Components
DevelopersAll levels as needed
DevOpsContainer + Deployment

References

  • references/c4-syntax.md [blocked] - Complete Mermaid C4 syntax
  • references/common-mistakes.md [blocked] - Anti-patterns to avoid
  • references/advanced-patterns.md [blocked] - Microservices, event-driven, deployment

来源与署名

来源：softaworks/agent-toolkit位于skills/c4-architecture提交3027f20

许可证： 无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

更多来自 softaworks/agent-toolkit 的技能

Writing Clearly And Concisely

softaworks

运用 Strunk《风格的要素》规则和 AI 写作模式清单，让面向人类的文字更清晰、更简洁。

Writing & Content2.5K7个月前更新

Web To Markdown

softaworks

使用本地安装的 web2md 命令行工具（Puppeteer 与 Readability）将网页 URL 转换为干净的 Markdown。

Productivity & Workflow2.5K7个月前更新

Skill Judge

softaworks

依据官方规范与最佳实践评估 Agent Skill 的设计质量，提供多维度评分与改进建议。

AI & Agents2.5K7个月前更新

Ship Learn Next

softaworks

把课程、文章等学习内容转化为 Ship-Learn-Next 行动计划，包含可交付的每周迭代。

Learning & Education2.5K7个月前更新

Reducing Entropy

softaworks

引导智能体以删除为优先，通过衡量最终代码量来最小化代码库总规模。

Software Development2.5K7个月前更新

Qa Test Planner

softaworks

生成 QA 测试计划、手工测试用例、回归测试套件、Figma 设计校验和缺陷报告。

包含脚本
Software Development2.5K7个月前更新

更多Software Development技能

Playground

anthropics

精选

构建自包含的交互式 HTML 演练场，包含控件、实时预览和可复制的提示词输出。

Software Development37K今天更新

M5 Onboard

anthropics

精选

通过 USB 检测 M5Stack ESP32 开发板，刷写 UIFlow 2.0 固件并安装 MicroPython 应用包。

Software Development37K今天更新

Cardputer Buddy

anthropics

精选

指导迭代 Cardputer-Adv 的 MicroPython 应用包：添加应用、通过 USB 串口推送文件、查看日志并运行 REPL 命令。

Software Development37K今天更新

Web Design Guidelines

vercel-labs

精选

依据从远程来源获取的 Web Interface Guidelines 审查 UI 代码，并以 file:line 形式报告问题。

Software Development32K5周前更新

Vercel React Native Skills

vercel-labs

精选

React Native 与 Expo 最佳实践规则，涵盖列表性能、动画、导航、UI 模式、状态与 monorepo 配置。

Software Development32K5周前更新

Vercel React Best Practices

vercel-labs

精选

Vercel 的 React 与 Next.js 性能指南，以 70 条规则的形式用于编写、审查和重构代码。

Software Development32K5周前更新