Vibe Coding là gì? Cách lập trình với AI đúng cách từ ý tưởng đến sản phẩm

Có một chuyện khá thú vị trong nghề lập trình.

Ngày trước, để xây dựng một website, chúng ta thường bắt đầu bằng việc cài môi trường, tạo database, thiết kế giao diện, viết API rồi dành không ít thời gian tìm xem tại sao chương trình không chạy.

Đôi khi chỉ vì một dấu ngoặc.

Bây giờ, chúng ta có thể mở một công cụ AI và yêu cầu: "Hãy xây dựng cho tôi một ứng dụng quản lý công việc, có đăng nhập, phân quyền, giao việc và báo cáo tiến độ".

Chỉ sau một số lượt trao đổi, một ứng dụng với giao diện, mã nguồn và cơ sở dữ liệu có thể đã hình thành.

Nghe thích thật!

Nhưng chú Nha 27 tuổi muốn đặt một câu hỏi khác: Nếu AI có thể viết phần lớn mã nguồn, vậy con người cần làm gì để phần mềm được xây dựng đúng, vận hành ổn định và không trở thành một mớ code mà chẳng ai hiểu?

Câu trả lời không nằm ở việc viết prompt thật dài.

Chúng ta cần một quy trình.

Trong bài viết này, tôi sẽ chia sẻ cách hiểu Vibe Coding, cách sử dụng AI để nghiên cứu và chuẩn hóa yêu cầu, tổ chức tài liệu Markdown, giao nhiệm vụ cho AI Coding Agent, kiểm thử và triển khai phần mềm.

Đây không phải cách duy nhất để lập trình với AI. Nhưng đó là một phương pháp có thể áp dụng, kiểm tra và cải thiện dần, thay vì chỉ hy vọng AI hiểu đúng ý mình.

1. Vibe Coding là gì?

Vibe Coding là cách xây dựng phần mềm thông qua việc mô tả mong muốn bằng ngôn ngữ tự nhiên, để AI tạo mã nguồn và tiếp tục điều chỉnh dựa trên phản hồi của người dùng.

Thuật ngữ Vibe Coding được Andrej Karpathy phổ biến vào tháng 2/2025. Theo cách mô tả ban đầu, người sử dụng có thể ít quan tâm đến mã nguồn, chấp nhận những thay đổi AI đề xuất và liên tục gửi lỗi trở lại để AI sửa.

Cách làm này phù hợp với tinh thần thử nghiệm nhanh. Một người có ý tưởng có thể tạo ra sản phẩm mẫu mà không phải tự viết toàn bộ code.

Tuy nhiên, có một điểm cần phân biệt.

• Vibe Coding theo nghĩa ban đầu: Người dùng chủ yếu điều khiển bằng ngôn ngữ tự nhiên, có thể không đọc hoặc hiểu kỹ mã nguồn do AI tạo ra.
• AI-assisted Software Engineering: AI hỗ trợ phân tích, thiết kế, viết code, kiểm thử và xử lý lỗi, nhưng mọi thay đổi vẫn nằm trong một quy trình kỹ thuật có yêu cầu và kiểm soát.

Hiện nay, trong các cuộc trao đổi công nghệ, nhiều người dùng tên gọi Vibe Coding cho cả hai hình thức.

Với dự án cá nhân, prototype hoặc ứng dụng thử nghiệm, việc sử dụng AI theo cách linh hoạt có thể mang lại nhiều lợi ích.

Nhưng khi phần mềm liên quan đến khách hàng, tài chính, dữ liệu cá nhân hoặc quy trình kinh doanh, chúng ta cần một cách tiếp cận chặt chẽ hơn.

Vì thế, trong bài viết này, tôi sử dụng tên gọi Vibe Coding theo cách phổ biến, nhưng hướng dẫn một phương pháp có kiểm soát mà tôi gọi là Human-Directed AI Coding.

Hiểu đơn giản: Con người định hướng và chịu trách nhiệm. AI hỗ trợ nghiên cứu và thực thi.

2. Tư duy quan trọng nhất: Con người quyết định WHAT, WHY, RULES; AI thực hiện HOW

Trước khi nói đến công cụ, hãy xác định trách nhiệm.

Tôi muốn chia quá trình phát triển phần mềm thành bốn câu hỏi:

• WHY: Tại sao chúng ta cần xây dựng phần mềm này?
• WHAT: Phần mềm phải làm được những gì?
• RULES: Những quy tắc và giới hạn nào phải được tuân thủ?
• HOW: Chúng ta sẽ triển khai bằng giải pháp kỹ thuật nào?

WHY - Tại sao phải làm?

Ví dụ, chúng ta muốn xây dựng một ứng dụng quản lý công việc.

WHY không đơn giản là "vì công ty cần phần mềm quản lý công việc".

Mục tiêu thực tế có thể là:

• Giảm tình trạng công việc bị bỏ sót.
• Giúp mọi người biết công việc đang do ai phụ trách.
• Phát hiện vướng mắc sớm để cùng xử lý.
• Giúp người quản lý theo dõi tiến độ mà không cần hỏi từng người.

Nếu chưa xác định WHY, chúng ta rất dễ xây dựng nhiều chức năng nhưng lại bỏ sót vấn đề quan trọng nhất.

WHAT - Phần mềm phải làm được những gì?

WHAT là những yêu cầu cụ thể.

Với ứng dụng quản lý công việc, có thể bao gồm:

• Tạo công việc và giao cho người phụ trách.
• Thiết lập thời hạn hoàn thành.
• Cập nhật tiến độ.
• Ghi nhận vướng mắc.
• Thông báo công việc quá hạn.
• Báo cáo theo nhóm hoặc phòng ban.

Mỗi yêu cầu nên có tiêu chí nghiệm thu để xác định khi nào chức năng được xem là hoàn thành.

RULES - Những quy tắc không được vi phạm

Đây là phần rất dễ bị bỏ quên nếu chúng ta chỉ mô tả giao diện.

Ví dụ:

• Nhân viên chỉ được xem công việc trong phạm vi được phân quyền.
• Người giao việc phải có quyền giao cho người nhận.
• Không được tự ý xóa lịch sử thay đổi quan trọng.
• Mỗi công việc phải có mã định danh duy nhất.
• Không được ghi nhận giao dịch thành công nếu việc lưu dữ liệu thất bại.
• Không được để lộ mật khẩu hoặc khóa truy cập trong mã nguồn.

