ADR (architecture decision record, bản ghi quyết định kiến trúc) là một tệp văn bản ngắn ghi lại một quyết định kỹ thuật quan trọng: bối cảnh lúc đó, quyết định là gì, và hệ quả chấp nhận. Mỗi quyết định một tệp, lưu ngay trong kho mã. Khi nhóm dùng tác tử AI, sổ ADR trở thành thứ chặn tác tử "dọn dẹp" ngược lại những lựa chọn đã cân nhắc kỹ, và là thứ người mới đọc để hiểu vì sao mã trông như vậy.
Khuôn ADR được Michael Nygard phổ biến qua một bài viết năm 2011, và từ đó nhiều nhóm dùng với các biến thể. Bài này đi từ cách viết một ADR trong mười lăm phút, cách tổ chức thư mục, đến cách nối sổ ADR với tệp hướng dẫn dự án để tác tử đọc đúng lúc. Phần viết tài liệu cho mã nguồn như README hay chú thích hàm có bài riêng ở danh mục giao việc cho AI.
Vấn đề ADR giải quyết, rõ hơn khi có AI trong nhóm
Mỗi dự án đều có những chỗ trông "sai" với người mới đến: một bảng dữ liệu không chuẩn hoá, một thư viện cũ không chịu nâng, một chức năng tự viết trong khi có thư viện sẵn. Thường đằng sau là một lý do có thật: hiệu năng, giới hạn của máy chủ khách hàng, một sự cố năm trước. Lý do đó nằm trong đầu người viết, trong một cuộc họp, trong một tin nhắn đã trôi mất.
Người mới gặp chỗ "sai" đó thì hỏi, hoặc sửa. Tác tử AI gặp thì không hỏi, nó sửa, vì nó được huấn luyện trên những cách làm phổ biến và coi điều khác thường là lỗi. Ví dụ giả định: nhóm cố ý ghi nhật ký bằng một hàm tự viết vì máy chủ của khách không cho ghi tệp ở thư mục mặc định. Tác tử được giao dọn mã, thấy hàm tự viết, thay bằng thư viện ghi nhật ký phổ biến. Mọi kiểm thử qua. Lên máy chủ khách thì hỏng.
ADR không phải tài liệu kiến trúc dày. Nó là những mẩu ngắn, mỗi mẩu trả lời một câu "vì sao lại thế này". Đủ ngắn để viết ngay khi quyết định, đủ cụ thể để một người, hay một tác tử, đọc xong biết không nên đổi nếu chưa xét lại bối cảnh.
Năm phần của một ADR
Khuôn gốc chỉ có vài đề mục. Giữ ngắn là điều kiện để nhóm thật sự viết; một ADR tốt thường dưới một trang.
| Phần | Nội dung | Ví dụ giả định |
|---|---|---|
| Tiêu đề | Số thứ tự và quyết định viết dưới dạng câu | Số 7: Ghi nhật ký qua hàm riêng, không dùng thư viện ghi tệp mặc định |
| Trạng thái | Đề xuất, đã chấp nhận, đã thay thế bởi số mấy | Đã chấp nhận |
| Bối cảnh | Tình huống, ràng buộc, các lựa chọn đã xét | Máy chủ của khách chỉ cho ghi vào một thư mục; thư viện phổ biến không cấu hình được đường dẫn đó ở bản đang dùng |
| Quyết định | Nhóm làm gì, một hai câu | Viết hàm ghi nhật ký riêng, ghi vào thư mục được phép, cùng định dạng dòng với thư viện |
| Hệ quả | Được gì, mất gì, khi nào nên xét lại | Phải tự bảo trì hàm; xét lại khi khách đổi máy chủ hoặc thư viện hỗ trợ cấu hình đường dẫn |
Mục "khi nào nên xét lại" không có trong mọi khuôn nhưng rất đáng thêm. Nó biến ADR từ một lời cấm thành một điều kiện: không phải "đừng bao giờ đổi", mà là "đổi được khi điều kiện này thay đổi". Tác tử đọc được điều kiện đó và có thể báo bạn khi thấy điều kiện đã khác.
Tổ chức sổ ADR trong kho mã
Cách tổ chức đơn giản nhất cũng là cách bền nhất:
- Tạo một thư mục cố định cho ADR trong thư mục tài liệu của kho, ví dụ thư mục con tên adr.
- Đặt tên tệp theo số thứ tự bốn chữ số và tiêu đề không dấu nối bằng gạch, để sắp xếp theo thứ tự thời gian.
- Không sửa nội dung ADR đã chấp nhận. Khi đổi quyết định, viết ADR mới, ghi trạng thái ADR cũ là đã được thay thế bởi số mới.
- Có một tệp mục lục liệt kê mọi ADR với một dòng tóm tắt và trạng thái; tác tử và người mới đọc tệp này trước.
- ADR mới đi qua yêu cầu gộp như mã, để cả nhóm thấy và góp ý trước khi chấp nhận.
Luật "không sửa, chỉ thay thế" là điểm làm ADR khác wiki. Wiki luôn hiện bản mới nhất và xoá dấu vết lý do cũ; sổ ADR giữ cả lịch sử suy nghĩ. Khi một quyết định bị đảo ngược hai lần, đọc chuỗi ADR là thấy ngay nhóm đang lặp vòng và vì sao.
Nối sổ ADR với tác tử AI
Nhắc sổ ADR trong tệp hướng dẫn dự án. Một dòng: trước khi đổi cấu trúc, thay thư viện, hay sửa những chỗ trông khác thường, đọc mục lục ADR và các ADR liên quan. Tệp hướng dẫn được nhiều công cụ tác tử nạp tự động mỗi phiên, nên dòng này đến được tác tử.
Ghi số ADR ngay cạnh chỗ mã khác thường. Một chú thích ngắn kiểu "xem ADR số 7" ở đầu hàm ghi nhật ký tự viết. Tác tử đọc tệp sẽ thấy chú thích ngay chỗ nó định sửa, chắc hơn là trông vào việc nó tự đi tìm sổ ADR.
Đưa ADR vào điểm dừng chuẩn. Trong danh sách tình huống tác tử phải dừng hỏi, thêm: định làm trái một ADR đang có hiệu lực. Tác tử nên nêu ADR nào, vì sao muốn đổi, rồi chờ.
Nhờ AI viết nháp ADR, người duyệt nội dung. Sau một buổi thảo luận, đưa ghi chú buổi họp cho AI để soạn nháp ADR theo khuôn. Phần bối cảnh và hệ quả phải do người trong cuộc đọc lại, vì AI dễ thêm lý do nghe hợp lý mà nhóm không hề cân nhắc. Nhớ che tên khách hàng và thông tin hợp đồng trong ghi chú trước khi đưa vào.
Một ADR mẫu viết trọn, để chép khuôn
Ví dụ giả định cho một nhóm làm ứng dụng đặt lịch cho tiệm cắt tóc. Tiêu đề: Số 12: Lưu giờ hẹn theo giờ địa phương của tiệm kèm mã múi giờ, không quy về giờ quốc tế. Trạng thái: đã chấp nhận.
Bối cảnh: phần lớn tiệm dùng ứng dụng nằm ở Việt Nam, nhưng đã có vài tiệm ở nước có giờ mùa hè. Cách phổ biến là quy mọi thời điểm về giờ quốc tế khi lưu. Với lịch hẹn tương lai, cách đó sai khi quy tắc giờ mùa hè của một nước thay đổi sau lúc khách đặt: giờ hẹn đã lưu sẽ lệch một tiếng so với giờ khách và tiệm thống nhất. Nhóm đã xét ba phương án: quy về giờ quốc tế, lưu giờ địa phương kèm mã múi giờ, lưu cả hai.
Quyết định: lịch hẹn tương lai lưu giờ địa phương của tiệm kèm mã múi giờ; thời điểm đã xảy ra như lúc tạo bản ghi, lúc thanh toán vẫn lưu theo giờ quốc tế. Hệ quả: truy vấn so sánh lịch giữa các tiệm khác múi giờ phức tạp hơn, phải quy đổi lúc đọc; hàm quy đổi nằm ở một mô-đun duy nhất. Tác tử và người mới không được "chuẩn hoá" cột giờ hẹn về giờ quốc tế. Xét lại nếu ứng dụng bỏ hẳn tính năng đặt lịch trước.
Toàn bộ ADR khoảng hai trăm chữ, viết trong mười lăm phút sau buổi họp. Chú ý câu về tác tử và người mới trong phần hệ quả: chính câu đó biến một ghi chép lịch sử thành chỉ dẫn hành động cho phiên làm việc sau.
Sổ ADR cho người mới vào nhóm
Với người mới, sổ ADR là con đường nhanh nhất để hiểu dự án ở tầng "vì sao". Một buổi chiều đọc hai ba chục ADR ngắn cho họ bức tranh mà nhiều tuần đọc mã chưa chắc có: những lựa chọn lớn, những lần nhóm đổi ý, những ràng buộc của khách hàng. Kết hợp với trợ lý AI, họ có thể hỏi về mã cụ thể và đối chiếu câu trả lời với ADR thay vì tin trọn lời AI.
Một bài tập hữu ích cho tuần đầu: giao người mới đọc sổ ADR, chọn một ADR, rồi tìm trong mã những chỗ quyết định đó thể hiện ra. Họ được dùng AI để tìm và giải thích mã. Cuối tuần, họ trình bày năm phút. Bài tập này buộc họ đi qua mã thật với một câu hỏi rõ ràng, và thường lòi ra những ADR đã lỗi thời mà nhóm quên cập nhật.
Ngược lại, khi người mới đề xuất đổi một chỗ đã có ADR, đừng gạt đi. Bối cảnh có thể đã đổi thật. Mời họ viết ADR mới đề xuất thay thế, với phần bối cảnh nêu điều gì đã khác. Đó là cách người mới đóng góp vào tầng kiến trúc mà không gây xáo trộn.
Những lỗi khiến sổ ADR chết sau vài tháng
Nhiều nhóm bắt đầu hào hứng rồi bỏ. Các nguyên nhân hay gặp:
- Viết quá dài, quá trang trọng: mỗi ADR thành một tài liệu thiết kế, không ai muốn viết thêm.
- Viết cho mọi thứ nhỏ nhặt: đặt tên biến, chọn thư viện định dạng ngày. ADR dành cho quyết định khó đảo ngược hoặc dễ bị hiểu nhầm.
- Viết sau khi quyết định đã cũ: lý do đã quên một nửa, ADR thành hồi ký mơ hồ. Viết ngay trong tuần quyết định.
- Không ai đọc: không có mục lục, không nhắc trong tệp hướng dẫn, không gắn số ADR vào mã.
- Không cập nhật trạng thái: ADR đã bị thay thế vẫn ghi "đã chấp nhận", tác tử và người mới làm theo quyết định cũ.
Một mẹo giữ nhịp: trong buổi nhìn lại định kỳ của nhóm, dành hai phút hỏi tuần này có quyết định nào đáng ghi ADR không. Câu hỏi đều đặn hiệu quả hơn bất kỳ quy định bắt buộc nào. Nếu tuần nào cũng không có, cũng tốt: nghĩa là nhóm đang làm trong khuôn đã định, chưa có gì cần ghi.
Câu hỏi thường gặp
ADR khác tài liệu thiết kế kỹ thuật ở điểm nào?
Tài liệu thiết kế mô tả hệ thống sẽ được xây thế nào, thường dài và viết trước khi làm. ADR ghi một quyết định riêng lẻ và lý do, ngắn, có thể viết bất cứ lúc nào có quyết định. Một tài liệu thiết kế có thể sinh ra nhiều ADR.
Dự án nhỏ một hai người có cần ADR không?
Có ích ngay cả với một người, vì sáu tháng sau chính bạn cũng quên lý do. Với dự án nhỏ, chỉ cần ghi những quyết định khó đảo ngược, có lẽ năm bảy cái trong cả dự án.
Có nên lưu ADR trên wiki thay vì trong kho mã?
Lưu trong kho mã có lợi là đi cùng phiên bản mã, được rà qua yêu cầu gộp, và tác tử AI đọc được ngay khi làm việc trong kho. Wiki tiện cho người ngoài nhóm kỹ thuật đọc; có thể liên kết từ wiki sang thư mục ADR.
Tác tử AI có tự động đọc sổ ADR không?
Không chắc, tuỳ công cụ và cách bạn cấu hình. Cách chắc hơn là nhắc trong tệp hướng dẫn dự án, ghi số ADR cạnh mã liên quan, và đưa việc làm trái ADR vào điểm phải dừng hỏi.
Ai nên viết ADR trong nhóm?
Người đề xuất quyết định viết nháp, nhóm góp ý qua yêu cầu gộp, trưởng nhóm hoặc người phụ trách kiến trúc chấp nhận. Không nên để một người viết hết, vì sổ ADR sẽ phản ánh góc nhìn của một người.
Có nên viết ADR bù cho các quyết định cũ?
Nên viết bù cho vài quyết định gây hiểu nhầm nhiều nhất, những chỗ người mới hay hỏi hoặc tác tử hay sửa sai. Không cần viết bù toàn bộ lịch sử; ghi rõ trong ADR là viết bù và phần bối cảnh có thể không đầy đủ.