Tài liệu hướng dẫn Vibe Engineering với bộ tài liệu khoa học

Sau một thời gian nghiên cứu và áp dụng cũng như kế thừa tư tưởng của framework BMAD, TEDU đã làm ra một tài liệu chứa danh sách prompt hướng dẫn mọi người cách tạo bộ tài liệu giúp cho Claude Code có thể sinh code nhất quán, đảm bảo prompt ít hiểu nhiều giúp việc làm phần mềm với AI nhanh và tốn ít công hơn.Mình đã hệ thống hóa lại thành hệ thống 9 prompt tạo ra 9 file tài liệu để trong repository của mọi người, các tài liệu này dạng Markdown sẽ được sử dụng bởi CLAUDE.md giúp Claude Code luôn đọc và kiểm tra trên tất cả các task giúp việc output và validate một cách khoa học:

• prd.md: Là file project requirement chứa nghiệp vụ của hệ thống, giải quyết vấn đề gì? cho ai? yêu cầu chức năng và phi chức năng ra sao? Bảo mật và hiệu năng ra sao? Từ yêu cầu cơ bản của bạn, AI sẽ tạo ra 1 file hoàn chỉnh giúp làm source of truth cho toàn bộ dự án.

• domain-glossary.md: Là file thống nhất toàn bộ thuật ngữ nghiệp vụ của dự án — khái niệm nào gọi tên gì, không được gọi thành từ đồng nghĩa khác. Đây là chỗ hay bị bỏ qua nhất khi làm việc với AI: PRD gọi là "Học viên", kiến trúc lại đặt entity là User, giao diện lại hiển thị "Người dùng" — 3 tên cho cùng 1 khái niệm. AI sẽ đọc PRD, trích ra mọi danh từ nghiệp vụ, và chốt lại thành 1 bảng tên gọi duy nhất để mọi file sau bám theo.

• decisions.md: Là nhật ký quyết định — tại sao lúc đó chọn giải pháp này mà không phải giải pháp khác. Làm phần mềm một mình hoặc với AI có một vấn đề thực tế: vài tháng sau quay lại dự án, không ai nhớ vì sao ngày trước chọn Postgres thay vì MySQL, hay vì sao bỏ qua 1 best practice nào đó. AI sẽ tự ghi lại bối cảnh, các lựa chọn đã cân nhắc, và lý do chọn — trước khi báo hoàn thành task, không phải ghi sau khi đã quên.

• architecture.md: Là file mô tả kiến trúc, tech stack, bảo mật, hiệu năng — nhưng không phải kiểu liệt kê công nghệ cho có, mà mỗi lựa chọn phải gắn với đúng yêu cầu đã nêu trong prd.md. AI sẽ tự giải thích vì sao chọn công nghệ này, module nào giải quyết yêu cầu nào, và nêu rõ rủi ro nếu có yêu cầu nào chưa đáp ứng được — không được im lặng bỏ qua.

• ux.md: Là file quy định giao diện trông và hoạt động ra sao — nguyên tắc thiết kế, luồng màn hình, trạng thái loading/lỗi/rỗng bắt buộc phải có. Đây là chỗ AI hay code thiếu nhất nếu không có file này: code xong luồng chính rồi quên mất màn hình lỗi. AI sẽ tự đề xuất design token, pattern component dùng lại được, và đảm bảo mọi copy trên giao diện dùng đúng thuật ngữ đã chốt ở domain-glossary.md.

• deploy.md: Là file hướng dẫn đưa hệ thống lên môi trường thật — môi trường nào, quy trình CI/CD ra sao, rollback thế nào khi có sự cố. AI sẽ tự dựng quy trình deploy khớp với hạ tầng đã chọn ở architecture.md, và có 1 quy tắc cứng: không bao giờ được tự ý deploy lên production khi chưa có xác nhận của mình, dù mọi test đã pass.

• conventions.md: Là chuẩn code dùng để AI tự review lại chính code nó vừa viết ra — naming, cấu trúc thư mục, cách xử lý lỗi, chuẩn test. Mỗi quy tắc phải cụ thể tới mức trả lời được đúng/sai, không phải khuyến nghị chung chung như "code sạch". AI sẽ tự đặt ra bộ chuẩn khớp đúng với stack đã chọn, rồi dùng chính nó để tự chấm điểm code trước khi báo xong việc.

• status.md: Là bản đồ tiến độ — chia dự án thành từng phase, mỗi phase có checklist cụ thể. Quy tắc quan trọng nhất ở đây: 1 hạng mục chỉ được tick xong khi có đủ unit test, integration test, và e2e test đều pass — code chạy được thôi chưa đủ. AI phải tự cập nhật file này sau mỗi task, không đợi mình nhắc.

• CLAUDE.md: Là file luật chơi, đặt ở gốc repo để Claude Code tự động đọc mỗi khi mở phiên làm việc mới. Đây là file ràng buộc tất cả 8 file trên phải được đọc trước mỗi task, quy định thế nào là "xong" một cách khoa học (đủ 3 tầng test mới tính), và bắt AI phải hỏi lại mình thay vì tự đoán khi có mâu thuẫn giữa các file