Tài liệu ra quyết định sinh ra để giải quyết đúng chuyện đó. Gọi là ADR, RFC hay decision log cũng được, cái tên không quan trọng. Quan trọng là ghi lại bối cảnh, các phương án và lập luận ngay tại thời điểm lựa chọn. Năm nay, khi quản lý một đội lập trình viên, tôi càng thấm giá trị của loại tài liệu này hơn bao giờ hết: có nó thì tổ chức có trí nhớ thật, không có thì chỉ còn lại những lời truyền miệng.

Vì sao đáng bỏ công

#

Cái lợi dễ thấy nhất là không phải cãi nhau về cùng một chuyện hai lần. “Ơ, chiến lược quản lý phiên bản (versioning) cho API mình chốt rồi mà nhỉ?” Khi có một bản ghi rõ ràng về điều đã quyết và lý do, chuyện gì đã xong sẽ nằm yên, và cả đội dồn sức vào làm thay vì quay lại đi con đường cũ.

Cái lợi âm thầm hơn thì phải một thời gian mới lộ ra. Dự án kéo dài hàng tháng, hàng năm, người đến rồi người đi, thứ còn lại chỉ là mã nguồn. Mã nguồn cho bạn biết điều gì đã được quyết, nhưng không bao giờ cho biết vì sao. Tài liệu ra quyết định thì giữ lại được lập luận: lúc đó có những ràng buộc gì, phương án nào đã bị loại, ai là người chốt. Người mới vào có bối cảnh để hiểu, thay vì chỉ nghe kể lại. Những quyết định liên quan tới nhiều đội cũng nhận được sự đồng thuận thật, vì ai cũng thấy các yếu tố đã được cân nhắc thế nào, chứ không chỉ thấy kết luận cuối cùng. Và khi tài liệu ghi rõ ai ra quyết định, ai đóng góp ý kiến, thì phần việc tiếp theo sẽ có người thật sự chịu trách nhiệm.

Khi nào nên viết

#

Không phải quyết định nào cũng đáng một tài liệu. Tôi chỉ viết khi quyết định đó:

• Tốn kém nếu muốn quay đầu: chọn bộ công nghệ (tech stack) như framework, cơ sở dữ liệu hay nhà cung cấp điện toán đám mây; chọn mẫu kiến trúc (vi dịch vụ (microservices) hay nguyên khối (monolith), hướng sự kiện hay yêu cầu-phản hồi); chọn nhà cung cấp bên thứ ba; hay cách tiếp cận về bảo mật và tuân thủ
• Có tác động lâu dài: hợp đồng API mà các hệ thống bên ngoài phụ thuộc vào, mô hình dữ liệu trải qua nhiều dịch vụ, hoặc những thay đổi phá vỡ các mẫu thiết kế đã thành nếp
• Liên quan tới nhiều đội: bất cứ thứ gì cần nhiều đội hoặc các bên liên quan không làm kỹ thuật cùng đồng ý, các quyết định về phân bổ nguồn lực và thứ tự ưu tiên
• Là kết quả của một đợt spike: khi một đợt tìm hiểu có giới hạn thời gian vừa kết thúc, hãy ghi lại những gì tìm được và quyết định rút ra trước khi mọi người quên sạch

Với những quyết định dễ đảo ngược, những chi tiết triển khai nội bộ trong đội, hay những thứ gần như không ảnh hưởng ra ngoài phạm vi trực tiếp của bạn, thì bỏ qua thủ tục. Một tài liệu không ai cần tới thì chỉ là bài tập về nhà.

Vòng đời

#

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Draft     │ ──► │   Review    │ ──► │  Approved   │ ──► │ Implemented │
│  Proposed   │     │  Feedback   │     │  Accepted   │     │  Completed  │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │  Rejected/  │
                    │  Superseded │
                    └─────────────┘

Người viết phác thảo vấn đề và các giải pháp có thể chọn. Sau đó các bên liên quan đọc và góp ý. Đây là giai đoạn làm nên giá trị của cả quá trình, vì đây là lúc các giả định bị chất vấn và những điểm mù lộ ra. Người ra quyết định (thường là trưởng nhóm kỹ thuật, kiến trúc sư hoặc người phụ trách sản phẩm) chốt lần cuối, đội bắt tay triển khai, và nếu thực tế buộc phải thay đổi giữa chừng thì tài liệu được cập nhật theo. Có tài liệu chết ngay ở vòng góp ý, có tài liệu về sau bị thay thế khi hoàn cảnh đổi khác. Trường hợp nào cũng phải đánh dấu cho rõ, vì một tài liệu “accepted” đã lỗi thời chính là cái bẫy cho người tiếp theo tìm thấy nó.