Một ứng dụng có thể chạy rất mượt, giao diện đẹp, nhưng nếu nhân viên nhìn thấy dữ liệu không thuộc quyền của mình thì phần mềm vẫn có lỗi nghiêm trọng.

HOW - Triển khai bằng cách nào?

Khi mục tiêu, yêu cầu và quy tắc đã rõ, AI có thể giúp đề xuất và thực hiện phần lớn công việc kỹ thuật.

• Đề xuất kiến trúc.
• Thiết kế database.
• Viết frontend và backend.
• Xây dựng API.
• Viết kiểm thử.
• Phát hiện và sửa lỗi.
• Chuẩn hóa mã nguồn.
• Viết tài liệu kỹ thuật.

Tuy nhiên, HOW không phải vùng AI được toàn quyền quyết định. Những lựa chọn có ảnh hưởng lớn đến dữ liệu, bảo mật, chi phí hoặc kiến trúc vẫn cần con người phê duyệt.

Và có thêm một điều quan trọng: Con người quyết định WHAT, WHY, RULES không có nghĩa là con người phải tự viết tất cả tài liệu.

Chúng ta có thể nhờ AI hỗ trợ cả giai đoạn nghiên cứu này.

3. Con người quyết định, AI hỗ trợ nghiên cứu và chuẩn hóa yêu cầu

Đây là phần tôi muốn nhấn mạnh trong quy trình sử dụng AI để lập trình.

Thay vì mở một AI Coding Agent rồi yêu cầu viết code ngay, chúng ta có thể sử dụng một công cụ AI khác để nghiên cứu, trao đổi và chuẩn hóa ý tưởng trước.

AI có thể đóng vai Business Analyst, Product Manager hoặc Solution Architect.

Con người đưa ra mục tiêu. AI đặt câu hỏi, phát hiện yêu cầu còn thiếu, đưa ra các phương án và giúp tổ chức thông tin.

Sau khi trao đổi, con người kiểm tra và phê duyệt các quyết định.

Những nội dung đã thống nhất sẽ được lưu thành các file Markdown (.md), chẳng hạn như BRD, SRS, business rules và acceptance criteria.

Sau đó, AI Coding Agent sử dụng bộ tài liệu này để triển khai.

Vì sao nên tách AI nghiên cứu và AI lập trình?

Hãy lấy ví dụ một ứng dụng quản lý bán hàng.

Nếu yêu cầu AI "Tạo phần mềm bán hàng có khuyến mãi, công nợ, thanh toán và báo cáo", AI có thể tự giả định nhiều quy tắc.

Chẳng hạn:

• Khuyến mãi được áp dụng trước hay sau thuế?
• Có cho phép khách hàng nợ không?
• Đơn hàng đã thanh toán có được sửa không?
• Ai được quyền hoàn tiền?
• Khi hoàn hàng thì tồn kho được cập nhật thế nào?
• Hai nhân viên cùng bán sản phẩm cuối cùng trong kho thì xử lý ra sao?

Nếu những câu hỏi này chưa được trả lời, AI có thể viết code dựa trên một loạt giả định.

Code có thể đúng về mặt cú pháp, nhưng sai nghiệp vụ.

Do đó, tôi đề xuất hai vai trò riêng biệt:

• AI Research / Business Analyst: Hỗ trợ nghiên cứu, đặt câu hỏi, phân tích yêu cầu, chuẩn hóa BRD và SRS.
• AI Coding Agent: Nhận tài liệu đã được phê duyệt, lập kế hoạch kỹ thuật và triển khai mã nguồn.

Không nhất thiết phải sử dụng hai nhà cung cấp AI khác nhau. Có thể dùng hai công cụ, hai agent hoặc hai phiên làm việc riêng biệt.

Điều quan trọng là phân chia trách nhiệm, không phải số lượng công cụ.

Chuẩn hóa tài liệu dưới dạng Markdown

Markdown là định dạng văn bản đơn giản, dễ đọc, dễ chỉnh sửa và có thể quản lý phiên bản bằng Git.

Hầu hết công cụ AI Coding hiện đại đều có thể sử dụng nội dung Markdown làm nguồn tham khảo, tùy theo khả năng đọc file và cơ chế quản lý context của từng công cụ.

Một cấu trúc tài liệu tham khảo:

project/
|
+-- AGENTS.md
+-- README.md
|
+-- docs/
|   +-- 00-project-overview.md
|   +-- 01-business-requirements.md
|   +-- 02-software-requirements.md
|   +-- 03-business-rules.md
|   +-- 04-user-roles-permissions.md
|   +-- 05-data-model.md
|   +-- 06-api-contracts.md
|   +-- 07-acceptance-criteria.md
|   +-- 08-architecture.md
|   +-- 09-non-functional-requirements.md
|   +-- decisions/
|
+-- tasks/
|   +-- TASK-001.md
|   +-- TASK-002.md
|
+-- frontend/
+-- backend/
+-- tests/

Trong đó:

• BRD: Business Requirements Document, mô tả mục tiêu, nhu cầu và yêu cầu nghiệp vụ.
• SRS: Software Requirements Specification, mô tả chức năng và các yêu cầu kỹ thuật, phi chức năng của phần mềm.
• Business Rules: Các quy tắc nghiệp vụ phải được tuân thủ.
• Roles & Permissions: Vai trò, quyền truy cập và phạm vi dữ liệu.
• Data Model: Các thực thể, thuộc tính, quan hệ và ràng buộc dữ liệu.
• API Contracts: Quy định cách các thành phần giao tiếp.
• Acceptance Criteria: Điều kiện nghiệm thu từng yêu cầu.
• Architecture: Kiến trúc hệ thống và những quyết định kỹ thuật đã được phê duyệt.
• Task Files: Mỗi file mô tả một nhiệm vụ triển khai cụ thể.

Với dự án nhỏ, không nhất thiết phải tạo đủ các tài liệu này. Có thể kết hợp những phần liên quan để tránh quản lý quá nhiều file.

