Từ RFC đến ADR: Đạt được Quyết định và Giữ gìn Lý do

Quyết định mà không ai có thể tái tạo lại.

Người lãnh đạo công nghệ mới đặt ra một câu hỏi hợp lý: tại sao mọi dịch vụ lại giao tiếp với hệ thống thanh toán thông qua hàng đợi đó? Có một ADR — ADR-014, bốn câu, được viết cách đây mười một tháng. Ngữ cảnh: "chúng tôi cần tích hợp thanh toán đáng tin cậy." Quyết định: "sử dụng hàng đợi." Hệ quả: "một số độ trễ thêm vào." Về mặt kỹ thuật, đây là một bản ghi. Nó không trả lời được gì.

Bạn đã ở đó, vì vậy bạn biết ADR-014 không nói gì: cuộc tranh luận kéo dài ba tuần qua hai kênh Slack và một chuỗi PR căng thẳng; tùy chọn API đồng bộ đã thua vì một giới hạn tỷ lệ mà sau đó đã được nâng lên; sự phản đối của kỹ sư chính đã được trả lời bằng một bài kiểm tra mà không ai có thể tìm thấy bây giờ. Cuộc tranh luận đã diễn ra. Hồ sơ đã được viết lại sau đó, từ trí nhớ, bởi một người, vào một ngày thứ Sáu.

Đây là chế độ thất bại gần như phổ quát đã được tài liệu hóa của một thực hành thực sự tốt. Hướng dẫn quy định của AWS và tài liệu Well-Architected của Microsoft đều khuyến nghị sử dụng ADR — và cả hai đều lưu ý về nỗi đau: việc giữ cho chúng luôn cập nhật tốn thời gian, và việc quản lý chúng trở nên phức tạp khi các nhóm và lựa chọn gia tăng. Nguyên nhân gốc rễ là cấu trúc: cuộc tranh luận và hồ sơ sống ở những nơi khác nhau, vì vậy hồ sơ luôn là một bản sao không đầy đủ. Giải pháp là làm cho chúng trở thành cùng một nơi. Thực hành này không chỉ dành riêng cho kỹ thuật, hoặc thậm chí là riêng cho ADR. Google yêu cầu một tài liệu thiết kế — vấn đề, phương pháp đề xuất, các lựa chọn đã xem xét, các đánh đổi — được viết và xem xét trước khi công việc kỹ thuật quan trọng bắt đầu, một thực hành được nêu trong Kỹ thuật Phần mềm tại Google của công ty. Nó là cùng một kỷ luật như một ADR, được áp dụng sớm hơn một bước: ADR ghi lại lựa chọn mà tài liệu thiết kế đã lập luận để đạt được. Cả hai đều thất bại theo cùng một cách vì cùng một lý do, và cả hai đều được khắc phục bằng cùng một động thái — giữ cuộc tranh luận ở nơi hồ sơ tồn tại, thay vì sao chép một cái vào cái khác sau đó. Đọc từng bước dưới đây như bao gồm cả hai tài liệu.

Tại sao ADR lại hỏng?

Một câu từ tài liệu của cộng đồng ADR mang theo toàn bộ chẩn đoán: một RFC thường liên quan đến việc đạt được thỏa thuận; một ADR ghi lại thỏa thuận khi đã đạt được. Hai hiện vật, hai khoảnh khắc — và mọi thứ giữa chúng đều bị rò rỉ. Những lựa chọn mà "rõ ràng" là sai không được ghi lại (cho đến khi chúng không còn rõ ràng). Sự phản đối đã hình thành thiết kế cuối cùng chỉ tồn tại như một bình luận PR trên một chủ đề đã đóng. Phần ngữ cảnh được viết cuối cùng, tệ nhất, bởi bất kỳ ai thua trong trò chơi không phải là nó. Các cuộc họp lẽ ra nên đưa ra quyết định lại chỉ sản xuất tóm tắt thay thế, và lý do khiến một quyết định bền vững — điều mà toàn bộ chuỗi chất lượng quyết định phụ thuộc vào — chính là điều mà việc phiên âm bỏ qua.

Bước 1–3: Đề xuất, bối cảnh, các tùy chọn

