Giải thích cho người mới · 10/2026

Ghi quyết định
một trang

Một trang ADR ghi vì sao nhóm chọn cách này. Người mới đọc được, AI agent cũng đọc được. Có mẫu để dán.

Ví dụ đời thường Mẫu một trang Ví dụ tính được Danh sách kiểm
ADR 0007 Vì sao lại thế này?
Câu hỏi của bài này

Code không cho biết vì sao ta làm vậy

1Lý do nằm trong đầu vài người, rồi đi mất cùng họ. Người mới chỉ thấy code.
2Một trang ADR giữ lại lý do. Người mới đọc được, và AI agent cũng đọc được.
3Chưa ai hiểu hết cách AI đọc tài liệu. Hình ảnh trong bài chỉ để dễ nhớ, lời khuyên về AI là tổng hợp thực hành.
Hình dung trước

Cuốn công thức thiếu một dòng

Thiếu dòng “vì sao”

“Không cho muối”

Bạn mới thấy canh nhạt, tiện tay cho muối. Hôm đó có khách dị ứng muối gọi món.

Có dòng “vì sao”

“Không cho muối, vì khách ăn kiêng”

Bạn mới đọc là hiểu. Nếu quán đổi chính sách, có chỗ để sửa dòng ấy.

ADR là dòng chú thích đó, nhưng cho code. AI agent cũng đọc được nó.
Từ khó, nói dễ

Sáu từ sẽ gặp trong bài

ADR

bản ghi quyết định

Một trang ghi vì sao nhóm chọn cách này, như dòng chú thích trong công thức.

Bối cảnh

tên kỹ thuật: context

Hoàn cảnh lúc quyết định: cần gì, bị ràng buộc gì, ai đang chờ.

Quyết định

tên kỹ thuật: decision

Điều nhóm sẽ làm, viết thành câu đầy đủ bắt đầu bằng “Chúng tôi sẽ”.

Hệ quả

tên kỹ thuật: consequences

Điều xảy ra sau quyết định: cái được, cái mất và cái trung tính.

Trạng thái

tên kỹ thuật: status

Bản ghi đang ở đâu: đề xuất, đã chấp nhận hay bị thay thế.

Bị thay thế

tên kỹ thuật: superseded

Quyết định cũ hết hiệu lực vì có bản mới. Bản cũ được giữ lại và đánh dấu.

Michael Nygard, 2011

Người mới chỉ có hai đường, cả hai đều xấu

Đường 1

Chấp nhận mà không hiểu

Làm theo vì “xưa nay vẫn vậy”. Không biết khi nào nên đổi.

Đường 2

Đảo ngược mà không biết hệ quả

Sửa cho gọn. Rồi một lý do cũ quay lại gây chuyện.

Theo Nygard (15/11/2011), quá nhiều quyết định không giải thích làm cả nhóm sợ đổi bất cứ thứ gì.
Cấu trúc

Năm phần của một ADR

1Tiêu đềMột cụm danh từ ngắn
2Bối cảnhNêu sự việc, không phán xét
3Quyết địnhCâu đầy đủ, thể chủ động, bắt đầu bằng “Chúng tôi sẽ”
4Trạng tháiĐề xuất, đã chấp nhận, rồi có thể bị thay thế
5Hệ quảCả cái được, cái mất và cái trung tính
Số liệu · Stack Overflow 2026

Tri thức nhóm hay rời rạc

Thông tin chưa đầy đủ63,2%
Ngữ cảnh nằm trong đầu người60,9%
Thông tin đã cũ56,5%
Rải trong nhiều công cụ53,4%

Phần trăm người trả lời khảo sát nói đây là khó khăn về ngữ cảnh.

Tín hiệu chung: tri thức nhóm thường rời rạc. Không phải bằng chứng về ADR.

Đọc qua bản tóm tắt, chưa đối chiếu từng bảng. Mẫu là người chịu trả lời.

Với AI agent

Agent thấy code, không thấy lý do

Agent thấy
  • Một đoạn code vòng vèo
  • Mọi test hiện có đều đạt
  • Cơ hội để làm cho gọn
Agent không thấy
  • Cuộc họp tuần trước
  • Vì sao đoạn code lại vòng vèo
  • Phương án đã loại và lý do
ADR được trỏ tới từ tệp hướng dẫn là chỗ để agent kiểm tra trước khi sửa.
Mẫu một trang

Mẫu một trang, mười phút là điền xong

ADR 0007: Tiêu đề ngắn
Trạng thái · Ngày · Người quyết định
Bối cảnh: hoàn cảnh, ràng buộc
Quyết định: Chúng tôi sẽ
Phương án đã loại: và vì sao
Hệ quả: được, mất, trung tính
Khi nào xem lại: điều kiện cụ thể
Cách kiểm: một kiểm tra tự động
Ba quy tắc
  • Một ADR, một quyết định
  • Câu đầy đủ ở bối cảnh và quyết định
  • Chi tiết dài thì để liên kết

Hai ô cuối lấy ý từ MADR, để quyết định có lối thoát và có cách kiểm.

Minh họa, không có thật