Với dự án lớn, nên tổ chức tài liệu theo module và sử dụng mã yêu cầu thống nhất để dễ truy vết.

Markdown có giúp tiết kiệm token không?

Có thể, nếu được tổ chức và sử dụng đúng cách.

Nhưng không phải cứ chuyển tài liệu sang .md là tự động giảm token.

Token phụ thuộc vào nội dung được đưa vào context, cách công cụ xử lý tài liệu và số lần thông tin được sử dụng.

Ví dụ, một cuộc trò chuyện dài có thể chứa nhiều lần sửa yêu cầu, các phương án đã bị loại bỏ và những đoạn giải thích lặp lại.

Nếu AI Coding Agent phải đọc lại toàn bộ cuộc trò chuyện, chi phí context có thể tăng lên.

Thay vào đó, chúng ta chuẩn hóa các quyết định đã được chốt thành tài liệu ngắn gọn, bỏ những thông tin không còn hiệu lực và chỉ cung cấp phần liên quan đến nhiệm vụ hiện tại.

Ví dụ, khi lập trình chức năng đăng nhập, AI cần đọc tài liệu xác thực, phân quyền và những phần kiến trúc có liên quan. Không cần đọc toàn bộ yêu cầu quản lý kho, chương trình khuyến mãi hoặc báo cáo doanh thu.

Đó mới là cách tối ưu context.

Không phải nén càng ngắn càng tốt. Tài liệu quá ngắn đến mức thiếu quy tắc nghiệp vụ cũng có thể khiến AI phải hỏi lại hoặc viết sai.

Mục tiêu là cung cấp đủ thông tin cần thiết, không thiếu và không lặp vô ích.

4. Quy trình Human-Directed AI Coding gồm bốn giai đoạn

Từ những nguyên tắc trên, tôi đề xuất một quy trình bốn giai đoạn.

Đây là cách tổ chức công việc mà chúng ta có thể dùng từ lúc hình thành ý tưởng đến khi có sản phẩm vận hành.

PHASE 1: HUMAN + AI RESEARCH
        |
        | WHY / WHAT / RULES
        | Research / BRD / SRS
        | Markdown Documents
        v
PHASE 2: HUMAN APPROVAL
        |
        | Review Requirements
        | Resolve Assumptions
        | Approve Baseline
        v
PHASE 3: AI CODING AGENT
        |
        | Read Relevant Context
        | Implementation Plan
        | Code / Tests / Documentation
        v
PHASE 4: REVIEW, TEST & DEPLOY
        |
        | Automated Tests
        | Human Review
        | Security / UAT
        | Deploy / Monitor
        v
FEEDBACK & IMPROVEMENT

Phase 1 - Human + AI Research

Giai đoạn đầu tiên không phải lập trình, mà là làm rõ vấn đề.

Con người mô tả ý tưởng, mục tiêu và những thông tin đã biết. AI hỗ trợ phân tích, đặt câu hỏi và đề xuất phương án.

Chúng ta có thể yêu cầu AI:

• Xác định các nhóm người dùng.
• Phân tích mục tiêu kinh doanh.
• Đề xuất phạm vi MVP.
• Phát hiện yêu cầu còn thiếu.
• Phân tích các trường hợp ngoại lệ.
• Đề xuất business rules.
• Đề xuất mô hình dữ liệu.
• Chuẩn hóa tài liệu BRD và SRS.
• Tạo danh sách task cho giai đoạn phát triển.

AI phải phân biệt rõ ba loại thông tin: nội dung con người đã xác nhận, giả định cần kiểm tra và đề xuất chưa được phê duyệt.

Đầu ra của giai đoạn này là một bộ tài liệu có cấu trúc, kèm danh sách vấn đề còn cần quyết định.

Phase 2 - Human Approval

Đây là bước kiểm tra và xác nhận.

Con người không cần tự viết từng dòng tài liệu, nhưng phải hiểu và đồng ý với những quyết định có ảnh hưởng đến sản phẩm.

Những nội dung cần xem xét gồm:

• Mục tiêu nghiệp vụ có đúng không?
• Phạm vi chức năng có phù hợp không?
• Có yêu cầu nào mâu thuẫn không?
• Business rules đã đầy đủ chưa?
• Phân quyền và bảo mật có phù hợp không?
• Tiêu chí nghiệm thu có kiểm chứng được không?
• Kiến trúc đề xuất có phù hợp với nguồn lực không?

Sau khi phê duyệt, tài liệu được đưa vào Git để quản lý phiên bản.

Có thể gắn mã phiên bản, trạng thái phê duyệt và người chịu trách nhiệm với từng nhóm yêu cầu.

Tài liệu đã được duyệt trở thành baseline để triển khai, không có nghĩa là không bao giờ được thay đổi. Khi yêu cầu thay đổi, cần cập nhật và phê duyệt lại phần bị ảnh hưởng.

Phase 3 - AI Coding Agent

Đây là lúc AI thực hiện HOW.

Agent được cung cấp:

• Bộ quy tắc dự án.
• Tài liệu yêu cầu đã phê duyệt.
• Task cụ thể.
• Mã nguồn hiện tại.
• Các giới hạn quyền truy cập và thao tác.

Trước khi viết code, AI cần phân tích phạm vi thay đổi, đọc những file liên quan, kiểm tra sự phụ thuộc và đề xuất kế hoạch thực hiện.

Khi kế hoạch được chấp thuận theo mức kiểm soát của dự án, AI triển khai mã nguồn, viết kiểm thử, chạy các bước kiểm tra được phép và báo cáo kết quả.

Không nên cho phép AI tự ý thay đổi yêu cầu nghiệp vụ chỉ vì cách triển khai hiện tại gặp khó khăn.

Nếu phát hiện tài liệu chưa đầy đủ hoặc mâu thuẫn, agent cần báo lại để làm rõ.

Phase 4 - Review, Test & Deploy

AI viết xong code không có nghĩa phần mềm đã hoàn thành.

Chúng ta cần kiểm tra:

• Mã nguồn có đáp ứng yêu cầu đã phê duyệt không?
• Chức năng có hoạt động với dữ liệu hợp lệ và không hợp lệ không?
• Phân quyền có được kiểm tra đúng không?
• Test đã chạy thực tế chưa?
• Có ảnh hưởng đến chức năng hiện tại không?
• Có rủi ro bảo mật hoặc mất dữ liệu không?
• Có thể triển khai và khôi phục khi cần không?

Với dự án quan trọng, nên có môi trường staging, quy trình review độc lập, kiểm thử bảo mật và kế hoạch rollback hoặc khôi phục dữ liệu.

Sau khi triển khai, hệ thống cần được giám sát để phát hiện lỗi và thu thập phản hồi.

Vòng phản hồi giữa các giai đoạn

Quy trình này không phải một đường thẳng chỉ đi từ trên xuống.

Nếu trong lúc viết code, AI phát hiện một business rule chưa rõ, cần quay lại bước nghiên cứu và phê duyệt.

Nếu trong lúc kiểm thử phát hiện yêu cầu chưa đúng với thực tế, cần điều chỉnh tài liệu trước khi tiếp tục.

Điều quan trọng là không để AI tự sửa yêu cầu gốc chỉ để làm cho code chạy được.

5. Mười bước thực hành Vibe Coding từ ý tưởng đến sản phẩm

Bốn giai đoạn giúp chúng ta nhìn tổng thể. Bây giờ hãy chuyển thành những bước thực hiện cụ thể.

Bước 1. Viết mô tả vấn đề

Hãy bắt đầu bằng một đoạn ngắn trả lời những câu hỏi:

• Phần mềm dành cho ai?
• Người dùng đang gặp khó khăn gì?
• Chúng ta muốn cải thiện điều gì?
• Ba chức năng quan trọng nhất là gì?
• Chức năng nào chưa cần làm?
• Làm thế nào để biết sản phẩm có ích?

Chưa cần quyết định ngôn ngữ lập trình.

Bước 2. Sử dụng AI để nghiên cứu và đặt câu hỏi

Đưa mô tả ban đầu cho một công cụ AI và yêu cầu phân tích, phát hiện điểm chưa rõ, đề xuất phương án.

Đừng chỉ hỏi AI "Bạn thấy ý tưởng này tốt không?".

Hãy yêu cầu AI tìm những giả định có thể khiến sản phẩm thất bại, những quy tắc còn thiếu và những trường hợp người dùng thực tế có thể gặp.

Bước 3. Chuẩn hóa BRD, SRS và Business Rules

Sau khi trao đổi, yêu cầu AI tổng hợp thành các file Markdown.

Tài liệu cần có yêu cầu cụ thể, quy tắc nghiệp vụ, tiêu chí nghiệm thu, trường hợp ngoại lệ và những vấn đề chưa được xác nhận.

Đừng đưa toàn bộ nội dung chat vào file tài liệu. Chỉ giữ những quyết định còn hiệu lực và thông tin cần thiết để triển khai.

Bước 4. Con người kiểm tra và phê duyệt tài liệu

Đọc lại yêu cầu với góc nhìn của người sử dụng và người chịu trách nhiệm vận hành.

Kiểm tra đặc biệt những nội dung liên quan đến dữ liệu, tiền, phân quyền, lịch sử giao dịch và những tình huống ngoại lệ.

Bước 5. Thiết kế kiến trúc và bộ quy tắc AI

Yêu cầu AI đề xuất các phương án công nghệ, so sánh ưu nhược điểm và giải thích những quyết định quan trọng.

Sau khi lựa chọn, ghi nhận kiến trúc vào tài liệu và thiết lập project instructions, chẳng hạn AGENTS.md đối với công cụ có hỗ trợ.

Bước 6. Chia dự án thành task nhỏ

Mỗi task nên có mục tiêu, phạm vi, tài liệu tham chiếu, tiêu chí nghiệm thu và danh sách kiểm thử.

Không nên giao một task kiểu "Xây dựng toàn bộ hệ thống quản lý doanh nghiệp" rồi kỳ vọng AI hoàn thành an toàn trong một lượt.

Bước 7. AI phân tích trước khi viết code

Yêu cầu Coding Agent đọc tài liệu liên quan, kiểm tra mã nguồn hiện tại và đưa ra implementation plan.

Nếu có thay đổi lớn về kiến trúc, API hoặc dữ liệu, cần phê duyệt trước.

Bước 8. AI triển khai và kiểm thử

Agent thực hiện công việc trong phạm vi được giao, viết test và chạy các lệnh kiểm tra phù hợp.

Cần yêu cầu báo cáo rõ những test đã chạy thành công, thất bại hoặc chưa thể chạy.

Bước 9. Review, nghiệm thu và triển khai

So sánh kết quả với acceptance criteria, review thay đổi, kiểm tra bảo mật và thử trên môi trường phù hợp.

Với hệ thống đang vận hành, cần có phương án khôi phục trước khi triển khai.

Bước 10. Cập nhật tài liệu và cải thiện quy trình

Khi phát hiện lỗi do yêu cầu thiếu rõ ràng, hãy bổ sung business rules.

Khi phát hiện lỗi có thể tái diễn, hãy bổ sung test.

Khi một quyết định kỹ thuật thay đổi, hãy cập nhật tài liệu kiến trúc.

Mục tiêu là để những lần phát triển tiếp theo ít phải giải thích lại và ít mắc cùng một lỗi.

6. Thực hành với ví dụ: Xây dựng phần mềm quản lý công việc

Giả sử chúng ta muốn tạo ứng dụng quản lý công việc cho một nhóm 20 người.

Thay vì bắt đầu bằng việc yêu cầu AI viết frontend, hãy thử quy trình sau.

Prompt 1 - AI nghiên cứu và xây dựng tài liệu

Bạn đóng vai Senior Business Analyst, Product Manager và Solution Architect.

Tôi muốn xây dựng ứng dụng quản lý công việc cho nhóm 20 người.

Mục tiêu:
- Biết ai đang làm việc gì
- Theo dõi thời hạn
- Phát hiện công việc bị vướng mắc
- Hỗ trợ phối hợp giữa các thành viên

PHASE 1 - RESEARCH

