Làm phần mềm bằng cách ra đề, duyệt và nghiệm thu

Vibe code là cách làm phần mềm trong đó AI viết toàn bộ mã nguồn, còn người quyết định làm gì, duyệt cách làm và nghiệm thu kết quả. Người làm không đọc từng dòng mã. Người làm đọc đặc tả, chạy thử sản phẩm và giữ kỷ luật quy trình.

Trong khoá này bạn làm hai sản phẩm theo cách đó:

• Sổ thuật ngữ dự án. Bắt đầu là trang web tĩnh dựng bằng Vite, phát hành lên Cloudflare Pages. Sau đó thêm máy chủ Hono với SQLite, gợi ý bản dịch bằng AI, rồi nối với Backlog và Teams.
• Hỏi đáp với khách. Kho luyện tập có sẵn: ứng dụng theo dõi câu hỏi giữa khách Nhật và đội phát triển. Bạn vào kho này để tập sửa lỗi an toàn.

Ba vai bạn phải giữ

Những gì vibe code không phải

• Không phải chat rồi dán mã vào đâu đó. Claude Code chạy trong thư mục dự án, tự đọc và sửa tệp, tự chạy lệnh kiểm tra.
• Không phải bỏ qua quy trình. Dự án lớn phải đi theo thứ tự: đặc tả trước, kế hoạch sau, rồi mới làm. Bỏ bước là cách nhanh nhất để mất một ngày.
• Không phải một người một lần. Dự án thật thường chạy vài phiên AI song song trên cùng thư mục. Phần lớn quy tắc an toàn ở học phần 08 ra đời từ tình huống này.

Nơi mã sống

Kho mã nguồn (repository)

Một thư mục dự án có Git theo dõi. Mỗi dự án là một kho.

Commit

Một mốc lưu có tên và thời gian. Quay lại mốc được. Commit là đơn vị bạn nghiệm thu và bàn giao.

Nhánh (branch)

Một dòng phát triển tách ra để thử. Dự án nhỏ thường làm thẳng trên nhánh chính, kèm kỷ luật commit chặt.

Cây làm việc (working tree)

Trạng thái hiện tại của các tệp trên đĩa, gồm cả phần chưa commit. Nhiều phiên AI dùng chung một cây là tình huống nguy hiểm nhất.

Tệp .env và khoá API

Tệp chứa mật khẩu và khoá dịch vụ. Không bao giờ dán vào chat, không bao giờ commit.

Cách sản phẩm chạy

Giao diện (frontend)

Phần người dùng nhìn thấy trong trình duyệt.

Máy chủ (backend)

Phần xử lý, lưu dữ liệu, gọi AI. Sổ thuật ngữ bản đầu là trang tĩnh nên chưa có phần này.

Cơ sở dữ liệu và schema

Nơi lưu dữ liệu và bản mô tả cấu trúc của nó. Đổi schema là thay đổi lớn, luôn cần đặc tả và sao lưu.

API

Cửa để giao diện nói chuyện với máy chủ, hoặc để ta nói chuyện với dịch vụ ngoài như một mô hình AI.

localhost và cổng

Sản phẩm chạy trên máy bạn ở địa chỉ dạng http://localhost:5173. Mỗi dự án một số cổng. Hai dự án chung cổng thì một cái không chạy.

Chạy tại chỗ, dev, prod

Ba môi trường: máy bạn, máy thử, máy thật có người dùng. Đọc dữ liệu phải đúng môi trường, xem quy tắc đọc cấu hình ở học phần 08.

Triển khai (deploy)

Đưa bản mới lên máy thật. Chỉ làm khi người phụ trách ra lệnh.

Cách biết mã có đúng không

Typecheck

Kiểm tra máy móc xem mã có tự mâu thuẫn không. Xanh là điều kiện tối thiểu trước mỗi commit.

Kiểm thử đơn vị (test)

Kịch bản chạy tự động kiểm tra từng phần. Xanh nghĩa là những gì đã được viết kịch bản vẫn đúng.

Kiểm thử đầu cuối (e2e)