Ví dụ: ADR 0007 gửi nhắc lịch

ADR 0007: Gửi nhắc lịch qua hàng đợi
Quyết định: đưa việc gửi email vào
hàng đợi, trả lời yêu cầu đặt lịch ngay.
Đã loại: gửi trực tiếp (trang treo),
quét bảng mỗi phút (email trễ).
Được: trang nhanh. Mất: thêm một thành phần.
Xem lại: dưới 50 email mỗi ngày trong 6 tháng.

Phần “đã loại” ngăn người và AI quay lại phương án đơn giản nhất, vì ai cũng nghĩ tới nó trước.

Minh họa: công ty, sản phẩm và mọi con số đều là bịa.

Ví dụ tính được

Tính thử: 24 ADR một năm

adr, words, wpm = 24, 300, 150
read all = 24 * 300 / 150 48 min
index only = 24 * 12 / 150 1.92 min
senior = 5 * 15 75 min
newcomer = 5 * 300 / 150 10 min

Minh họa: mọi con số là giả định, chưa tính thời gian viết ADR. Hãy thay bằng số của nhóm bạn.

Đọc hết 24 ADR mất 48 phút. Chỉ đọc danh mục tiêu đề: gần 2 phút.

Senior giải thích 5 quyết định: 75 phút. Người mới tự đọc 5 ADR: 10 phút.

Cho cả người lẫn AI

Viết sao cho AI agent đọc được

1Đặt ADR trong kho mãVí dụ thư mục docs/adr, đi cùng code
2Có một tệp danh mụcMỗi ADR một dòng: tiêu đề, trạng thái, đường dẫn
3Trỏ tới từ AGENTS.mdNếu trái một ADR đã chấp nhận, dừng lại và hỏi
4Trạng thái ở dòng đầuDùng từ cố định để người và máy cùng lọc được
5Người viết hai phần đầuAI soạn nháp được, nhưng lý do nghe hợp lý chưa chắc là thật
Quy tắc kinh nghiệm của tác giả

Khi nào không cần viết ADR

Không viết
  • Đảo lại được trong khoảng một giờ
  • Lý do đã có trong tài liệu chuẩn
  • Chỉ để cho đủ thủ tục
Nên viết
  • Người mới sẽ hỏi “vì sao thế này?”
  • Đảo quyết định tốn hơn nửa ngày
  • Vừa loại phương án ai cũng nghĩ tới trước
Trong công việc

ADR cũng có chỗ hỏng

1Viết sau khi đã quên lý doViết ngay lúc quyết định, hoặc ghi “chưa rõ lý do ban đầu”
2Quá dàiGiữ một trang, chi tiết để liên kết
3Không cập nhật trạng tháiHỏi “ADR nào bị ảnh hưởng?” trong mẫu PR
4Không ai đọcTrỏ từ AGENTS.md, README và mẫu PR
5AI soạn lý do nghe hợp lý nhưng saiNgười điền bối cảnh, hỏi “ai chứng kiến điều này?”
Minh họa, không có thật

Minh họa: một buổi sáng, hai kịch bản

Không có ADR
09:20 · AgentHàng đợi này là lớp thừa, đổi thành gọi trực tiếp.
11:00 · DevTest đạt, diff hợp lý, gộp.
15:30 · KháchTrang đặt lịch treo, tôi bấm đặt hai lần.
Có ADR và AGENTS.md
09:10 · AgentADR 0007 đã chấp nhận hàng đợi này. Tôi không đổi. Có muốn mở ADR mới không?
09:20 · DevGiữ nguyên, chỉ dọn phần khác.
09:50 · AgentXong. Đã đọc ADR 0007, không đụng hàng đợi.
Dừng ở chỗ agent muốn bỏ thứ trông thừa và hỏi nó có lý do không.
Danh sách kiểm

Tám câu hỏi trước khi chốt một ADR

1Một quyết định hay hai quyết định ghép?
2Người đọc sau một năm hiểu bối cảnh?
3Quyết định bắt đầu bằng “Chúng tôi sẽ”?
4Đã ghi phương án đã loại và lý do?
5Hệ quả có cả cái mất?
6Có điều kiện xem lại và cách kiểm?
7Trạng thái và danh mục đã cập nhật?
8AGENTS.md hoặc README đã trỏ tới?
Nhìn cân bằng

Nhìn cân bằng: được gì, chưa được gì

Làm được
  • Giữ lại lý do của quyết định
  • Người mới tự tìm câu trả lời
  • Cho agent chỗ kiểm tra trước khi sửa
  • Buộc nhóm nói rõ cái mất
Chưa làm được
  • Không bảo đảm quyết định đúng
  • ADR cũ không cập nhật có thể hại hơn không có
  • Chưa thấy thử nghiệm đo agent tuân theo ADR
  • Tốn công, nhóm rất nhỏ có thể chỉ cần một câu trong README
Kết luận

Code cho thấy ta đã làm gì. ADR cho thấy vì sao.

Bắt đầu từ một quyết định mà người mới hay hỏi. Một trang, viết ngay lúc quyết định, có đường dẫn từ nơi người và AI đọc.