ADR và tài liệu kỹ thuật: ghi lại vì sao, không chỉ cái gì Trung cấp

Trang này cho bạn bản đồ của cụm: mỗi loại tài liệu trả lời câu hỏi nào, và nên đọc phần nào trước.

Vấn đề

Kỹ sư mới hỏi: “Sao order service không publish Kafka ngay sau commit mà phải qua bảng outbox?” Không ai trả lời được. Người quyết định đã nghỉ, thread Slack đã trôi mất.

Hai kết cục quen thuộc, đúng như Nygard mô tả năm 2011:

• Chấp nhận mù quáng (cargo-culting): giữ outbox, rồi copy sang cả service không cần, vì “kiến trúc nó vậy”.
• Đảo ngược mù quáng (re-litigating): ai đó “đơn giản hoá” về publish trực tiếp. Ba tháng sau, sự cố mất event lặp lại.

Code trả lời cái gì. Git log trả lời khi nào, ai. Không gì trong repo trả lời vì sao, đã loại phương án nào: đó là chỗ của ADR.

Luồng tài liệu và thứ tự đọc

Đang tải diagram…

Trong cụm này

Phần	Câu hỏi nó trả lời
ADR là gì	ADR là gì, khi nào đáng viết, chọn Nygard hay MADR?
Viết ADR tốt	Một ADR tốt trông thế nào, đổi ý thì làm gì với ADR cũ?
Docs ngoài ADR	Design doc, Diátaxis, runbook on-call, sơ đồ C4 dùng khi nào?
Giữ docs sống	Làm sao để docs không mục; checklist review ADR và README
Lỗi hay gặp	ADR, runbook, README hay viết sai thế nào, hậu quả ra sao?

Tóm tắt: câu hỏi nào, tài liệu nào

Câu hỏi của người đọc	Loại tài liệu	Viết khi nào	Sống ở đâu
“Vì sao hệ thống làm thế này?”	ADR	Ngay khi chốt một quyết định khó đảo ngược	docs/adr/NNNN-*.md trong repo
“Nên làm thế nào, phương án nào?”	Design doc / RFC	Trước thay đổi lớn, còn mơ hồ	Repo hoặc công cụ doc của team, link từ ADR
“Chạy service này lên thế nào?”	README (quickstart)	Từ commit đầu tiên	README.md ở gốc repo
“Alert X đang kêu, làm gì?”	Runbook	Cùng PR thêm alert	docs/runbooks/, link từ alert
“Endpoint/event/env var này nhận gì?”	Reference	Sinh từ code nếu được	OpenAPI, schema event, bảng config
“Các khối lớn nối với nhau ra sao?”	Sơ đồ C4 mức 1–2	Khi thêm/bớt service hoặc datastore	docs/architecture.md

Mặc định của cụm: mọi thứ trên nằm trong repo, review trong cùng PR với code. Ngoại lệ hay gặp là design doc cần comment rộng ngoài team.

Tóm tắt

• Code nói “cái gì”, git nói “khi nào”; chỉ ADR nói “vì sao, và đã loại phương án nào”.
• Viết ADR khi quyết định khó đảo ngược hoặc sẽ bị hỏi lại; quyết định “không làm X” cũng đáng ghi.
• Nygard (Title, Context, Decision, Status, Consequences) đủ để bắt đầu; MADR 4.0.0 khi cần liệt kê phương án và cách kiểm chứng.
• ADR accepted là bất biến; đổi ý thì viết ADR mới và supersede. Số tăng đơn điệu, không dùng lại.
• Design doc trước khi quyết, ADR khi chốt. Phần còn lại tổ chức theo Diátaxis; runbook gắn với alert; C4 mức 1–2 đủ cho đa số service.
• Docs sống khi nằm trong repo, review cùng PR, có owner, và doc sai được xoá.

Tiếp theo: ADR là gì và khi nào viết.