Máy tự mở trình duyệt và bấm như người dùng, dùng Playwright. Bắt được lỗi hiển thị mà typecheck không thấy.

Nhật ký (log)

Dòng chữ hệ thống ghi khi chạy. Khi có lỗi, nhật ký là thứ đầu tiên AI cần đọc.

Lỗi im lặng

Hệ không báo gì nhưng làm sai. Nguy hiểm hơn lỗi đỏ. Chỉ bắt được bằng nghiệm thu trên trình duyệt thật.

Cách làm việc với AI

Claude Code

Công cụ AI chạy trong cửa sổ dòng lệnh hoặc VS Code, đọc và sửa được tệp trong thư mục dự án.

CLAUDE.md

Tệp luật của dự án, AI đọc mỗi phiên. Có một bản cấp máy áp cho mọi dự án và một bản riêng mỗi kho.

Đặc tả, kế hoạch, đầu việc

Ba tài liệu spec-kit sinh ra trước khi viết mã: cái gì và vì sao, làm thế nào, chia thành những bước nào.

Skill và agent

Skill là quy trình đóng gói gọi bằng lệnh gạch chéo. Agent là AI con nhận một vai (BA, kiểm thử) để chạy song song.

MCP

Cách nối Claude Code với công cụ ngoài, như Stitch để vẽ giao diện hay sentrux để đo chất lượng mã.

Token và chi phí

AI tính tiền theo lượng chữ đọc và viết. Đề bài rõ và tệp CLAUDE.md gọn giúp tiết kiệm.

Phiên (session)

Một cửa sổ Claude Code đang chạy. Dự án lớn có nhiều phiên cùng lúc.

Ảo giác (hallucination)

AI nói chắc điều không có thật, ví dụ "đã kiểm tra trên trình duyệt" khi chưa làm. Cách phòng là đòi bằng chứng.

Hướng dẫn cho máy Mac chip Apple. Tích vào ô khi xong. Trạng thái tích được lưu trên trình duyệt của bạn.

Bậc 1. Nền tảng, bắt buộc

• Homebrew, trình cài phần mềm cho MacCài theo hướng dẫn tại brew.sh. Kiểm tra: brew --version. Máy chip Apple phải dùng bản arm64, bản Intel chạy qua Rosetta gây lỗi khó hiểu về sau.
• Gitbrew install git. Kiểm tra: git --version. Sau đó đặt tên và email: git config --global user.name "Tên".
• Node.js 22 trở lên và pnpmbrew install node@22 rồi npm install -g pnpm. Kiểm tra: node --version phải in ra v22 trở lên. Nhiều máy có sẵn bản Node cũ hơn làm mặc định, và một số dự án không chạy được với bản đó.
• Python 3 và uvMac có sẵn Python. Cài uv theo hướng dẫn tại astral.sh/uv, là công cụ chạy spec-kit. Kiểm tra: uvx --version.
• Claude Codenpm install -g @anthropic-ai/claude-code. Kiểm tra: claude --version. Nếu máy dùng nvm thì lệnh claude gắn với bản Node đang chọn, đổi Node phải cài lại. Đăng nhập bằng cấu hình lấy từ cổng AI nội bộ Gateway, xem bậc 2.
• VS Code và tiện ích Claude CodeTải tại code.visualstudio.com, cài tiện ích "Claude Code" từ kho tiện ích. Dùng VS Code để đọc tệp và xem khác biệt, không cần sửa tay. Phiên Claude trong VS Code dùng chung cấu hình với dòng lệnh: cùng thư mục ~/.claude, cùng MCP, cùng hook.

Bậc 2. Nối vào hạ tầng công ty

