c4-architecture

Tổng quan về skill c4-architecture

Skill c4-architecture giúp bạn tạo tài liệu kiến trúc phần mềm dưới dạng sơ đồ Mermaid C4, chứ không chỉ “vẽ vài cái hộp”. Đây là lựa chọn phù hợp nhất cho kỹ sư, technical writer, staff architect và các nhóm cần tài liệu kiến trúc giải thích hệ thống đúng theo mức độ mà từng đối tượng người đọc cần: context cho người đọc tổng quan, container cho các bên liên quan kỹ thuật, component cho lập trình viên và deployment view cho đội vận hành.

c4-architecture dùng để làm gì

Hãy dùng c4-architecture khi công việc thực sự là biến một codebase, bức tranh dịch vụ hiện có hoặc mô tả hệ thống còn thô thành tài liệu kiến trúc có cấu trúc. Skill này đặc biệt hữu ích khi bạn cần sơ đồ có thể sống cùng Markdown và version control, thay vì một bản export từ whiteboard chỉ dùng một lần.

Trường hợp sử dụng phù hợp nhất

c4-architecture skill đặc biệt phù hợp để:

• tài liệu hóa một repo sẵn có phục vụ onboarding
• tạo system context và container view cho ADR hoặc tài liệu kỹ thuật
• giải thích microservices, hệ thống event-driven và các phụ thuộc bên ngoài
• tạo sơ đồ kiến trúc cho docs site, wiki hoặc pull request
• xây dựng nội dung kiến trúc cho quy trình Technical Writing

Điểm khác biệt so với một prompt vẽ sơ đồ thông thường

Một prompt thông thường có thể tạo ra câu trả lời trông giống sơ đồ, nhưng skill này cho bạn workflow rõ ràng hơn và mặc định tốt hơn:

• lấy mô hình C4 làm trung tâm, giúp các mức trừu tượng sạch và nhất quán hơn
• xem Context và Container là lớp nền bắt buộc, không phải phần tùy chọn
• kèm hướng dẫn cú pháp cho Mermaid C4 diagrams
• chỉ ra các lỗi mô hình hóa phổ biến trước khi bạn xuất bản tài liệu gây hiểu nhầm
• có các pattern nâng cao cho microservices và những hệ thống phức tạp hơn

Điều người dùng thường muốn biết đầu tiên

Trước khi cài hoặc gọi c4-architecture, đa số người dùng thường muốn biết:

• Nếu hệ thống của tôi mới chỉ được hiểu một phần thì có dùng được không? Có, miễn là bạn cung cấp được actor, dịch vụ chính, data store và external system.
• Có phù hợp với tài liệu ưu tiên Markdown không? Có, vì đầu ra Mermaid chính là giá trị cốt lõi.
• Technical writer không có chuyên môn kiến trúc sâu có dùng hiệu quả không? Có, vì skill này khá rõ ràng và có chủ đích về các level cũng như lỗi thường gặp.
• Nó có thay thế được quá trình review kiến trúc chuyên sâu không? Không. Nó giúp tăng tốc bản nháp đầu tiên và tài liệu hóa có cấu trúc, nhưng độ chính xác của hệ thống vẫn phụ thuộc vào đầu vào của bạn.

Cách dùng skill c4-architecture

Cài c4-architecture trong môi trường skills của bạn

Nếu agent của bạn hỗ trợ mẫu skills CLI mà repository này dùng, hãy cài bằng:

npx skills add softaworks/agent-toolkit --skill c4-architecture

Nếu môi trường của bạn nạp skills từ repository đã clone, hãy dùng skill tại:

skills/c4-architecture

Đọc các file này trước khi dùng c4-architecture lần đầu

Để có một c4-architecture guide ngắn gọn nhưng nhiều tín hiệu, hãy đọc theo thứ tự sau:

1. skills/c4-architecture/SKILL.md
2. skills/c4-architecture/references/common-mistakes.md
3. skills/c4-architecture/references/c4-syntax.md
4. skills/c4-architecture/references/advanced-patterns.md
5. skills/c4-architecture/README.md

Vì sao thứ tự này hiệu quả:

• SKILL.md cho bạn workflow mà skill hướng tới
• common-mistakes.md giúp tránh các lỗi mô hình hóa phổ biến nhất
• c4-syntax.md giúp bạn debug đầu ra Mermaid nhanh hơn
• advanced-patterns.md đặc biệt quan trọng khi hệ thống của bạn không phải một monolith đơn giản

Chọn đúng level C4 trước khi prompt với c4-architecture

Yếu tố tác động lớn nhất đến chất lượng khi c4-architecture usage là chọn đúng level cho đúng đối tượng người đọc:

• C4Context: luôn bắt đầu từ đây; cho thấy người dùng và external system
• C4Container: thường là bắt buộc; cho thấy app, database, queue và service
• C4Component: chỉ thêm khi cấu trúc bên trong thực sự giúp người đọc hiểu hơn
• C4Deployment: dùng cho các vấn đề runtime/infrastructure
• C4Dynamic: dùng cho các luồng request hoặc event quan trọng

Một lỗi rất thường gặp là nhảy thẳng vào component, khiến sơ đồ rối ngay từ đầu trước khi người đọc kịp hiểu ranh giới hệ thống.

Cung cấp cho skill đúng mức đầu vào tối thiểu mà nó thực sự cần

Bạn không cần bộ ghi chú kiến trúc hoàn hảo, nhưng vẫn cần đủ cấu trúc để tránh tạo ra topology bị “hallucinated”. Đầu vào tốt thường gồm:

• tên hệ thống và mục đích
• người dùng chính hoặc external actor
• các service/app/datastore chủ chốt
• external system hoặc vendor
• các relationship và protocol quan trọng
• đối tượng người đọc
• các level sơ đồ mong muốn
• file đầu ra hoặc vị trí tài liệu

Nếu bạn chỉ nói “make a C4 diagram for my app”, hãy chờ một đầu ra khá chung chung.

Biến một yêu cầu sơ sài thành prompt c4-architecture mạnh hơn

Prompt yếu:

Create a C4 diagram for our platform.

Prompt tốt hơn:

Use the c4-architecture skill to document our B2B analytics platform. Audience: engineering and product. Create C4Context and C4Container diagrams in Mermaid plus brief Markdown explanations. System boundary: Analytics Platform. Actors: Customer Admin, Analyst. External systems: Okta, Stripe, Snowflake, SendGrid. Internal containers: React web app, API gateway, Python ingestion service, dbt transform jobs, PostgreSQL app DB, Redis cache. Show key relationships and protocols. Avoid component-level detail unless necessary.

Phiên bản tốt hơn cho kết quả chất lượng hơn vì nó chỉ rõ đối tượng người đọc, phạm vi, ranh giới, actor, container nội bộ và các phụ thuộc bên ngoài.

Dùng workflow thực tế với c4-architecture, đừng kỳ vọng một phát ăn ngay

Quyết định có nên c4-architecture install hay không thường phụ thuộc vào việc workflow của nó có khớp với công việc tài liệu hóa thực tế hay không. Trong thực tế, bạn nên làm như sau:

1. yêu cầu context diagram trước
2. rà soát actor và external system còn thiếu
3. sinh container diagram
4. chỉ bổ sung component hoặc deployment view ở nơi người đọc thực sự cần
5. lưu sơ đồ vào Markdown cùng phần giải thích ngắn

Cách làm theo từng bước này tốt hơn nhiều so với việc yêu cầu cùng lúc năm loại sơ đồ, vì lỗi ở Level 1 và 2 sẽ lan xuống toàn bộ các sơ đồ cấp thấp hơn.

Dùng c4-architecture hiệu quả cho Technical Writing

c4-architecture for Technical Writing rất phù hợp khi người viết cần tài liệu kiến trúc dễ đọc, dễ bảo trì và được version cùng code. Skill này giúp bằng cách tạo ra các sơ đồ có thể nhúng trực tiếp trong Markdown và đi kèm phần diễn giải ngắn.

Với các tác vụ technical writing, hãy thêm:

• mức độ người đọc mục tiêu: executive, mixed technical, developer, ops
• glossary hoặc tên sản phẩm đã được chốt
• thuật ngữ ưu tiên cho service và team
• vị trí tài liệu, ví dụ /docs/architecture/
• liệu đầu ra có cần giải thích vì sao từng sơ đồ tồn tại hay không

