Bài 5 — Thực thi từng task và review từng bước để chặn drift

Plan đã chốt. Giờ là vòng lặp lõi của spec-driven: một task → agent code → bạn review diff → chạy test → commit → task tiếp theo. Kỷ luật "một task một lần" chính là thứ giữ agent không trôi.

Vòng lặp thực thi chuẩn

• Yêu cầu agent làm đúng một task, dừng lại.
• Đọc diff (không đọc lại toàn bộ file — chỉ phần thay đổi).
• Chạy npm run check (lint + test).
• Nếu đạt: commit với message tham chiếu task. Nếu không: phản hồi, sửa.
• Sang task kế tiếp.

Prompt mẫu:

Làm T2 trong plans/002-search.plan.md.
Chỉ làm T2. Viết test theo AC1, AC2. Chạy npm run check.
Sau đó dừng và tóm tắt cái đã thay đổi. ĐỪNG làm T3.

Review diff: bạn nhìn gì

Review không phải đọc lại từng ký tự. Hãy quét theo bốn câu hỏi:

• Đúng phạm vi task? Diff chỉ đụng thứ liên quan T2, hay lan sang file lạ?
• Khớp acceptance criteria? Test có thật sự kiểm AC1/AC2, hay chỉ expect(true)?
• Vi phạm ràng buộc nào không? Có log secret, có gọi API đồng bộ bị cấm?
• Có "tự tiện thêm"? Agent hay bonus tính năng ngoài spec — cắt ngay.

git diff --stat        # xem phạm vi lan tới đâu
git diff src/routes/   # đọc chi tiết phần cốt lõi
npm run check          # đối chứng khách quan

Commit nhỏ, thường xuyên

Mỗi task xong = một commit. Lợi ích: khi task 6 hỏng, bạn git revert đúng một commit, không mất 5 task trước. Commit message nên tham chiếu spec/task:

feat(search): endpoint GET /search (spec 002, T2)

Khi test đỏ hoặc review lệch — phản hồi thế nào

Đừng tự sửa tay im lặng (agent sẽ không học được ngữ cảnh). Hãy phản hồi cụ thể, tham chiếu spec:

Test AC2 fail: tìm "Cà Phê" không ra "ca phe".
Spec yêu cầu bỏ dấu + không phân biệt hoa thường.
Sửa normalize input trước khi query, thêm test cho trường hợp có dấu.

Phản hồi neo vào spec giúp agent sửa đúng gốc, không vá triệu chứng.

Nhận diện drift sớm — các tín hiệu đỏ

• Diff đụng nhiều file ngoài dự kiến của task.
• Agent "nhân tiện" refactor thứ không ai yêu cầu.
• Test được viết để pass cho có, không phản ánh AC.
• Agent bắt đầu thêm tính năng trong mục "ngoài phạm vi".
• Câu trả lời của agent mô tả thứ khác với task hiện tại.

Gặp tín hiệu đỏ: dừng, hỏi lại, hoặc git restore phần thừa. Rẻ hơn nhiều so với gỡ rối sau 10 task.

Ví dụ tình huống

Bạn giao T2 (endpoint search). Agent trả về diff đụng cả src/auth.js và thêm middleware rate-limit "cho chắc". Rate-limit không có trong spec search. Xử lý: yêu cầu bỏ thay đổi ở auth.js, giữ diff gọn trong phạm vi T2. Nếu rate-limit thực sự cần, nó phải thành task riêng có spec riêng.

Khung tư duy: "Diff là hợp đồng của task"

Mỗi diff phải chứng minh được: đây là ít nhất những gì cần để hoàn thành đúng task này, không hơn. Thừa thì cắt, thiếu thì bổ sung — nhưng luôn quy chiếu về task và spec.

Checklist trước khi commit một task

• [ ] Diff chỉ chạm phạm vi của task.
• [ ] Test mới phản ánh đúng acceptance criteria.
• [ ] npm run check xanh.
• [ ] Không vi phạm ràng buộc/bất biến trong spec.
• [ ] Không có tính năng "ngoài phạm vi" lọt vào.
• [ ] Commit message tham chiếu spec + task.

Sai lầm thường gặp

• Cho agent làm nhiều task một lượt: Diff khổng lồ, review đuối, drift lọt lưới.
• Duyệt diff kiểu "nhìn lướt cho qua": Test giả (expect(true)) lọt qua và bạn tưởng đã xong.
• Tự sửa tay không phản hồi agent: Lần sau agent lặp lại đúng lỗi vì không được nắn.
• Commit gộp cả feature: Khi hỏng phải revert cả cụm, mất công đã đúng.
• Bỏ qua tín hiệu đỏ vì "vẫn chạy được": Chạy được không có nghĩa đúng spec.

Bài 6: dùng test và acceptance criteria làm "lưới an toàn" tự động cho toàn bộ vòng lặp.