Bạn giao cho Claude Code một feature cỡ 3-4 ngày công: module quản lý API key cho hệ thống nội bộ. Prompt đầu tiên chạy ổn. Prompt thứ năm, agent bắt đầu quên ràng buộc bạn nói ở prompt thứ hai. Đến ngày thứ ba, bạn phát hiện nó tự đổi cách hash key giữa chừng, một nửa codebase dùng cách cũ, nửa kia dùng cách mới. Bạn xóa hết, làm lại từ đầu.
Đó không phải lỗi của model. Đó là lỗi quy trình: bạn đang điều khiển một việc dài hơi bằng những mẩu context rời rạc trôi trong lịch sử chat. Con số phản ánh đúng cảm giác chung — 92% dev Mỹ dùng AI coding hàng ngày, nhưng chỉ 29% tin code nó sinh ra.
Vì sao prompt ad-hoc thất bại với feature lớn
Prompt ad-hoc hoạt động tốt khi toàn bộ yêu cầu nằm gọn trong một lượt hội thoại: sửa bug, viết một hàm, thêm một endpoint đơn giản. Nó vỡ khi feature kéo dài nhiều phiên làm việc, vì ba lý do:
- Context bay hơi. Quyết định "dùng Argon2, không dùng bcrypt" bạn nói hôm thứ hai không tồn tại trong phiên hôm thứ tư. Agent chỉ biết những gì nằm trong cửa sổ context hiện tại.
- Không có nguồn sự thật. Khi requirement nằm rải rác trong 40 prompt, không ai — kể cả bạn — biết trạng thái "đúng" của feature là gì. Review code sinh ra dựa vào... trí nhớ.
- Sai một pha, đập cả công trình. Phát hiện thiếu requirement ở ngày thứ ba nghĩa là regenerate gần như từ đầu, vì không có điểm neo nào để quay lại ngoài "prompt lại cho khéo hơn".
GitHub báo cáo các team dùng Spec Kit giảm khoảng 10 lần số chu kỳ "regenerate from scratch". Cơ chế đằng sau con số đó đơn giản: thay vì sửa hội thoại, bạn sửa tài liệu.
Bốn pha: Spec → Plan → Tasks → Implement
Spec Kit (github/spec-kit, hơn 90 nghìn sao GitHub giữa 2026) cài quy trình này thành các slash command trong agent bạn đang dùng. Mỗi pha sinh ra một artifact Markdown, và artifact đó là context đầu vào cho pha sau — không phải lịch sử chat.
graph LR
A["/specify<br/>spec.md"] --> B["/plan<br/>plan.md"]
B --> C["/tasks<br/>tasks.md"]
C --> D["/implement<br/>code + tests"]
Đi qua từng pha với ví dụ module API key:
1. /specify → spec.md. Bạn mô tả cái gì và vì sao, không mô tả làm thế nào. "Người dùng tạo được API key có scope, key hiển thị đúng một lần, revoke có hiệu lực trong 60 giây, có audit log." Agent sẽ hỏi ngược lại những chỗ mơ hồ — key hết hạn không? rate limit theo key hay theo user? — và ghi hết vào spec.md. Đây là chỗ bạn cãi nhau với chính mình về requirement, khi chi phí sửa còn bằng chi phí sửa một câu văn.
2. /plan → plan.md. Nạp spec.md làm context, agent đề xuất kiến trúc kỹ thuật: bảng api_keys lưu hash chứ không lưu key, dùng Argon2, prefix key để lookup nhanh, revoke qua cache invalidation. Bạn review plan này như review một design doc — vì nó là một design doc. Quyết định "Argon2, không bcrypt" giờ nằm trong file, không nằm trong trí nhớ của ai cả.
3. /tasks → tasks.md. Plan được băm thành danh sách task nhỏ, có thứ tự phụ thuộc: migration trước, model trước service, service trước handler, test đi kèm từng task. Mỗi task đủ nhỏ để agent làm trong một lượt và bạn review trong vài phút.
4. /implement. Agent thực thi từng task, luôn có spec.md và plan.md trong context. Khi nó định "sáng tạo" một cách hash khác, spec là guardrail kéo nó về.
Điểm mấu chốt: khi phát hiện thiếu requirement ở pha implement, bạn không prompt chữa cháy. Bạn sửa spec.md, chạy lại /plan cho phần bị ảnh hưởng, và diff giữa hai phiên bản plan cho bạn thấy chính xác cái gì phải làm lại. Vòng lặp sửa chữa có địa chỉ, thay vì lan man trong chat.
Tool-agnostic: đổi agent giữa chừng không mất gì
Spec Kit không gắn với model hay agent nào. Nó hỗ trợ hơn 30 agent — Claude Code, GitHub Copilot, Codex, Gemini CLI, Cursor... — vì toàn bộ "trạng thái" của dự án là mấy file Markdown nằm trong repo.
Hệ quả thực dụng: bạn có thể dùng Claude Code cho pha spec và plan (nơi cần suy luận dài), rồi chuyển sang agent khác cho pha implement, hoặc đổi hẳn tool khi team đổi license — spec, plan, tasks đi theo repo, không đi theo subscription. Trong bối cảnh 2026 model và tool thay nhau ra mắt vài tháng một lần, việc artifact sống lâu hơn tool tạo ra nó không phải chi tiết phụ. Nó là lý do Thoughtworks Radar vol.34 đưa nhóm SDD tool vào diện đánh giá nghiêm túc thay vì coi là trend.
Spec, ADR, AGENTS.md: hệ tài liệu ba tầng
Nếu bạn đã có ADR và AGENTS.md trong repo, spec không thay thế chúng — ba thứ trả lời ba câu hỏi khác nhau, ở ba tầm thời gian khác nhau:
| Tài liệu | Trả lời câu hỏi | Vòng đời | Ai đọc |
|---|---|---|---|
| ADR | Quyết định kiến trúc gì, vì sao, đánh đổi gì | Năm | Người + agent (qua MCP) |
| AGENTS.md | Khi sửa code trong repo này, điều gì không được xảy ra | Quý | Chủ yếu agent |
| Spec (Spec Kit) | Feature này phải làm gì, plan kỹ thuật ra sao | Feature | Người + agent |
ADR nói "chúng ta chọn PostgreSQL, không chọn DynamoDB, vì X". AGENTS.md nói "mọi query phải qua repository layer, đừng import ORM trực tiếp trong handler". Spec nói "module API key cần những behavior này, implement theo plan này". Agent tốt nhất là agent được đọc cả ba: ADR cho ranh giới dài hạn, AGENTS.md cho luật chơi của repo, spec cho việc đang làm.
Và spec.md sau khi ship không nên vứt đi. Nó là tài liệu kiến trúc sống của module — thứ mà sáu tháng sau, khi một dev (hoặc một agent) mở module ra sửa, sẽ trả lời câu hỏi "cái này được thiết kế để làm gì" nhanh hơn mọi đoạn code comment.
Khi nào KHÔNG cần SDD
Nói thẳng: viết spec cho một bug fix hai dòng là lãng phí. Quy tắc quyết định chỉ có một — chi phí viết spec phải nhỏ hơn chi phí kỳ vọng của việc làm lại.
Không cần SDD khi:
- Fix nhỏ, refactor cục bộ, việc gói gọn trong một phiên làm việc.
- Prototype vứt đi — mục tiêu là học nhanh, không phải code đúng; vibe coding ở đây là đúng công cụ.
- Bạn chưa biết mình muốn gì: spec viết lúc mơ hồ chỉ là đóng băng sự mơ hồ vào file. Prototype trước, spec sau.
Cần SDD khi feature trải nhiều ngày, chạm nhiều module, có nhiều hơn một người (hoặc một agent) tham gia, hoặc sai sót gây chi phí thật — auth, billing, data migration.
Ranh giới giữa vibe coding và engineering chưa bao giờ nằm ở việc ai gõ code. Nó nằm ở chỗ nguồn sự thật là một tài liệu người ta có thể review, diff và sửa — hay là một cuộn lịch sử chat không ai dám đọc lại. Spec Kit chỉ làm một việc: bắt bạn trả lời câu hỏi "mình đang xây cái gì" trước khi máy bắt đầu trả lời hộ.
