c4-model

c4-model

生成规范 C4 LikeC4 模型，默认包含 Context 和 Container 视图，Deployment 视图为可选项。拒绝所有会使图表超出 Simon Brown 规范 C4 范畴的 LikeC4 功能。此处使用的规范 C4 功能在各个 LikeC4 版本中保持稳定；请运行 npx likec4 validate，以确认其与你安装的版本兼容。

此技能会创建的内容

• 一个包含规范说明和模型的 model.c4 文件
• 一个范围限定为当前焦点系统的 <system>.c4 文件
• 一个包含一个 Context 视图和一个 Container 视图（可选再加一个 Deployment 视图）的 views.c4 文件
• 一个 likec4.config.js 文件

此技能会拒绝的内容

拒绝的内容	原因	架构师的替代方案
Component 视图	“Component 视图的层级比 ADR 所适用的层级更深。”	使用代码级图表工具（例如在源代码中使用 Mermaid）——这不属于 C4。
Dynamic 视图	序列／运行时流程不属于规范 C4。	单独使用序列图工具。
自定义元素类型	规范 C4 只有 Person / Software System / Container——仅此而已。	使用 container，并将类型填入 technology 属性。
自定义关系类型	规范关系类型：uses、reads、writes、publishes、consumes。	选择最接近的规范类型。
自定义样式	图表应当看起来明显符合 C4 风格。	如果样式比规范性更重要，请直接在此技能之外使用 LikeC4。
嵌套系统	C4 只有 Context 和 Container；在系统中嵌套系统会模糊层级。	拆分为多个模型。
多个焦点系统	每个 .c4 文件只包含一个系统才符合规范。	为每个系统单独创建模型，并通过 externalSystem 链接。

这些拒绝规则正是此技能的意义所在。想要充分利用 LikeC4 自由度的架构师不应使用此技能。

术语

• Actor — C4 术语中的 Person（人类角色）。在系统边界之外渲染。
• 外部系统 — 团队不拥有的系统。在系统边界之外渲染。
• 系统 — 当前焦点中的单个有界产品。每个文件中恰好一个。
• Container — 焦点系统内可运行／可部署的单元。不是代码类。
• 关系 — 带有单行描述的有向边；描述为必填项。

硬性规则

1. **每个关系都必须有单行描述。**没有描述 → 不绘制边。
2. **元素名称必须与架构师在需求梳理中确认的名称一致。**不得翻译、缩写或改为复数。
3. 除非架构师明确要求，否则不得自行添加样式。
4. 每个 .c4 文件中必须恰好定义一个 system。

锁定的规范说明代码块

原样使用此 specification 代码块。不得编辑、扩展或重命名。

specification {
  element actor {
    style {
      shape person
    }
  }
  element externalSystem {
    style {
      color secondary
    }
  }
  element system
  element container

  relationship uses
  relationship reads
  relationship writes
  relationship publishes
  relationship consumes

  tag open-question {
    style {
      color red
      border dashed
    }
  }
}

未决问题约定

对于已存在但细节尚未确定的元素或关系：

• 添加标签 #open-question
• 在描述前加上 OPEN Q<N>:，其中编号须与 docs/architecture/open-questions.md 中的条目编号一致
• 样式会将其渲染为红色虚线——视觉上非常醒目

示例：

container payments-service "Payments Service" "OPEN Q7: tech stack unconfirmed" {
  #open-question
}

八个阶段

阶段 1 — 信息收集

如果 docs/architecture/discovery-brief.md 存在且包含 CONFIRMED 元素，则直接使用——不要再次询问。否则，逐个引导架构师确认每个元素（每轮只问一个问题，遵循与 adr-discovery 相同的原则）。

阶段 2 — 定位或搭建框架

搜索 **/*.c4 和 **/likec4.config.*。分两种情况：

• **文件已存在：**读取这些文件。确定焦点系统。如果架构师确认范围，则在现有模型中添加内容。
• **没有文件：**在架构师选择的路径下搭建 model.c4、<system>.c4、views.c4 和 likec4.config.js（默认路径为仓库根目录下的 likec4/）。

第 3 阶段 — 生成 DSL

model.c4 中包含三个代码块：

1. 规格说明 — 与上方锁定的代码块完全一致。
2. 模型 — 演员和外部系统位于顶层；容器嵌套在 system 代码块中。请参阅 references/likec4-dsl-cheatsheet.md。
3. 视图 — 在 views.c4 中：一个 context 视图（系统及其演员和外部系统）、一个 container 视图（系统内的容器），以及可选的一个 deployment 视图。

第 4 阶段 — Canonical-C4 检查

验证前，运行包含 11 项的检查清单：

#	检查项
1	恰好有一个 system 定义。
2	所有容器都嵌套在该 system 中。
3	所有演员都位于顶层（不在 system 内）。
4	所有外部系统都位于顶层。
5	每个关系都有非空描述。
6	关系类型仅限于规范中的五种。
7	元素类型仅限于 actor、externalSystem、system、container。
8	不存在嵌套系统。
9	视图仅限于 context、container、deployment。
10	规格说明代码块与锁定的代码块完全一致。
11	每个带有 #open-question 标签的元素，其描述前缀均为 OPEN Q<N>:。

打印 PASS 或 FAIL，并附上带编号的违规项列表。若为 FAIL，请勿继续。

第 5 阶段 — 显示差异，不要应用

逐个代码块以差异形式呈现拟议的文件更改。逐块审批。架构师批准前，不要写入文件。

第 6 阶段 — 验证语法

运行 npx likec4 validate。如果验证失败，将错误告知架构师，不要自动修复。

第 7 阶段 — 提供渲染指南

告知架构师如何查看图表。未经邀请，不要启动服务。

To view: npx likec4 start    # interactive browser at http://localhost:5173
To serve: npx likec4 serve   # static export

第 8 阶段 — 漂移检查

扫描 ADR 目录（docs/adr/、docs/decisions/、docs/architecture/decisions/、**/adr/*.md；也检查旧目录 architecture/decisions/）。对于每个 ADR，将正文中提及的组件名称与 LikeC4 模型中的名称进行比较。将名称不匹配项报告为 drift 候选项，由架构师决定以哪一方为准。不要自动重命名任何一方。

DSL 说明

对于复杂的 DSL 问题（作用域视图、extend、部署规范），请查阅 references/likec4-dsl-cheatsheet.md。对于超出规范 C4 范围的功能，请引导架构师查阅上游 LikeC4 文档，而不要在此技能中实现这些功能。

参考资料

• references/likec4-dsl-cheatsheet.md — 精简的规范 C4 LikeC4 DSL 备忘单
• references/canonical-c4-refusals.md — 针对不允许功能的逐字拒绝脚本
• adr-discovery 技能 — 已确认元素和关系的上游来源
• adr-critique 技能 — 用于检测与 ADR 漂移的下游使用方