Muốn làm spec-driven bền vững, bạn cần một chỗ cố định để đặt spec, plan và "luật chơi" cho agent. Nếu spec nằm rải rác trong lịch sử chat, agent sẽ quên. Bài này thiết lập bộ khung tối thiểu, dùng được với hầu hết agent (Claude Code, Cursor, Aider...).
Cấu trúc thư mục đề xuất
my-project/
├── AGENT.md # Luật chơi cho agent (context nền)
├── specs/
│ ├── 001-auth-reset.md # Spec từng feature
│ └── 002-export-csv.md
├── plans/
│ └── 001-auth-reset.plan.md # Plan agent sinh ra, bạn duyệt
├── src/
└── tests/
Mỗi feature = 1 file spec đánh số. Plan tương ứng cùng số. Dễ tra cứu, dễ review.
Bước 1 — Viết file AGENT.md (context nền)
AGENT.md là "hiến pháp" agent đọc mỗi phiên. Nó chứa những thứ đúng cho mọi task, không riêng feature nào:
# Hướng dẫn cho Agent
## Tech stack
- Node.js 20, Express, PostgreSQL, Jest.
## Quy tắc bắt buộc
- Không commit secret; đọc config qua process.env.
- Mỗi feature phải có test trước khi coi là xong.
- Migration DB đặt trong /migrations, không sửa migration cũ.
## Quy trình
- Luôn đọc file spec trong /specs trước khi code.
- Làm từng task, dừng cho tôi review sau mỗi task.
- Không tự cài thư viện mới nếu chưa hỏi.
Agent như Claude Code tự đọc file CLAUDE.md/AGENT.md ở gốc repo; các agent khác bạn nạp thủ công vào ngữ cảnh.
Bước 2 — Tạo template spec
Có template giúp mọi spec đồng nhất, agent parse tốt hơn. Lưu specs/_TEMPLATE.md:
# Spec: <tên feature>
## Mục tiêu & lý do
## Người dùng / kịch bản
## Acceptance Criteria
- [ ] ...
## Ràng buộc (bảo mật, hiệu năng, tương thích)
## Ngoài phạm vi
## Câu hỏi mở
Mục "Câu hỏi mở" rất quan trọng: đây là nơi agent ghi những chỗ nó chưa chắc, thay vì tự đoán bừa.
Bước 3 — Cấu hình quyền và an toàn
Spec-driven mạnh nhất khi agent chạy được lệnh (test, lint) nhưng không phá môi trường. Nguyên tắc:
- Cho phép chạy lệnh đọc/kiểm thử:
npm test,git diff,ls. - Yêu cầu xác nhận với lệnh nguy hiểm:
rm,git push,DROP TABLE, deploy. - Làm việc trên nhánh riêng (
git switch -c feature/001-auth), không phải nhánh chính. - Bật review diff trước khi apply (hầu hết agent có chế độ này).
Bước 4 — Kiểm tra vòng lặp phản hồi (feedback loop)
Đảm bảo agent có cách tự biết đúng/sai mà không cần bạn: test chạy được bằng 1 lệnh, linter cấu hình sẵn. Ví dụ thêm script:
{
"scripts": {
"test": "jest",
"lint": "eslint src",
"check": "npm run lint && npm test"
}
}
Giờ bạn chỉ cần nói "chạy npm run check" sau mỗi task — agent tự kiểm chứng.
Checklist thiết lập xong
- [ ] Có AGENT.md ở gốc repo, nêu stack + quy tắc + quy trình.
- [ ] Có thư mục specs/ và plans/, kèm template.
- [ ] Lệnh test + lint chạy được bằng một lệnh duy nhất.
- [ ] Làm việc trên nhánh riêng, lệnh nguy hiểm cần xác nhận.
- [ ] Agent được yêu cầu "dừng review sau mỗi task".
Sai lầm thường gặp
- Nhét mọi thứ vào AGENT.md: File 500 dòng làm loãng ngữ cảnh. Giữ nó ngắn, đưa chi tiết feature vào spec.
- Không có feedback loop: Agent code xong không tự chạy test được nên bạn phải kiểm tra tay từng dòng — rất mệt.
- Cho agent toàn quyền trên nhánh main: Một lệnh sai có thể xóa việc. Luôn dùng nhánh + review diff.
- Bỏ mục "Câu hỏi mở": Agent buộc phải đoán, và nó sẽ đoán sai đúng chỗ bạn quan tâm.