Điều này giúp tránh tình huống phổ biến: sơ đồ có vẻ đúng về mặt kỹ thuật nhưng lại lệch với giọng văn tài liệu hoặc cấu trúc thông tin của bộ docs.

Nắm các quy tắc mô hình hóa ảnh hưởng mạnh nhất đến chất lượng đầu ra

Tài liệu về lỗi trong repository nêu ra một số quy tắc đặc biệt quan trọng:

• container là các đơn vị deploy/runtime, không phải class
• component là các phần bên trong một container
• đừng tự bịa thêm các level C4 không chính thức
• giữ mức trừu tượng nhất quán trong cùng một sơ đồ
• chỉ thêm chi tiết phục vụ quyết định của người đọc

Nếu chỉ nhớ một điều, hãy nhớ điều này: phần lớn sơ đồ C4 tệ không hỏng vì sai cú pháp mà vì trộn lẫn các level.

Dùng tài liệu tham chiếu khi đầu ra Mermaid của c4-architecture bị lỗi

Khi sơ đồ sinh ra không render được hoặc nhìn sai về cấu trúc, hãy kiểm tra:

• references/c4-syntax.md để xem các khai báo và phần tử Mermaid C4 hợp lệ
• cú pháp relationship và boundary trước tiên
• bạn đã dùng đúng loại sơ đồ hay chưa, ví dụ C4Container hay C4Component

Skill này dễ dùng hơn một prompt chung chung một phần cũng vì tài liệu cú pháp cho bạn lộ trình sửa lỗi rõ ràng.

Khi nào cần đến các advanced pattern của c4-architecture

Hãy mở references/advanced-patterns.md khi kiến trúc của bạn có:

• microservices với nhiều ranh giới service
• API gateway
• workflow event-driven hoặc dựa trên queue
• nhiều hơn một ranh giới ownership
• infrastructure hoặc deployment view cần node và environment thực tế

File này đặc biệt hữu ích khi mô hình tư duy kiểu “một hệ thống, một app, một database” sẽ dẫn tới tài liệu gây hiểu nhầm.

Câu hỏi thường gặp về skill c4-architecture

c4-architecture có phù hợp cho người mới bắt đầu không?

Có, đặc biệt nếu bạn mô tả được hệ thống bằng ngôn ngữ thông thường. Workflow và tài liệu lỗi thường gặp của skill giúp giảm các lỗi C4 phổ biến. Người mới nên bắt đầu chỉ với Context và Container, đồng thời tránh Component diagram cho đến khi ranh giới hệ thống đã ổn định.

Khi nào không nên dùng c4-architecture?

Hãy bỏ qua c4-architecture nếu bạn chỉ cần một bản phác nhanh mang tính không chính thức, một artifact thiết kế cần độ hoàn hảo về pixel, hoặc một mô hình thiết kế nội bộ nặng về UML. Skill này mạnh nhất khi bạn muốn tài liệu kiến trúc có thể bảo trì bằng Mermaid, chứ không phải một bản thiết kế triển khai chi tiết đến mức bao quát mọi thứ.

Có tốt hơn việc hỏi AI tạo Mermaid diagram trực tiếp không?

Thường là có, nếu mục tiêu là tài liệu kiến trúc. Prompt chung có thể sinh ra Mermaid, nhưng c4-architecture cho bạn cấu trúc vững hơn: chọn level, kỷ luật mô hình hóa, tài liệu cú pháp và các anti-pattern đã được nhận diện. Nhờ vậy nó đáng tin cậy hơn cho các tài liệu mà người khác sẽ đọc và duy trì lâu dài.

c4-architecture có dùng được cho cả monolith và microservices không?

Có. Với monolith, skill này giúp tách bạch context, container và những component view thực sự cần thiết. Với microservices, tài liệu advanced patterns đặc biệt hữu ích để quyết định khi nào service nên được thể hiện như container, và khi nào nên được xem là ranh giới hệ thống rộng hơn.

Tôi có cần quyền truy cập toàn bộ codebase không?

Không, nhưng tài liệu nguồn càng tốt thì kết quả càng chính xác. Skill có thể làm việc từ ghi chú kiến trúc, cấu trúc repo, danh sách service, tài liệu API, deployment manifest hoặc mô tả từ stakeholder. Nếu đầu vào của bạn chưa đầy đủ, hãy yêu cầu skill ghi rõ các giả định.

