# Thực hành: biến dự án vừa giao thành playbook, runbook và repo mẫu cho khách tiếp theo

> Những gì học được ở một lần deployment rất dễ bị FDE mang theo khi rời dự án, và hướng dẫn này giúp bạn giữ chúng lại trong năm phần tài liệu cùng một template repo.

Bản gốc: https://fdetimes.net/vi/bach-khoa/thuc-hanh-playbook-va-repo-mau-tai-su-dung/

Tuần cuối của một deployment thường trôi qua rất nhanh: demo, ký nghiệm thu, bàn giao rồi chuyển sang khách mới. Ba tháng sau, khách thứ hai đưa ra đúng bài toán cũ và đội lại bắt đầu từ một trang trắng.

Playbook FDE trên fde.academy chia một lần triển khai thành sáu giai đoạn. Giai đoạn cuối là một vòng phản hồi, nơi phần việc tuỳ biến làm riêng cho từng khách dần được chuẩn hoá thành tính năng dùng lại được. Bài viết về mô hình Palantir trên cùng trang còn nói thẳng hơn: mỗi giải pháp FDE xây đều góp vào việc phát triển sản phẩm về sau.

Bài viết đó cũng nêu luôn mặt trái: nếu không quản lý vòng lặp này, công việc sẽ trượt thành tuỳ biến thuần tuý và rất khó mở rộng. Vì thế, có thể xem khả năng đóng gói một dự án đã giao là ranh giới giữa việc góp vào sản phẩm và việc chỉ làm tuỳ biến cho từng khách một.

## Bạn sẽ dựng được gì sau một buổi tối?

Bạn sẽ có một thư mục tài liệu và một template repo trên GitHub. Để có ví dụ xuyên suốt, thử hình dung bạn vừa giao cho một công ty logistics một agent đọc hoá đơn PDF và đẩy dữ liệu vào ERP. Ví dụ này là giả định, nhưng cấu trúc bên dưới dùng được cho mọi loại dự án.

Bạn cần chuẩn bị bốn thứ: một tài khoản GitHub, repo của dự án cũ, ghi chú họp hoặc lịch sử chat trong lúc triển khai, và khoảng ba giờ không bị làm phiền. Cấu trúc đích trông như sau (đã giản lược):

```text
fde-invoice-agent-template/
├── README.md            # repo này giải quyết bài toán gì, chạy thế nào
├── docs/
│   ├── adr/             # quyết định kiến trúc, mỗi tệp một quyết định
│   ├── runbooks/        # how-to: xử lý sự cố, vận hành
│   ├── explanation/     # vì sao hệ thống hoạt động như vậy
│   └── playbook.md      # các giai đoạn triển khai cho khách mới
├── config/
│   └── customer.example.yaml
└── src/
```

Năm phần tài liệu cần viết là README, ADR, runbook, phần giải thích và playbook. Các bước dưới đây đi qua lần lượt từng phần, rồi kết thúc bằng việc đóng gói tất cả vào template repo.

## Bước 1: Chép lại quyết định trước khi trí nhớ phai

Định nghĩa trên adr.github.io rất gọn: một Architectural Decision Record ghi lại đúng một quyết định kiến trúc cùng lý do đằng sau nó. Hãy mở ghi chú họp và tìm những chỗ đội từng tranh luận, chẳng hạn chọn OCR nào, chạy batch hay realtime, hay để agent tự sửa dữ liệu hay chờ người duyệt.

```markdown
# ADR-003: Agent không ghi thẳng vào ERP, chờ người duyệt

## Tình huống
Hoá đơn có định dạng không ổn định; ERP của khách không hỗ trợ rollback.

## Quyết định
Agent ghi vào bảng staging; kế toán duyệt rồi mới đẩy sang ERP.

## Hệ quả
+ Không có dữ liệu sai lọt vào sổ sách.
- Thêm một bước thủ công; cần đo thời gian duyệt.

## Khi nào nên xem lại
Khi ERP của khách mới có API hoàn tác.
```

