Radar quyết định — cái gì cần ADR, cái gì không

Câu hỏi khó nhất của nghề SA không phải "quyết thế nào" mà "cái này có phải việc của tôi không". Tài liệu này chốt ngưỡng đó, để skill và người dùng không tranh cãi mỗi lần.

1. Phép thử một câu

Quyết định sai, sửa mất ≤ 2 ngày → không phải việc của SA. Ghi DEC-nn là đủ. Sai mà sửa mất ≥ 4 tuần, hoặc phải migrate dữ liệu, hoặc phải đổi contract công khai → bắt buộc ADR. Ở giữa → dùng bảng chấm điểm §2.

2. Bảng chấm điểm

Chấm 5 tiêu chí, mỗi tiêu chí 0–2 điểm.

#	Tiêu chí	0 điểm	1 điểm	2 điểm
1	Chi phí đảo ngược	< 2 ngày	1–3 tuần	> 4 tuần hoặc phải migrate dữ liệu
2	Bán kính ảnh hưởng	Trong một module	Nhiều module cùng team	Nhiều team / hệ thống ngoài / khách hàng
3	Chạm thuộc tính chất lượng	Không	Ảnh hưởng gián tiếp	Quyết định trực tiếp một `QAS` mức Must
4	Ràng buộc dài hạn	Đổi lúc nào cũng được	Ràng trong một release	Ràng buộc ≥ 1 năm (license, vendor, mô hình dữ liệu)
5	Tranh cãi	Cả team đồng ý ngay	Có ý kiến khác	Đã tranh luận ≥ 2 lần hoặc có bên phản đối

Tổng	Xử lý
0–2	Không ghi gì. Là quyết định thi công, thuộc Tech Lead/Dev
3–4	Ghi `DEC-nn` trong `00-index/` — một dòng, không cần ADR
5–7	`ADR` bắt buộc
8–10	`ADR` + phải có POC hoặc bài đo trước khi chuyển `Accepted`

🔴 Tiêu chí 5 hay bị coi thường. Một quyết định team đã cãi nhau hai lần mà không ai ghi lại sẽ được cãi lại lần thứ ba, thứ tư — chi phí thật nằm ở đó, không nằm ở kỹ thuật.

3. Danh mục quyết định thường đạt ngưỡng ADR

Dùng làm checklist rà soát: dự án nào cũng nên trả lời được từng dòng, hoặc bằng một ADR, hoặc bằng câu "không áp dụng vì …".

Cấu trúc hệ thống

Kiểu kiến trúc tổng thể (modular monolith / microservices / serverless / hybrid)
Ranh giới service — cắt theo đâu, vì sao (thường là quyết định đắt nhất cả dự án)
Đồng bộ hay bất đồng bộ giữa các thành phần lõi
Có event bus / message broker không, loại nào
Chiến lược multi-tenant (chung DB / chung schema / tách schema / tách DB)

Dữ liệu

Loại CSDL chính và vì sao (quan hệ / tài liệu / khoá-giá trị / cột / đồ thị)
Ai là single source of truth cho từng thực thể lõi
Consistency model: mạnh hay eventual, eventual thì trễ tối đa bao nhiêu
Cơ chế giao dịch xuyên service (saga / outbox / 2PC / không có)
Chiến lược migration dữ liệu legacy, cách rollback
Sharding / partitioning, khoá phân mảnh
Retention và xoá dữ liệu cá nhân (ràng buộc pháp lý)

Tích hợp

Kiểu contract công khai (REST / GraphQL / gRPC / event)
Chính sách versioning và thời gian hỗ trợ phiên bản cũ
Idempotency: khoá là gì, giữ bao lâu
Cách xử lý khi hệ thống ngoài hỏng (degrade / hàng đợi / từ chối)

Bảo mật