• Khoá ảo và cấu hình Claude Code từ GatewayGateway là cổng AI nội bộ. Mỗi người nhận một khoá ảo riêng, cổng dùng khoá này để quản hạn mức theo người và nhóm. Địa chỉ và khoá do người phụ trách gửi. Khoá chỉ hiện một lần: lưu ngay vào trình quản lý mật khẩu, không dán vào chat hay tài liệu. Người phụ trách hướng dẫn lệnh nạp cấu hình để claude đi qua cổng.
• Tệp luật cấp máy ~/.claude/CLAUDE.mdNhận bản chuẩn từ người phụ trách và đặt vào đúng đường dẫn này. Tệp áp cho mọi dự án, chứa 10 quy tắc Git nhiều phiên và luật "tài liệu đi trước mã". Không tự sửa tệp này.
• Bộ spec-kit và kịch bản xuất HTMLNhận bộ spec-kit kèm kịch bản cài install-speckit.sh từ người phụ trách. Mỗi dự án mới chạy ./install-speckit.sh "đường/dẫn/dự-án" một lần.
• Bộ skill và agent dùng chungBộ skill superpowers đặt trong thư mục .claude/skills. Bốn agent theo vai dùng chung đặt ở ~/.claude/agents cấp máy. Cách dùng và giới hạn ở học phần 05.

Bậc 3. Cần khi dự án có máy chủ hoặc phát hành

• DockerDocker Desktop, hoặc brew install colima docker nếu máy không cài được Desktop. Kiểm tra: docker --version. Dùng để chạy cơ sở dữ liệu tại chỗ và đóng gói phát hành.
• PlaywrightCài trong từng dự án bằng pnpm add -D @playwright/test rồi pnpm exec playwright install chromium. Là công cụ nghiệm thu giao diện tự động.
• Wrangler, phát hành lên Cloudflarenpm install -g wrangler rồi wrangler login. Dùng cho trang tĩnh như Sổ thuật ngữ bản đầu.
• Công cụ truy cập máy chủChỉ cài khi được giao phát hành lên máy chủ. Người phụ trách cho biết công cụ cần dùng và cách cấp quyền. Khoá truy cập đặt trong tệp môi trường đã gitignore, không tự tạo.
• PostgreSQL tại chỗbrew install postgresql@15. Chỉ cần khi dự án dùng PostgreSQL mà không chạy Docker. Hai sản phẩm của khoá dùng SQLite nên chưa cần.

Bậc 4. Máy chủ MCP, tuỳ chọn nhưng nên có

Kiểm tra toàn bộ một lần

Dán khối lệnh sau vào cửa sổ dòng lệnh. Dòng nào in "không có" thì quay lại bậc tương ứng. Công cụ tuỳ chọn mà bạn chưa cài thì bỏ qua.

for t in brew git node pnpm uvx claude docker wrangler sentrux gitnexus; do
  printf "%-10s " "$t"
  command -v "$t" >/dev/null && "$t" --version 2>/dev/null | head -1 || echo "không có"
done

Bước 0. Khởi tạo kho

Làm một lần cho mỗi dự án mới, mất khoảng 15 phút.

1. Tạo thư mục, chạy git init.
2. Chạy install-speckit.sh trỏ vào thư mục đó. Lệnh này cài các lệnh /speckit-* và bộ xuất HTML.
3. Mở Claude Code trong thư mục, chạy /speckit-constitution để chốt nguyên tắc dự án: công nghệ, kiểu commit, cách nghiệm thu.
4. Viết CLAUDE.md của kho theo mẫu ở phụ lục học phần 10. Ghi rõ hai luồng làm việc và những bẫy riêng của dự án.
5. Tạo .env.example liệt kê khoá cần có nhưng để trống. Thêm .env vào .gitignore.

Hai luồng làm việc

Mọi kho nên ghi hai luồng này trong CLAUDE.md. Chọn sai luồng là lỗi phổ biến nhất của người mới.

Năm bước của luồng chuẩn

Tài liệu sinh ra nằm ở specs/00X-tên-tính-năng/. Mỗi thư mục là một tính năng đã giao. Kho "Hỏi đáp với khách" đã có sẵn vài thư mục như vậy, ví dụ danh sách câu hỏi và lọc theo trạng thái. Đó là lịch sử dự án mà người mới vào đọc được.

Hai kiểu nhịp giao hàng

Chọn theo khách hàng và ghi vào CLAUDE.md, vì nó đổi cách AI dừng lại chờ bạn.

