Files

Leonard-ThindPad-P50 c81f249920 init git

2026-09-08 10:26:21 +07:00

4.1 KiB

Raw Blame History

ADR- — <quyết định, viết ở thể khẳng định>

Tên file: adr/ADR-<nnn>_<slug-ngắn>.md — ví dụ ADR-007_chon-postgres-thay-mongo.md


Status	`Proposed` / `Accepted` / `Rejected` / `Superseded by ADR-nnn` / `Deprecated`
Date	YYYY-MM-DD
Người quyết	(ai ký — theo `decision-radar.md` §5)
Người đề xuất
Điểm radar	… /10 (chấm theo `decision-radar.md` §2)
Supersedes	—
Superseded by	—
Liên quan	`ASR-nnn` · `QAS-nnn` · `CON-nn` · `ADR-nnn`

⚠️ ADR bất biến sau khi Accepted. Muốn đổi quyết định thì viết ADR mới có Supersedes: ADR-<nnn> và đổi trạng thái bản cũ thành Superseded by. Không sửa nội dung ADR đã Accepted, không xoá ADR đã Rejected.

1. Bối cảnh

Tình huống buộc phải quyết. Viết ở thì hiện tại, mô tả sự thật đang có — không viết "chúng tôi sẽ…". Người đọc sau 2 năm phải hiểu được vì sao lúc đó việc này là một vấn đề.

Ràng buộc đang chi phối:

Nguồn	Nội dung
`CON-nn`
`QAS-nnn`
`ASR-nnn`

Cái đã biết chắc / cái còn là giả định:

Điều	🟢 Đã kiểm chứng / 🔴 Giả định	Bằng chứng
		POC-nn / bài đo / tài liệu …

2. Phương án đã cân nhắc

Bắt buộc ≥ 2 phương án (quy tắc D3). Một phương án duy nhất không phải quyết định.

PA-1 — <tên>


Mô tả
Ưu
Nhược
Chi phí đảo ngược	(nếu sau này sai thì sửa mất bao lâu)

PA-2 — <tên>

(cùng cấu trúc)

Bảng so sánh

Tiêu chí (sinh từ `QAS`/`CON`)	PA-1	PA-2

3. Quyết định

Chọn PA-…

Viết ở thể khẳng định, một câu, đủ cụ thể để kiểm chứng được là có tuân thủ hay không.

Vì sao: (gắn với CON-nn hoặc QAS-nnn cụ thể, không phải sở thích)

Phạm vi áp dụng: (toàn hệ thống / chỉ component nào / chỉ tới khi nào)

4. Phương án bị loại và lý do

Phương án	Loại vì	Gắn với	Điều kiện nào thì xét lại
PA-…		`CON-nn` / `QAS-nnn`

"Team quen công nghệ X" là lý do hợp lệ — nhưng phải viết thành CON-nn có tên, để sau này biết quyết định gắn với con người chứ không phải với kỹ thuật.

5. Hệ quả

Phần quan trọng nhất và bị viết sơ sài nhất. Ghi cả hệ quả tốt lẫn xấu — ADR chỉ có hệ quả tốt là ADR viết để hợp thức hoá.

Hệ quả tích cực

Hệ quả tiêu cực phải sống chung

Cái quyết định này khoá lại (chi phí đảo ngược sau này)

Muốn đổi về sau thì	Tốn

Việc phát sinh

Việc	Chủ	Hạn	Ghi ở đâu
Cập nhật `SAD` §…
Thêm fitness function			`FIT-nn`
Đào tạo team về …			`TCO` §5

6. Cách kiểm chứng quyết định này được tuân thủ

Quy tắc D8: không verify tự động được thì chỉ là khuyến nghị.

Cách kiểm	Công cụ	Chạy ở đâu	`FIT`
	ArchUnit / dependency-cruiser / lint / kiểm thử tải / kiểm tra hạ tầng	CI	`FIT-nn`

Không kiểm tự động được ⇒ ghi thẳng: ⚠️ Khuyến nghị — không tự kiểm được, và nêu cách kiểm thủ công cùng tần suất.

7. Điều kiện xét lại

ADR không vĩnh viễn. Ghi trước dấu hiệu nào thì phải mở lại quyết định này.

Dấu hiệu	Ngưỡng	Ai theo dõi
	(ví dụ: thông lượng vượt … msg/s, chi phí vượt … /tháng, team vượt … người)

8. Tham chiếu

POC: ARISK_… §6 POC-nn
Bài đo:
Tài liệu ngoài:
Thảo luận: (link biên bản họp, ngày)

4.1 KiB Raw Blame History