c4-model

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

c4-model

C4 Model là gì

什么是C4 Model

C4 (nguồn: https://c4model.com/) là cách vẽ kiến trúc phần mềm qua 4 tầng, zoom dần từ tổng quan xuống chi tiết — mỗi tầng phục vụ một loại người đọc khác nhau, không nhồi hết vào 1 sơ đồ:

Tầng	Trả lời câu hỏi	Đọc bởi	Trong kit này
1. System Context	Hệ thống tương tác với ai, hệ thống ngoài nào?	Mọi người (kỹ thuật + phi kỹ thuật)	`c4-context.md`
2. Container	Hệ thống gồm những container nào (web app/API/DB/service...), giao tiếp ra sao?	Kỹ thuật (architect/dev/ops)	`c4-container.md`
3. Component	Bên trong 1 container có những component/module nào?	Dev trong team sở hữu container đó	`c4-component-<mã-container>.md` , 1 file/container
4. Code	Class/function cụ thể	Dev đang code trực tiếp	Không tạo — để code + IDE tự giải thích

Kit này tạo Level 1–3 theo mặc định: Context + Container cho toàn hệ thống, và 1 file Component riêng cho mỗi container có codebase thực sự (bỏ qua container không có component nội bộ để mô hình hoá, ví dụ DB thuần hoặc dịch vụ bên thứ ba dùng nguyên trạng). Level 4 (Code) không tạo — để code + IDE tự giải thích, tránh diagram chi tiết đến mức không ai maintain nổi, nhanh lỗi thời hơn cả code.

Ngoài 4 Level trên (đây KHÔNG phải 1 Level mới, chỉ là phụ lục dữ liệu đi kèm Container/ Component): khi giao tiếp giữa 2 container có dữ liệu thật cần thống nhất trước, tạo thêm

container-interface.md

, mỗi luồng giao tiếp gán 1 mã

CIC-xxx

— xem mục "Quy trình tạo Container Interface Contract" bên dưới. Nếu nhiều entity dùng chung bởi nhiều CIC/ container mà mô tả rời rạc sẽ bị lặp/lệch nhau, tạo thêm

entity-interface.md

— xem mục "Quy trình tạo Entity Interface" bên dưới.

Mọi file

*-template.md

skill này dùng nằm trong

docs/system-overview/templates/

nếu dự án đã có (tách biệt khỏi tài liệu thật để dễ đọc), hoặc trong thư mục

templates/

đi kèm chính skill này nếu dự án chưa có — xem quy tắc chọn nguồn ở "Điều kiện tiên quyết". Ví dụ

c4-context-template.md

dùng để tạo

c4-context.md

container-interface-template.md

dùng để tạo

container-interface.md

. Tài liệu thật (không có suffix

-template

) luôn tạo trực tiếp trong

docs/system-overview/

, không tạo trong

templates/

C4（来源：https://c4model.com/）是一种通过4个层级绘制软件架构的方法，从全局概览逐步深入细节——每个层级对应不同的受众，避免将所有信息堆砌在一张图中：

层级	解答的问题	受众	本工具包对应文件
1. System Context	系统与哪些角色、外部系统交互？	所有人员（技术+非技术）	`c4-context.md`
2. Container	系统包含哪些容器（Web应用/API/数据库/服务...），它们如何交互？	技术人员（架构师/开发/运维）	`c4-container.md`
3. Component	单个容器内部包含哪些组件/模块？	负责该容器的团队开发人员	`c4-component-<容器编号>.md` ，每个容器对应一个文件
4. Code	具体的类/函数	正在编写代码的开发人员	不生成——由代码和IDE自行说明

本工具包默认生成第1-3层级：面向整个系统的Context + Container，以及每个拥有实际代码库的容器对应的独立Component文件（忽略无需建模内部组件的容器，如纯数据库或直接使用的第三方服务）。第4层级（Code）不生成——由代码和IDE自行说明，避免绘制过于详细的图导致无人维护，且比代码更快过时。

除上述4个层级（这并非新层级，只是Container/Component的配套数据附录）：当两个容器间的交互需要提前统一数据标准时，额外创建

container-interface.md

，为每个交互流分配一个

CIC-xxx

编号——详见下文「创建容器接口契约流程」。如果多个实体被多个CIC/容器共享，分散描述会导致重复或不一致，则创建

entity-interface.md

——详见下文「创建实体接口流程」。

本技能使用的所有

*-template.md

模板，若项目已存在则位于

docs/system-overview/templates/

（与正式文档分离以便阅读），若项目未存在则位于本技能自带的

templates/

目录——详见「前置条件」中的模板来源规则。例如

c4-context-template.md

用于生成

c4-context.md

，

container-interface-template.md

用于生成

container-interface.md

。正式文档（无

-template

后缀）始终直接创建在

docs/system-overview/

目录下，不创建在

templates/

中。

Khi nào dùng skill này

何时使用本技能

User hỏi C4 model là gì / vì sao kit tách riêng Context và Container.

docs/business-requirement

docs/user-requirement

docs/functional-requirement

liên quan đã

status: approved

, cần sinh system overview.

用户询问C4 Model是什么 / 为何工具包要将Context和Container分开。

docs/business-requirement

、

docs/user-requirement

、

docs/functional-requirement

Điều kiện tiên quyết

前置条件

Template cần cho mọi file C4/Interface Contract đi kèm sẵn trong thư mục

templates/

cạnh chính

SKILL.md

này — không cần cài/copy gì thêm để có chúng:

Tài liệu	Template đi kèm skill
`docs/spec-kit-conventions.md`	`templates/spec-kit-conventions.md`
`docs/system-overview/c4-context.md`	`templates/c4-context-template.md`
`docs/system-overview/c4-container.md`	`templates/c4-container-template.md`
`docs/system-overview/c4-component-*.md`	`templates/c4-component-template.md`
`docs/system-overview/container-interface.md`	`templates/container-interface-template.md`
`docs/system-overview/entity-interface.md`	`templates/entity-interface-template.md`

Quy tắc chọn nguồn template — áp dụng ở mọi "Quy trình" bên dưới: ưu tiên

docs/system-overview/templates/<tên>-template.md

nếu dự án đã có sẵn; chỉ dùng bản

templates/<tên>-template.md

đi kèm skill này khi dự án chưa có — lúc đó tự tạo

docs/system-overview/templates/

(nếu chưa có) rồi copy nguyên trạng bản đi kèm skill vào đúng vị trí trước khi tạo tài liệu thật. Không tự bịa cấu trúc/tên bảng/section khác ngoài 2 nguồn này. Container/Entity Interface Contract chỉ cần scaffold khi điều kiện tạo tương ứng (mục "Quy trình tạo Container Interface Contract" bước 1, "Quy trình tạo Entity Interface" bước 1) đã đúng — không scaffold trước nếu hệ thống chưa cần tới.

docs/glossary/glossary.md

cần đã tồn tại (thường được

setup-context

tạo trước — chạy skill đó trước nếu chưa có).

docs/spec-kit-conventions.md

dùng đúng quy tắc chọn nguồn ở trên: kiểm tồn tại chưa trước khi làm bất kỳ việc gì bên dưới, nếu chưa có thì copy nguyên trạng từ

templates/spec-kit-conventions.md

. Quy tắc cốt lõi (không thiết kế API/DB cụ thể, ranh giới Level 1-3, xác nhận với user...) đã được nhắc lại trực tiếp trong các mục dưới đây, và đầy đủ hơn ở

docs/spec-kit-conventions.md

— bảng prefix/ID, vòng đời

status

, glossary-link theo độ sâu thư mục, ma trận lan truyền thay đổi.

所有C4/接口契约相关文件的模板需预先放置在本

SKILL.md

所在目录的

templates/

文件夹中——无需额外安装/复制即可使用：

文档	技能自带模板
`docs/spec-kit-conventions.md`	`templates/spec-kit-conventions.md`
`docs/system-overview/c4-context.md`	`templates/c4-context-template.md`
`docs/system-overview/c4-container.md`	`templates/c4-container-template.md`
`docs/system-overview/c4-component-*.md`	`templates/c4-component-template.md`
`docs/system-overview/container-interface.md`	`templates/container-interface-template.md`
`docs/system-overview/entity-interface.md`	`templates/entity-interface-template.md`

模板来源选择规则——适用于以下所有「流程」： 优先使用项目已存在的

docs/system-overview/templates/<名称>-template.md

；仅当项目未存在时，才使用本技能自带的

templates/<名称>-template.md

——此时需先创建

docs/system-overview/templates/

目录（若不存在），再将技能自带的模板原样复制到对应位置，然后再生成正式文档。不得自行修改这两个来源之外的结构/表格/章节。仅当满足对应创建条件时（「创建容器接口契约流程」步骤1、「创建实体接口流程」步骤1），才生成Container/Entity接口契约的框架——若系统暂不需要则不提前生成。

docs/glossary/glossary.md

需已存在（通常由

setup-context

技能提前生成——若未存在则先运行该技能）。

docs/spec-kit-conventions.md

需遵循上述模板来源规则：在执行以下任何操作前先检查是否已存在，若未存在则从

templates/spec-kit-conventions.md

原样复制。核心规则（不设计具体API/数据库、明确1-3层级边界、与用户确认...）已在以下章节中提及，完整内容详见

docs/spec-kit-conventions.md

——包括前缀/ID规则、

status

生命周期、按目录深度添加术语表链接、变更传播矩阵。

Quy trình tạo Context Diagram (Level 1)

创建Context图（第1层级）流程

Đọc
```
docs/glossary/glossary.md
```
(thuật ngữ dự án, dùng nhất quán khi đặt tên hệ thống/ container/component), rồi toàn bộ BR/UR/FR đã approved (đặc biệt UR để lấy Actor/Persona, FR để lấy hệ thống ngoài cần tích hợp). Khi viết nội dung ở Context/ Container/Component/Interface Contract, thuật ngữ đã có trong glossary → gắn link Markdown tới đúng mục ở lần xuất hiện đầu tiên trong mỗi tài liệu (xem
```
docs/spec-kit-conventions.md
```
mục 3).
Viết 1–2 câu mô tả hệ thống trung tâm.
Điền
```
docs/system-overview/c4-context.md
```
: bảng Actors/Personas, bảng Hệ thống ngoài liên quan (mục đích tích hợp + hướng dữ liệu in/out), diagram mermaid
```
graph TD
```
.
Không đưa chi tiết kỹ thuật (tên container, công nghệ, API) vào tầng này — đó là việc của Container Diagram. Audience tầng này gồm cả người phi kỹ thuật.

阅读
```
docs/glossary/glossary.md
```
（项目术语，确保系统/容器/组件命名一致），然后阅读所有已获批的BR/UR/FR文档（尤其UR用于获取角色/用户画像，FR用于获取需要集成的外部系统）。在Context/Container/Component/接口契约文档中，若术语已在术语表中存在→在每个文档的首次出现处添加Markdown链接指向对应条目（详见
```
docs/spec-kit-conventions.md
```
第3条）。
撰写1-2句话描述核心系统。
填写
```
docs/system-overview/c4-context.md
```
：角色/用户画像表、相关外部系统表（集成目的+数据流入/流出方向）、mermaid
```
graph TD
```
图。
不得将技术细节（容器名称、技术栈、API）放入此层级——这些属于Container图的范畴。此层级受众包含非技术人员。

Quy trình tạo Container Diagram (Level 2)

创建Container图（第2层级）流程

Bắt đầu từ Context Diagram đã có (
```
source_docs: [SYS-CTX-001]
```
).
Liệt kê từng container, mỗi container gán 1 mã (slug ngắn, duy nhất trong bảng, vd
```
checkout-web
```
,
```
checkout-api
```
,
```
db
```
), kèm loại (web app/mobile/service/DB...) và trách nhiệm. Không liệt kê công nghệ/stack cụ thể — Container Diagram dừng ở mức giao tiếp/ interface abstract (container nào tồn tại, giao tiếp với nhau ra sao), chọn công nghệ là quyết định triển khai ở Bước C. Bảng này là dữ liệu gốc mà mọi việc lập kế hoạch sau này sẽ đọc lại và tham chiếu đúng theo mã — không nơi nào khác tự đặt mã container mới.
Nếu chưa rõ hệ thống nên tách thành bao nhiêu container độc lập (mô hình còn mơ hồ, ranh giới trách nhiệm giữa các phần chưa rõ): hỏi trực tiếp user, ví dụ "hệ thống này gồm bao nhiêu service/app độc lập?" — không tự suy đoán ranh giới. Nếu user chưa có tên cụ thể cho container, có thể tự đề xuất tên gợi ý theo trách nhiệm (ví dụ
```
checkout-service
```
,
```
notification-service
```
) nhưng phải để user xác nhận trước khi ghi chính thức vào bảng. Ghi nguyên văn câu hỏi đã hỏi + câu trả lời/xác nhận thật của user vào mục "Xác nhận với user" trong
```
c4-container.md
```
(xem template) — không chỉ khẳng định suông "đã đề xuất và được xác nhận" mà không có gì đối chiếu được; bằng chứng nằm ngay trong tài liệu, không phụ thuộc git log hay trí nhớ phiên làm việc.
Vẽ giao tiếp giữa các container: từ đâu → tới đâu, giao thức (REST/HTTPS, gRPC, message queue...), mô tả ngắn. Nếu 1 container gọi trực tiếp tới hệ thống ngoài đã liệt kê ở
```
c4-context.md
```
(payment gateway, hệ thống bên thứ ba...) — thêm 1 hàng riêng cho giao tiếp đó vào cùng bảng "Giao tiếp" này (không chỉ nhắc ở Context Diagram) — đây là bảng duy nhất mà "Quy trình tạo Container Interface Contract" bên dưới quét qua để cấp mã CIC cho từng hàng.
Với mỗi container có codebase thực sự (không phải DB thuần/dịch vụ bên thứ ba dùng nguyên trạng), tiếp tục sang Quy trình tạo Component Diagram bên dưới. Không tự vẽ Code diagram (Level 4) trừ khi user yêu cầu rõ ràng.

基于已有的Context图（
```
source_docs: [SYS-CTX-001]
```
）开始。
列出每个容器，为每个容器分配一个编号（简短唯一的标识，例如
```
checkout-web
```
、
```
checkout-api
```
、
```
db
```
），并标注类型（Web应用/移动端/服务/数据库...）和职责。不得列出具体技术栈——Container图仅停留在抽象交互/接口层面（存在哪些容器、如何交互），技术栈选择属于C阶段的实现决策。此表格是后续所有规划的基础数据来源，必须严格按照编号引用——不得在其他地方自行创建新的容器编号。
若不清楚系统应拆分为多少个独立容器（模型模糊、各部分职责边界不清晰）：直接询问用户，例如「该系统包含多少个独立的服务/应用？」——不得自行假设边界。若用户未给容器指定具体名称，可根据职责建议名称（例如
```
checkout-service
```
、
```
notification-service
```
）但必须经用户确认后再正式写入表格。将提问原文 + 用户实际回答/确认内容写入
```
c4-container.md
```
的「与用户确认」章节（详见模板）——不得仅笼统说明「已提出并获确认」而无依据；证据需直接体现在文档中，无需依赖git日志或会议记忆。
绘制容器间的交互：从哪到哪、协议（REST/HTTPS、gRPC、消息队列...）、简短描述。若某个容器直接调用
```
c4-context.md
```
中列出的外部系统（支付网关、第三方系统...）——需在本「交互」表格中单独添加一行记录该交互（不得仅在Context图中提及）——此表格是后续「创建容器接口契约流程」为每行分配CIC编号的唯一依据。
对于每个拥有实际代码库的容器（非纯数据库/直接使用的第三方服务），继续执行下文的「创建Component图流程」。不得自行绘制Code图（第4层级），除非用户明确要求。

Quy trình tạo Component Diagram (Level 3)

创建Component图（第3层级）流程

Với mỗi container thuộc diện cần Component diagram (xem bước 5 ở trên), tạo file
```
docs/system-overview/c4-component-<mã-container>.md
```
(
```
<mã-container>
```
là "Mã" của container đó trong
```
c4-container.md
```
),
```
source_docs: [SYS-CTR-xxx]
```
trỏ về container cha.
Liệt kê từng component/module bên trong container, mỗi component gán tên ngắn gọn kèm trách nhiệm chính — ở mức đủ để dev trong team sở hữu container hiểu bố cục mà không cần đọc code trước. Không xuống tới class/function cụ thể (đó là Level 4, không thuộc phạm vi skill này). Nếu
```
container-interface.md
```
đã tồn tại và container này tham gia ít nhất 1 mã CIC, điền cột "CIC liên quan" cho đúng component khởi tạo/xử lý CIC đó (đối chiếu tên component phải khớp với bảng tổng hợp CIC — không tự đặt tên khác ở đây); nếu chưa tạo
```
container-interface.md
```
, để trống cột này, không tự suy đoán mã CIC chưa tồn tại.
Vẽ giao tiếp giữa các component trong cùng container (gọi hàm, event nội bộ...) bằng diagram mermaid
```
graph TD
```
.
Trước khi kết luận "container quá đơn giản, bỏ qua Component diagram": phải thử liệt kê candidate component trước (kể cả khi kết quả là 1-2 component) — không kết luận "quá đơn giản" mà không có danh sách này. Nếu sau khi liệt kê, container thực sự chỉ có 1-2 component không có cấu trúc nội bộ đáng vẽ → không tạo file Component, nhưng vẫn ghi trong
```
c4-container.md
```
danh sách candidate đã xét qua và lý do gộp/bỏ qua (không chỉ ghi kết luận suông) — tránh việc bỏ qua vì muốn giảm số file thay vì vì container thực sự đơn giản.
Trước khi ghi chính thức vào file Component: liệt kê danh sách component vừa xác định (tên + trách nhiệm 1 dòng) và thực sự dừng lại chờ user xác nhận — cùng mức xác nhận nhẹ như bước 3 ở Container Diagram (không phải hỏi lại từng chi tiết, chỉ để user chỉnh trước khi ghi thành dữ liệu gốc mà
```
Context cho Agent
```
của User Story sau này sẽ trỏ tới). Không được coi im lặng là đồng ý, và không được tự liệt kê rồi tự đi tiếp ghi file luôn trong cùng lượt — đây chính là chỗ 1 component không ai yêu cầu (ví dụ tự thêm 1 cơ chế retry/queue nội bộ) dễ lọt vào dữ liệu gốc mà không ai bắt lại, vì các bước tự-rà-soát ở
```
setup-context
```
/
```
plan-backlog
```
không quét tới tầng C4 (xem 2 skill đó). Ghi nguyên văn danh sách candidate đã trình bày + phản hồi thật của user vào mục "Xác nhận với user" trong file Component (xem template) — không chỉ khẳng định suông "đã đề xuất và PO xác nhận". Đây không phải cơ chế mới:
```
setup-context
```
đã dùng đúng cách này cho BR/UR/FR từ trước — bằng chứng nằm trong tài liệu, đọc lại được độc lập mà không cần git log (không phải lúc nào cũng có, ví dụ trong môi trường test/sandbox không có git) hay trí nhớ phiên làm việc.
Dừng ở Level 3. Không tự vẽ Code diagram trừ khi user yêu cầu rõ ràng.

对于每个需要绘制Component图的容器（见上文步骤5），创建文件
```
docs/system-overview/c4-component-<容器编号>.md
```
（
```
<容器编号>
```
为
```
c4-container.md
```
中该容器的「编号」），
```
source_docs: [SYS-CTR-xxx]
```
指向父容器。
列出容器内的每个组件/模块，为每个组件添加简短名称及核心职责——粒度需足够让负责该容器的团队开发人员理解结构，无需提前阅读代码。不得深入到具体类/函数（这属于第4层级，不在本技能范围内）。若
```
container-interface.md
```
已存在且该容器参与至少一个CIC编号，需为发起/处理该CIC的对应组件填写「关联CIC」列（组件名称需与CIC汇总表一致——不得在此处自行命名）；若未创建
```
container-interface.md
```
，则留空该列，不得自行假设不存在的CIC编号。
使用mermaid
```
graph TD
```
图绘制同一容器内组件间的交互（函数调用、内部事件...）。
在得出「容器过于简单，无需绘制Component图」结论前：必须先列出候选组件（即使结果只有1-2个组件）——不得未列出候选组件就直接得出「过于简单」的结论。若列出后发现容器确实只有1-2个无内部结构的组件→不创建Component文件，但仍需在
```
c4-container.md
```
中记录已评估的候选组件列表及合并/忽略的原因（不得仅记录结论）——避免因减少文件数量而忽略实际需要建模的容器。
在正式写入Component文件前：列出刚确定的组件列表（名称+1句话职责）并暂停等待用户确认——确认程度与Container图步骤3相同（无需逐细节询问，只需让用户在写入基础数据前进行调整）。不得将沉默视为同意，不得在同一轮操作中自行列出组件后直接写入文件——这正是未经需求的组件（例如自行添加内部重试/队列机制）容易混入基础数据且无人发现的环节，因为
```
setup-context
```
/
```
plan-backlog
```
技能的自检步骤不会检查C4层级（详见这两个技能）。将提交的候选组件列表原文 + 用户实际反馈写入Component文件的「与用户确认」章节（详见模板）——不得仅笼统说明「已提出并获产品负责人确认」。这并非新机制：
```
setup-context
```
技能早已对BR/UR/FR使用此方式——证据体现在文档中，可独立查阅，无需依赖git日志（并非所有环境都有，例如测试/沙箱环境）或会议记忆。
停留在第3层级。不得自行绘制Code图，除非用户明确要求。

Quy trình tạo Container Interface Contract (mã CIC)

创建容器接口契约（CIC编号）流程

Không phải 1 Level của C4 — là phụ lục dữ liệu đi kèm Container/Component, trả lời câu hỏi "dữ liệu thật trao đổi qua 1 luồng giao tiếp là gì" mà bảng "Giao tiếp" trong

c4-container.md

(chỉ có cột giao thức + mô tả ngắn) không đủ chỗ trả lời.

Chỉ tạo khi có dữ liệu thật cần 2 bên thống nhất trước khi Bước C thực thi độc lập (ví dụ 2 User Story ở 2 container khác nhau cùng chạm 1 luồng). Không bắt buộc tạo cho mọi hệ thống. 1b. Áp dụng cho cả container nội bộ ↔ hệ thống ngoài đã liệt kê ở bảng "Hệ thống ngoài liên quan" trong
```
c4-context.md
```
(ví dụ payment gateway, hệ thống chấm công bên thứ ba) — không chỉ 2 container nội bộ tự thoả thuận với nhau; luồng đó vẫn được gán mã CIC như bình thường (đánh số chung, không tách bảng riêng). Điều kiện: giao tiếp đó đã có 1 hàng riêng trong bảng "Giao tiếp" của
```
c4-container.md
```
(xem Container Diagram bước 4) — nếu chưa có, thêm vào đó trước, vì đây là bảng duy nhất mỗi hàng ứng với 1 mã CIC (xem bước 3). Khác biệt duy nhất so với luồng nội bộ: với hệ thống ngoài, mục đích của phần schema là ghi lại kỳ vọng tích hợp cần xác nhận với bên thứ ba (dữ liệu team mình cần gửi/nhận theo hiểu biết hiện tại), không phải 1 hợp đồng 2 bên nội bộ tự chốt — nếu chưa xác nhận được với bên thứ ba, ghi rõ "chưa xác nhận với <hệ thống ngoài>" thay vì để trống hoặc bỏ qua không ghi gì (bỏ qua là sai, vì đây chính là dữ liệu Bước C cần để không tự bịa hợp đồng tích hợp).
Tạo
```
docs/system-overview/container-interface.md
```
(
```
SYS-IFC-xxx
```
, dùng template đúng theo quy tắc chọn nguồn ở "Điều kiện tiên quyết"),
```
source_docs
```
trỏ về
```
c4-container.md
```
/
```
c4-component-*.md
```
liên quan.
Gán 1 mã CIC (
```
CIC-001
```
tăng dần) cho mỗi hàng (cạnh có hướng) trong bảng "Giao tiếp" của
```
c4-container.md
```
cần chốt trước — 2 container gọi nhau cả 2 chiều, ghi thành 2 hàng ở đó, thì thành 2 mã CIC. Mã đã cấp là cố định: luồng bị bỏ thì đánh dấu ngừng dùng tại chỗ, không đánh số lại các mã còn lại. Điền bảng tổng hợp CIC (mục 3 của template): Từ, Tới, Loại (
```
nội bộ
```
/
```
hệ thống ngoài
```
), đồng bộ/bất đồng bộ, component khởi tạo/xử lý (lấy tên thật từ
```
c4-component-*.md
```
nếu container đó có file Component, ngược lại ghi
```
—
```
) — không tự đặt tên component mới ở đây. Nếu nhiều component thật trong cùng container cùng khởi tạo/xử lý 1 mã CIC (ví dụ nhiều UI component khác nhau theo persona cùng gọi 1 API) — liệt kê tất cả tên thật đó, cách nhau bằng dấu phẩy, không chọn đại 1 trong số đó và không bịa 1 component trung gian không có trong Component diagram để đại diện. Sau khi điền, cập nhật ngược cột "CIC liên quan" ở đúng file
```
c4-component-*.md
```
của từng component vừa ghi tên (xem Component Diagram bước 2) — 2 chỗ phải khớp tên component và mã CIC, kể cả khi liệt kê nhiều component.
Với mỗi mã CIC: liệt kê theo từng thao tác nghiệp vụ (kèm US liên quan nếu có, tên đọc hiểu ngay như "Tạo task mới" — KHÔNG phải tên kỹ thuật của endpoint) — dữ liệu cần gửi đi/lưu và dữ liệu cần nhận lại/đọc, mỗi field kèm kiểu ở mức khái niệm (text/số/ngày-giờ/boolean/enum — liệt kê giá trị hợp lệ nếu là enum) và bắt buộc/tuỳ chọn, cùng ràng buộc nghiệp vụ nếu có (trỏ về mục quy ước chung nếu trùng, xem bước 5). Áp dụng như nhau cho mọi CIC, kể cả khi 1 bên là container DB thuần (không có Component diagram) — xác định dữ liệu cần trao đổi từ vai trò của container đó trong Context/Container/Component, không thiết kế riêng cho DB. Tên field dùng camelCase nhất quán — đây là quy ước viết tài liệu để tên field khớp giữa
```
container-interface.md
```
và
```
entity-interface.md
```
(khi CIC trỏ về 1 entity, xem bước 6 ở "Quy trình tạo Entity Interface"), KHÔNG phải quyết định định danh trong code/DB thật (đó vẫn là Bước C, có thể khác quy ước case của ngôn ngữ/framework thật sự dùng).
Quy ước áp dụng cho nhiều CIC (phân nhóm lỗi, idempotency, khuôn mẫu thao tác chạy lâu, định danh & phiên bản dữ liệu) nêu 1 lần ở mục "Quy ước chung", không lặp lại ở từng CIC — chỉ 4 chủ đề này, đây là danh sách đóng (xem template); chủ đề khác (xác thực/token, phân trang, rate limit, giao thức, timeout...) không viết vào tài liệu này dù có vẻ áp dụng cho nhiều CIC.
KHÔNG thiết kế API hay DB cụ thể — không viết method HTTP, path, status code, hình dạng response chi tiết, hay tên bảng/cột/kiểu cột SQL/ngôn ngữ cụ thể (
```
varchar(255)
```
,
```
timestamptz
```
,
```
int32
```
...), index. Đó đều là Code (Level 4), quyết định ở Bước C khi thực thi User Story, không phải việc của tài liệu này — kể cả trong mục "Quy ước chung" (bước 5) và nhãn mũi tên nếu vẽ sequence diagram minh hoạ (mục 6 của template, chỉ vẽ khi 1 luồng nghiệp vụ đi qua từ 2 CIC trở lên). Kiểu dữ liệu khái niệm (text/số/ngày-giờ/boolean/enum) vẫn phải ghi — không phải ngoại lệ của quy tắc này, chỉ kiểu cụ thể của DB/ngôn ngữ mới ngoài phạm vi. Chỉ chốt schema dữ liệu, để 2 bên độc lập triển khai không lệch nhau.

这并非C4的一个层级——而是Container/Component的配套数据附录，用于解答「某个交互流实际传输的数据是什么」，而

c4-container.md

中的「交互」表格（仅包含协议+简短描述）无法充分说明。

仅当C阶段需独立执行且数据需提前双方统一时才创建（例如两个不同容器的用户故事涉及同一交互流）。并非所有系统都需要创建。 1b. 适用于内部容器 ↔
c4-context.md
中列出的外部系统（例如支付网关、第三方考勤系统）——不仅限于内部容器间的约定；该交互流仍需正常分配CIC编号（统一编号，无需单独建表）。条件：该交互需已在
```
c4-container.md
```
的「交互」表格中拥有独立行（见Container图步骤4）——若未存在则先添加，因为此表格是每行对应一个CIC编号的唯一依据（见步骤3）。与内部交互流的唯一区别：对于外部系统，schema部分的目的是记录需要与第三方确认的集成预期（基于当前认知，团队需要发送/接收的数据），并非内部双方的约定——若尚未与第三方确认，需明确标注「未与<外部系统>确认」，不得留空或忽略（若忽略则错误，因为这正是C阶段避免自行编造集成约定所需的数据）。

创建

docs/system-overview/container-interface.md

（

SYS-IFC-xxx

，根据「前置条件」中的模板来源规则选择模板），

source_docs

指向相关的

c4-container.md

c4-component-*.md

。

为
```
c4-container.md
```
「交互」表格中需要提前约定的每行（有向边）分配一个CIC编号（
```
CIC-001
```
依次递增）——若两个容器双向调用，在表格中分为两行，则对应两个CIC编号。编号一旦分配即固定：若交互流被取消则标记为停用，不得重新编号剩余编号。填写CIC汇总表（模板第3节）：来源、目标、类型（
```
内部
```
/
```
外部系统
```
）、同步/异步、发起/处理组件（若容器有Component文件则从
```
c4-component-*.md
```
获取实际名称，否则填写
```
—
```
）——不得在此处自行创建新组件名称。若同一容器内多个实际组件共同发起/处理同一个CIC编号（例如不同用户画像的多个UI组件调用同一API）——需列出所有实际名称，用逗号分隔，不得选择其中一个代表，不得编造Component图中不存在的中间组件来代表。填写完成后，反向更新对应
```
c4-component-*.md
```
中每个已记录组件的「关联CIC」列（见Component图步骤2）——两处的组件名称和CIC编号必须一致，即使列出多个组件。
对于每个CIC编号：按业务操作列出（若有相关用户故事则标注，名称需易懂如「创建新任务」——不得使用端点的技术名称）——需要发送/存储的数据和需要接收/读取的数据，每个字段需标注概念级类型（文本/数字/日期时间/布尔/枚举——枚举需列出有效值）及必填/可选，若有业务约束则标注（若与通用约定重复则指向通用约定章节，见步骤5）。此规则适用于所有CIC，即使其中一方是纯数据库容器（无Component图）——需根据该容器在Context/Container/Component中的角色确定传输数据，不得单独为数据库设计。字段名称统一使用camelCase——这是文档编写约定，确保
```
container-interface.md
```
与
```
entity-interface.md
```
的字段名称一致（当CIC指向某个实体时，见「创建实体接口流程」步骤6），并非决定实际代码/数据库中的命名（这仍属于C阶段，可能与实际使用的语言/框架命名约定不同）。
适用于多个CIC的约定（错误分组、幂等性、长时操作模式、数据标识与版本）在「通用约定」章节中统一说明，不得在每个CIC中重复——仅包含这4个主题，为固定列表（详见模板）；其他主题（认证/令牌、分页、速率限制、协议、超时...）即使适用于多个CIC也不得写入本文档。
不得设计具体API或数据库——不得编写HTTP方法、路径、状态码、详细响应格式，或具体表名/列名/数据库类型（
```
varchar(255)
```
、
```
timestamptz
```
、
```
int32
```
...）、索引。这些都属于Code（第4层级），是执行用户故事时C阶段的决策，不属于本文档范畴——即使在「通用约定」章节（步骤5）或示例序列图的箭头标签中（模板第6节，仅当业务流程涉及2个及以上CIC时绘制）也不得提及。概念级数据类型（文本/数字/日期时间/布尔/枚举）仍需标注——这不属于本规则的例外，仅数据库/语言的具体类型超出范围。仅约定数据schema，确保双方可独立实现而不出现偏差。

Quy trình tạo Entity Interface (entity + quan hệ, mã SYS-SIC)

创建实体接口（实体+关系，SYS-SIC编号）流程

Không phải 1 Level của C4 — là phụ lục dữ liệu riêng, tách khỏi Container/Component/CIC, trả lời câu hỏi "entity nào tồn tại trong hệ thống và quan hệ giữa chúng là gì" — câu hỏi mà từng mục CIC riêng lẻ (chỉ trả lời "dữ liệu gì qua 1 luồng") không có chỗ trả lời khi cùng 1 entity xuất hiện ở nhiều luồng/nhiều container.

Chỉ tạo khi nhiều entity dùng chung bởi nhiều CIC/container, và mô tả rời rạc trong từng CIC sẽ bị lặp lại hoặc lệch nhau. Không bắt buộc cho mọi hệ thống — hệ thống ít entity/quan hệ rời rạc thì field list ngay trong từng CIC là đủ, dừng ở
```
container-interface.md
```
.
Tạo
```
docs/system-overview/entity-interface.md
```
(
```
SYS-SIC-xxx
```
, dùng template đúng theo quy tắc chọn nguồn ở "Điều kiện tiên quyết"),
```
source_docs
```
trỏ về
```
c4-container.md
```
(container/DB sở hữu entity) và/hoặc
```
container-interface.md
```
liên quan.
Vẽ sơ đồ quan hệ entity (mermaid
```
erDiagram
```
) + bảng mô tả quan hệ: cardinality (
```
1–1
```
,
```
1–0..n
```
,
```
n–n
```
, đệ quy...), bên nào là FK, bắt buộc hay tuỳ chọn.
Với mỗi entity: liệt kê field, kiểu ở mức khái niệm (text/số/ngày-giờ/boolean/enum — liệt kê giá trị hợp lệ; định danh cho field id/FK, không quy định ULID/UUID/số tăng dần cụ thể; object/array<kiểu> cho cấu trúc lồng), bắt buộc/tuỳ chọn. Tên field dùng camelCase nhất quán — quy ước viết tài liệu để khớp tên với
```
container-interface.md
```
khi 1 CIC trỏ về entity này (xem bước 6 bên dưới), không phải quyết định định danh trong code/DB thật. Field/giá trị nào FR/UR chưa đặc tả đủ để suy chắc chắn (ví dụ tự đề xuất giá trị enum, tự thêm field không ai yêu cầu) — dừng lại, liệt kê đề xuất, chờ user xác nhận thật trước khi ghi chính thức, cùng mức nghiêm ngặt như bước xác nhận ở Component Diagram (không được coi im lặng là đồng ý, không tự liệt kê rồi tự ghi file luôn trong cùng lượt). Ghi nguyên văn đề xuất + phản hồi thật của user vào đúng mục ghi giả định cần xác nhận trong
```
entity-interface.md
```
(tên/số mục theo đúng template hiện tại — không hardcode ở đây, template là nguồn sự thật cho cấu trúc) — không chỉ gắn nhãn
```
[Agent đề xuất]
```
rồi tự cho qua. Nếu phản hồi thật làm thay đổi đề xuất ban đầu (thêm/bớt/sửa giá trị) — ghi phản hồi thôi chưa đủ, phải quay lại cập nhật đúng bảng field/quan hệ của entity đó cho khớp (xoá giá trị bị từ chối, thêm giá trị mới được yêu cầu), không để bảng field giữ nguyên theo đề xuất cũ trong khi mục xác nhận đã ghi rõ đề xuất đó bị từ chối/thay đổi — 2 chỗ lệch nhau là tài liệu tự mâu thuẫn.
KHÔNG thiết kế DDL/collection schema thật (kiểu cột, index, khoá ngoại vật lý — đó là Bước C), KHÔNG mô tả request/response body của từng thao tác (đó là CIC trong
```
container-interface.md
```
), KHÔNG mô tả định dạng file/wire format cụ thể hay quy ước storage key (đó là Bước C). Tài liệu này chỉ mô tả bản thân dữ liệu (entity, field, quan hệ) — không quan tâm nó di chuyển qua luồng nào hay lưu trữ ra sao.
Khi 1 mã CIC gửi/nhận đúng 1 entity (hoặc subset field) đã định nghĩa ở đây, cập nhật CIC đó trỏ về entity này thay vì liệt kê lại toàn bộ field — tránh 2 nguồn field cho cùng 1 entity dễ lệch nhau khi 1 bên sửa mà quên bên kia.

这并非C4的一个层级——是独立的配套数据附录，与Container/Component/CIC分离，用于解答「系统中存在哪些实体及它们之间的关系是什么」——当同一实体出现在多个交互流/容器中时，单个CIC条目（仅解答「某个交互流传输什么数据」）无法解答此问题。

仅当多个实体被多个CIC/容器共享，且分散描述会导致重复或不一致时才创建。并非所有系统都需要——实体/关系较少的系统，直接在每个CIC中列出字段即可，无需创建
```
entity-interface.md
```
。
创建
```
docs/system-overview/entity-interface.md
```
（
```
SYS-SIC-xxx
```
，根据「前置条件」中的模板来源规则选择模板），
```
source_docs
```
指向
```
c4-container.md
```
（拥有实体的容器/数据库）和/或相关的
```
container-interface.md
```
。
绘制实体关系图（mermaid
```
erDiagram
```
）+ 关系描述表：基数（
```
1–1
```
、
```
1–0..n
```
、
```
n–n
```
、递归...）、外键所属方、必填/可选。
对于每个实体：列出字段、概念级类型（文本/数字/日期时间/布尔/枚举——列出有效值；标识字段id/外键，不指定具体的ULID/UUID/自增数字；object/**array<类型>**用于嵌套结构）、必填/可选。字段名称统一使用camelCase——这是文档编写约定，确保与
```
container-interface.md
```
中CIC指向该实体时的字段名称一致（见下文步骤6），并非决定实际代码/数据库中的命名。若FR/UR未充分描述字段/值（例如自行建议枚举值、自行添加未被要求的字段）——暂停，列出建议内容，等待用户实际确认后再正式写入，严格程度与Component图的确认步骤相同（不得将沉默视为同意，不得在同一轮操作中自行列出后直接写入文件）。将建议内容原文 + 用户实际反馈写入
```
entity-interface.md
```
中对应的待确认假设章节（根据当前模板确定正确章节名称/编号——不得硬编码，模板为结构的唯一依据）——不得仅标注「[Agent建议]」就自行通过。若实际反馈修改了初始建议（添加/删除/修改值）——仅记录反馈不足够，必须返回更新对应实体的字段/关系表以匹配反馈（删除被拒绝的值，添加新要求的值），不得让字段表仍保留初始建议内容而待确认章节已明确记录建议被拒绝/修改——这会导致文档自相矛盾。
不得设计实际DDL/集合schema（列类型、索引、物理外键——这属于C阶段），不得描述每个操作的请求/响应体（这属于
```
container-interface.md
```
中的CIC），不得描述具体文件格式/传输格式或存储键约定（这属于C阶段）。本文档仅描述数据本身（实体、字段、关系）——不关心数据通过哪个交互流传输或如何存储。
当某个CIC编号发送/接收的是已在此处定义的完整实体（或字段子集）时，更新该CIC条目指向此实体，而非重复列出所有字段——避免同一实体的两个字段来源在一方修改时另一方未同步导致不一致。

Trước khi kết thúc phiên

结束会话前的检查

Liệt kê ra từng file C4/Interface Contract đã tạo/sửa trong phiên — kể cả khi có nhiều file
c4-component-*.md
(1 file/container), không chỉ file đầu tiên hay file đang nhớ. Với từng file trong danh sách đó (

c4-context.md

c4-container.md

, mỗi

c4-component-<mã>.md

container-interface.md

entity-interface.md

). Đọc lại thủ công không đủ tin cậy cho bước này (lỗi thật đã xảy ra theo đúng mẫu hình: đúng ở file đầu tiên mỗi loại, bị quên ở các file cùng loại tạo sau — 1 lượt eval khác ghi nhận 4/5 file C4 thiếu link dù đã biết trước rủi ro và cố ý đọc lại): liệt kê toàn bộ thuật ngữ có trong

docs/glossary/glossary.md

, dùng công cụ tìm chuỗi sẵn có (search/grep) quét từng file trong danh sách trên theo từng thuật ngữ đó, thay vì chỉ đọc mắt. Với file nào phát hiện thiếu, kiểm lại đúng lần xuất hiện đầu tiên trong thân bài có link chưa (xem bước 1 ở Context Diagram,

docs/spec-kit-conventions.md

mục 3). Tìm thấy link chưa đủ — còn phải xác nhận link đó resolve đúng file, không chỉ "có xuất hiện" (lỗi thật đã xảy ra: 21/21 file sai độ sâu

../

vẫn qua được checkpoint vì có link, chỉ trỏ sai chỗ): đếm số

../

trong từng link tìm được có đúng 1 cấp không — mọi file C4/Interface Contract nằm ngay trong

docs/system-overview/

, luôn đúng 1 cấp (

../glossary/glossary.md

, xem bảng độ sâu mục 3); sai số cấp thì sửa lại link, không chỉ tính là "đã có link" rồi bỏ qua. Nếu file đó đã
status: approved
khi phát hiện thiếu link — đưa lại về

draft

trước khi sửa (xem

docs/spec-kit-conventions.md

mục 1), không sửa thẳng nội dung mà giữ nguyên

approved

Đối chiếu chéo backlink CIC ↔ Component ↔ SIC — cùng 1 lượt vừa viết vừa tự rà dễ bỏ sót lỗi chính mình tạo ra (cùng mẫu hình với checkpoint glossary ở trên), nên kiểm lại đây như 1 bước riêng, không chỉ tin đã khớp lúc viết:

Mỗi mã CIC trong bảng tổng hợp (
```
container-interface.md
```
mục 3) có đúng tên component khởi tạo/xử lý khớp với cột "CIC liên quan" trong file
```
c4-component-*.md
```
tương ứng — cả 2 chiều: component có tên trong bảng CIC phải backlink đúng mã đó, và mã CIC nào cũng phải có mặt ở backlink của component nó liệt kê (không thiếu, không thừa).
Nếu
```
entity-interface.md
```
tồn tại: mọi field ở CIC không trỏ về entity (tự liệt kê field thay vì tham chiếu) phải cùng tên với field tương ứng ở SIC — không để 2 tên khác nhau cho cùng 1 khái niệm (vd
```
sku
```
ở CIC nhưng
```
productId
```
ở SIC).
Nếu
```
entity-interface.md
```
tồn tại: mọi giả định/đề xuất đã ghi trong mục ghi giả định cần xác nhận (xem template hiện tại để biết đúng tên/số mục) có phản hồi thật của user chưa, hay còn giả định mới gắn nhãn
```
[Agent đề xuất]
```
mà chưa thực sự hỏi — khác với checkpoint glossary ở trên (chỉ kiểm thiếu link), đây kiểm nội dung có được xác nhận thật hay chưa, cùng mức nghiêm ngặt như bước "Xác nhận với user" của Component/Container. Với mỗi mục đã có phản hồi thật: nếu phản hồi đó thay đổi đề xuất ban đầu (thêm/bớt/sửa giá trị), đối chiếu xem bảng field/quan hệ của entity tương ứng đã cập nhật khớp theo phản hồi chưa — lỗi thật đã xảy ra: phản hồi ghi rõ 1 giá trị bị từ chối, nhưng bảng field vẫn giữ nguyên giá trị đó như đã chốt, khiến tài liệu tự mâu thuẫn ngay trong chính nó.

Đối chiếu ngược mỗi hàng "Giao tiếp" với FR nguồn — System Overview chỉ được sinh từ FR/UR/BR đã

approved

(nguyên tắc chung #2), nhưng viết Container Diagram vẫn có thể lỡ thêm 1 hàng giao tiếp không thực sự bắt nguồn từ yêu cầu nào (lỗi thật đã xảy ra: 1 chiều giao tiếp 2 chiều với hệ thống ngoài được vẽ vì "nghe hợp lý về mặt kỹ thuật", nhưng không FR/US nào yêu cầu chiều đó). Với mỗi hàng mới/sửa trong bảng "Giao tiếp" của

c4-container.md

(và mã CIC tương ứng nếu

container-interface.md

tồn tại): xác nhận có ít nhất 1 FR (trực tiếp, hoặc gián tiếp qua US đã tham chiếu tới hàng đó) yêu cầu đúng chiều giao tiếp này — không chỉ tồn tại vì "có vẻ cần". Hàng nào không truy vết được về FR nào → hoặc xoá hàng đó, hoặc quay lại Bước A/hỏi user bổ sung FR trước khi giữ lại, không để nguyên không giải thích.

列出本次会话中已创建/修改的所有C4/接口契约文档——即使存在多个
c4-component-*.md
文件（每个容器对应一个），不得仅列出第一个或记忆中的文件。对于列表中的每个文件（

c4-context.md

、

c4-container.md

、每个

c4-component-<编号>.md

、

container-interface.md

、

entity-interface.md

）。手动复查不足以保证此步骤的准确性（实际错误案例：同一类型的第一个文件正确，后续创建的文件遗漏链接——即使提前知晓风险并刻意复查，仍有评估案例中5个C4文件里4个缺少链接）：列出

docs/glossary/glossary.md

中的所有术语，使用内置搜索工具（search/grep）逐个术语扫描列表中的每个文件，而非仅目视阅读。对于发现缺少链接的文件，检查正文首次出现的术语是否已添加链接（见Context图步骤1、

docs/spec-kit-conventions.md

第3条）。发现链接存在后——还需确认链接指向正确文件，不得仅满足于「有链接」（实际错误案例：21个文件的

../

层级错误仍通过检查，因为仅检查是否有链接，未检查指向是否正确）：统计每个链接中的

../

数量是否为1级——所有C4/接口契约文档都位于

docs/system-overview/

目录下，链接应始终为1级（

../glossary/glossary.md

，见第3节的层级表）；若层级错误则修改链接，不得仅视为「已有链接」而忽略。**若文件已标记

status: approved

**但发现缺少链接——需先将状态改回

draft

再修改（见

docs/spec-kit-conventions.md

第1条），不得直接修改内容而保留

approved

状态。

交叉核对CIC ↔ Component ↔ SIC的反向链接——同一轮操作中边写边自检容易遗漏自身产生的错误（与术语表检查的错误模式相同），因此需单独执行此步骤，不得仅依赖编写时的核对：

```
container-interface.md
```
第3节的CIC汇总表中，每个CIC编号对应的发起/处理组件名称需与对应
```
c4-component-*.md
```
的「关联CIC」列一致——双向核对：CIC表中列出的组件需反向链接到正确的CIC编号，且每个CIC编号都需在对应的组件反向链接中存在（无遗漏、无多余）。
若
```
entity-interface.md
```
已存在：所有未指向实体的CIC字段（自行列出字段而非引用实体）的名称需与SIC中对应字段名称一致——不得对同一概念使用不同名称（例如CIC中用
```
sku
```
而SIC中用
```
productId
```
）。
若
```
entity-interface.md
```
已存在：待确认假设章节中的所有假设/建议（根据当前模板确定正确章节名称/编号）是否已获得用户实际反馈，是否仍存在标注
```
[Agent建议]
```
但未实际询问的新假设——与术语表检查不同（仅检查链接缺失），此步骤检查内容是否已获得实际确认，严格程度与Component/Container的「与用户确认」步骤相同。对于每个已获得实际反馈的条目：若反馈修改了初始建议（添加/删除/修改值），核对对应实体的字段/关系表是否已更新以匹配反馈——实际错误案例：反馈明确拒绝某个值，但字段表仍保留该值，导致文档内部自相矛盾。

反向核对每个「交互」行与来源FR——系统概览仅能从已

approved

的FR/UR/BR生成（通用规则#2），但编写Container图时仍可能添加无需求依据的交互行（实际错误案例：与外部系统的双向交互因「技术上看似合理」而绘制，但无任何FR/用户故事要求该方向的交互）。对于

c4-container.md

「交互」表格中的每个新增/修改行（若

container-interface.md

已存在则对应CIC编号）：确认至少有一个FR（直接或通过引用该行的用户故事间接）要求该方向的交互——不得仅因「看似需要」而存在。无法追溯到FR的行→要么删除该行，要么返回A阶段/询问用户补充FR后再保留，不得无解释地保留。

Lỗi thường gặp cần tránh

需避免的常见错误

Nhồi chi tiết kỹ thuật vào Context Diagram — sai audience, người phi kỹ thuật không đọc nổi.
Vẽ Code diagram (Level 4) cho toàn bộ hệ thống khi chưa ai yêu cầu — tốn công, nhanh lỗi thời.
Tạo Component diagram hình thức cho container quá đơn giản (không có cấu trúc nội bộ đáng vẽ) — xem bước 4 ở Quy trình tạo Component Diagram.
Bỏ qua Context Diagram, nhảy thẳng vào Container — mất bối cảnh actor/hệ thống ngoài mà Container Diagram cần tham chiếu.
Không cập nhật diagram khi kiến trúc đổi — review lại Container/Component Diagram mỗi khi có Epic mới ảnh hưởng kiến trúc (bump
```
version
```
, không tạo file mới cho mỗi lần sửa).
Nhồi method HTTP/path/status code, hoặc tên bảng/cột/kiểu SQL cụ thể vào
```
container-interface.md
```
— đó đều là Code (Level 4), ngoài phạm vi tài liệu này (xem mục "Quy trình tạo Container Interface Contract").
Liệt kê component rồi tự ghi file luôn mà không thực sự dừng lại chờ xác nhận (bước 5 ở Quy trình tạo Component Diagram) — dễ để lọt 1 component không ai yêu cầu vào dữ liệu gốc mà không cơ chế nào ở tầng sau bắt lại được.
Tạo
```
entity-interface.md
```
cho hệ thống ít entity/quan hệ rời rạc — không cần thiết, field list ngay trong từng CIC đã đủ (xem bước 1 ở Quy trình tạo Entity Interface).
Để field của cùng 1 entity lệch nhau giữa
```
entity-interface.md
```
và các mục CIC trong
```
container-interface.md
```
— khi cả 2 file cùng tồn tại, CIC phải trỏ về entity thay vì tự liệt kê lại field (xem bước 6 ở Quy trình tạo Entity Interface).

向Context图中添加技术细节——受众错误，非技术人员无法理解。
在无人要求的情况下为整个系统绘制Code图（第4层级）——耗时且易过时。
为过于简单的容器（无值得建模的内部结构）形式化创建Component图——见「创建Component图流程」步骤4。
跳过Context图直接绘制Container图——丢失Container图需要参考的角色/外部系统上下文。
架构变更时未更新图——每当有影响架构的新Epic时，复查Container/Component图（更新
```
version
```
，不得为每次修改创建新文件）。
向
```
container-interface.md
```
中添加HTTP方法/路径/状态码，或具体表名/列名/SQL类型——这些都属于Code（第4层级），超出本文档范围（见「创建容器接口契约流程」）。
列出组件后直接写入文件而未暂停等待确认（「创建Component图流程」步骤5）——容易让未经需求的组件混入基础数据且无后续机制发现。
为实体/关系较少的系统创建
```
entity-interface.md
```
——无必要，直接在每个CIC中列出字段即可（见「创建实体接口流程」步骤1）。
同一实体的字段在
```
entity-interface.md
```
与
```
container-interface.md
```
的CIC条目中不一致——当两个文件同时存在时，CIC需指向实体而非自行列出字段（见「创建实体接口流程」步骤6）。