Ghi quyết định một trang (ADR) cho người và cho AI

Dành cho bất kỳ ai làm việc trong một nhóm có code, kể cả người mới và người đang giao việc cho AI agent. Không cần biết thiết kế phần mềm. Thuật ngữ nào cũng đi kèm một ví dụ đời thường, và phần tính toán được đánh dấu để bỏ qua nếu bạn không cần.

Số liệu lấy từ nguồn công khai, có liệt kê cuối bài. Ví dụ ghi là "minh họa" được dựng lại, không nhắc đến người hay công ty cụ thể. Cách AI agent đọc và dùng tài liệu bên trong chưa ai hiểu hết, nên các hình dung dưới đây chỉ là cách tưởng tượng để dễ nhớ. Các lời khuyên về AI trong bài là tổng hợp thực hành, không phải kết quả của một thử nghiệm đối chứng.

---

Tóm tắt nhanh#

• Phần khó nhất của một dự án thường không phải là code mà là lý do đằng sau code. Lý do hay nằm trong đầu một vài người, rồi đi mất cùng họ.
• ADR (architecture decision record, bản ghi quyết định) là một trang ngắn ghi một quyết định: bối cảnh, quyết định, hệ quả và trạng thái. Khuôn này do Michael Nygard đề xuất năm 2011, độ dài khuyến nghị là một đến hai trang.
• Người mới thiếu lý do thì chỉ còn hai đường, cả hai đều xấu: chấp nhận mà không hiểu, hoặc đảo ngược mà không biết hệ quả. Nygard mô tả đúng hai đường đó.
• AI agent cũng có thể gặp tình huống tương tự: thấy một đoạn code "rườm rà" và dọn gọn, không biết rằng sự rườm rà là có chủ ý. Một ADR được trỏ tới từ tệp hướng dẫn cho agent là chỗ để nó kiểm tra trước khi sửa.
• Một ADR tốt chỉ cần một trang: viết cho một người đọc trong tương lai, nêu cả phương án đã loại và điều ta chấp nhận đánh đổi. Bài có sẵn mẫu để dán.
• ADR không phải thủ tục cho mọi thay đổi. Quyết định nhỏ và dễ đảo thì không cần. Và ADR chỉ có ích nếu có người cập nhật trạng thái và có người đọc.

---

Từ khó, nói dễ#

---

1. Hình dung trước: dòng chú thích trong công thức#

Hình dung một quán ăn có cuốn sổ công thức. Món canh ghi: "Không cho muối, nêm bằng nước mắm cuối cùng." Một bạn mới vào bếp thấy canh nhạt, tiện tay cho thêm muối. Hôm đó một khách dị ứng muối gọi canh. Không ai sai ý định. Cuốn sổ chỉ thiếu một dòng: "vì sao không cho muối".

Giờ hình dung cuốn sổ có dòng đó: "Không cho muối, vì món này phục vụ cả khách ăn kiêng. Muối do khách tự thêm ở bàn." Bạn mới đọc là hiểu, và nếu quán đổi chính sách thì có chỗ để sửa dòng ấy.

ADR là dòng chú thích đó, nhưng cho code. Đồng thời, đối với một AI agent bước vào kho mã, nó là dòng chú thích mà agent đọc được, trước khi tiện tay "cho thêm muối".

Điều rút ra: thứ cần lưu không phải là cuốn sổ lớn mà là lý do của từng quyết định đáng nhớ, đủ ngắn để có người đọc.

---

2. ADR là gì, theo nguồn gốc#

2.1 Bản gốc của Michael Nygard (2011)#

Trong bài "Documenting Architecture Decisions" đăng ngày 15/11/2011 trên blog Cognitect, Michael Nygard viết rằng các quyết định kiến trúc thường không có ghi chép về lý do. Người mới vào dự án chỉ có hai đường: chấp nhận quyết định mà không hiểu, hoặc đảo ngược nó mà không biết hệ quả. Ông nói cả hai đều có thể làm hại dự án, và quá nhiều quyết định không giải thích khiến cả nhóm sợ đổi bất cứ thứ gì.

Ông đề xuất mỗi bản ghi gồm năm phần:

• Tiêu đề: cụm danh từ ngắn.
• Bối cảnh: các lực tác động lên quyết định (kỹ thuật, chính trị, xã hội, đặc thù dự án), nêu sự việc không phán xét.
• Quyết định: câu đầy đủ, thể chủ động, bắt đầu bằng "Chúng tôi sẽ".
• Trạng thái: "đề xuất" cho đến khi các bên đồng ý, rồi "đã chấp nhận". Về sau có thể là "không dùng nữa" hoặc "bị thay thế", kèm liên kết tới bản mới.
• Hệ quả: bối cảnh sau quyết định, gồm cả điều tích cực, tiêu cực và trung tính.

Về độ dài: một đến hai trang. Về giọng văn: viết như đang trò chuyện với một lập trình viên trong tương lai, dùng câu đầy đủ, chỉ dùng gạch đầu dòng để trình bày chứ không để thay câu bằng mảnh vụn. Về lưu trữ: trong kho mã của dự án, ví dụ doc/arch/adr-NNN.md, đánh số tuần tự và không dùng lại số. Quyết định bị đảo không bị xóa: bản cũ giữ nguyên và đánh dấu bị thay thế.

Nygard cũng kể một trải nghiệm: sau khoảng ba tháng dùng trên vài dự án, sáu đến mười lập trình viên luân phiên qua các dự án nói phần bối cảnh trong bản ghi có giá trị. Đây là lời kể của chính tác giả, mẫu nhỏ, không phải nghiên cứu đối chứng.

2.2 MADR: một mẫu Markdown phổ biến#

MADR (Markdown Architectural Decision Records) là một mẫu gọn viết bằng Markdown. Theo trang chính thức, các phần gồm: tiêu đề, phần đầu tùy chọn (trạng thái, ngày, người quyết định, người được hỏi, người được báo), bối cảnh và vấn đề, các yếu tố quyết định (tùy chọn), các phương án đã xét, kết quả quyết định (kèm hệ quả tốt xấu), cách xác nhận việc tuân thủ (tùy chọn), ưu nhược của từng phương án, và thông tin thêm (có thể ghi điều kiện để xem lại). Quy ước lưu trữ: thư mục docs/decisions, tên tệp NNNN-tieu-de-viet-lien.md với số thứ tự. Phiên bản mới nhất trang mô tả là 4.0.0, ngày 17/9/2024, cấp phép kép MIT hoặc CC0.

2.3 Y-statement: ADR trong một câu#

Y-statement là dạng rút gọn do Olaf Zimmermann và các tác giả gắn với nó phổ biến, một câu theo mẫu: "Trong bối cảnh (tình huống), đối mặt với (mối lo), chúng tôi chọn (phương án) và không chọn (các phương án khác), để đạt (mục tiêu chất lượng), chấp nhận (cái mất)." Các nguồn tôi đọc ghi từ nối khác nhau một chút ("and against" hoặc "and neglected"), nên hãy coi đây là mẫu, không phải chuẩn cứng. Y-statement hợp với quyết định đơn giản. Với quyết định phức tạp, các nguồn khuyên dùng mẫu đầy đủ như MADR hoặc bản của Nygard.

Điều rút ra: ADR không phải công cụ phức tạp. Cốt lõi là bốn câu hỏi: ta đang ở hoàn cảnh nào, ta chọn gì, ta bỏ gì, và ta chấp nhận mất gì.

---

3. Vì sao nhóm mất quyết định, và vì sao AI làm vấn đề rõ hơn#

3.1 Dữ liệu từ khảo sát Stack Overflow 2026#

Trang kết quả khảo sát Stack Overflow Developer Survey 2026 có phần về những khó khăn liên quan đến ngữ cảnh. Theo bản tóm tắt tôi đọc, khoảng 60,9% người trả lời nói ngữ cảnh quan trọng nằm trong đầu một số người, 56,5% nói thông tin đã cũ, 53,4% nói thông tin rải trong quá nhiều công cụ và 63,2% nói thông tin chưa đầy đủ. Tôi đọc qua bản tóm tắt chứ chưa đối chiếu từng bảng, câu hỏi gốc có thể rộng hơn chuyện quyết định kỹ thuật, và người trả lời là những người chịu làm khảo sát. Vì vậy hãy hiểu đây là tín hiệu chung rằng tri thức nhóm thường rời rạc, không phải bằng chứng về ADR.