• Theo sprint, dừng chờ nghiệm thu: làm xong một sprint, khách kiểm tra và duyệt, rồi mới chạy sprint sau. Hợp với dự án làm cho khách bên ngoài, ví dụ một cửa hàng nhỏ đặt làm trang bán hàng.
• Chạy hết rồi rà soát một thể: AI làm toàn bộ danh sách đầu việc, bạn rà soát cuối. Hợp với công cụ nội bộ mà người ra đề cũng là người dùng, ví dụ Sổ thuật ngữ cho đội của bạn.

Nhịp một ngày làm việc

1. Sáng: mở Claude Code, hỏi "hôm qua dừng ở đâu, có gì chưa commit". Nếu kho có phiên khác đang chạy, khai vùng mình sẽ sửa.
2. Ra đề: viết đề bài theo mẫu học phần 06. Chọn luồng nhanh hay chuẩn.
3. Duyệt: đọc bản HTML của đặc tả. Sửa bằng lời, không sửa tệp.
4. Để AI làm: trong lúc chờ, chuẩn bị kịch bản nghiệm thu.
5. Nghiệm thu: mở trình duyệt, bấm theo kịch bản, chụp màn hình khi lệch.
6. Commit: AI commit theo đường dẫn tường minh, tài liệu và mã cùng một commit.
7. Cuối ngày: ghi vào tệp bàn giao trong kho: đã xong gì, dở gì, bẫy gì mới phát hiện. Tin nhắn giữa các phiên không bền, tệp trong kho mới bền.

Đang có gì trên máy

Ba cách để skill chạy chắc chắn

1. Gọi tay. Gõ /brainstorming trước tính năng mới, /systematic-debugging khi có lỗi, /verification-before-completion trước khi cho AI nói "xong". Cách này luôn đúng, không cần cài gì.
2. Ghi vào CLAUDE.md của kho. Thêm dòng "Tính năng mới: chạy /brainstorming trước /speckit-specify. Có lỗi: chạy /systematic-debugging." AI đọc CLAUDE.md mỗi phiên nên sẽ tự gọi.
3. Cài hook nạp khi mở phiên. Thêm hook SessionStart vào ~/.claude/settings.json để nạp nội dung using-superpowers vào mọi phiên. Đây là cách bản gốc superpowers làm. Việc sửa cấu hình cấp máy do người phụ trách quyết định, không để AI tự thêm.

Luồng superpowers và cách ghép với spec-kit

Hai bộ trùng vai ở bước lập kế hoạch. Quy ước trong khoá: spec-kit là luồng chuẩn, superpowers bổ trợ ở đầu, giữa và cuối.

Agent theo vai

Agent là một AI con nhận một vai và làm trong ngữ cảnh riêng. Nó không thấy cuộc trò chuyện chính, nên đề bài giao cho agent phải đủ như giao cho người mới vào.

Luồng phối hợp chung: quản lý dự án chia lộ trình, phân tích nghiệp vụ làm rõ yêu cầu, trưởng kỹ thuật chia đầu việc, agent lập trình viết, rà soát mã soát, kiểm thử kiểm. Bạn giao bằng câu tự nhiên, ví dụ: "Nhờ business-analyst viết tiêu chí nghiệm thu cho tính năng gợi ý bản dịch, xong thì cho tester viết ca kiểm thử."

Ba giới hạn cần biết

• Claude Code chỉ đọc .claude/agents tại thư mục mở phiên và ~/.claude/agents cấp máy, không đọc thư mục cha. Vì vậy agent nên chia hai lớp: các vai dùng chung ở cấp máy, thấy được ở mọi kho; vai lập trình để trong từng kho.
• Vai lập trình ghi cứng công nghệ và bẫy của kho. Mỗi agent mở đầu bằng đọc CLAUDE.md và spec của kho, kèm các sự cố đã xảy ra trong kho đó. Kho mới cần agent lập trình thì sao chép bộ của kho gần nhất về công nghệ và sửa lại.
• Nhiều agent cùng sửa một tệp thì đè nhau. Phát song song chỉ khi việc độc lập, và chia theo tệp: mỗi tệp một agent.