Tài liệu thế nào thì đáng đọc

#

Bắt đầu từ vấn đề, đừng bắt đầu từ giải pháp bạn thích nhất. Mình đang giải quyết chuyện gì, vì sao lúc này chuyện đó quan trọng, và nếu không làm gì thì sẽ ra sao? Khi mọi người còn chưa thống nhất vấn đề là gì, thì tranh luận về giải pháp chỉ là diễn kịch.

Tiếp theo, đưa ra các phương án thật sự, ít nhất hai hoặc ba, kể cả khi bạn đã nghiêng hẳn về một cái. Mỗi phương án cần có: mô tả ngắn, ưu và nhược điểm, ước lượng công sức sơ bộ (ước theo cỡ áo S/M/L/XL là đủ), cùng các rủi ro và cách bạn sẽ giảm thiểu chúng. Có ghi lại các phương án thay thế thì người đọc sau này mới hiểu vì sao phương án được chọn lại thắng.

Nói thẳng ra những đánh đổi. “Chúng tôi chọn ra thị trường nhanh hơn, chấp nhận kiến trúc không được đẹp.” “Chúng tôi chấp nhận vận hành phức tạp hơn để đổi lấy khả năng mở rộng quy mô tốt hơn.” “Chúng tôi ưu tiên trải nghiệm của lập trình viên hơn hiệu năng thuần.” Chỉ vài câu như vậy thôi đã giúp người đọc sau này nhiều hơn cả chục trang phân tích.

Neo cuộc thảo luận vào những thứ cụ thể: đoạn mã minh hoạ giải pháp sẽ trông ra sao, sơ đồ tương tác giữa các hệ thống, liên kết tới các bản thử nghiệm khái niệm (proof of concept) từ những đợt spike. Thảo luận chung chung thì chỉ sinh ra quyết định chung chung.

Cuối cùng, đặt hạn chót: khi nào phải ra quyết định, ai phải góp ý trước ngày nào, và những việc gì đang bị kẹt lại trong lúc chờ. Quyết định mà không có hạn chót thì sẽ bị treo mãi.

Ví dụ: Architecture Decision Record (ADR)

#

Dưới đây là một ví dụ thực tế về tài liệu ra quyết định:

# ADR-001: API Authentication Strategy

**Status:** Accepted
**Date:** 2024-11-15
**Decision Maker:** Sarah Chen (Platform Architect)
**Contributors:** Backend Team, Security Team, Mobile Team

## Context

Our public API currently uses API keys for authentication. As we expand to
support third-party integrations and mobile apps, we need a more robust
authentication mechanism that supports:
- Token expiration and refresh
- Scoped permissions
- User-level authentication (not just service-level)

## Decision

We will implement OAuth 2.0 with JWT tokens for API authentication.

## Options Considered

### Option 1: OAuth 2.0 with JWT (Recommended)
**Description:** Industry-standard protocol with self-contained tokens

| Pros | Cons |
|------|------|
| Industry standard, well-documented | More complex initial implementation |
| Self-contained tokens reduce database lookups | Tokens cannot be revoked instantly |
| Broad library support | Requires refresh token management |

**Effort:** Medium (2-3 sprints)

### Option 2: Session-based Authentication
**Description:** Traditional server-side sessions with cookies

| Pros | Cons |
|------|------|
| Simple to implement | Not suitable for mobile apps |
| Easy to revoke sessions | Requires sticky sessions or shared session store |
| Familiar to most developers | Doesn't scale as well |

**Effort:** Small (1 sprint)

### Option 3: Custom Token System
**Description:** Build our own token-based authentication

| Pros | Cons |
|------|------|
| Fully customizable | Reinventing the wheel |
| No external dependencies | Security risks from custom implementation |

**Effort:** Large (4+ sprints)

## Consequences

- Mobile team can implement standard OAuth flows
- We'll need to set up a token refresh mechanism
- API documentation will need updates for OAuth flows
- Existing API key users will need a migration path (6-month deprecation)

## References

