0001. Ghi lại các quyết định về kiến trúc

Trạng thái: Đã chấp nhận Ngày: 2026-06-19

Bối cảnh

Chúng tôi hy vọng sẽ đưa ra các quyết định về kiến trúc trong suốt thời gian tồn tại của dự án này — những lựa chọn mà bản thân mã không giải thích đầy đủ (phần phụ trợ suy luận nào, đường nối hộp cát cục bộ và từ xa, chiến lược nén ngữ cảnh, chọn Kitaru vì độ bền, mô hình không đồng bộ nào). Sáu tháng kể từ bây giờ, chúng ta sẽ không nhớ tại sao mình lại chọn điều mình đã chọn. Nếu không có hồ sơ, chúng tôi sẽ khởi kiện lại các quyết định tương tự và có thể đưa ra các kết luận khác nhau. Với tư cách là một cơ sở mã giảng dạy, lý do đằng sau mỗi lựa chọn chính là một phần của tài liệu.

Quyết định

Chúng tôi sẽ sử dụng Bản ghi Quyết định Kiến trúc, như được mô tả bởi Michael Nygard, được lưu trữ trong docs/adr/ như NNNN-kebab-title.md. Mỗi ADR có bốn phần: Trạng thái, Bối cảnh, Quyết định, Hậu quả. Việc đánh số đơn điệu và không bao giờ được sử dụng lại; các ADR được thay thế vẫn giữ số lượng và liên kết với sự thay thế của chúng.

hậu quả

• Mỗi lựa chọn kiến trúc không rõ ràng sẽ nhận được một bản ghi dài một trang.
• Những người đóng góp mới (và người đọc khóa học) có thể đọc docs/adr/ để hiểu tại sao cơ sở mã lại được định hình như vậy.
• Các ADR trước đó được đọc trong quá trình lập kế hoạch để tránh đề xuất lại các câu hỏi đã được giải quyết.
• Chi phí: ~30 phút/ADR. Chúng tôi chấp nhận chi phí này vì giải pháp thay thế - lấy lại lý luận trong quá khứ - đắt hơn.