# Ba tuần code đổ bỏ vì một câu hỏi về nơi đặt dữ liệu

> Khi xây ứng dụng AI trong hạ tầng của khách, một trang design doc viết trong hai ngày lôi bất đồng ra sớm, lúc sửa còn rẻ.

Bản gốc: https://fdetimes.net/vi/bach-khoa/thuc-hanh-system-design-cho-ung-dung-ai-tai-khach/

Thử hình dung: tuần đầu ở một ngân hàng, bạn dựng xong prototype trợ lý tra cứu quy trình nội bộ, chạy rất mượt trên laptop và gọi model qua API công khai. Sang tuần thứ ba, đội bảo mật của ngân hàng cho biết tài liệu nội bộ không được ra khỏi mạng của họ. Gần như toàn bộ phần tích hợp phải làm lại.

Rủi ro kiểu này gắn liền với nghề, vì công việc của FDE diễn ra trong nhà người khác. Tin tuyển FDE của Anthropic ghi rõ một trách nhiệm cốt lõi: làm việc bên trong hệ thống của khách để xây ứng dụng production với model Claude. Code của bạn phải sống chung với mạng, quy trình duyệt và đội vận hành của khách.

Vì thế, bên cạnh prompt hay RAG, viết design doc trước khi code là một kỹ năng đáng luyện sớm nếu bạn muốn làm FDE. Lý do rất đơn giản: một trang giấy viết trong hai ngày rẻ hơn nhiều so với ba tuần code đi sai hướng.

## Một trang giấy để lộ ra bất đồng

Design doc không phải đặc tả từng hàm. Ở Google, nó ghi lại chiến lược triển khai ở mức tổng thể và các quyết định thiết kế then chốt, nhấn mạnh vào những đánh đổi đã cân nhắc. Nó trả lời câu hỏi: ta định làm gì, theo hướng nào, và vì sao.

Viết ra là cách nhanh nhất để biết mọi người có thật sự đồng ý hay không. Như Gergely Orosz của The Pragmatic Engineer nhận xét, nếu cả nhóm đã thống nhất cách làm thì viết ra chỉ là chuyện nhỏ; bất đồng thường lộ ra ngay trong lúc viết. Tờ giấy lôi chúng ra sớm, khi sửa vẫn còn rẻ.

Văn bản được chia sẻ còn tạo ra trách nhiệm giải trình, và theo Orosz, gần như luôn dẫn đến quyết định kỹ lưỡng hơn. Với FDE, đây là lợi ích thiết thực: khi quyết định về dữ liệu hay phạm vi được ghi lại và khách đã đọc, về sau ít có chuyện mỗi bên nhớ một kiểu.

Dù vậy, không phải việc gì cũng cần doc. Hãy để độ dày của doc tương xứng với độ phức tạp của việc. Các công ty Orosz khảo sát thường dành RFC cho dự án rộng và phức tạp, cho yêu cầu kỹ thuật áp dụng toàn công ty hoặc cho thay đổi API.

## Bắt đầu từ những gì đang xảy ra hôm nay

Câu "quy trình chuẩn là gì" sẽ cho bạn tài liệu đẹp. Câu "lần gần nhất anh cần tra quy trình, anh làm thế nào" mới cho bạn sự thật. Pooya Golchian, người làm FDE từ 2024 đến 2026, tóm gọn nguyên tắc này: hỏi chuyện đang diễn ra hôm nay, đừng hỏi chuyện lẽ ra phải diễn ra.

Ở ví dụ ngân hàng, câu trả lời có thể là: chuyên viên lục thư mục chia sẻ, không thấy thì nhắn hỏi một người lâu năm. Chi tiết đó nên được ghi ngay vào mục đầu tiên của doc.

Nó cho biết đối thủ thật của bạn là một đồng nghiệp trả lời qua chat, nên câu trả lời của hệ thống phải nhanh và có trích dẫn đủ để người dùng tin.

Từ đây mới viết mục tiêu. Và ngay sau mục tiêu là phần mà người mới hay bỏ qua nhất.

## Non-goals: nơi bạn vẽ ranh giới

Non-goal không phải mục tiêu bị viết ngược. "Hệ thống không được chậm" là một mục tiêu đội lốt. Bản hướng dẫn của Google định nghĩa non-goal là những thứ hoàn toàn có thể là mục tiêu, nhưng được chủ động chọn để không làm.