3.2 Với AI agent: nhìn thấy code, không thấy lý do#

Hình dung agent như một đồng nghiệp rất nhanh nhưng mới vào hôm nay: đọc toàn bộ code trong vài giây, nhưng không nhớ cuộc họp tuần trước. Khi nó thấy một đoạn code vòng vèo, phản xạ hợp lý là đơn giản hóa. Nếu sự vòng vèo là kết quả của một quyết định có lý do, thứ duy nhất ngăn nó lại là lý do được viết ở chỗ nó tìm thấy.

Cần nói rõ về giới hạn: tôi chưa tìm thấy nghiên cứu nào đo việc đưa ADR vào ngữ cảnh làm giảm bao nhiêu lần agent đảo quyết định. Cách nhìn ở đây là một lập luận thực hành, nối với bài Sổ tay cho AI: AGENTS.md, nơi ta đặt những điều agent cần biết ở chỗ nó đọc.

3.3 Phép tính để bạn tự kiểm lại (minh họa, có thể bỏ qua)#

Đây là ví dụ minh họa với số dựng sẵn, không phải số đo. Giả sử một nhóm sáu người ghi hai quyết định mỗi tháng, mỗi ADR dài 300 từ, và tốc độ đọc tài liệu kỹ thuật là 150 từ mỗi phút (giả định). Một năm nhóm có 24 ADR.

adr, words, wpm = 24, 300, 150
read_all = adr * words / wpm          # 7200 từ, tức 48 phút
index = adr * 12 / wpm                # 24 tiêu đề, 12 từ mỗi dòng, tức 288 từ, gần 2 phút

asked, explain = 5, 15                # người mới hỏi lại 5 quyết định, senior giải thích 15 phút mỗi lần
without = asked * explain             # 75 phút của senior
with_adr = asked * words / wpm        # 5 ADR x 2 phút = 10 phút của người mới
print(read_all, round(index, 2), without, with_adr)
# 48.0 1.92 75 10.0

newcomers = 4
print(newcomers * without, newcomers * with_adr)
# 300 40.0  (phút mỗi năm)

Đọc kết quả: đọc hết 24 ADR mất khoảng 48 phút, đọc riêng danh sách tiêu đề mất gần 2 phút, nên không ai phải nạp hết mọi thứ. Nếu mỗi người mới hỏi lại 5 quyết định và senior giải thích 15 phút mỗi lần, đó là 75 phút của senior cho một người, tức 300 phút một năm với 4 người mới. Với ADR, người mới tự đọc 5 bản trong khoảng 10 phút mỗi người, tức 40 phút một năm.

Lưu ý rõ: 300 từ, 150 từ mỗi phút, 5 câu hỏi và 15 phút là số tôi giả định. ADR cũng tốn thời gian viết và cập nhật, và chưa tính ở đây. Hãy thay bằng số của nhóm bạn.

---

4. Mẫu một trang#

Hình dung phiếu nộp bài: ít ô, ô nào cũng bắt buộc điền, và đủ nhỏ để điền trong mười phút. Mẫu dưới đây dựa trên bản của Nygard, thêm hai ô lấy ý từ MADR (điều kiện xem lại và cách xác nhận) để quyết định có lối thoát và có cách kiểm.

# ADR 0007: Gửi nhắc lịch qua hàng đợi

Trạng thái: đã chấp nhận (đề xuất / đã chấp nhận / bị thay thế bởi ADR 00NN)
Ngày: 2026-03-12
Người quyết định: tên hoặc vai trò

## Bối cảnh
Hoàn cảnh và ràng buộc, nêu sự việc, không phán xét. Ai đang chờ gì?

## Quyết định
Chúng tôi sẽ (một hoặc hai câu đầy đủ, thể chủ động)

## Phương án đã loại
- Phương án A: vì sao không chọn.
- Phương án B: vì sao không chọn.

