Đồng Use Claude — Phần 5: BUILD, điều phối Claude Code viết code

Ba file INTENT → SPEC → PLAN đã chốt làm gì và chứng minh thế nào. Đến BUILD, việc của bạn đổi vai: từ người viết yêu cầu sang người giám sát thi công. Bạn vẫn không gõ code — nhưng bạn đọc diff, bạn dừng AI khi nó lạc plan, và bạn quyết định khi nào được đi tiếp.

Bài 5 trong series. Đã có đủ ba file cho app sổ khách; giờ cho AI thi công.

Hai file nền trước khi build

CLAUDE.md — quy ước cho đội AI

File CLAUDE.md ở root dự án là thứ Claude Code tự đọc mỗi phiên. Đây là “quy chế làm việc” của đội kỹ thuật AI — viết một lần, mọi phiên sau đều tuân:

# CLAUDE.md — sổ khách

## Quy trình bắt buộc
- Mọi việc đi theo file: intent/ → spec/ → plan/ → build → test/
- KHÔNG đụng file ngoài bảng "Files that change" của
  plan đang làm. Cần đụng → dừng, hỏi.
- KHÔNG thêm tính năng ngoài spec. Thấy nên có → đề
  xuất, đợi duyệt.
- Sau mỗi thay đổi: chạy app, đưa bằng chứng (output
  lệnh, response) — không nói "đã xong" bằng miệng.

## Stack
- Cloudflare Workers + Hono + D1. Không thêm framework khác.
- TypeScript. Không dùng `any` trừ khi bất khả kháng.

## Lệnh thường dùng
- Chạy local: `npx wrangler dev`
- Tạo DB local: `npx wrangler d1 execute DB --local --file=schema.sql`

DESIGN.md — chuẩn giao diện

AI generate UI rất nhanh và rất xấu theo một kiểu đặc trưng: gradient tím, bo góc 12px, icon emoji khắp nơi. File DESIGN.md giữ app trông như có người thiết kế:

# DESIGN.md — sổ khách

## Nguyên tắc
- Đây là công cụ nội bộ: dữ liệu > trang trí.
- KHÔNG gradient, KHÔNG emoji trong UI, KHÔNG animation
  không cần thiết, KHÔNG thư viện CSS ngoài.

## Token
- Nền #FAFAF7, chữ #1a1a1a, đường kẻ #e0ddd4,
  nhấn #FFD300 (chỉ cho nút chính + trạng thái "đã gộp").
- Font: hệ thống (system-ui). Số liệu: font mono.
- Bo góc: 0 cho khung/bảng, 4px cho nút và input.

## Layout
- Mobile-first, form một cột, nút submit full-width.
- Bảng danh sách: hàng đầu border-top 2px đậm, các
  hàng sau 1px nhạt.

Có file này, khi AI sinh ra một card tím huề bóng mờ, bạn chỉ cần nói “đọc lại DESIGN.md” thay vì tranh cãi thẩm mỹ.

Prompt build — từ plan, không phải cảm hứng

> Đọc plan/PLAN-01.md. Thi công đúng thứ tự mục 2.
  Làm đến đâu chạy thử đến đó và show output. Xong mỗi
  bước thì dừng báo lại, chưa nhảy bước tiếp. Quy ước
  trong CLAUDE.md và DESIGN.md là bắt buộc.

Ba ý cố tình trong prompt:

• “Đúng thứ tự mục 2” — plan đã sắp thứ tự (schema → API → UI). Để AI tự chọn thứ tự, nó hay viết UI trước vì dễ khoe.
• “Show output” — bắt nó chứng minh bằng output lệnh/response, không chấp nhận “xong rồi”.
• “Dừng báo lại” — checkpoint sau mỗi bước để bạn review, thay vì nhận một cục 800 dòng.

Review diff khi không biết code

Bạn không cần đọc hiểu từng dòng. Cần kiểm 4 thứ:

1. Đụng đúng file không? Diff chỉ nằm trong bảng files-that-change. AI tạo thêm file lạ → hỏi tại sao.
2. Có thứ gì ngoài plan không? Thư viện mới trong package.json, endpoint mới không ai yêu cầu — dấu hiệu phình scope kinh điển.
3. Chạy được không? Bắt nó wrangler dev và đưa bạn URL local. Bạn tự mở, tự bấm — đừng tin screenshot của nó.
4. Bằng chứng đâu? Mỗi PRF trong plan phải có output tương ứng. Chưa có → chưa xong.

Và một thói quen xưa nhưng cứu mạng: git init ngay từ đầu, commit sau mỗi bước được duyệt. Claude Code sửa hỏng thì git checkout . quay lại bản tốt cuối — rẻ hơn mọi kỹ thuật undo.

git init && git add -A && git commit -m "checkpoint: spec + plan approved"

Khi AI lạc plan — và nó sẽ lạc

Dấu hiệu và cách xử lý:

Dấu hiệu	Xử lý
Tạo file/endpoint ngoài plan	”Dừng. File X không có trong plan/PLAN-01.md. Lý do?”
Sửa spec để hợp code đã viết	Không bao giờ cho phép. Code sửa theo spec, không ngược lại
Báo “xong” không có output	”Show output lệnh/response chứng minh PRF-n”
Sửa chỗ A hỏng chỗ B	git diff xem nó đụng gì, rewind về checkpoint
Lan man context, bắt đầu lặp	/compact hoặc /clear + đọc lại file plan — đây là lý do mọi thứ phải thành file

Dòng cuối là toàn bộ lý do của quy trình: context AI có thể mất, file không mất. Khi phiên dài và Claude bắt đầu “quên”, bạn clear context rồi bảo nó đọc lại intent/spec/plan — dự án tiếp tục như chưa hề gián đoạn.

Bài tập

1. Viết CLAUDE.md và DESIGN.md cho dự án của bạn (copy template trên rồi sửa).
2. git init + commit checkpoint ngay bây giờ, trước khi AI viết dòng code nào.
3. Prompt build từ plan, review theo checklist 4 mục.
4. Khi AI làm sai: tập nói “dừng, đọc lại plan” thay vì mô tả lại từ đầu bằng miệng.

Nguồn tham khảo

• Phần 4 — PLAN
• /compact, /clear, /rewind đúng cách

Bài tiếp theo: Phần 6 — TEST.