Đồng Use Claude — Phần 8: WORKBOOK, đóng gói tính năng để không làm lại từ đầu
App chạy rồi thì rút phần khó nhất thành workbook: một file chứa toàn bộ logic, rủi ro đã dự phòng và kịch bản nghiệm thu của một tính năng — để lần sau AI gắn vào là dùng, không dựng lại từ đầu.
Bạn vừa ship app sổ khách. Phần đáng giá nhất trong đó không phải cái app — mà là luật gộp khách trùng: normalize phone, UNIQUE constraint, merge-into-existing, import batch với skipped count. Lần tới làm app khác cũng cần quản lý khách, bạn muốn mang nguyên phần đó đi mà không phải suy nghĩ lại.
Workbook là file chứa trọn một tính năng đã qua nghiệm thu: logic, rủi ro đã dự phòng, và kịch bản kiểm tra. Gắn vào dự án mới → AI đọc, đối chiếu hệ thống đang có, trình phương án, bạn gật → nó tự thi công theo chuẩn đã kiểm chứng.
Bài cuối trong series.
Vì sao không copy code
Copy folder code từ dự án cũ sang dự án mới thất bại vì code cũ gắn chặt với quyết định cũ: tên bảng, stack, quy ước lỗi. Cái tái sử dụng được là quyết định, không phải dòng code. Workbook giữ quyết định — code thì AI viết lại theo quyết định đó, trong stack của dự án mới.
Đây cũng là lý do cả series ép mọi thứ thành file: INTENT/SPEC/PLAN của dự án cũ chính là nguyên liệu để rút workbook.
Cấu trúc một workbook
# Workbook: crm-dedup
Gộp khách trùng theo số điện thoại. Rút từ dự án sổ
khách, đã nghiệm thu [date].
## 1. Tính năng
Thêm khách (đơn lẻ hoặc import) mà không bao giờ tạo
hai bản ghi cùng phone. Trùng → gộp vào bản ghi cũ.
## 2. Business rules
- phone_norm = chỉ chữ số; "+84"/"84" → "0"
- phone_norm UNIQUE toàn hệ thống
- Trùng: giữ bản cũ, điền field trống, nối ghi chú,
không ghi đè tên
- Import: dòng thiếu phone → skipped, không fail batch
## 3. Cài đặt chuẩn (tham khảo)
- UNIQUE constraint ở DB — KHÔNG check-then-insert
- Insert thẳng → catch lỗi unique → merge vào bản cũ
- Trả về { merged: bool, customer } để UI báo rõ
## 4. Rủi ro đã dự phòng
- Race: 2 request cùng phone đồng thời → constraint
ở DB chặn, không phải code
- Phone format loạn: khoảng trắng, gạch, +84, 84
- CSV lỗi format → skipped, báo số dòng
## 5. Kịch bản nghiệm thu
- [ ] Tạo mới → merged:false
- [ ] Cùng phone, format khác → merged:true, id cũ
- [ ] Import 2 dòng trùng → added:1, merged:1
- [ ] 10 request đồng thời cùng phone → đúng 1 row
- [ ] Dòng thiếu phone → skipped, không crash
## 6. Điều kiện áp dụng
- Cần DB có UNIQUE constraint (SQLite/Postgres/D1 đều được)
- Dedup theo phone; nếu nghiệp vụ cần dedup theo email
→ thêm cột norm + constraint tương tựNhìn quen không? Đúng — đây là SPEC + PLAN + TEST của một tính năng, rút gọn thành một file độc lập với dự án.
Cách dùng trong dự án mới
Đặt workbook vào workbooks/crm-dedup.md trong dự án mới, rồi:
> Đọc workbooks/crm-dedup.md và toàn bộ codebase hiện
tại. Đề xuất cách gắn tính năng này vào hệ thống đang
có: file nào đổi, schema nào thêm, trade-off nào phát
sinh. Chưa code — trình phương án để tao duyệt.Cơ chế nghiệm thu vẫn là phần quan trọng nhất: mục 5 của workbook buộc AI tự chạy kịch bản kiểm thử thực tế trước khi bàn giao — y như lúc bạn làm lần đầu, nhưng lần này kịch bản đã có sẵn.
Năm workbook đáng rút đầu tiên
Gần như mọi app nghiệp vụ đều quay về năm mảnh này:
| Workbook | Tính năng | Rủi ro kinh điển |
|---|---|---|
crm-dedup | Quản lý khách, gộp trùng | Race khi tạo đồng thời, format phone loạn |
booking | Đặt chỗ theo slot | Hai người đặt đè một ô giờ |
payments | Thu tiền | Double-charge, webhook lặp, tiền về nhưng đơn chưa ghi |
auth-roles | Đăng nhập, phân quyền | Session rò, role check ở client thay vì server |
email | Gửi mail | Gửi trùng, template vỡ, bị spam-flag |
Mỗi lần ship xong một tính năng thuộc dạng này, dành 20 phút rút nó thành workbook. Sau ba dự án bạn có bộ quy chuẩn riêng — tương đương thuê một kỹ sư giỏi đã viết sẵn tài liệu đặc tả và kịch bản test cho từng mảng.
Vòng đời đầy đủ, nhìn lại
Ý tưởng
→ INTENT (vì sao, cho ai)
→ SPEC (làm gì, luật gì)
→ PLAN (thứ tự, rủi ro, proof)
→ BUILD (AI thi công, bạn giám sát)
→ TEST (nghiệm thu bằng kịch bản)
→ DEPLOY (lên mạng, tài khoản của bạn)
→ WORKBOOK (rút bài học thành tài sản tái dùng)Dự án đầu tiên đi hết vòng này chậm và vất — bạn phải viết mọi file từ con số không. Dự án thứ ba, bạn mở máy ra đã có sẵn nửa bộ workbook, file CLAUDE.md quen thuộc, và quy trình đã vào tay. Đó là lúc “không biết code” ngừng là vấn đề: bạn đang điều hành một đội kỹ thuật, chỉ là đội đó không đi vệ sinh giữa giờ.