## Hệ quả
- Được: điều tốt.
- Mất: điều ta chấp nhận đánh đổi.
- Trung tính: điều chỉ thay đổi, không tốt không xấu.

## Khi nào xem lại
Điều kiện cụ thể khiến ta mở lại quyết định.

## Cách kiểm
Một kiểm tra tự động hoặc dấu hiệu quan sát được cho thấy quyết định vẫn được tuân thủ.

Ba quy tắc giữ trong một trang:

1. Một ADR, một quyết định. Nếu cần chữ "và" ở tiêu đề, có lẽ đó là hai quyết định.
2. Câu đầy đủ trong phần bối cảnh và quyết định. Gạch đầu dòng chỉ dành cho danh sách ngắn như phương án và hệ quả.
3. Chi tiết dài để ở nơi khác. Bảng so sánh, biểu đồ, kết quả thử nghiệm: đặt liên kết, không dán vào.

---

5. Ví dụ minh họa: một ADR đã điền#

Đây là ví dụ minh họa, dựng lại cho bài này, không nhắc đến công ty hay sản phẩm thật. Tình huống: một ứng dụng nhỏ giúp tiệm dịch vụ đặt lịch hẹn và gửi nhắc lịch qua email. Mọi con số trong ví dụ đều là bịa.

# ADR 0007: Gửi nhắc lịch qua hàng đợi, không gửi trong lúc xử lý yêu cầu

Trạng thái: đã chấp nhận
Ngày: 2026-03-12

## Bối cảnh
Khi khách đặt lịch, ứng dụng gửi email xác nhận ngay trong lúc xử lý yêu cầu.
Dịch vụ gửi email thỉnh thoảng phản hồi mất vài giây và từng lỗi cả giờ.
Trong thời gian đó trang đặt lịch treo, và có khách bấm đặt hai lần.

## Quyết định
Chúng tôi sẽ đưa việc gửi email vào một hàng đợi công việc. Yêu cầu đặt lịch
chỉ ghi lịch vào cơ sở dữ liệu rồi trả lời ngay. Một bộ xử lý riêng gửi email
và thử lại tối đa ba lần.

## Phương án đã loại
- Gửi trực tiếp trong yêu cầu: đơn giản nhất, nhưng trang treo khi dịch vụ chậm.
- Quét bảng mỗi phút bằng lịch chạy định kỳ: không cần hàng đợi, nhưng email trễ
  tới một phút và phải quét cả bảng lớn.

## Hệ quả
- Được: trang đặt lịch phản hồi nhanh, lỗi email không làm hỏng việc đặt lịch.
- Mất: thêm một thành phần phải theo dõi, email có thể đến trễ vài giây.
- Trung tính: nhật ký có thêm một nguồn cần đọc khi gỡ lỗi.

## Khi nào xem lại
Nếu trong sáu tháng số email gửi dưới 50 mỗi ngày, hoặc nhà cung cấp email
có sẵn hàng đợi tích hợp.

## Cách kiểm
Một test đảm bảo yêu cầu đặt lịch không gọi trực tiếp dịch vụ email.

Phiên bản Y-statement của cùng quyết định: "Trong bối cảnh đặt lịch hẹn, đối mặt với dịch vụ email chậm và hay lỗi, chúng tôi chọn đưa việc gửi vào hàng đợi và không chọn gửi trực tiếp hay quét bảng định kỳ, để trang đặt lịch luôn nhanh, chấp nhận thêm một thành phần phải theo dõi."

Bản đầy đủ dài khoảng 260 chữ trong tiếng Việt, nằm trong mục tiêu một trang (khoảng 300 từ). Điểm đáng chú ý: phần "Phương án đã loại" chính là thứ ngăn người và AI quay lại phương án đơn giản nhất, vì phương án đơn giản nhất là thứ ai cũng nghĩ tới trước.

---

6. Viết ADR sao cho AI agent đọc được và dùng được#

Hình dung bạn để lại một tờ ghi chú cho người trực ca sau: tờ ghi chú chỉ có ích nếu được dán đúng chỗ người đó nhìn thấy.