Mục "Khi nào nên xem lại" là phần đáng tiền nhất. Nó cho người đến sau biết quyết định này phụ thuộc vào điều kiện của riêng khách cũ, nên ở khách mới có thể làm khác. **Kiểm tra:** đưa ADR cho một đồng nghiệp không tham gia dự án. Nếu họ đọc xong mà vẫn phải hỏi "sao không ghi thẳng vào ERP?", tệp đó còn thiếu bối cảnh.

## Bước 2: Tách runbook khỏi phần giải thích

Diátaxis định nghĩa how-to guide là chỉ dẫn đưa người đọc đi qua một vấn đề, hoặc đi tới một kết quả. Runbook nên được viết theo đúng tinh thần đó: mỗi bước là một hành động, không có đoạn văn giải thích nào chen vào. Phần "vì sao" để dành cho `docs/explanation/`.

```markdown
# Runbook: Hàng đợi hoá đơn bị kẹt

Mục tiêu: hàng đợi chạy lại, không mất hoá đơn.

1. Mở dashboard hàng đợi; ghi lại số hoá đơn đang chờ.
2. Kiểm tra log worker trong 15 phút gần nhất, tìm lỗi timeout OCR.
3. Nếu có timeout: chuyển worker sang chế độ xử lý từng tệp.
4. Xác nhận số hoá đơn chờ giảm dần.
5. Nếu không giảm sau 30 phút: báo người trực phía khách (xem danh bạ).

Tìm hiểu nguyên nhân: docs/explanation/ocr-timeouts.md
```

Các con số trong ví dụ là minh hoạ, bạn thay bằng ngưỡng thật của hệ thống mình. **Kiểm tra:** đọc lướt runbook. Nếu có bước nào bắt đầu bằng "Lưu ý rằng hệ thống…", hãy chuyển câu đó sang phần giải thích.

## Bước 3: Viết runbook cùng những người sẽ dùng nó

Sách SRE của Google, ở chương về quản lý sự cố, khuyên chuẩn bị trước: xây dựng và ghi lại quy trình xử lý sự cố từ sớm, có tham vấn những người sẽ tham gia xử lý. Trong ví dụ agent hoá đơn, nếu khách tự vận hành hệ thống sau bàn giao, những người đó là đội IT của khách chứ không phải đội của bạn.

Vì vậy, đừng viết runbook một mình rồi gửi file đi. Hãy đặt một buổi 45 phút, cho người vận hành thử làm theo từng bước trong khi bạn ngồi im quan sát. Bước nào họ phải hỏi lại thì bước đó cần viết lại.

## Bước 4: Gom thành playbook theo giai đoạn

`playbook.md` không phải bản sao các ADR. Nó là bản đồ: với mỗi giai đoạn triển khai, bạn ghi cần hỏi khách những gì, ADR nào nên đọc, runbook nào cần chuẩn bị trước. Bạn có thể dùng sáu giai đoạn trong playbook của fde.academy làm khung, miễn là giai đoạn cuối luôn là vòng phản hồi về sản phẩm.

```markdown
## Giai đoạn: Tích hợp dữ liệu
- Hỏi khách: ERP có hỗ trợ hoàn tác không? (→ ADR-003)
- Chuẩn bị: runbooks/queue-stuck.md
- Phần đã tuỳ biến ở khách trước: parser cho mẫu hoá đơn riêng
→ ứng viên đưa vào sản phẩm (đã báo đội lõi)
```

Dòng cuối là chỗ vòng lặp kiểu Palantir thật sự diễn ra: giải pháp ngoài hiện trường được đội lõi xem xét rồi biến thành năng lực của sản phẩm. Mỗi lần ghi "ứng viên đưa vào sản phẩm", bạn đang kéo dự án ra khỏi cái bẫy tuỳ biến thuần tuý.

## Bước 5: Dựng template repo, đừng fork

Tài liệu GitHub ghi rằng ai có quyền truy cập một template repository đều tạo được repo mới từ nó. Repo tạo ra theo cách này bắt đầu với một commit duy nhất. Fork thì khác: nó mang theo toàn bộ lịch sử.