Mô hình xác thực (session / JWT / OAuth2 / mTLS) và nơi giữ trạng thái
Mô hình phân quyền (RBAC / ABAC / kết hợp) và chỗ ra quyết định (gateway hay service)
Quản lý secret và xoay khoá
Phân loại dữ liệu nhạy cảm và ranh giới mã hoá
Mô hình audit log: ghi gì, giữ bao lâu, ai đọc được

Hạ tầng & vận hành

Cloud/vùng, và có ràng buộc dữ liệu phải nằm trong lãnh thổ không
Mô hình chạy (VM / container / K8s / PaaS / serverless)
Chiến lược HA và DR kèm RTO/RPO
Chiến lược release (blue-green / canary / rolling) và cách rollback
Bộ observability và nơi giữ log, chi phí kèm theo

Frontend (khi giải pháp có giao diện)

SPA / SSR / hybrid và lý do gắn với QAS (SEO, thời gian hiển thị đầu, thiết bị yếu)
Chiến lược trạng thái và cache phía client
Cách xử lý số lớn (id/số tiền vượt 2^53) xuyên suốt tầng giao diện
Chiến lược đa ngôn ngữ và nơi giữ chuỗi hiển thị

4. Cái KHÔNG nên viết ADR

Viết ADR cho những thứ này làm loãng sổ quyết định, và người đọc sẽ ngừng đọc:

Không ADR	Vì sao	Ghi ở đâu
Chọn thư viện tiện ích (date, lodash…)	Thay được trong một buổi chiều	Không ghi, hoặc `AGD`
Quy ước đặt tên, format code	Không phải quyết định kiến trúc	`AGD`
Cấu trúc thư mục trong một module	Bán kính hẹp	`AGD`
Chọn màu, spacing, component UI	Thuộc design system	Tài liệu thiết kế
"Dùng interface hay abstract class"	Quyết định thi công	Code review
Bug fix, tối ưu cục bộ	Không ràng buộc gì về sau	Commit message

🔴 Ngoại lệ: một quyết định nhỏ trở thành ADR khi nó thiết lập tiền lệ. "Dùng thư viện X" là nhỏ; "mọi service từ nay dùng cùng một thư viện logging và cùng một định dạng log" là ADR, vì nó ràng buộc mọi service tương lai.

5. Ai được đề xuất, ai được chốt

Loại quyết định	Đề xuất	Chốt	Phủ quyết
Cấu trúc hệ thống, dữ liệu, tích hợp	SA	SA + Tech Lead	EA (nếu lệch chuẩn doanh nghiệp)
Bảo mật, quyền riêng tư	SA	Security	Security
Hạ tầng, HA/DR, chi phí vận hành	SA	SA + SRE	PO (nếu vượt ngân sách)
Đánh đổi nghiệp vụ (rẻ hơn nhưng chậm hơn)	SA trình bảng	PO	—
Công cụ, thư viện, quy ước code	Tech Lead	Tech Lead	SA (nếu chạm `QAS`)

Dev và Tech Lead được quyền đề xuất ADR. Một tổ chức mà chỉ SA viết được ADR là tổ chức mà kiến trúc sẽ bị vòng qua chứ không bị phản biện.

6. Khi nào một ADR cần POC trước

Bắt buộc POC trước khi chuyển Proposed → Accepted nếu có bất kỳ điều nào:

Điểm radar ≥ 8
Quyết định dựa trên một con số hiệu năng chưa ai đo trong ngữ cảnh này
Công nghệ chưa ai trong team từng chạy production
Phụ thuộc vào hành vi của hệ thống bên ngoài mà ta chỉ đọc tài liệu, chưa gọi thật
Ước lượng chi phí hạ tầng dựa trên suy đoán, không có báo giá hay bài đo

POC phải có tiêu chí pass/fail viết trước khi làm, và kết quả (kể cả fail) ghi vào ARISK rồi tham chiếu từ ADR. POC không có tiêu chí trước là POC luôn "thành công".

7.1 KiB Raw Blame History Unescape Escape