1. Đặt ADR trong kho mã, ví dụ thư mục docs/adr, đi cùng code và cùng lịch sử thay đổi.
2. Có một tệp danh mục liệt kê tiêu đề, trạng thái và đường dẫn của từng ADR, mỗi bản một dòng. Agent đọc danh mục rồi mở bản liên quan, nên không phải nạp hết.
3. Trỏ tới từ tệp hướng dẫn cho agent. Trong AGENTS.md hoặc tệp hướng dẫn của công cụ, thêm vài dòng như khối dưới đây.
4. Ghi trạng thái ở dòng đầu, bằng từ cố định (đề xuất, đã chấp nhận, bị thay thế), để cả người và máy lọc được.
5. Để người viết hai phần đầu. Bối cảnh và quyết định do người điền. AI có thể gợi ý phương án đã loại hoặc soạn nháp, nhưng một lý do nghe hợp lý chưa chắc là lý do thật. Người xác nhận lý do, đúng tinh thần của bài Làm cho kết quả của AI tự chứng minh.

## Quyết định đã có
- Trước khi đổi cách làm đã có trong docs/adr, đọc danh mục docs/adr/README.md
  và mở ADR liên quan.
- Nếu thay đổi của bạn trái với một ADR đã chấp nhận, dừng lại và hỏi,
  đừng tự sửa.
- Khi báo xong, ghi rõ bạn đã đọc ADR nào.

Ba dòng, đủ ngắn để người và agent đọc hết. Dòng cuối dùng ý của cách thứ tư trong bài về bằng chứng: tách điều đã đọc khỏi điều giả định.

---

7. Vòng đời của một ADR#

Điểm quan trọng nhất: không xóa bản cũ. Người đọc cần thấy cả điều ta từng quyết và vì sao ta đổi.

---

8. Khi nào không nên viết ADR#

Đây là quy tắc kinh nghiệm của tôi, không phải chuẩn của Nygard hay MADR. Hình dung thùng rác của nhà bếp: không phải thứ gì cũng cần cuốn sổ riêng.

• Không viết khi quyết định đảo lại được trong khoảng một giờ làm việc (đổi tên biến, chọn tên tệp).
• Không viết khi lý do đã có trong tài liệu chuẩn của công cụ và ai cũng tra được.
• Không viết chỉ để cho đủ thủ tục. Một ADR không ai đọc tốn công mà không ích gì.
• Nên viết khi người mới có khả năng hỏi "vì sao lại thế này?", khi đảo quyết định tốn hơn nửa ngày, hoặc khi ta vừa loại một phương án mà ai cũng sẽ nghĩ tới trước.

---

9. Chỗ nào ADR cũng hỏng#

Hình dung cuốn sổ công thức: có cuốn rất dày mà không ai mở, có cuốn ghi sai từ lâu.

9.1 Minh họa: một buổi sáng có và không có ADR#

Đây là tình huống minh họa, không nhắc đến người hay sản phẩm thật, dùng lại ví dụ ở mục 5.

Không có ADR:

• 09:00. Dev nhờ agent: "Dọn gọn phần đặt lịch, bớt các thành phần thừa."
• 09:20. Agent thấy hàng đợi gửi email như một lớp thừa và chuyển thành gọi trực tiếp. Mọi test hiện có đều đạt.
• 11:00. Dev đọc diff thấy hợp lý, gộp vào nhánh chính.
• 15:30. Dịch vụ email chậm. Trang đặt lịch treo, khách bấm đặt hai lần.

Có ADR và AGENTS.md trỏ tới:

• 09:00. Cùng yêu cầu.
• 09:10. Agent đọc danh mục ADR, mở ADR 0007 rồi báo: "Hàng đợi này là quyết định đã chấp nhận. Tôi không đổi. Bạn có muốn mở ADR mới để thay không?"
• 09:20. Dev trả lời: "Giữ nguyên. Chỉ dọn phần khác."
• 09:50. Agent nộp thay đổi, ghi "đã đọc ADR 0007, không đụng hàng đợi".

