ADR là gì, khi nào viết, chọn Nygard hay MADR Trung cấp

Thời gian đọc ước tính: 3 phút

Cần đọc trước

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

Trang này trả lời: ADR là gì (và không là gì), quyết định nào đáng một ADR, và nên bắt đầu bằng template nào.

ADR là gì, không là gì

Theo adr.github.io, một ADR “ghi lại một architectural decision và lý do của nó”, kèm trade-off và hệ quả. Tập hợp ADR của project là decision log.

ADR là	ADR không là
Một quyết định, một file, 1–2 trang (Nygard)	Tài liệu thiết kế 20 trang
Bối cảnh tại thời điểm quyết định	Mô tả hệ thống hiện tại, sửa liên tục
Bất biến sau khi accepted; đổi ý thì viết ADR mới	Wiki page ai cũng sửa đè
Nói thẳng hệ quả xấu	Bài “bán” giải pháp
Viết cho kỹ sư 2 năm sau, câu đầy đủ	Biên bản họp, gạch đầu dòng cụt

Nygard nhấn mạnh: mỗi ADR nên đọc như một cuộc trò chuyện với developer tương lai. Viết thành câu và đoạn; bullet chỉ để trình bày, không để thay câu.

Khi nào viết ADR, khi nào không

Hai câu hỏi lọc gần như mọi trường hợp: khó đảo ngược không? và người khác sẽ thắc mắc không?

Đang tải diagram…

Đáng một ADR	Không cần ADR
Dùng transactional outbox thay vì publish sau commit	Đổi tên biến, tách hàm
Giữ modular monolith, chưa tách microservice	Nâng patch version một thư viện
Ranh giới bounded context: Shipping có model `Order` riêng	Chọn format log (đã có convention chung)
Trừ tồn kho bằng `READ COMMITTED` + `SELECT ... FOR UPDATE` thay vì `SERIALIZABLE` (xem isolation levels)	Thêm một index (ghi trong migration là đủ)
Chọn PostgreSQL thay vì MongoDB cho order	Quy ước đã có trong linter / style guide
Không làm một điều mọi người tưởng nên làm (ví dụ: không cache số dư)	Chi tiết triển khai bên trong một module

Quyết định “không làm” thường đáng ghi nhất. Nó vô hình trong code, nên là thứ bị đề xuất lại nhiều nhất.

Nygard vs MADR

Hai template phổ biến. Tên section dưới đây lấy đúng theo bài gốc của Nygard và template MADR 4.0.0 (phát hành 2024-09-17).

	Nygard (2011)	MADR 4.0.0
Section	Title, Context, Decision, Status, Consequences	Title, Context and Problem Statement, Decision Drivers, Considered Options, Decision Outcome (Consequences, Confirmation), Pros and Cons of the Options, More Information*
Metadata	Status là một section	YAML front matter*: `status`, `date`, `decision-makers`, `consulted`, `informed`
Phương án đã loại	Không có section riêng (thường viết trong Context)	Bắt buộc liệt kê `Considered Options`
Kiểm chứng tuân thủ	Không có	`Confirmation`: design review, test tự động
Status gợi ý	proposed, accepted, deprecated, superseded	proposed, rejected, accepted, deprecated, superseded by ADR-NNNN
Đặt file	`doc/arch/adr-NNN.md`	`docs/decisions/NNNN-title-with-dashes.md`
Hợp với	Team nhỏ, muốn bắt đầu trong 10 phút	Nhiều phương án cạnh tranh, cần audit

* = optional theo template MADR.

Đang tải diagram…

Mặc định đề xuất: dùng Nygard, thêm mục “Phương án đã cân nhắc” ngắn trong Context. Khi team bắt đầu cãi về phương án bị loại, chuyển sang MADR. Đừng mất một sprint chọn template.

Tiếp theo: Viết một ADR tốt.

#engineering #adr #documentation #madr