1. 1Trình bày đề xuất như là tuyên bố gốc — quyết định được đề xuất, không phải là câu hỏi: "Chúng tôi sẽ chuyển tất cả các ghi chép thanh toán qua một hàng đợi bền vững." Câu này là tiêu đề của ADR trong tương lai. Điểm kiểm tra: gốc tồn tại, một câu, do người đề xuất viết.
2. 2Bối cảnh như các lập luận pro tách biệt. Mỗi lực lượng khiến quyết định trở nên cần thiết — yêu cầu độ tin cậy, giới hạn tỷ lệ hệ thống thanh toán, nghĩa vụ kiểm toán — là một lập luận riêng biệt dưới gốc. Một đoạn "Bối cảnh" đơn nhất không thể bị thách thức; ba tuyên bố bối cảnh tách biệt có thể được đặt câu hỏi, xác nhận hoặc bác bỏ từng cái một. Điểm kiểm tra: ≥2 lập luận bối cảnh, mỗi lập luận là một lực lượng.
3. 3Mỗi tùy chọn đều có một nút riêng. Hàng đợi, API đồng bộ, công việc theo lô — các đối số anh em, mỗi cái có những ưu và nhược điểm riêng. Ưu/nhược điểm là tương đối so với cha mẹ, vì vậy những nhược điểm của một tùy chọn gắn liền với tùy chọn đó, không phải với quyết định. Bao gồm cả những tùy chọn mà bạn dự kiến sẽ từ chối: đối tượng anh em bị từ chối chính là câu trả lời cho câu hỏi "tại sao chúng ta không chỉ…". Điểm kiểm tra: mỗi tùy chọn mà người đọc có thể hỏi đều tồn tại.

Bước 4–6: Vòng RFC để lại một bản ghi

Bây giờ là vòng đánh giá — thường là phần diễn ra rải rác qua trò chuyện, bình luận và hành lang. Ở đây, nó diễn ra dưới dạng ba loại trao đổi có cấu trúc, mỗi loại là một cuộc đối thoại bốn lượt giữa người đánh giá và tác giả của tùy chọn:

Bước 7: Quyết định — và đánh giá không phải là gì

Các nhà ra quyết định đánh giá các tùy chọn: mỗi tùy chọn được gán một mức đánh giá. Sự phân phối là bằng chứng thực sự — nơi mà phòng họp đã đứng, theo hồ sơ, trước cuộc gọi. Nhưng mức đánh giá không phải là quyết định. Một con người cụ thể vẫn sẽ quyết định, và nếu cuộc gọi đi ngược lại với sự phân phối, nút quyết định là nơi điều đó được giải thích. (Ai là con người cụ thể đó, và cách gán vai trò trước cuộc tranh luận thay vì sau, là một lĩnh vực riêng — xem hướng dẫn về quyền quyết định.)

Bước 8–9: ADR bạn không cần phải viết

Đây là phần thưởng. Hồ sơ không phải là một tài liệu bạn viết sau đó — nó là nút của tùy chọn đã chọn cộng với mọi thứ đã được gắn liền với nó: các lập luận ngữ cảnh (Context), các anh chị em bị từ chối (Options Considered), các chuỗi đã hoàn thành (cuộc thảo luận, với các tác giả), các đánh giá (tình hình của phòng), và lập luận quyết định với lý do của nó (Decision). Không có gì được ghi chép lại, vì vậy không có gì bị mất trong quá trình ghi chép.

1. 1Ghi lại những hậu quả mà bạn chấp nhận. Những nhược điểm đã biết — độ trễ thêm, gánh nặng vận hành của hàng đợi — tiếp tục tồn tại như những đứa con của lựa chọn đã chọn, được công nhận bởi người quyết định. Việc ghi chúng lại là điều làm cho đó trở thành một quyết định chứ không phải chỉ là một sở thích. Điểm kiểm tra: ≥1 hậu quả đã chấp nhận được ghi lại.
2. 2Xuất nếu tổ chức của bạn yêu cầu các ADR được theo dõi bởi kho lưu trữ. Nhiều tổ chức đúng là như vậy — ADR markdown bên cạnh mã vẫn là tài liệu tuân thủ. Viết tóm tắt bốn phần từ cây (năm phút, không phải thứ Sáu), liên kết trở lại cuộc thảo luận để có cuộc tranh luận đầy đủ. Điểm kiểm tra: ADR của kho lưu trữ trích dẫn cây; cây giữ lý do.

Không đồng ý nhưng vẫn cam kết, trên hồ sơ