- [OAuth 2.0 RFC 6749](https://tools.ietf.org/html/rfc6749)
- Internal spike document: [Authentication Options Spike](/spikes/auth-spike-2024)
- Security team review: SEC-2024-042

Mẫu tài liệu, cứ lấy về mà dùng

#

Lấy mẫu (template) này làm điểm xuất phát, rồi cắt gọt cho vừa với đội của bạn:

Mô tả vấn đề

#

Mình đang giải quyết vấn đề gì? Vì sao nó quan trọng? Không làm gì thì phải trả giá thế nào?

Bối cảnh

#

Nêu bối cảnh, lịch sử và các chi tiết liên quan. Dẫn liên kết tới những tài liệu liên quan, các quyết định trước đó, hoặc kết quả spike.

Ràng buộc

#

Giải pháp nào cũng phải tuân theo những giới hạn hay yêu cầu gì?

• Ràng buộc về ngân sách
• Yêu cầu về tiến độ
• Ràng buộc kỹ thuật (hệ thống hiện có, kỹ năng của đội)
• Yêu cầu về tuân thủ hoặc bảo mật

Các giải pháp đã cân nhắc

#

Đề xuất

#

Nêu phương án bạn đề xuất, và tóm tắt vì sao với các ràng buộc và đánh đổi hiện có, đó là lựa chọn tốt nhất.

Quyết định

#

Chốt xong thì ghi lại quyết định cuối cùng. Nếu khác với đề xuất, giải thích lý do.

Hệ quả

#

Quyết định này kéo theo những gì? Cần làm tiếp những việc gì?

Việc cần làm

#

Tài liệu tham khảo

#

Liên kết tới các tài liệu liên quan, nguồn bên ngoài, kết quả spike, hoặc các quyết định trước đó.

Làm sao để thói quen này bám rễ

#

Lưu tài liệu ở một chỗ cố định, chẳng hạn một thư mục riêng trong kho mã nguồn (repo) hay một không gian trên wiki, vì một quyết định không ai tìm thấy thì cũng như chưa từng có. Viết thật gọn nhẹ thôi; tài liệu mà mất cả mấy ngày mới viết xong thì sẽ chẳng bao giờ có ai viết. Nhắc tới chúng trong chú thích trong mã, thông điệp commit và pull request, để phần “vì sao” luôn đi liền với phần “cái gì”. Khi một quyết định bị thay thế, đừng xoá tài liệu cũ, mà hãy đánh dấu nó là superseded rồi dẫn liên kết sang tài liệu mới; giữ lại lịch sử mới là mục đích. Và hãy mang các quyết định cũ ra xem lại trong những buổi họp nhìn lại (retrospective): cái nào vẫn còn đứng vững, cái nào bây giờ bạn sẽ quyết khác đi.

Những kiểu thất bại thì cũng dễ đoán y như vậy. Phân tích mãi mà không quyết được: hãy đặt hạn chót, quyết dựa trên thông tin đang có, và nhớ rằng phần lớn quyết định đều có thể xem xét lại. Góp ý cho có, chỉ để đóng dấu mà không bao giờ có phản biện thật, thì chỉ thêm quy trình chứ không thêm giá trị. Tài liệu viết xong rồi bỏ đó, không dẫn tới hành động nào, còn tệ hơn là không có tài liệu. Quá nhiều chi tiết cũng là một lỗi: tài liệu nên nói về vì sao và cái gì, không phải làm thế nào; phần triển khai là việc của bản đặc tả kỹ thuật. Và khi các bên liên quan bất đồng, hãy ghi lại ý kiến phản đối. Quyết định có thể vẫn giữ nguyên, nhưng chính lời phản đối đó là bối cảnh mà một năm sau sẽ có người cần tới.

Hãy bắt đầu từ quyết định quan trọng tiếp theo của bạn. Cứ viết ra, dù còn thô, rồi vừa làm vừa chỉnh lại quy trình. Mỗi cuộc họp “sao hồi đó mình chọn X?” không cần diễn ra nữa vì ai đó chỉ việc mở ADR ra đọc, là thêm một tiếng đồng hồ đội bạn lấy lại được.

Đọc thêm

#

Bài viết liên quan trên blog này:

• Tìm hiểu về spike trong phát triển phần mềm Agile - làm một đợt spike để thu thập thông tin trước khi chốt quyết định lớn
• Họp nhìn lại: sức mạnh của vòng lặp phản hồi - xem lại các quyết định cũ như một phần của quá trình cải tiến liên tục
• Lên kế hoạch cho một API - áp dụng tư duy tài liệu ra quyết định vào thiết kế API
• Dùng GitHub để quản lý dự án - để tài liệu ra quyết định nằm ngay cạnh mã nguồn

Tài liệu bên ngoài:

• Documenting Architecture Decisions - Michael Nygard - bài viết gốc đã giúp ADR trở nên phổ biến
• ADR GitHub Organization - công cụ, mẫu tài liệu và ví dụ cho Architecture Decision Record
• Design Docs at Google - cách Google viết tài liệu thiết kế
• Quy trình RFC của Rust - quy trình RFC của ngôn ngữ Rust, được ghi chép rất kỹ
• Mẫu Decision Record của Spotify - góc nhìn của Spotify về chuyện khi nào nên viết ADR