Tôi có thể dùng c4-architecture cho deployment và runtime view không?

Có. Skill hỗ trợ C4Deployment và cả dynamic flow diagram. Chỉ nên dùng các dạng này khi topology runtime hoặc luồng request thực sự quan trọng với người đọc; nếu không, chúng dễ làm tăng nhiễu.

Cách cải thiện skill c4-architecture

Bắt đầu từ fact, đừng bắt đầu từ cấu trúc suy diễn

Cách nhanh nhất để cải thiện đầu ra của c4-architecture là cung cấp một danh sách fact trước khi yêu cầu vẽ sơ đồ:

• users
• system boundary
• deployable units
• data stores
• external dependencies
• protocols
• environments hoặc mô hình hosting

Cách này giúp giảm các relationship nghe có vẻ tự tin nhưng lại sai.

Yêu cầu liệt kê giả định một cách tường minh

Một bổ sung rất đáng giá cho prompt là:

If any element is uncertain, list assumptions before generating the final Mermaid.

Điều này đặc biệt hữu ích khi bạn đang tài liệu hóa một hệ thống được bàn giao lại hoặc dùng skill từ những ghi chú còn thiếu.

Rà soát output context và container trước khi đi sâu hơn

Đừng chấp nhận component diagram cho đến khi lớp context và container đã đúng. Nếu mô hình container sai, chi tiết component chỉ làm tài liệu trông bóng bẩy hơn trong khi bản chất vẫn không chính xác.

Sửa lỗi về mức trừu tượng một cách dứt khoát

Nếu đầu ra thể hiện class, package hoặc endpoint như container, hãy dừng lại và sửa ngay điểm đó. Hướng dẫn trong common-mistakes.md rất quan trọng vì sai level trừu tượng sẽ khiến toàn bộ tài liệu trở nên khó tin cậy.

Một prompt sửa lỗi hữu ích là:

Revise this as a true C4Container diagram. Only include deployable applications, services, data stores, and external systems. Move internal modules to a later component view.

Luôn chỉ rõ audience trong mọi yêu cầu nghiêm túc

Audience sẽ quyết định thế nào là “đủ tốt”:

• executives cần context, kết quả và các phụ thuộc bên ngoài
• engineers cần container, protocol và ranh giới trách nhiệm
• developers có thể cần chi tiết component bên trong một container
• ops teams cần deployment node và environment

Nếu không có audience, skill có thể tạo ra mức độ chi tiết sai ngay cả khi cú pháp hoàn toàn hợp lệ.

Ghép sơ đồ với phần diễn giải ngắn gọn

Skill sẽ hữu ích hơn nhiều nếu bạn yêu cầu thêm 2–5 bullet dưới mỗi sơ đồ để nêu:

• sơ đồ này thể hiện điều gì
• vì sao chọn level này
• các tương tác chính
• những gì được cố ý loại ra

Bổ sung nhỏ này khiến đầu ra dễ dùng hơn rõ rệt trong docs và các luồng review.

Lặp lại bằng chỉnh sửa có mục tiêu, không phải viết lại từ đầu

Sau lượt đầu tiên, hãy nâng chất lượng bằng các chỉnh sửa tập trung như:

• thêm external system còn thiếu
• đổi tên container cho khớp thuật ngữ sản phẩm
• tách một service đang bị nhồi quá nhiều trách nhiệm thành hai container
• thêm protocol vào relationship
• loại bỏ chi tiết component khỏi container view
• tạo deployment view chỉ cho production

Cách lặp có mục tiêu sẽ giữ lại cấu trúc tốt sẵn có và hội tụ nhanh hơn nhiều so với kiểu “try again”.

Dùng c4-architecture như một hệ thống tài liệu, không chỉ là công cụ sinh sơ đồ

Cách dùng lâu dài tốt nhất của c4-architecture skill là chuẩn hóa tài liệu kiến trúc trong repo của bạn. Hãy đặt các sơ đồ Mermaid gần code hoặc docs, review chúng trong pull request và cập nhật chúng khi service hoặc ranh giới thay đổi. Đó chính là điểm skill này vượt trội so với prompt ad hoc: nó hỗ trợ tài liệu kiến trúc lặp lại được, thuần Markdown và có thể duy trì theo thời gian.