Với FDE, khác biệt này rất quan trọng. Lịch sử commit của dự án cũ có thể chứa tên khách, endpoint nội bộ, hay một file CSV mẫu ai đó lỡ commit rồi xoá đi.

Quy trình gọn nhất là tạo một repo mới, chỉ chép sang mã đã làm sạch, thay mọi giá trị riêng của khách bằng `customer.example.yaml`, rồi bật chế độ template trong phần cài đặt repo.

**Điểm mấu chốt:** Một dự án chỉ thật sự xong khi khách tiếp theo bắt đầu nhanh hơn khách trước.

**Kiểm tra:** tạo thử một repo mới từ template, mở lịch sử commit và xác nhận chỉ có một commit. Sau đó tìm trong toàn bộ mã tên khách cũ, tên miền của họ và các từ như "prod". Kết quả phải trống.

## Ba lỗi khiến bộ tài liệu thành vô dụng

Lỗi thứ nhất là coi runbook như sách giáo khoa. Chương về đào tạo người trực của sách SRE xếp việc đào tạo chỉ bằng quy trình, checklist và playbook vào nhóm anti-pattern.

Runbook giúp người ta làm đúng thao tác, còn thư mục `explanation/` giúp họ hiểu vì sao, và khi sự cố không giống bất kỳ bước nào đã viết thì chỉ hiểu biết đó mới cứu được.

Lỗi thứ hai là fork repo của khách cũ cho nhanh, kéo theo toàn bộ lịch sử. Lỗi thứ ba là chỉ ghi lại "làm gì" mà bỏ qua "vì sao". Thiếu ADR, khách tiếp theo sẽ thừa hưởng cả những quyết định chỉ hợp lý trong hoàn cảnh của khách cũ.

## Kỹ năng này hiện ra ở đâu khi đi tuyển?

Khi đọc JD FDE, bạn có thể gặp vòng phản hồi ở trên dưới nhiều cách gọi khác nhau. Hãy để ý những đoạn mô tả việc đưa bài học từ hiện trường về đội sản phẩm, hoặc xây tài sản dùng lại cho nhiều khách: đó là dấu hiệu công ty cần đúng kỹ năng này.

Trong CV, đừng chỉ viết "triển khai hệ thống X cho khách Y". Hãy viết cụ thể hơn, ví dụ: "đóng gói dự án thành template repo, ADR và runbook; khách tiếp theo dùng lại mà không phải viết lại từ đầu". Nếu được, kèm link một template repo công khai đã làm sạch. Ở vòng phỏng vấn, chọn một ADR và kể lại cuộc tranh luận đằng sau nó.

Ngày đầu ở khách mới, việc đầu tiên nên làm là mở `playbook.md` của dự án trước, không phải mở IDE. Dự án đã giao chỉ trở thành tài sản của đội khi người sau dùng lại được nó.

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

- Chọn dự án gần nhất bạn đã giao, viết ba ADR cho ba quyết định gây tranh luận nhiều nhất
- Viết một runbook xử lý sự cố, rồi ngồi đọc lại từng bước với người từng trực hệ thống đó
- Tạo một template repo với cấu trúc thư mục trong bài và đưa link vào CV kèm một dòng mô tả

## Nguồn

- [The Forward Deployed Engineer Playbook: How Top FDEs Approach a New Deployment](https://fde.academy/blog/forward-deployed-engineer-playbook)

- [How Palantir Invented the Forward Deployed Engineer Model and Why AI Startups Are Adopting It](https://fde.academy/blog/how-palantir-invented-the-forward-deployed-engineer-model)

- [Managing Incidents (Google SRE book, ch. 14)](https://sre.google/sre-book/managing-incidents/)

- [Chapter 28 - Accelerating SREs to On-Call and Beyond](https://sre.google/sre-book/accelerating-sre-on-call/)

- [Creating a repository from a template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template)

- [How-to guides](https://diataxis.fr/how-to-guides/)

- [Architectural Decision Records (ADRs)](https://adr.github.io/)