Đề bài tốt có sáu phần. Thiếu phần nào AI sẽ tự đoán phần đó, và bạn sẽ mất thời gian sửa lại thứ đáng lẽ chỉ cần một câu.

Câu nói hay và câu nói dở

Bốn thói quen khi nói chuyện với AI

• Mô tả hiện tượng, không đoán nguyên nhân. "Trang trắng sau khi bấm Lưu" tốt hơn "chắc là lỗi cơ sở dữ liệu". Khi bạn đoán sai, AI đi theo hướng sai.
• Đòi bằng chứng cho mỗi câu "đã xong". Hỏi: "Kiểm bằng cách nào? Cho tôi xem kết quả lệnh hoặc ảnh chụp."
• Yêu cầu AI hỏi lại trước khi làm việc lớn. Câu "Liệt kê những gì bạn chưa chắc trước khi bắt đầu" tiết kiệm nhiều giờ.
• Một lượt một việc. Gộp ba yêu cầu vào một câu thì AI ưu tiên cái dễ và quên cái khó.

Dùng skill có sẵn

• /brainstorming trước khi ra đề cho tính năng mới, để AI hỏi ngược và làm rõ ý bạn.
• /systematic-debugging khi gặp lỗi, để AI tìm nguyên nhân gốc thay vì vá triệu chứng.
• /verification-before-completion trước khi AI được phép nói "xong".
• Skill viết tiếng Việt chuẩn, nếu máy bạn có, để soạn và rà soát tài liệu gửi khách.
• Bảng ghép đầy đủ giữa superpowers và spec-kit ở học phần 05.

Nghiệm thu là vai quan trọng nhất của người không viết mã. Người viết mã có thể tự đọc mã để tin. Bạn phải tin bằng bằng chứng bên ngoài mã.

Ba mức bằng chứng, từ yếu đến mạnh

Kịch bản nghiệm thu mẫu

Viết trước khi AI làm, từ phần "tiêu chí nghiệm thu" của đề bài. Mỗi dòng một hành động và một kết quả mong đợi.

# Tính năng: chốt thuật ngữ và báo Teams (Sổ thuật ngữ)
1. Mở /terms/new                      → thấy ô "Trạng thái", mặc định Nháp
2. Nhập 仕様書 (shiyōsho, bản đặc tả), lưu Nháp → kênh Teams KHÔNG có tin mới sau 2 phút
3. Mở lại thuật ngữ đó, bấm Chốt     → kênh Teams có đúng một tin trong 1 phút
4. Danh sách, lọc "Đã chốt"          → chỉ hiện thuật ngữ ở bước 3
5. Kiểm DB: SELECT status FROM Term WHERE id=... → đúng giá trị Đã chốt

Kiểm chứng phải đi đúng đường hệ thống thật đi

Đây là bẫy tinh vi nhất. Một phép kiểm trả lời câu hỏi khác với câu bạn muốn hỏi thì kết quả xanh vô nghĩa.

• Kiểm tra tệp tồn tại trên đĩa không chứng minh hệ đọc được tệp đó qua đường tải lên.
• Biến môi trường in ra từ cửa sổ dòng lệnh của bạn không phải biến môi trường trong tiến trình đang chạy.
• Kiểm thử với dữ liệu tự bịa không bắt được lỗi chỉ xảy ra với dữ liệu thật. Ví dụ ở Sổ thuật ngữ: gợi ý dịch chạy tốt với câu tiếng Nhật ngắn tự gõ, nhưng hỏng với đoạn dán từ email của khách có ký tự toàn khổ và xuống dòng. Chỉ thử bằng đúng đoạn văn thật mới thấy.
• Lớp kiểm chứng của chính bạn cũng có thể báo sai. Bước kiểm tra tự động có thể báo "AI không gợi ý được" trong khi bản gợi ý đã lưu đúng vào cơ sở dữ liệu.

Bảng kiểm trước khi nói "đạt"