Việc nên làm ở cả hai: dừng lại ở bước agent muốn bỏ một thứ trông thừa và hỏi thứ đó có lý do không. Đây là minh họa nên không chứng minh điều gì. Tín hiệu từ khảo sát Stack Overflow (đã nêu ở mục 3) và lời kể của Nygard chỉ cho thấy việc thiếu ngữ cảnh là có thật, và bản ghi ngắn có thể giúp.

---

10. Số liệu và tài liệu đã dùng#

Đọc cho đúng: các nguồn trên ủng hộ việc ghi lại lý do ngắn gọn. Tôi chưa tìm thấy nghiên cứu đối chứng đo trực tiếp ADR làm giảm lỗi hay giúp AI agent tránh đảo quyết định. Phần về AI trong bài là tổng hợp thực hành.

---

11. Thói quen áp dụng từ ngày mai#

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

1. Đây là một quyết định, hay hai quyết định đang ghép?
2. Người đọc sau một năm có hiểu bối cảnh mà không cần hỏi ai không?
3. Phần quyết định bắt đầu bằng "Chúng tôi sẽ" và là câu đầy đủ chưa?
4. Đã ghi phương án đã loại và lý do loại chưa?
5. Hệ quả có cả cái mất và cái trung tính, không chỉ cái được?
6. Có điều kiện xem lại và cách kiểm cụ thể chưa?
7. Trạng thái và ngày ở dòng đầu, và danh mục đã cập nhật chưa?
8. AGENTS.md hoặc README có trỏ tới ADR này chưa?

11.2 Ba việc làm ngay#

1. Tạo thư mục docs/adr và một danh mục trống.
2. Chọn một quyết định gần đây mà người mới hay hỏi, rồi viết ADR đầu tiên trong khoảng 15 phút.
3. Thêm ba dòng ở mục 6 vào tệp hướng dẫn cho AI agent.

---

12. Nhìn cân bằng: ADR làm được gì, chưa làm được gì#

Làm được: giữ lại lý do, giúp người mới tự tìm câu trả lời, cho agent chỗ để kiểm tra trước khi sửa, và buộc nhóm nói rõ cái mất của mỗi quyết định.

Chưa làm được:

• ADR không bảo đảm quyết định đúng. Nó chỉ ghi lại việc ta đã nghĩ gì lúc đó.
• Một ADR không được cập nhật có thể gây hại hơn không có ADR, vì nó nói sai điều đang có hiệu lực.
• Agent không bắt buộc phải đọc ADR, và tôi chưa thấy thử nghiệm đo mức độ nó tuân theo. Hãy kiểm bằng cách yêu cầu agent báo đã đọc ADR nào.
• ADR tốn công viết và duy trì. Với nhóm rất nhỏ hoặc dự án ngắn hạn, một câu trong README có thể đủ.
• Lý do AI soạn thay có thể nghe trôi chảy mà không đúng. Cần người xác nhận.

Đừng thổi phồng: ADR không thay cho giao tiếp trong nhóm. Đừng coi nhẹ: chi phí của một quyết định mất lý do thường nằm ở cuối, khi ai đó đảo ngược nó vì không biết nó từng có lý do.

---

13. Kết luận#

Code cho thấy ta đã làm gì, ADR cho thấy vì sao. Một trang ngắn, viết ngay lúc quyết định, kể cả phương án đã bỏ và cái mất, có đường dẫn từ nơi người và AI sẽ đọc, đủ để nhiều quyết định khỏi bị đảo ngược chỉ vì không ai biết chúng từng có lý do. Hãy bắt đầu từ một quyết định mà người mới hay hỏi.

---

Nguồn tham khảo#

Số liệu lấy từ nguồn công khai tính đến tháng 10/2026. Một số con số được đọc qua bản tóm tắt, nên hãy mở nguồn gốc để kiểm tra trước khi trích dẫn.

• Michael Nygard, Documenting Architecture Decisions (Cognitect, 15/11/2011)
• Architectural Decision Records, adr.github.io và MADR (phiên bản 4.0.0)
• Olaf Zimmermann, Y-Statements (mẫu ADR một câu)
• Stack Overflow, 2026 Developer Survey (đọc qua bản tóm tắt, chưa đối chiếu từng bảng)