architecture-documentation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Architecture Documentation

架构文档

When to Use This Skill

何时使用该Skill

Use this skill when you need to:

Generate architecture documentation for a system
Create C4 diagrams (Context, Container, Component)
Document architecture for different stakeholder viewpoints
Produce technical overviews or executive summaries

Keywords: document, c4, container, context, component, viewpoint, architecture description, technical overview, executive summary

当你需要以下操作时，使用该Skill：

为系统生成架构文档
创建C4图（上下文图、容器图、组件图）
为不同利益相关者视角记录架构
生成技术概述或执行摘要

关键词： 文档、c4、容器、上下文、组件、视角、架构描述、技术概述、执行摘要

Document Types

文档类型

Type	Audience	Content
Context	All stakeholders	System boundaries, external interactions
Container	Technical leads	Services, databases, major components
Component	Developers	Internal structure of containers
Deployment	Operations	Infrastructure, environments
Data	Data architects	Data flows, storage, schemas
Executive Summary	Leadership	Business value, key decisions

类型	受众	内容
上下文图	所有利益相关者	系统边界、外部交互
容器图	技术负责人	服务、数据库、主要组件
组件图	开发人员	容器的内部结构
部署图	运维人员	基础设施、环境
数据图	数据架构师	数据流、存储、模式
执行摘要	管理层	业务价值、关键决策

Document Generation Workflow

文档生成流程

1. Analyze the Codebase

1. 分析代码库

Before generating documentation:

Identify the scope (single service, multiple services, entire system)
Find existing documentation to incorporate
Locate key architectural files (configs, deployment specs)

生成文档前：

确定范围（单个服务、多个服务、整个系统）
查找现有文档以纳入内容
定位关键架构文件（配置、部署规范）

2. Select Document Type

2. 选择文档类型

Choose based on:

Audience: Who will read this?
Purpose: Decision support, onboarding, compliance?
Scope: Component, service, or system level?

根据以下因素选择：

受众：谁会阅读这份文档？
目的：决策支持、新员工入职、合规性要求？
范围：组件、服务还是系统层面？

3. Generate Documentation

3. 生成文档

Each document type has a standard structure:

每种文档类型都有标准结构：

Context Document

上下文文档

markdown

undefined

markdown

undefined

System Context: [System Name]

系统上下文：[系统名称]

Overview

概述

[1-2 paragraph description]

[1-2段描述]

Context Diagram

上下文图

[C4 Context diagram - via visualization plugin]

[C4上下文图 - 通过可视化插件生成]

External Systems

外部系统

System	Description	Integration
...	...	...

系统	描述	集成方式
...	...	...

Users/Actors

用户/参与者

Actor	Description	Interactions
...	...	...

undefined

参与者	描述	交互内容
...	...	...

undefined

Container Document

容器文档

markdown

undefined

markdown

undefined

Container Architecture: [System Name]

容器架构：[系统名称]

Overview

概述

[Architecture summary]

[架构摘要]

Container Diagram

容器图

[C4 Container diagram - via visualization plugin]

[C4容器图 - 通过可视化插件生成]

Containers

容器

[Container Name]

[容器名称]

Technology: [Stack]
Purpose: [Description]
Responsibilities: [List]
Dependencies: [List]

undefined

技术栈：[相关技术]
用途：[描述]
职责：[列表]
依赖项：[列表]

undefined

Component Document

组件文档

markdown

undefined

markdown

undefined

Component Architecture: [Container Name]

组件架构：[容器名称]

Overview

概述

[Component structure summary]

[组件结构摘要]

Component Diagram

组件图

[C4 Component diagram - via visualization plugin]

[C4组件图 - 通过可视化插件生成]

Components

组件

[Component Name]

[组件名称]

Type: [Service/Repository/Controller/etc.]
Responsibilities: [List]
Interfaces: [Public APIs]

undefined

类型：[服务/仓库/控制器等]
职责：[列表]
接口：[公开API]

undefined

4. Integrate Diagrams

4. 集成图表

If the visualization plugin is available:

Invoke
```
visualization:diagram-generator
```
agent
Request appropriate C4 diagram type
Embed generated Mermaid/PlantUML code in document

Fallback: If visualization plugin unavailable, create text-based architecture description and note that diagrams can be added with the visualization plugin.

如果可视化插件可用：

调用
```
visualization:diagram-generator
```
agent
请求合适的C4图类型
将生成的Mermaid/PlantUML代码嵌入文档

备选方案：如果可视化插件不可用，创建基于文本的架构描述，并注明可通过可视化插件添加图表。

Template Structure

模板结构

All architecture documents should include:

Header: Title, version, date, authors
Overview: 1-2 paragraph summary
Diagram: Visual representation
Details: Structured information about components
Decisions: Link to relevant ADRs
References: Links to related documentation

所有架构文档应包含以下部分：

页眉：标题、版本、日期、作者
概述：1-2段摘要
图表：可视化展示
详情：组件的结构化信息
决策：链接到相关的ADR
参考资料：相关文档的链接

Completeness Checklist

完整性检查清单

Repository Location

仓库位置

Generated documentation should be placed in:

text

/architecture/
  /viewpoints/
    context.md
    containers.md
    components/
      [container-name].md
    executive-summary.md

生成的文档应放置在：

text

/architecture/
  /viewpoints/
    context.md
    containers.md
    components/
      [container-name].md
    executive-summary.md

Integration with Other Skills

与其他Skill的集成

adr-management: Link to relevant ADRs in documentation
togaf-guidance: Align with current ADM phase
zachman-analysis: Ensure appropriate viewpoint coverage

adr-management：在文档中链接到相关的ADR
togaf-guidance：与当前ADM阶段保持一致
zachman-analysis：确保覆盖合适的视角

Version History

版本历史

v1.0.0 (2025-12-05): Initial release
- Document generation workflow for C4 diagrams
- Six document types (context, container, component, deployment, data, executive summary)
- Visualization plugin integration
- Completeness checklist

v1.0.0（2025-12-05）：初始版本
- 用于C4图的文档生成流程
- 六种文档类型（上下文、容器、组件、部署、数据、执行摘要）
- 可视化插件集成
- 完整性检查清单

Last Updated

最后更新

Date: 2025-12-05 Model: claude-opus-4-5-20251101

日期： 2025-12-05 模型： claude-opus-4-5-20251101