Với trợ lý của ngân hàng, non-goal thật có thể là: chưa trả lời khách hàng bên ngoài, chưa xử lý PDF dạng ảnh scan, chưa cập nhật chỉ mục theo thời gian thực. Cả ba đều hợp lý, đều có người sẽ hỏi, và đều bị loại có chủ đích.

Không cần ghi mọi thứ bị loại. Hãy ghi những thứ hợp lý, đã từng được nêu ra khi review, hoặc sẽ tốn kém nếu phải tranh luận lại, đúng như cách Joshka mô tả pattern "document intentional non-goals".

Không ghi, ba tháng sau sẽ có người bên khách hỏi vì sao hệ thống không đọc được file scan, và quyết định về phạm vi bị coi là sơ suất.

**Điểm mấu chốt:** Một non-goal ghi rõ hôm nay sẽ cứu bạn khỏi một cuộc tranh cãi ba tháng sau.

## Hạ tầng của khách đi vào bản thiết kế ở đâu?

Mẫu RFC của Uber có các mục về SLA của service, các phụ thuộc, kiểm thử tải và hiệu năng, bảo mật, đo lường và giám sát. Đặt vào bối cảnh ứng dụng AI trong hạ tầng của khách, mỗi mục là một nhóm câu hỏi bạn phải hỏi trước khi code.

Với ngân hàng trong ví dụ, đó là: dữ liệu được phép nằm ở đâu, chỉ trong mạng nội bộ hay được đưa lên một vùng cloud đã duyệt? Model chạy trên GPU on-prem của khách hay qua dịch vụ ngoài? Quy trình review bảo mật kéo dài bao lâu, ai ký? Và câu hay bị quên nhất: sau bàn giao, ai vận hành cluster?

Mục SLA nên có luôn kịch bản lỗi. Chẳng hạn: nếu cluster GPU quá tải, hệ thống chuyển sang một model nhỏ hơn, câu trả lời ngắn và ít chi tiết hơn nhưng vẫn kèm trích dẫn. Nếu model ngừng hẳn, hệ thống chỉ trả về danh sách tài liệu liên quan. Viết ra trước giúp khách biết họ đang chấp nhận điều gì.

Sau đó đến mục "Phương án đã cân nhắc": liệt kê những thiết kế khác cũng có thể đạt kết quả tương tự, để người review thấy được đánh đổi. Ở ví dụ ngân hàng, bảng so sánh có thể trông như sau:

| Phương án | Được gì | Mất gì |
|---|---|---|
| Model qua API cloud | Triển khai nhanh, chất lượng cao | Có thể vướng quy định dữ liệu không được rời mạng |
| Model mở chạy trên GPU on-prem của khách | Dữ liệu ở lại trong nhà | Khách phải có người vận hành GPU |
| Chỉ tìm kiếm, không sinh câu trả lời | Đơn giản, dễ duyệt bảo mật | Người dùng vẫn phải tự đọc tài liệu |

Bảng này không quyết định thay bạn. Nó buộc cuộc họp với khách xoay quanh đánh đổi thật thay vì sở thích công nghệ.

## Bộ khung một design doc

Ghép các phần trên lại, bản nháp đầu tiên cho trợ lý của ngân hàng có thể dài chưa tới hai trang:

```
# Trợ lý tra cứu quy trình nội bộ — design doc v0.1

## Hôm nay đang diễn ra thế nào
- Chuyên viên lục thư mục chia sẻ, không thấy thì hỏi người lâu năm

## Mục tiêu
- Trả lời câu hỏi về quy trình nội bộ, luôn kèm trích dẫn tài liệu gốc

## Non-goals (kèm lý do)
- Chưa phục vụ khách hàng bên ngoài: rủi ro pháp lý, cần duyệt riêng
- Chưa đọc PDF scan: cần OCR, hạ tầng chưa có

## Ràng buộc hạ tầng
- Dữ liệu được nằm ở đâu / model chạy ở đâu
- Ai duyệt bảo mật, mất bao lâu
- Ai vận hành sau bàn giao

## Thiết kế đề xuất
- Model mở chạy trên GPU on-prem, tìm trong thư mục chia sẻ,
  mỗi câu trả lời kèm link tới đoạn tài liệu gốc
- Chờ đội bảo mật xác nhận: dữ liệu không rời mạng nội bộ

## Phương án đã cân nhắc
- API cloud / model mở on-prem / chỉ tìm kiếm (xem bảng đánh đổi)

## SLA, phụ thuộc và kịch bản lỗi
- GPU quá tải: chuyển sang model nhỏ hơn, vẫn kèm trích dẫn

## Kiểm thử và rollout
- Thử với 10 chuyên viên một phòng ban trong 2 tuần rồi mới mở rộng

## Đo lường và giám sát
- Tỷ lệ câu trả lời có trích dẫn đúng, số câu người dùng báo sai

## Bàn giao: runbook + eval suite
- Eval suite: bộ câu hỏi lấy từ những lần chuyên viên phải nhắn
  hỏi người lâu năm, kèm đáp án và tài liệu đúng
- Đội vận hành của ngân hàng chạy lại eval mỗi khi đổi model
  hoặc cập nhật tài liệu
- Runbook: GPU quá tải, chỉ mục lỗi thời, câu trả lời thiếu trích dẫn
```

