Khi khách đổi ý, ADR giúp dự án khỏi cãi lại từ đầu

Thử hình dung tháng thứ ba của một dự án. Một giám đốc mới phía khách hàng vào họp và hỏi: “Sao dữ liệu lại đồng bộ theo đêm? Phải real-time chứ.” Cả phòng quay sang nhìn bạn.

Người từng đồng ý với thiết kế đó đã chuyển công tác, email cũ chìm đâu đó trong hộp thư, còn bạn chỉ nhớ lờ mờ rằng hồi đó có một lý do rất hợp lý.

Microsoft Learn mô tả đúng cảnh này: một quyết định đã chốt mà không được ghi lại thì dễ bị quên, rồi dẫn tới tranh luận lặp lại hoặc những thay đổi về sau vô tình đi ngược ý định ban đầu. Đội hoặc làm theo vì không ai đủ lý lẽ phản bác, hoặc cố giữ một quyết định mà không ai nhớ vì sao.

FDE làm việc ngay tại chỗ khách, nơi người và yêu cầu phía khách có thể thay đổi giữa chừng, nên cảnh này rất dễ gặp. Công cụ rẻ nhất để chống lại nó là Architecture Decision Record, gọi tắt là ADR, và chỉ cần một đến hai trang giấy.

ADR ghi lại lý do, vì lý do là thứ người ta quên trước

Michael Nygard, trong bài viết năm 2011 về việc ghi lại quyết định kiến trúc, cho rằng một trong những thứ khó theo dõi nhất suốt vòng đời dự án là động cơ đằng sau các quyết định. Ông đặt giới hạn rõ: cả tài liệu chỉ nên dài một hoặc hai trang. Martin Fowler còn chặt hơn, khuyên giữ ADR ngắn gọn, thường chỉ một trang.

adr.github.io định nghĩa mỗi ADR ghi lại một quyết định kiến trúc duy nhất cùng lý do của nó, và tập hợp các ADR của dự án là nhật ký quyết định. AWS Prescriptive Guidance nói thẳng mục đích: không phải bàn đi bàn lại cùng một chủ đề kiến trúc.

Ba phần tối thiểu, hai chi tiết hay bị bỏ qua

Theo AWS, tối thiểu mỗi ADR phải có bối cảnh của quyết định, bản thân quyết định, và hệ quả của nó với dự án. Phần bối cảnh nên liệt kê cả các phương án đội đã cân nhắc. Thêm trạng thái và lịch sử thay đổi, bạn có đủ khung để dùng khi khách đổi ý.

Hai chi tiết phân biệt một ADR dùng được với một ADR cho có. Chi tiết đầu là phần hệ quả: ghi cả mặt xấu, không chỉ ưu điểm. Một ADR toàn ưu điểm đọc như tài liệu bán hàng và khó thuyết phục ai khi có người phản đối.

Chi tiết thứ hai là cách viết câu quyết định. Nên viết dứt khoát kiểu “Đội dùng…” thay vì “nên dùng…”. Câu “nên dùng batch” mở cửa cho tranh cãi, còn câu “Đội dùng batch” là một cam kết.

Một ADR mẫu cho tình huống ở đầu bài

Thử hình dung bạn đang triển khai một agent tìm kiếm hồ sơ cho một công ty bảo hiểm. Phòng IT của họ chỉ mở bản sao chỉ đọc (read replica) của database từ 0h đến 5h sáng, vì ban ngày hệ thống lõi đang chịu tải. Bạn chọn đồng bộ theo đêm. ADR sẽ trông thế này:

# ADR-0007: Đồng bộ hồ sơ vào chỉ mục tìm kiếm theo batch mỗi đêm

## Status
Accepted (đại diện IT phía khách xác nhận)

## Context
- Agent cần dữ liệu hồ sơ từ hệ thống lõi của khách.
- IT khách chỉ cho phép đọc read replica trong khung 0h–5h.
- Người dùng chính là nhân viên thẩm định, họ xử lý hồ sơ của ngày hôm trước.
- Phương án đã cân nhắc:
  1. Batch mỗi đêm từ read replica.
  2. Real-time qua change data capture: IT khách chưa cho phép.
  3. Gọi API hệ thống lõi theo từng truy vấn: rủi ro gây tải giờ cao điểm.
- Xem lại quyết định nếu IT mở CDC hoặc thẩm định cần hồ sơ trong ngày.

## Decision
Đội dùng job batch chạy lúc 1h sáng, đọc read replica và cập nhật chỉ mục.

## Consequences
- Tốt: không chạm vào hệ thống lõi giờ hành chính.
- Xấu: hồ sơ tạo trong ngày chưa tìm được cho tới sáng hôm sau.
- Xấu: job lỗi một đêm thì dữ liệu chậm thêm một ngày; cần cảnh báo.
- Trung tính: nếu IT mở CDC, phải viết ADR mới.

