c4-diagrams

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

C4 Diagrams

C4 图表

Overview

概述

Use C4 diagrams to clarify software architecture before detailed design. Focus on boundaries, responsibilities, actors, dependencies, and data flow; draw only the levels that add value.

在详细设计前，可使用C4图表明确软件架构。重点关注边界、职责、参与者、依赖关系和数据流；仅绘制能带来价值的层级。

First Gates

前期决策

Before diagramming, determine these choices. If the user already specified one, honor it. If multiple choices are ambiguous, ask one concise combined question.

Choice	Options	Default behavior
Purpose	Existing code, new system, design review	Existing code requires codebase exploration first; new systems require assumptions called out.
Format	ASCII, Mermaid	Ask the user. Mermaid means plain Mermaid syntax, not C4-specific Mermaid.
Rigor	Strict C4, lightweight C4-inspired, hybrid	Ask the user. Do not decide silently.

If the user asks to skip questions for speed, still preserve unresolved choices as explicit assumptions and keep the first diagram lightweight.

绘图前，先确定以下选项。如果用户已指定其中一项，则遵循该选择。若多个选项不明确，可提出一个简洁的组合问题。

选项	可选值	默认行为
用途	现有代码、新系统、设计评审	针对现有代码需先探索代码库；针对新系统需明确列出假设条件。
格式	ASCII、Mermaid	询问用户。Mermaid指纯Mermaid语法，而非C4专用的Mermaid语法。
严谨程度	严格遵循C4、轻量C4风格、混合模式	询问用户。不得自行决定。

如果用户要求跳过问题以提升速度，仍需将未明确的选项作为显性假设保留，并保持首张图表为轻量版本。

Workflow

工作流程

Establish purpose, format, and rigor.
For existing code, inspect entry points, runtime boundaries, integrations, and persistence before drawing. For a quick pass, inspect enough to identify language/framework, launch entry points, major directories, external integrations, and data stores; label anything else as unknown.
Pick the smallest useful diagram set. Start with system context or container; add component, dynamic, or deployment only when it answers a real question.
Draw the diagram using ASCII or plain Mermaid.
Explain the diagram in 3-6 bullets: boundaries, responsibilities, key relationships, assumptions, and open questions.
Stop before detailed design unless the user approves the diagram and asks to continue.

确定用途、格式和严谨程度。
针对现有代码，绘图前需检查入口点、运行时边界、集成项和持久化机制。若快速梳理，需检查足够内容以识别语言/框架、启动入口点、主要目录、外部集成项和数据存储；其他未明确的内容标记为未知。
选择最小的实用图表集。从系统上下文图或容器图开始；仅当需要解答实际问题时，再添加组件图、动态图或部署图。
使用ASCII或纯Mermaid语法绘制图表。
用3-6条要点解释图表：边界、职责、关键关系、假设条件和待解决问题。
除非用户认可图表并要求继续，否则在进入详细设计前停止。

C4 Level Selection

C4 层级选择

Level	Use when	Avoid when
System context	Identifying users, external systems, and scope	The scope is already obvious and local.
Container	Showing deployable/runnable units, data stores, APIs, CLIs, queues	You only need code-level call flow.
Component	Explaining internals of one container	The container has few meaningful internal parts.
Code	Rarely, for critical classes/modules	A normal component diagram would be enough.
Dynamic	Showing request, event, or workflow sequence	Static structure is the actual question.
Deployment	Showing infrastructure, nodes, networks, runtime placement	Deployment is unknown or irrelevant.

For small systems, challenge requests for all four C4 levels and offer a smaller set. If the user still wants all four, produce them but mark low-value levels as lightweight sketches and explain why they may not be worth maintaining.

层级	使用场景	避免场景
系统上下文	识别用户、外部系统和范围	范围已明确且局限于本地。
容器	展示可部署/可运行单元、数据存储、API、CLI、队列	仅需代码级调用流程。
组件	解释单个容器的内部结构	容器内部无多少有意义的组件。
代码	极少使用，仅针对关键类/模块	普通组件图已足够。
动态	展示请求、事件或工作流序列	实际需求是静态结构。
部署	展示基础设施、节点、网络、运行时部署位置	部署信息未知或无关。

对于小型系统，需质疑绘制全部四个C4层级的需求，并建议使用更小的图表集。若用户仍要求绘制全部四个层级，可生成但将低价值层级标记为轻量草图，并解释为何这些层级可能不值得维护。

Output Rules

输出规则

Mermaid diagrams must use plain
```
flowchart
```
or
```
sequenceDiagram
```
syntax for portability.
ASCII diagrams should favor readable boxes and arrows over decorative complexity.
Keep labels concrete: actor, system, container, component, database, queue, external service.
Do not mix levels accidentally: containers are runnable/deployable units; components live inside one container.
Always include assumptions when diagramming a future system or incomplete codebase.
Always include open questions when boundaries, ownership, data flow, or deployment are uncertain.

Mermaid图表必须使用纯
```
flowchart
```
或
```
sequenceDiagram
```
语法以保证可移植性。
ASCII图表应优先保证可读性的框和箭头，而非装饰性的复杂设计。
标签需具体：参与者、系统、容器、组件、数据库、队列、外部服务。
不得意外混合层级：容器是可运行/可部署单元；组件存在于单个容器内部。
绘制未来系统或不完整代码库的图表时，务必包含假设条件。
当边界、归属、数据流或部署情况不确定时，务必列出待解决问题。

Templates

模板

Use

templates.md

in this skill directory for compact ASCII and Mermaid starting points.

可使用本技能目录中的

templates.md

作为ASCII和Mermaid的简洁起始模板。

Common Mistakes

常见错误

Mistake	Fix
Drawing all four C4 levels by default	Draw only levels that answer the current question.
Jumping into detailed design immediately	Validate context/container boundaries first.
Using C4-specific Mermaid syntax	Use plain Mermaid `flowchart` or `sequenceDiagram` .
Treating modules as containers	Containers are runnable/deployable units; modules are usually components.
Hiding uncertainty	State assumptions and open questions after the diagram.

错误	修正方法
默认绘制全部四个C4层级	仅绘制能解答当前问题的层级。
立即进入详细设计	先验证上下文/容器边界。
使用C4专用的Mermaid语法	使用纯Mermaid的 `flowchart` 或 `sequenceDiagram` 语法。
将模块视为容器	容器是可运行/可部署单元；模块通常属于组件。
隐藏不确定性	在图表后说明假设条件和待解决问题。