Hãy thực hiện:
1. Phân tích WHY và WHAT
2. Xác định nhóm người sử dụng
3. Đề xuất phạm vi MVP
4. Phát hiện yêu cầu chưa rõ
5. Đặt câu hỏi cần xác nhận
6. Đề xuất business rules
7. Xác định trường hợp ngoại lệ
8. Đề xuất acceptance criteria
9. Xác định rủi ro nghiệp vụ

Phân biệt rõ:
- Confirmed Requirements
- Assumptions
- Recommendations
- Open Questions

Không tự biến giả định thành yêu cầu chính thức.

PHASE 2 - DOCUMENTATION

Sau khi tôi phê duyệt, hãy tạo bộ tài liệu Markdown:
- 00-project-overview.md
- 01-business-requirements.md
- 02-software-requirements.md
- 03-business-rules.md
- 04-user-roles-permissions.md
- 05-data-model.md
- 06-api-contracts.md
- 07-acceptance-criteria.md
- 08-architecture.md

Yêu cầu:
- Rõ ràng, không lặp vô ích
- Có requirement ID
- Có business rule ID
- Có acceptance criteria
- Có liên kết giữa các yêu cầu
- Có danh sách quyết định chưa chốt
- Không tự bịa thông tin

PHASE 3 - HANDOFF

Tạo danh sách task có thể giao cho AI Coding Agent.

Mỗi task cần:
- Task ID
- Objective
- Scope
- Requirement references
- Business rule references
- Acceptance criteria
- Dependencies
- Suggested tests
- Security considerations

Sau khi AI phân tích, hãy trao đổi để chốt những quyết định quan trọng, đặc biệt là phân quyền, quy tắc thay đổi trạng thái và xử lý công việc quá hạn.

Ví dụ một yêu cầu trong SRS

Requirement ID: TASK-FR-001
Name: Create Task
Status: Approved

Description:
Người dùng có quyền được tạo công việc mới.

Inputs:
- Title
- Description
- Assignee
- Due Date
- Priority

Business Rules:
- BR-TASK-001
- BR-TASK-002
- BR-AUTH-003

Acceptance Criteria:
- AC-001: Tạo thành công với dữ liệu hợp lệ.
- AC-002: Từ chối nếu tiêu đề trống.
- AC-003: Từ chối nếu người dùng không có quyền tạo công việc.
- AC-004: Không ghi dữ liệu không hoàn chỉnh khi giao dịch thất bại.
- AC-005: Ghi nhận lịch sử tạo công việc.

Ví dụ này giúp AI biết phải thực hiện điều gì và cung cấp cơ sở để viết test.

Prompt 2 - AI thiết kế kiến trúc

Bạn đóng vai Software Architect.

Dựa trên bộ BRD, SRS và Business Rules đã phê duyệt, hãy đề xuất kiến trúc hệ thống.

Công nghệ ưu tiên:
- Frontend: Next.js + TypeScript
- Backend: ASP.NET Core Web API
- Database: SQL Server
- Version Control: Git

Hãy trình bày:
1. Kiến trúc tổng thể
2. Cấu trúc repository
3. Database schema
4. API contracts
5. Authentication
6. Authorization
7. Logging và error handling
8. Testing strategy
9. Deployment strategy
10. Rủi ro kỹ thuật

Chưa viết mã nguồn.
Nếu có nhiều giải pháp, hãy so sánh và đề xuất.
Các quyết định ảnh hưởng đến dữ liệu, bảo mật, chi phí hoặc khả năng mở rộng phải được đánh dấu cần phê duyệt.

Prompt 3 - Giao task cho AI Coding Agent

Bạn là Senior Software Engineer và AI Coding Agent của dự án.

Nhiệm vụ: TASK-001

Trước khi triển khai:
1. Đọc AGENTS.md
2. Đọc task specification
3. Đọc tài liệu được tham chiếu
4. Kiểm tra repository
5. Phân tích các file liên quan
6. Đề xuất implementation plan

Chỉ triển khai trong phạm vi đã được phê duyệt.

Yêu cầu:
- Tuân thủ business rules
- Validate dữ liệu đầu vào
- Kiểm tra quyền tại backend
- Không hardcode secrets
- Không sửa module không liên quan
- Viết test cho hành vi mới
- Kiểm tra trường hợp ngoại lệ
- Cập nhật tài liệu nếu cần

Khi hoàn thành:
1. Liệt kê files changed
2. Giải thích logic implemented
3. Liệt kê tests executed
4. Báo cáo test results
5. Nêu known limitations
6. Nêu risks requiring review

Không tuyên bố test đã pass nếu chưa thực sự chạy test.

Prompt 4 - Review mã nguồn

Bạn đóng vai Senior Code Reviewer và Application Security Reviewer.

Hãy review thay đổi của TASK-001 so với yêu cầu đã phê duyệt.

Kiểm tra:
- Business logic
- Authentication
- Authorization
- SQL injection
- XSS
- Sensitive data exposure
- Race conditions
- Transaction handling
- Error handling
- Breaking changes
- Test coverage

Phân loại:
- Critical
- High
- Medium
- Low

Với mỗi phát hiện:
- File và vị trí liên quan
- Mô tả vấn đề
- Điều kiện xảy ra
- Mức độ ảnh hưởng
- Đề xuất khắc phục
- Bằng chứng hoặc cách tái hiện

Không coi suy đoán là lỗi đã được xác nhận.

Với dự án quan trọng, review từ một AI khác có thể giúp tìm thêm vấn đề. Tuy nhiên, việc xác nhận lỗi cần dựa trên mã nguồn, kiểm thử và bằng chứng thực tế.

7. AGENTS.md - Bộ quy tắc giúp AI làm việc nhất quán

AGENTS.md có thể được xem như một bản hướng dẫn dành cho AI Coding Agent, tùy theo cơ chế hỗ trợ của công cụ đang sử dụng.

Thay vì mỗi lần đều phải nhắc lại những quy tắc, chúng ta ghi những chỉ dẫn ổn định vào repository.

Ví dụ:

# Project Instructions

## Project
Task Management Application

## Principles
Human owns WHY, WHAT, RULES and final acceptance.
AI assists with research, implementation and testing.

## Workflow
1. Read relevant requirements
2. Identify assumptions
3. Propose implementation plan
5. Obtain approval when required
5. Implement approved scope
6. Run relevant tests
7. Report changes and limitations

