Bài 12 · Vận dụng · 24 phút
Dùng AI dựng tài liệu C4 & BA
Biên soạn bởi Nguyễn Anh Tuấn
Mở rộng - dùng AI (Claude/Claude Code) sinh nháp sơ đồ C4 (Mermaid) từ mô tả/codebase, soạn tài liệu BA (user story, acceptance criteria) kèm KIỂM CHỨNG.
Ở bài trước, tài liệu đã có nhà trong repo. Nhưng viết hết bằng tay rất tốn công - và đây là việc AI làm rất tốt: dựng nháp nhanh. Vai trò của mèo con đổi từ "người gõ" sang người kiểm chứng và quyết định.
- ▸AI giỏi: nháp sơ đồ, nháp user story, rút glossary - phần tốn thời gian nhất.
- ▸AI dở: quyết định ranh giới, đánh đổi thiết kế, đúng/sai nghiệp vụ - phần của con người.
- ▸Quy tắc vàng: AI gợi ý, mèo con chịu trách nhiệm cuối.
Chưa quen AI?
Bí quyết là prompt rõ ràng: nói rõ hệ thống gì, mức C4 nào, và định dạng đầu ra (vd Mermaid). Với một agent đọc được repo (như Claude Code), bạn còn nhờ nó suy ra từ code.
prompt mẫu (gõ cho AI)
Doc thu muc src/ cua repo nay. Ve so do C4 muc Container cho he thong,
xuat ra Mermaid (C4Container). Voi moi container ghi cong nghe; voi moi
quan he ghi giao thuc. Liet ke ro container nao goi he thong ngoai.- ▸Nêu MỨC C4 cụ thể (Context/Container/Component) - đừng để AI tự đoán.
- ▸Yêu cầu định dạng (Mermaid/Structurizr) để dán thẳng vào docs/.
- ▸Với agent đọc repo: nhờ suy từ code, nhưng vẫn phải duyệt lại ranh giới.
Trung thực
AI cũng dựng nhanh tài liệu Business Analysis: user story, tiêu chí chấp nhận, và glossary. Đây là nháp để BA và đội tinh chỉnh, không phải bản chốt.
user-stories.md - nháp AI sinh (mèo con duyệt lại)
# User story: Nap tien vao vi
La nguoi dung, toi muon nap tien tu ngan hang vao vi
de co so du thanh toan.
## Tieu chi chap nhan
- Cho rang nguoi dung da lien ket tai khoan ngan hang,
Khi nap mot so tien hop le,
Thi so du vi tang dung bang so tien do.
- Cho rang so du ngan hang khong du,
Khi nap tien,
Thi he thong bao loi va khong tru tien.- ▸User story theo mẫu: "Là <vai trò>, tôi muốn <mục tiêu> để <lợi ích>".
- ▸Tiêu chí chấp nhận theo Cho/Khi/Thì (Given/When/Then) - rõ ràng, kiểm được.
- ▸Kiểm story theo INVEST (độc lập, thương lượng được, có giá trị, ước lượng được, nhỏ, kiểm thử được).
- ▸Glossary giữ thuật ngữ NHẤT QUÁN giữa kinh doanh và kỹ thuật - một từ một nghĩa.
Giá trị thật sự lộ ra khi tài liệu sống cùng code: một agent đọc được repo có thể giúp phát hiện khi sơ đồ và code lệch nhau, và đề xuất cập nhật.
- ▸Khi thêm một service mới, nhờ AI cập nhật sơ đồ Container tương ứng.
- ▸Nhờ AI rà: sơ đồ còn khớp cấu trúc code hiện tại không?
- ▸Mọi đề xuất của AI vẫn đi qua Pull Request để người thật review - không tự động merge.
Vòng lặp lành mạnh
Đây là phần quan trọng nhất bài, và là tinh thần xuyên suốt Mèo Ham Học: đừng tin mù quáng. Tài liệu sai còn nguy hơn không có, vì người ta sẽ tin nó.
- ▸Đối chiếu phần tử với thực tế: container/component này có THẬT trong hệ thống không?
- ▸Kiểm ranh giới trong/ngoài: AI có gộp nhầm hệ thống ngoài vào trong không?
- ▸Soi nghiệp vụ với người liên quan: user story có đúng điều họ cần không?
- ▸Không ship nháp chưa đọc lại - chữ ký của mèo con nằm trên tài liệu, không phải của AI.
Trung thực
Mèo con giờ có docs-as-code (nơi lưu) và AI (cách dựng nhanh). Bài cuối ghép tất cả thành một quy trình chạy được, từ ý tưởng tới code.
Bước tiếp theo
Câu hỏi thường gặp
Không. AI giỏi làm NHÁP nhanh - thứ tốn thời gian nhất khi viết tài liệu. Nhưng quyết định ranh giới hệ thống, đánh đổi thiết kế, và đúng/sai nghiệp vụ vẫn là việc của con người. AI là trợ thủ, không phải người chịu trách nhiệm.
Đây là rủi ro thật. AI có thể bịa một container không tồn tại, hay hiểu sai nghiệp vụ. Vì vậy LUÔN kiểm chứng nháp với thực tế: đối chiếu code, hỏi người liên quan. Không bao giờ ship tài liệu AI sinh mà chưa đọc lại.
Ghé khoá Claude Code trên Mèo Ham Học: nó dạy từ số 0 cách làm việc với một trợ lý lập trình AI - vòng lặp agentic, cấp ngữ cảnh, và quan trọng nhất là kiểm chứng.
Khoá Lập trình với Claude Code →Tick những điều em tự tin làm được. Càng lên cao, em càng hiểu sâu.
Trả lời vài câu để chắc rằng em đã nắm bài.
Vai trò hợp lý nhất của AI khi dựng tài liệu C4 & BA là gì?
- 1
Prompt sinh Context
Viết một prompt yêu cầu AI tạo sơ đồ C4 System Context (dạng Mermaid) cho một hệ thống mèo con biết. Nếu có AI, chạy thử và xem kết quả.
Hoàn thành khi: Prompt nêu rõ: hệ thống gì, mức Context, định dạng Mermaid; (nếu chạy) thu được sơ đồ render được.
- 2
Soát nháp của AI
Lấy một sơ đồ hoặc tài liệu do AI sinh, tìm ít nhất hai chỗ sai hoặc thiếu (vd bịa một container, sai ranh giới ngoài/trong) và sửa lại.
Hoàn thành khi: Chỉ ra ≥2 lỗi cụ thể; mỗi lỗi kèm cách sửa và lý do.
- 3
User story bằng AI
Nhờ AI viết 3 user story kèm tiêu chí chấp nhận (Cho/Khi/Thì) cho một tính năng. Kiểm theo INVEST và chỉnh lại.
Hoàn thành khi: Có 3 story đúng mẫu "Là... tôi muốn... để..."; mỗi story có tiêu chí chấp nhận; đã chỉnh ít nhất một story.
- 4
Glossary từ mô tả
Đưa một đoạn mô tả nghiệp vụ cho AI, nhờ rút ra glossary (từ điển thuật ngữ chung). Bổ sung hoặc sửa các định nghĩa.
Hoàn thành khi: Glossary có ≥5 thuật ngữ; mỗi thuật ngữ một định nghĩa ngắn, đã kiểm lại bằng kiến thức của mèo con.
- 5
Danh sách kiểm chứng
Viết một checklist mèo con sẽ dùng để kiểm một sơ đồ/tài liệu do AI sinh trước khi đưa vào repo.
Hoàn thành khi: Checklist có ≥4 mục (vd: phần tử có thật không, ranh giới đúng không, nhãn quan hệ đúng không, có bịa gì không).
- 6
Chưa quen AI?
Nếu mèo con chưa từng dùng AI, đọc lướt 1-2 bài đầu khoá Claude Code rồi ghi 3 điều áp dụng được vào việc dựng tài liệu.
Hoàn thành khi: Ghi được 3 ý (vd: cấp ngữ cảnh rõ, plan trước, luôn kiểm chứng).