• Đã bấm đủ các dòng trong kịch bản nghiệm thu trên trình duyệt thật
• Đã thử trên điện thoại hoặc khung hẹp nếu người dùng cuối dùng điện thoại
• Đã kiểm dữ liệu trong cơ sở dữ liệu đúng môi trường
• Đã thử trường hợp xấu: bỏ trống, nhập sai, bấm hai lần, mất mạng giữa chừng
• Typecheck, kiểm thử đơn vị và đầu cuối xanh, có kết quả lệnh
• Tài liệu trong specs/ và CLAUDE.md đã khớp hành vi mới

Khi nhiều phiên AI dùng chung một thư mục

Tình huống thường gặp ở dự án có nhiều người hoặc nhiều phiên AI cùng làm. Chỉ có một Git, một cây làm việc, không có cơ chế nào của Git bảo vệ bạn. Mười quy tắc đầy đủ nằm trong tệp luật cấp máy, đây là bản tóm tắt.

1. Khai vùng trước khi sửa. Đầu phiên, nhắn các phiên khác mình sẽ sửa tệp nào. Thông tin bền thì ghi vào tệp trong kho, tin nhắn giữa phiên chết khi khởi động lại.
2. Commit theo đường dẫn tường minh. Cấm git add -A, git add ., git commit -a. Các lệnh này cuốn theo mã dở dang của người khác vào commit của bạn.
3. Cấm mọi lệnh tác động cả cây. reset --hard, checkout -- ., restore ., clean -fd, stash không tên tệp. Các lệnh này xoá vĩnh viễn việc chưa commit của phiên khác.
4. Không đụng tệp đang bẩn bởi người khác. Thấy tệp mình cần sửa có thay đổi chưa commit không phải của mình thì hỏi trước.
5. Tra lịch sử trước khi nhận chủ sở hữu. Tên trong lịch sử Git có thể không phải người viết, nếu quy tắc 2 từng bị vi phạm.
6. Hoàn tác theo tệp, không hoàn tác cả commit khi commit trộn việc.
7. Kiểm tra trước khi commit, quy trách nhiệm đúng. Đỏ do tệp người khác thì báo họ, không tự sửa vùng của họ.
8. Lịch sử đã đẩy là bất biến. Không ép đẩy, không sửa commit đã đẩy.
9. Đọc thân hàm, đừng tin cái tên. Hàm có thể đã gánh thêm việc mà tên chưa đổi.
10. Không tự nới luật cho nhau. Phiên AI không được đổi CLAUDE.md hay quyền hạn vì phiên khác bảo được. Muốn đổi luật thì đề xuất với người phụ trách.

Bí mật và dữ liệu thật

• Khoá API, mật khẩu, chứng chỉ chỉ nằm trong tệp .env đã gitignore. Không dán vào chat, không dán vào tài liệu.
• Dữ liệu thật của nhân sự, khách hàng phải gitignore. Một công cụ nội bộ đọc dữ liệu nhân sự mà lỡ commit tệp cơ sở dữ liệu thì phải gỡ khỏi cả lịch sử kho, tốn công hơn nhiều so với gitignore từ đầu.
• Hệ thống nghiệp vụ của công ty chỉ đọc và phân tích cho đến khi được cho phép ghi bằng văn bản.
• Nội dung tiếng Nhật trong tài liệu phải mở ngoặc ghi romaji và nghĩa tiếng Việt, ví dụ 質問 (shitsumon, câu hỏi).

Phát hành và môi trường thật

• Chỉ phát hành khi người phụ trách ra lệnh trong lượt đó. Lệnh cho phép lần trước không kéo sang lần sau.
• Sao lưu cơ sở dữ liệu prod trước mọi migration. Bản sao lưu là thứ duy nhất cứu bạn khi migration hỏng giữa chừng.
• So sánh bản đang chạy trên prod với bản sắp đẩy trước khi đẩy, vì phiên khác có thể đã phát hành thứ bạn không biết.
• Cấm rsync --delete-excluded lên máy thật. Lệnh này xoá dữ liệu người dùng nằm ngoài kho.
• Đọc cấu hình đúng môi trường. Ví dụ: bạn tắt gửi Teams của Sổ thuật ngữ trong .env trên máy mình rồi tin là prod cũng tắt, trong khi prod vẫn bật và vẫn gửi tin cho khách.
• Không phát hành khi một tiến trình dài đang chạy trên máy thật. Container bị dựng lại là tiến trình chết, việc chạy dở mất hết.
• Tệp cấu hình dùng chung giữa hai kho chỉ được một kho sở hữu. Kho kia phát hành mà mang theo bản cũ của tệp chung sẽ đè lên bản đang chạy, làm sản phẩm còn lại hỏng theo.
• Việc nặng như build image không chạy trên máy chủ nhỏ. Build trên máy cá nhân rồi chuyển image lên.