## Coding Rules
- Follow existing architecture
- Prefer readable code
- Avoid unnecessary dependencies
- Do not duplicate business logic
- Validate untrusted inputs
- Handle errors explicitly

## Security Rules
- Never hardcode secrets
- Never expose sensitive data
- Enforce server-side authorization
- Use parameterized SQL queries
- Follow least privilege
- Never disable security controls

## Database Rules
- Never modify production directly
- Use reviewed migrations
- Protect existing data
- Consider backward compatibility
- Prepare rollback or recovery plans

## Change Control
- Do not expand scope automatically
- Do not modify unrelated modules
- Do not change public APIs without approval
- Do not deploy production without authorization
- Do not execute destructive actions without explicit approval

## Testing
- Test changed business behavior
- Cover invalid inputs
- Cover authorization failures
- Cover relevant edge cases
- Report tests not executed

## Definition of Done
- Acceptance criteria satisfied
- Required tests passed
- Security reviewed
- Changes reviewed
- Documentation updated
- Known limitations reported

## Final Report
Always provide:
- Summary
- Changed files
- Test results
- Risks
- Pending decisions

Cần lưu ý rằng không phải công cụ AI nào cũng tự động nạp AGENTS.md. Một số công cụ sử dụng tên file hoặc cơ chế project instructions khác.

Hãy kiểm tra tài liệu của công cụ đang dùng.

Và quan trọng hơn, file hướng dẫn không phải cơ chế bảo mật. Nếu không muốn AI truy cập production, phải giới hạn quyền truy cập thực tế, thay vì chỉ ghi một câu cấm trong tài liệu.

8. Context Engineering - Cách giúp AI hiểu đúng mà không phải đọc mọi thứ

Nhiều người tìm kiếm một prompt thật dài với hy vọng AI sẽ hiểu tất cả.

Nhưng một prompt dài chưa chắc tốt hơn một bộ context được tổ chức hợp lý.

Context Engineering là việc lựa chọn, tổ chức và cung cấp những thông tin phù hợp để AI thực hiện một nhiệm vụ.

Trong dự án phần mềm, context có thể bao gồm:

• Project overview.
• BRD và SRS.
• Business rules.
• Kiến trúc và database schema.
• API contracts.
• Mã nguồn liên quan.
• Quy tắc lập trình.
• Task specification.
• Acceptance criteria.
• Test cases.

Không nên nạp toàn bộ tài liệu trong mọi lượt

Giả sử dự án có các module quản lý nhân sự, đơn hàng, thanh toán và báo cáo.

Khi phát triển tính năng quản lý ca làm việc, AI có thể cần tài liệu nhân sự, phân quyền, lịch làm việc và những bảng dữ liệu liên quan.

Không nhất thiết phải đọc toàn bộ các tài liệu thanh toán và khuyến mãi.

Hãy bắt đầu bằng file tổng quan ngắn, sau đó cho AI đọc task và những tài liệu được tham chiếu.

Quản lý context theo từng task

Một task có thể chứa:

# TASK-001

## Objective
Create task management API.

## Requirements
- TASK-FR-001
- TASK-FR-002

## Business Rules
- BR-TASK-001
- BR-AUTH-003

## Relevant Documents
- docs/02-software-requirements.md
- docs/03-business-rules.md
- docs/06-api-contracts.md

## Expected Output
- API implementation
- Database migration if approved
- Automated tests
- Documentation update

## Acceptance Criteria
- AC-001
- AC-002
- AC-003

## Constraints
- No unrelated changes
- No production access
- No breaking API changes

Như vậy, AI biết nhiệm vụ cần làm, tài liệu cần đọc và giới hạn phải tuân thủ.

Đo hiệu quả bằng số liệu thực tế

Nếu muốn biết phương pháp này có tiết kiệm chi phí không, hãy theo dõi:

• Token đầu vào và đầu ra cho mỗi task.
• Chi phí sử dụng AI.
• Số lượt phải giải thích lại yêu cầu.
• Số lần chỉnh sửa do hiểu sai nghiệp vụ.
• Thời gian hoàn thành task.
• Số lỗi phát hiện sau nghiệm thu.

Một quy trình sử dụng ít token hơn nhưng tạo nhiều lỗi hơn chưa chắc là quy trình tốt.

Điều chúng ta muốn cải thiện là tổng chi phí và chất lượng phát triển phần mềm, không đơn giản chỉ là số token.

9. Kiểm thử: AI viết code được, nhưng ai xác nhận code đúng?

Đây là câu hỏi quan trọng.

AI có thể viết test. AI cũng có thể chạy test và sửa lỗi.

Nhưng test do AI tạo ra vẫn có khả năng kiểm tra sai kỳ vọng nếu yêu cầu ban đầu chưa rõ hoặc bị hiểu nhầm.

Vì vậy, cần đối chiếu các bài kiểm thử với acceptance criteria và business rules đã được phê duyệt.

Những lớp kiểm thử nên có

• Static Analysis: Phát hiện một số vấn đề trong mã nguồn mà không cần chạy chương trình.
• Unit Test: Kiểm tra những đơn vị logic riêng lẻ.
• Integration Test: Kiểm tra sự phối hợp giữa API, database và các thành phần.
• End-to-End Test: Kiểm tra luồng thao tác thực tế của người dùng.
• Security Test: Kiểm tra các rủi ro như xác thực, phân quyền, đầu vào không an toàn.
• UAT: Người sử dụng xác nhận phần mềm đáp ứng đúng nghiệp vụ.

Ví dụ, chức năng tạo công việc phải được kiểm thử cả khi dữ liệu hợp lệ, thiếu tiêu đề, người dùng không đủ quyền, giao dịch lưu thất bại hoặc nhiều người cùng cập nhật.

Không nên đánh đồng việc chương trình build thành công với việc chức năng đã đáp ứng yêu cầu.

10. Bảo mật khi sử dụng AI Coding Agent

Ngày nay, một AI Coding Agent có thể không chỉ tạo code. Tùy quyền được cấp, nó có thể đọc file, chạy lệnh, cài package hoặc tương tác với các dịch vụ bên ngoài.

Điều này rất hữu ích, nhưng cũng cần kiểm soát.

