Back to Details

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

文档类型

TypeAudienceContent
ContextAll stakeholdersSystem boundaries, external interactions
ContainerTechnical leadsServices, databases, major components
ComponentDevelopersInternal structure of containers
DeploymentOperationsInfrastructure, environments
DataData architectsData flows, storage, schemas
Executive SummaryLeadershipBusiness value, key decisions
类型受众内容
上下文图所有利益相关者系统边界、外部交互
容器图技术负责人服务、数据库、主要组件
组件图开发人员容器的内部结构
部署图运维人员基础设施、环境
数据图数据架构师数据流、存储、模式
执行摘要管理层业务价值、关键决策

Document Generation Workflow

文档生成流程

1. Analyze the Codebase

1. 分析代码库

Before generating documentation:
  1. Identify the scope (single service, multiple services, entire system)
  2. Find existing documentation to incorporate
  3. Locate key architectural files (configs, deployment specs)
生成文档前：
  1. 确定范围（单个服务、多个服务、整个系统）
  2. 查找现有文档以纳入内容
  3. 定位关键架构文件（配置、部署规范）

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

外部系统

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

Users/Actors

用户/参与者

ActorDescriptionInteractions
.........
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:
  1. Invoke 
    visualization:diagram-generator
    agent
  2. Request appropriate C4 diagram type
  3. 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.
如果可视化插件可用：
  1. 调用
    visualization:diagram-generator
    agent
  2. 请求合适的C4图类型
  3. 将生成的Mermaid/PlantUML代码嵌入文档
备选方案：如果可视化插件不可用，创建基于文本的架构描述，并注明可通过可视化插件添加图表。

Template Structure

模板结构

All architecture documents should include:
  1. Header: Title, version, date, authors
  2. Overview: 1-2 paragraph summary
  3. Diagram: Visual representation
  4. Details: Structured information about components
  5. Decisions: Link to relevant ADRs
  6. References: Links to related documentation
所有架构文档应包含以下部分：
  1. 页眉：标题、版本、日期、作者
  2. 概述：1-2段摘要
  3. 图表：可视化展示
  4. 详情：组件的结构化信息
  5. 决策：链接到相关的ADR
  6. 参考资料：相关文档的链接

Completeness Checklist

完整性检查清单

Before finalizing documentation, verify:
  • Scope is clearly defined
  • All major components identified
  • External dependencies documented
  • Key decisions linked to ADRs
  • Diagram matches text description
  • Audience-appropriate language used
  • Version and date included
最终确定文档前，请验证：
  • 范围已明确定义
  • 所有主要组件已识别
  • 外部依赖已记录
  • 关键决策已链接到ADR
  • 图表与文本描述一致
  • 使用了适合受众的语言
  • 包含版本和日期

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