Khi chạy tại chỗ

• Không chạy lệnh dựng bản phát hành khi máy chủ phát triển đang chạy. Kết quả có thể là mất toàn bộ giao diện và mất hàng giờ tìm lý do.
• Tiến trình theo dõi cũ tích lại thành tiến trình mồ côi làm mã mới không nạp. Thấy "sửa rồi mà vẫn như cũ" thì tắt sạch và chạy lại một tiến trình.
• Không chạy kiểm thử đầu cuối khi máy chủ phát triển đang giữ cơ sở dữ liệu SQLite.

Các sự cố dưới đây đã xảy ra thật. Bối cảnh và tên sản phẩm đã được thay bằng ví dụ chung hoặc sản phẩm của khoá học. Luật rút ra giữ nguyên.

Sau 4 tuần, học viên đủ điều kiện nhận dự án nội bộ nhỏ một mình, hoặc làm vai ra đề và nghiệm thu trong dự án lớn.

Phụ lục A. Mẫu CLAUDE.md cho kho mới

# CLAUDE.md: «Tên dự án» («một câu mô tả»)

«Công nghệ chính, cổng chạy local, nơi phát hành.»

## Quy trình làm việc: 2 luồng

**Luồng nhanh**: sửa lỗi, đầu việc nhỏ (1 đến 2 tệp, không đổi schema/API).
Code thẳng, typecheck + test xanh, commit tiếng Việt `feat|fix|chore(phạm vi): mô tả`.

**Luồng chuẩn (spec-kit)**: BẮT BUỘC khi tính năng mới trọn vẹn, đổi schema,
đụng phân quyền, ước tính > 5 tệp.
1. /speckit-specify → specs/00X-tên/spec.md + spec.html → đưa HTML cho người phụ trách duyệt.
2. Duyệt xong → /speckit-plan → /speckit-tasks → /speckit-implement.
3. Nhịp giao: «theo sprint chờ nghiệm thu | chạy hết rồi rà soát một thể».

## Kiểm chứng
Giao diện xong phải kiểm trên trình duyệt thật/Playwright hoặc nói rõ CHƯA kiểm.
Đo DB/DOM trước khi nói "đã sửa".

## Bẫy bắt buộc nhớ
- «mỗi sự cố một dòng: luật rút ra»

## Phát hành
Chỉ khi người phụ trách yêu cầu. «lệnh + máy đích + bước sao lưu».

Phụ lục B. Lệnh hay dùng, đọc để hiểu AI đang làm gì

Phụ lục C. Bảng kiểm trước khi commit

• Đã chạy git status --short, chỉ nhận những dòng của mình
• Typecheck và test xanh, kết quả lệnh có trong chat
• Tài liệu mô tả hành vi mới nằm cùng commit
• Không có tệp .env, khoá, dữ liệu thật trong danh sách add
• Thông điệp commit tiếng Việt, có phạm vi, nói rõ hành vi đổi

Phụ lục D. Tài liệu đọc thêm

• Tệp luật cấp máy ~/.claude/CLAUDE.md: 10 quy tắc Git nhiều phiên và luật tài liệu đi trước mã, bản đầy đủ.
• CLAUDE.md của kho "Hỏi đáp với khách": mẫu tệp luật dự án, có mục "Bẫy bắt buộc nhớ". Đọc để viết CLAUDE.md của mình.
• Thư mục specs/ của kho "Hỏi đáp với khách": các bộ đặc tả mẫu để học cách viết đề bài, đánh số theo thứ tự làm.
• .claude/skills/README.md và .claude/agents/README.md nếu kho có: danh sách skill và agent có sẵn.