Không đưa dữ liệu nhạy cảm vào prompt tùy tiện

Tránh cung cấp mật khẩu database, private key, token truy cập hoặc dữ liệu khách hàng thật khi chưa có cơ chế bảo vệ phù hợp.

Ưu tiên dữ liệu mẫu, biến môi trường và hệ thống quản lý secrets.

Giới hạn quyền của agent

Hãy áp dụng nguyên tắc cấp quyền tối thiểu.

AI chỉ nên có quyền cần thiết để thực hiện nhiệm vụ đang được giao.

Những thao tác như xóa dữ liệu, thay đổi hạ tầng, cấp quyền, chạy migration hoặc triển khai production cần cơ chế kiểm soát và phê duyệt phù hợp.

Đề phòng Prompt Injection

AI có thể đọc dữ liệu từ repository, tài liệu hoặc các nguồn bên ngoài.

Không phải mọi nội dung nó đọc được đều đáng tin cậy.

Một đoạn hướng dẫn nằm trong file hoặc trang web có thể cố tình khiến agent thực hiện hành động ngoài nhiệm vụ.

Do đó, cần phân biệt dữ liệu tham khảo với chỉ dẫn có thẩm quyền, hạn chế quyền công cụ và kiểm tra các thao tác nhạy cảm.

Kiểm tra thư viện và dependency

AI có thể đề xuất package không phù hợp hoặc thư viện có rủi ro.

Hãy kiểm tra nguồn chính thức, phiên bản, giấy phép và những vấn đề bảo mật đã được công bố.

Đừng coi một câu trả lời "đã kiểm tra an toàn" là bằng chứng đủ tin cậy.

11. Dự án mới và dự án đang vận hành cần cách làm khác nhau

Với dự án mới

Chúng ta có nhiều không gian thử nghiệm.

AI có thể giúp đề xuất kiến trúc, dựng prototype, thay đổi giao diện và kiểm chứng ý tưởng nhanh.

Nhưng những quyết định nền tảng như phân quyền, mô hình dữ liệu và bảo mật vẫn cần được cân nhắc.

Với dự án đang vận hành

Phải thận trọng hơn.

Một thay đổi nhỏ có thể ảnh hưởng đến nhiều module, API, database hoặc các hệ thống đang tích hợp.

Trước khi sửa code, cần yêu cầu AI phân tích tác động:

• Những module nào đang sử dụng chức năng này?
• Có thay đổi API contract không?
• Có ảnh hưởng dữ liệu cũ không?
• Có thay đổi quyền truy cập không?
• Có test bảo vệ hành vi hiện tại không?
• Có phương án rollback hoặc khôi phục không?

Với hệ thống cũ thiếu test, có thể bổ sung characterization tests để ghi nhận hành vi hiện tại trước khi refactor. Tuy nhiên, nếu hành vi hiện tại vốn là lỗi, cần xác nhận lại hành vi mong muốn thay vì giữ nguyên.

Và đừng giao một câu lệnh quá rộng như "Hãy tối ưu toàn bộ hệ thống" nếu chưa xác định rõ vấn đề, phạm vi và tiêu chí đo lường.

12. Những sai lầm phổ biến khi Vibe Coding

Chỉ mô tả giao diện mà bỏ quên nghiệp vụ

Một giao diện đẹp không bảo đảm phần mềm tính đúng tiền, xử lý đúng dữ liệu hoặc tuân thủ phân quyền.

Để AI tự quyết định những yêu cầu chưa rõ

AI có thể đưa ra giải pháp hợp lý theo một giả định, nhưng giả định ấy chưa chắc phù hợp với nhu cầu thực tế.

Yêu cầu AI thực hiện cả dự án trong một prompt

Task quá rộng làm việc kiểm soát thay đổi, kiểm thử và nghiệm thu trở nên khó khăn.

Không quản lý tài liệu và phiên bản

Khi những quyết định quan trọng chỉ nằm trong lịch sử trò chuyện, chúng ta dễ gặp tình trạng mỗi phiên AI hiểu một cách khác nhau.

Liên tục yêu cầu sửa lỗi nhưng không tìm nguyên nhân

Nếu một lỗi xuất hiện nhiều lần, hãy tìm nguyên nhân gốc, bổ sung test và cập nhật quy tắc hoặc tài liệu nếu cần.

Cho phép AI thay đổi ngoài phạm vi

Một yêu cầu sửa giao diện không nên tự động dẫn đến việc thay đổi cấu trúc database hoặc viết lại hệ thống xác thực.

Tin rằng AI tự kiểm thử là đủ

AI có thể viết test dựa trên cùng một cách hiểu sai như lúc viết code. Cần kiểm tra độc lập và đối chiếu với yêu cầu đã phê duyệt.

Không tính chi phí bảo trì

Chi phí tạo phiên bản đầu tiên có thể giảm, nhưng phần mềm vẫn cần nâng cấp, bảo mật, theo dõi, xử lý sự cố và hỗ trợ người dùng.

Một sản phẩm tạo nhanh mà không ai bảo trì được chưa chắc là một sản phẩm tiết kiệm.

13. Người không biết lập trình có thể sử dụng Vibe Coding không?

Có.

Người không có nền tảng lập trình vẫn có thể sử dụng AI để xây dựng prototype, website đơn giản hoặc công cụ phục vụ công việc cá nhân.

Tuy nhiên, tạo được ứng dụng không đồng nghĩa với việc đã đủ khả năng đánh giá chất lượng kỹ thuật, bảo mật và khả năng vận hành của ứng dụng.

Nếu mới bắt đầu, hãy chọn những dự án nhỏ, ít rủi ro, không xử lý thông tin nhạy cảm và không liên quan đến giao dịch tài chính quan trọng.

Trong quá trình làm, hãy yêu cầu AI giải thích:

• Mỗi thành phần có nhiệm vụ gì?
• Dữ liệu được lưu và xử lý ở đâu?
• Hệ thống kiểm tra quyền như thế nào?
• Điều gì xảy ra khi có lỗi?
• Làm thế nào để sao lưu và khôi phục?
• Những test nào chứng minh chức năng hoạt động đúng?

