Spec nói đích đến. Plan nói con đường: chuỗi task nhỏ, có thứ tự, mỗi task kiểm chứng được. Đây là điểm kiểm soát thứ hai của bạn — duyệt plan trước khi một dòng code được viết, sửa lệch khi còn cực rẻ.
Vì sao phải tách bước plan riêng
Nếu bảo agent "đọc spec rồi làm luôn", nó vừa nghĩ vừa gõ, và bạn chỉ thấy kết quả cuối. Tách plan ra giúp:
- Bạn thấy agent hiểu spec thế nào — nếu plan lệch, tức là nó hiểu sai spec.
- Phát hiện task thiếu (quên migration, quên test) hoặc thừa (over-engineering).
- Kiểm soát thứ tự: làm phần rủi ro/cốt lõi trước.
Prompt yêu cầu plan
Đọc specs/002-search.md và AGENT.md.
ĐỪNG viết code. Hãy tạo plan:
- Chia thành các task nhỏ, mỗi task <= ~1 giờ công.
- Mỗi task ghi: mục tiêu, file dự kiến đụng tới, cách kiểm chứng (test nào).
- Sắp thứ tự theo phụ thuộc; đánh dấu task rủi ro cao.
- Liệt kê giả định bạn đang đặt ra.
Ghi plan vào plans/002-search.plan.md.
Câu "liệt kê giả định" là mỏ vàng: nó lộ những chỗ agent định đoán bừa, để bạn chỉnh trước.
Một plan tốt trông thế nào
# Plan: Tìm kiếm sản phẩm (spec 002)
## Giả định
- Dùng PostgreSQL full-text search, chưa cần Elasticsearch.
- Phân trang offset (spec chưa chốt cursor).
## Tasks
### T1 — Thêm index tìm kiếm (rủi ro: trung bình)
- File: migrations/003_search_index.sql
- Kiểm chứng: migration chạy, EXPLAIN dùng index.
### T2 — Endpoint GET /search (rủi ro: cao)
- File: src/routes/search.js
- Kiểm chứng: test AC1, AC2 (giới hạn 20, không dấu).
### T3 — Xử lý rỗng + gợi ý từ khóa
- File: src/routes/search.js
- Kiểm chứng: test trả [] + gợi ý.
### T4 — Test hiệu năng P95 < 300ms
- File: tests/search.perf.test.js
Mỗi task map ngược về acceptance criteria trong spec. Nếu một AC không có task nào phủ, plan còn thiếu.
Bước duyệt plan (bạn làm)
- Đối chiếu spec: Mọi AC đều có ít nhất một task phủ? Có task nào lạc đề spec?
- Soi giả định: Giả định nào sai hoặc rủi ro? Sửa ngay, hoặc yêu cầu agent hỏi thêm.
- Xét thứ tự: Task cốt lõi/rủi ro cao có nên làm sớm để lộ vấn đề? Task lớn có nên chẻ nhỏ?
- Chốt định nghĩa "xong": Mỗi task phải có cách kiểm chứng rõ, nếu không, yêu cầu bổ sung.
- Cắt phạm vi lần cuối: Task nào là "vàng thau lẫn lộn" (nice-to-have)? Đẩy sang sau.
Khung "INVEST" rút gọn cho task
Một task tốt nên:
- Independent — làm và review độc lập được.
- Small — đủ nhỏ để review trong vài phút.
- Testable — có cách chứng minh nó đúng.
Ví dụ tình huống: plan lệch spec
Spec nói "ngoài phạm vi: autocomplete". Nhưng plan có task "T5 — thêm gợi ý gõ realtime". Đây là scope creep. Xử lý: yêu cầu agent bỏ T5, ghi chú "để phase sau". Bắt sớm ở bước plan tốn 30 giây; bắt muộn sau khi code xong tốn nửa ngày.
Checklist duyệt plan
- [ ] Mỗi acceptance criteria có task phủ.
- [ ] Không có task ngoài phạm vi spec.
- [ ] Mỗi task nêu rõ cách kiểm chứng.
- [ ] Giả định đã được soi và chấp nhận.
- [ ] Task rủi ro cao xếp sớm.
- [ ] Task quá to đã được chẻ nhỏ.
Sai lầm thường gặp
- Duyệt plan qua loa: Gật đầu cho nhanh rồi để agent chạy — bạn mất chính điểm kiểm soát rẻ nhất.
- Bỏ qua mục giả định: Không đọc giả định đồng nghĩa để agent tự quyết những chọn lựa kiến trúc quan trọng.
- Task không kiểm chứng được: "Cải thiện code" — không đo được là xong hay chưa.
- Không map task về AC: Kết quả là code chạy nhưng thiếu đúng thứ spec cần.