Mô hình mà Amazon đã làm nổi tiếng — không đồng ý và cam kết — có một vấn đề về tính rõ ràng: làm thế nào để ai đó biết rằng sự bất đồng đó là có thật, đã được lắng nghe và trả lời, chứ không phải bị áp đảo? Cơ chế chuỗi trả lời cho câu hỏi đó. Một chuỗi Đánh giá đã trải qua đủ bốn lượt và hoàn thành mà không có sự đồng ý chính là biên lai: sự phản đối đã được đưa ra, trả lời, nhấn mạnh, và lại được trả lời, được ghi lại, trước khi người phản đối cam kết. Người phản đối được ghi nhận là đã được lắng nghe — điều này làm cho việc cam kết sau đó trở nên hợp lý chứ không chỉ đơn thuần là tuân theo.

Bước 10: Thay thế mà không xóa

Quyết định tuổi. Khi giới hạn tỷ lệ mà đã loại bỏ tùy chọn đồng bộ được nâng lên, bước đi đúng đắn là một quyết định mới tham chiếu đến quyết định mà nó thay thế — một lập luận mới liên kết với nút của ADR-014, nêu rõ điều gì đã thay đổi. Quyết định cũ vẫn có thể đọc được; lý do của nó chính là lý do mà quyết định mới biết được điều gì đang bị lật ngược.

Một khoảng trống cần quản lý một cách rõ ràng: không có trường trạng thái ADR tích hợp sẵn. Đề xuất / chấp nhận / thay thế không phải là trạng thái hàng đầu trong một lập luận — việc thay thế được mô hình hóa bằng cách liên kết, và quy ước là do bạn duy trì. Nêu rõ điều này trong thỏa thuận làm việc của nhóm bạn thay vì giả định rằng sản phẩm sẽ thực thi điều đó.

Giới hạn trung thực

• ✗Điều này không thay thế các ADR trong kho của bạn nếu tổ chức của bạn yêu cầu chúng được kiểm soát phiên bên cạnh mã. Xuất và cam kết tóm tắt; sử dụng cây cho phần mà markdown kém — cuộc tranh luận.
• ✗Không có trường trạng thái ADR. Đề xuất/chấp nhận/thay thế là một quy ước liên kết mà bạn duy trì, không phải là điều mà sản phẩm thực thi.
• ✗Một chuỗi là bốn vòng. Sự bất đồng kiến trúc sâu sắc sẽ cần một cuộc gọi; chuỗi là bản ghi của những gì đã được thử nghiệm trước đó.
• ✗Đánh giá là một giá trị được gán nhãn đơn, không phải là điểm số đa tiêu chí có trọng số.
• ✗Nó không khiến ai viết bối cảnh tốt. Cấu trúc làm giảm chi phí cho một bản ghi tốt; nó không cung cấp sự phán xét.

Bài học thực hành

• ✓Một RFC, một cuộc thảo luận. Chống lại cây mega bao trùm toàn bộ kiến trúc của quý — các liên kết thay thế kết nối các quyết định tốt hơn là việc lồng ghép.
• ✓Hạt giống từ những gì tồn tại. Một bản sao chép nặng nề quyết định hoặc thư mục ADR cũ của bạn, được trích xuất, mang lại cho cuộc tranh luận một khởi đầu thuận lợi — được gán nhãn là nhập khẩu, vì vậy các lập luận trực tiếp vẫn có thể phân biệt được.
• ✓Đặt tên của các nhà phê bình lên chuỗi của họ và để chúng ở đó. Sự ghi nhận là trách nhiệm; những phản đối kiến trúc ẩn danh sẽ trở thành truyền thuyết.
• ✓Phần hậu quả là của người quyết định, không phải của ai khác. Những nhược điểm đã được chấp nhận bởi người đã chấp nhận chúng có trọng lượng khác với những cảnh báo của người đánh giá.

ADR-014, phiên bản trả lời

Quay lại câu hỏi của người dẫn dắt công nghệ mới. Trong phiên bản được xây dựng lại, ADR-014 là một nút: quyết định hàng đợi với lý do của nó, ba lực lượng ngữ cảnh (một hiện đã lỗi thời — rõ ràng), một đồng nghiệp API đồng bộ bị từ chối mà tên gọi của nó chỉ ra giới hạn tỷ lệ cũ, bốn chuỗi Đánh giá đã hoàn thành bao gồm cả của kỹ sư chính, và tiêu chuẩn được đính kèm như bằng chứng. Người dẫn dắt công nghệ đọc trong mười phút, thấy giới hạn tỷ lệ đã thay đổi, và mở một đề xuất thay thế liên kết với nút cũ. Không ai khai thác Slack. Đó là toàn bộ lời hứa: các chuỗi đạt được thỏa thuận, cây ghi lại điều đó — và bản ghi trả lời những câu hỏi mà bạn không biết nó sẽ được hỏi.