AI không chỉ là công cụ tạo code. Nó còn có thể giúp chúng ta học cách phần mềm hoạt động.

Với các hệ thống quan trọng, nên có người có chuyên môn kỹ thuật tham gia thiết kế và đánh giá.

14. Lập trình viên cần học gì khi AI đã viết được code?

Tôi không nghĩ lập trình viên nên ngừng học lập trình.

Ngược lại, khi AI có thể tạo nhiều mã nguồn trong thời gian ngắn, khả năng đọc hiểu và đánh giá code càng trở nên quan trọng.

Những kỹ năng đáng đầu tư gồm:

• Phân tích yêu cầu nghiệp vụ.
• Thiết kế hệ thống và kiến trúc.
• Mô hình hóa dữ liệu.
• Hiểu bảo mật và phân quyền.
• Thiết kế API và tích hợp.
• Kiểm thử và phân tích nguyên nhân lỗi.
• Quản lý Git và triển khai.
• Context Engineering.
• Viết tài liệu kỹ thuật.
• Quản lý AI Agent và giới hạn quyền thực thi.

Viết code vẫn quan trọng. Nhưng giá trị của người phát triển phần mềm không chỉ nằm ở số dòng code tạo ra.

Đôi khi, quyết định bỏ một chức năng không cần thiết còn giúp dự án nhiều hơn việc viết chức năng đó thật nhanh.

15. Checklist trước và sau khi giao việc cho AI

Trước khi bắt đầu

• Đã xác định rõ WHY và WHAT chưa?
• Business rules đã được ghi nhận chưa?
• Đã có acceptance criteria chưa?
• Tài liệu BRD/SRS đã được kiểm tra chưa?
• Những giả định chưa xác nhận đã được đánh dấu chưa?
• Đã xác định phạm vi task chưa?
• AI có được cung cấp đúng context không?
• Những quyền nguy hiểm đã được giới hạn chưa?
• Đã có Git branch hoặc phương án khôi phục chưa?
• Có cần phê duyệt trước khi thay đổi kiến trúc hoặc database không?

Sau khi AI hoàn thành

• Chức năng có đáp ứng acceptance criteria không?
• Test đã thực sự được chạy chưa?
• Có thay đổi ngoài phạm vi không?
• Có lỗi bảo mật hoặc phân quyền không?
• Có ảnh hưởng đến dữ liệu hiện tại không?
• Có phát sinh dependency mới không?
• Tài liệu có được cập nhật không?
• Có ghi nhận các giới hạn chưa xử lý không?
• Có phương án triển khai và khôi phục không?
• Đã có người chịu trách nhiệm nghiệm thu chưa?

16. Khi nào nên và không nên Vibe Coding?

Vibe Coding theo nghĩa thử nhanh, ít đọc code có thể phù hợp với sản phẩm mẫu, công cụ cá nhân hoặc những ý tưởng cần kiểm chứng với rủi ro thấp.

Với sản phẩm vận hành thực tế, AI vẫn có thể thực hiện phần lớn công việc kỹ thuật. Nhưng nên sử dụng quy trình có yêu cầu rõ ràng, kiểm thử và kiểm soát thay đổi.

Đặc biệt, những phần mềm liên quan đến tài chính, dữ liệu cá nhân, y tế hoặc nghiệp vụ có tác động lớn cần có mức đánh giá và phê duyệt tương ứng.

Điều cần tránh không phải là AI viết code.

Điều cần tránh là đưa mã nguồn chưa được kiểm chứng vào một hệ thống quan trọng mà không có ai chịu trách nhiệm.

17. Kết luận: AI giúp chúng ta lập trình nhanh hơn, nhưng con người vẫn phải biết mình đang làm gì

Từ góc nhìn của chú Nha 27 tuổi, điều thú vị nhất của AI Coding không phải là chuyện một người có thể tạo ra hàng nghìn dòng code chỉ bằng vài câu lệnh.

Điều thú vị hơn là chúng ta có thêm một cách tổ chức công việc.

Con người xác định mục tiêu và quy tắc. AI hỗ trợ nghiên cứu, đặt câu hỏi, phản biện và chuẩn hóa thành tài liệu. Con người kiểm tra, phê duyệt. Sau đó AI Coding Agent thực hiện công việc kỹ thuật, còn con người cùng các công cụ kiểm thử đánh giá kết quả.

Đó là quy trình bốn giai đoạn:

1. Human + AI Research.
2. Human Approval.
3. AI Coding Agent.
4. Review, Test & Deploy.

Trong quy trình ấy, Markdown giúp lưu lại kiến thức dự án, Git giúp quản lý thay đổi, acceptance criteria giúp xác định thế nào là hoàn thành và kiểm thử giúp chúng ta có bằng chứng thay vì chỉ cảm thấy phần mềm đã chạy ổn.

Chúng ta cũng không cần xem quy trình này như một bộ luật bất biến. Với dự án nhỏ, có thể thực hiện đơn giản hơn. Với hệ thống lớn, cần bổ sung nhiều lớp kiểm soát hơn.

Quan trọng là biết mình đang quyết định điều gì, giao cho AI phần việc nào và kiểm chứng kết quả bằng cách nào.

AI có thể giúp chúng ta làm nhanh hơn. Nhưng việc chọn đúng vấn đề để giải quyết vẫn là trách nhiệm của con người.

Và nếu một ngày nào đó AI có thể viết phần lớn code của một dự án, tôi vẫn nghĩ người làm phần mềm còn rất nhiều việc thú vị để làm: hiểu người dùng, thiết kế sản phẩm hữu ích, xác định những giới hạn cần được bảo vệ và đưa ra các quyết định có trách nhiệm.

Biết đâu nhờ vậy, chú Nha 27 tuổi lại có thêm chút thời gian uống cà phê buổi sáng mà không phải ngồi tìm một dấu ngoặc bị thiếu.

Nguồn tham khảo

• IBM - What is Vibe Coding?
• Anthropic - Claude Code Documentation
• GitHub - GitHub Copilot Documentation
• Visual Studio Code - AI Assisted Development
• AGENTS.md - Project Instructions for Coding Agents
• CommonMark - Markdown Specification
• OWASP - Top 10 Web Application Security Risks
• OWASP - Cheat Sheet Series