Biến request thành contract, rồi mới thành code đã verify.
CafeKit đưa phần quan trọng ra khỏi chat. Assistant viết contract trước, implement một task packet đã approve, sau đó prove bằng evidence và sync state.
Người dùng yêu cầu một thay đổi.
Scope, requirements, design, và tasks thành file bền vững.
Assistant implement một task packet đã approve.
Command thật và runtime proof kiểm tra kết quả.
Một pass riêng kiểm tra compliance và risk.
State chỉ được chuyển khi đã có evidence.
Hiểu đơn giản#
Spec-driven development nghĩa là spec là người cầm lái, không phải đoạn chat.
Trong AI coding bình thường, assistant thường làm theo trí nhớ hội thoại. Cách đó mong manh. Request có thể bị tóm tắt sai, scope có thể trôi, và session sau không biết vì sao một quyết định được đưa ra.
CafeKit đổi trọng tâm. Trước khi sửa code, công việc được ghi vào specs/<feature>/. Folder đó trở thành contract chung cho người dùng, assistant, reviewer, và các session sau.
Viết rõ điều cần xảy ra trước khi sửa code.
Chỉ implement đúng boundary của task đã approve.
Chạy command và ghi lại evidence chính xác.
Update spec.json và task markdown sau khi có proof.
Assistant được tin vào cái gì#
Assistant nên tin artifact bền vững trong repo trước:
Machine state: phase, scope lock, task registry, approvals.
Behavior user nhìn thấy và acceptance criteria.
Finding và decision có source backing.
Architecture, contracts, data flow, invariants.
Một gói implement gồm files, steps, criteria, evidence.
Điểm quan trọng không phải là CafeKit tạo nhiều file hơn. Điểm quan trọng là mỗi file trả lời một câu hỏi khác nhau:
| Artifact | Câu hỏi nó trả lời |
|---|---|
requirements.md | Product cần làm gì? |
research.md | Fact hoặc decision nào có source backing? |
design.md | System nên được thiết kế như thế nào? |
tasks/task-R*.md | Đơn vị implementation nào đang được approve? |
spec.json | Machine-readable state của feature là gì? |
Luật làm việc hằng ngày#
Khi feature đủ quan trọng, dùng luật này:
Dùng /hapo:brainstorm trước chỉ khi request chưa đủ rõ để viết specs. Delivery path chính bắt đầu ở đây:
- Chạy
/hapo:specskhi goal đã đủ rõ để thành contract. - Không develop khi spec chưa có task packet đã approve.
- Chạy
/hapo:developcho từng task packet. - Verify bằng
/hapo:testvà review bằng/hapo:code-review. - Chỉ chạy
/hapo:syncsau khi có proof, hoặc dùng/hapo:sync audit <feature>để repair drift.
Khi nào nên dùng full SDD#
Dùng full path khi work đổi product behavior, chạm nhiều file, đi qua runtime boundary, đổi data/auth/package contracts, ảnh hưởng user, cần review evidence, hoặc có khả năng handoff cho assistant hay teammate khác.
Với copy edit nhỏ hoặc fix một dòng đã rất rõ, full spec flow có thể hơi nặng. Nhưng thói quen vẫn giữ nguyên: nói rõ boundary, chỉ sửa đúng boundary đó, verify kết quả, và không để scope lớn lên âm thầm.
Đọc tiếp ở đâu#
Đọc Workflow chính để thấy toàn bộ command path. Đọc Vòng đời spec khi cần luật chi tiết hơn về spec.json, task packets, validation, và readiness.