Hãy để ý dòng cuối phần Context và dòng cuối phần Consequences. Chúng ghi ra điều kiện mà nếu thay đổi thì quyết định cần được xem lại. Chính hai dòng đó biến ADR từ một tờ ghi chú thành một công cụ đàm phán.

Khi khách đổi ý, đừng sửa ADR cũ

Quay lại buổi họp tháng thứ ba. Bạn không cần bảo vệ thiết kế cũ, cũng không cần nhượng bộ ngay. Bạn mở ADR-0007 và hỏi: IT đã cho phép change data capture chưa? Hay nhân viên thẩm định giờ phải xử lý hồ sơ trong ngày?

Nếu câu trả lời là không, cuộc tranh luận có thể kết thúc nhanh, vì lý do cũ vẫn còn nguyên. Nếu là có, bối cảnh đã thực sự đổi và việc đổi ý là hợp lý. Lúc đó, quy tắc của Fowler rất chặt: ADR đã được chấp nhận thì không bao giờ mở lại hay sửa, mà phải được thay thế bằng một ADR mới.

Cụ thể, bạn viết ADR-0012 cho phương án real-time, ghi bối cảnh mới và lịch sử thay đổi. ADR-0007 đổi trạng thái thành “Superseded by ADR-0012”.

Nygard viết rằng khi một quyết định bị đảo ngược, bản cũ vẫn được giữ lại, chỉ đánh dấu là superseded. Microsoft Learn khuyên liên kết hai bản với nhau, còn AWS Prescriptive Guidance nhấn mạnh phải giữ bản cũ trong nhật ký quyết định.

Sáu tháng sau, người mới đọc chuỗi này sẽ hiểu dự án đã đi qua những bước nào, và vì sao.

ADR nên nằm trong gói bàn giao

Một cách làm gọn là đặt ADR ngay trong repo chứa phần code nó mô tả, trong thư mục docs/adr/ với các file đánh số. Lợi ích lớn nhất với FDE đến vào ngày bàn giao: nhật ký quyết định đi cùng code, nằm cạnh README và runbook, nên đội vận hành phía khách không phải tìm trong một wiki mà họ có thể không vào được.

Hãy coi thư mục đó là một phần của gói bàn giao, ngang hàng với tài liệu cài đặt. Runbook trả lời câu hỏi “chạy thế nào”, còn ADR trả lời câu hỏi người tiếp quản sẽ hỏi khi muốn đổi thứ gì đó: “sao lại làm thế này?”.

Trong buổi bàn giao, dành vài phút đi qua danh sách ADR đang Accepted và những điều kiện khiến chúng cần xem lại.

Viết ngay khi quyết định vừa chốt, lúc lý do còn mới trong đầu mọi người, đừng dồn đến tuần cuối. Blog kiến trúc của AWS khuyên mỗi ADR chỉ tập trung vào một quyết định. Nếu thấy mình viết chữ “và” trong tiêu đề, hãy tách thành hai file.

Những lỗi khiến ADR thành giấy lộn

Lỗi phổ biến nhất là viết quá dài. Một ADR năm trang khó có ai đọc hết, nên nó khó cứu được buổi họp nào. Lỗi thứ hai là bỏ trống phần phương án đã cân nhắc: khi giám đốc mới đề xuất real-time, bạn cần cho thấy phương án đó đã được xét và bị loại vì sao.

Lỗi thứ ba là chỉ ghi ưu điểm, khiến người phản đối có cớ nghi ngờ cả tài liệu. Lỗi thứ tư là sửa trực tiếp ADR cũ khi đổi ý, làm mất dấu vết lịch sử, đúng thứ mà ADR sinh ra để giữ.

Lỗi cuối cùng là chỉ đội kỹ thuật biết ADR tồn tại. Trạng thái Accepted chỉ có giá trị khi người có thẩm quyền phía khách đã đọc và xác nhận.

Một kỹ năng nên đưa vào hồ sơ xin việc

Tài liệu kỹ thuật là việc thật trong mô tả công việc FDE. Tin tuyển dụng Forward Deployed Engineer của Tungsten Automation liệt kê việc viết tài liệu kỹ thuật riêng cho khách và các thực hành tốt nhằm hạn chế thất thoát kiến thức. ADR là một cách cụ thể để làm đúng việc đó.

Vì thế, khi đọc tin tuyển dụng, hãy tìm những dòng về documentation hay knowledge loss và nhắc tới thói quen này ở đó. Một vài ADR đã ẩn thông tin khách hàng trong portfolio, hoặc một câu chuyện phỏng vấn về lần bạn dùng ADR để chốt một đề nghị đổi kiến trúc, có sức nặng hơn mọi tính từ trên CV.

Khách sẽ luôn đổi ý, và đó là quyền của họ. Việc của bạn là để mỗi lần đổi ý chỉ tốn một trang giấy mới, không phải ba tuần tranh luận lại từ đầu.