## Viết cho người sẽ vận hành, không phải cho bạn

Thước đo cuối cùng của một design doc là đội của khách có tự vận hành được hệ thống hay không. Golchian định nghĩa FDE chính bằng điều đó: người xây phần mềm bên trong công ty khách cho đến khi đội của họ tự chạy được, và ở những lần bàn giao ông kể, kỹ sư của khách tiếp quản bằng runbook và eval suite.

Vì vậy mục cuối của doc không nên để trống đến tuần cuối. Như bộ khung trên, ngay từ v0.1 hãy ghi: eval suite gồm những bộ câu hỏi nào, ai bên khách sẽ chạy nó, runbook xử lý những sự cố nào.

Làm vài dự án, bộ khung này sẽ dày lên thành tài sản. Tin tuyển của Anthropic cũng mong FDE nhận diện và hệ thống hóa các pattern triển khai lặp lại được, rồi đóng góp ngược cho đội sản phẩm. Một template design doc được mài qua ba khách hàng chính là pattern như thế.

## Những lỗi hay gặp

Lỗi đầu tiên là viết doc sau khi đã code, biến nó thành tài liệu minh họa cho quyết định đã có sẵn. Lỗi thứ hai là non-goals viết ngược mục tiêu, kiểu "không chậm", "không sai", chẳng loại trừ được gì.

Lỗi thứ ba là mục phương án thay thế chỉ gồm những phương án dựng lên cho có, chỉ để bị loại. Người review bên khách nhận ra ngay, và bạn mất uy tín đúng lúc cần họ ký. Lỗi thứ tư là viết doc dày cho một thay đổi nhỏ, khiến cả đội ngại đọc.

Lỗi cuối cùng tốn kém nhất: không hỏi ai vận hành hệ thống sau khi bạn rời đi. Câu hỏi đó định hình gần như mọi lựa chọn hạ tầng ở trên.

Nếu muốn chứng minh kỹ năng này khi ứng tuyển, hãy đưa một design doc đã ẩn thông tin nhạy cảm vào portfolio, và khi đọc JD, để ý những cụm như "work within customer systems" trong tin tuyển của Anthropic. Nhà tuyển dụng sẽ thấy bạn nghĩ về hệ thống của khách trước khi nghĩ về model.

Prototype chạy trên laptop chứng minh được rằng ý tưởng khả thi. Design doc chứng minh được rằng nó sẽ còn chạy sau khi bạn đã rời khỏi tòa nhà của khách.

**Thử ngay tuần này:**

- Chọn một tính năng AI bạn từng làm, viết lại design doc một trang theo bộ khung trong bài, trong đó có ít nhất ba non-goal kèm lý do.
- Với dự án hiện tại, liệt kê bốn câu hỏi hạ tầng: dữ liệu được nằm ở đâu, model chạy ở đâu, ai duyệt bảo mật, ai vận hành sau bàn giao, rồi đánh dấu câu nào chưa có câu trả lời.
- Viết mục 'Phương án đã cân nhắc' với ba phương án thật, mỗi phương án nêu rõ được gì và mất gì.

## Nguồn

- [Design Docs at Google](https://www.industrialempathy.com/posts/design-docs-at-google/)

- [Scaling Engineering Teams via RFCs: Writing Things Down](https://blog.pragmaticengineer.com/scaling-engineering-teams-via-writing-things-down-rfcs/)

- [Companies Using RFCs or Design Docs and Examples of These](https://blog.pragmaticengineer.com/rfcs-and-design-docs/)

- [Forward Deployed Engineer (Anthropic, via General Catalyst job board)](https://jobs.generalcatalyst.com/companies/anthropic/jobs/89778489-forward-deployed-engineer)

- [forward deployed engineering](https://pooyagolchian.com/forward-deployed-engineering/)

- [Document Intentional Non Goals](https://www.joshka.net/practice/patterns/document-intentional-non-goals/)
