cook: xây tính năng

/znf:cook là workflow xây tính năng từ đầu đến khi mở PR. Nó đi qua brainstorm, spec, ground, plan, implement bằng subagent, rồi gọi /znf:ship.

Khi nào dùng

Dùng /znf:cook khi:

• Cần thiết kế hoặc đồng thuận trước khi code.
• Việc chạm nhiều file.
• Việc chạm tài nguyên chung: DB collection, endpoint, queue, channel.

Không dùng /znf:cook khi:

• Đã biết vì sao, chỉ sửa một dòng. Đi đường không dùng workflow, xem Chọn workflow.
• Đang hỏng, chưa biết vì sao. Dùng /znf:fix.
• Đang hỏng trên production. Dùng /znf:hotfix.

Cách gọi

/znf:cook <mô tả tính năng>
/znf:cook <path/to/plan.md>

Agent chỉ đề xuất /znf:cook, không tự chạy. Workflow này có gate chờ bạn quyết định và ghi ra spec, plan. Khi agent thấy việc giống cook, nó nói một câu và để bạn gõ lệnh.

Viết yêu cầu

Yêu cầu càng đủ các trường dưới đây, bước brainstorm càng ngắn.

Trường	Ví dụ
Kết quả mong muốn	Trang tài liệu tĩnh cho zenify-kit, host trên Cloudflare Pages
Ràng buộc	Chỉ người @zenify.vn đọc được; chi phí 0
Ngoài phạm vi	Không viết lại README, không đổi CLI
Tiêu chí nhận	Build xanh, không dead link, mọi lệnh ground trên binary thật
Repo liên quan	zenify-kit

Các bước

Các bước của một lần chạy cook

Bước	Kit làm gì	Bạn làm gì
0	git fetch base ref của mỗi repo liên quan	Không cần làm gì
1	Ground các tên trong yêu cầu bằng zenify db-read collections/doc	Đọc kết quả ground
2	Brainstorm 13 bước. Bước đầu viết lại hiểu biết chung (bạn nói gì, kit giả định gì) để bạn sửa trước khi đi tiếp. Sau câu hỏi làm rõ, bước Research check chạy checklist sáu mục (gồm mục "dựng hạ tầng quanh tool bên thứ ba", luôn đúng với loại thiết kế đó); một mục đúng thì gọi /znf:research (chạy tách context, trả về ≤ 40 dòng) trước khi đề xuất phương án. Câu hỏi làm rõ đi theo lượt: tối đa 4 câu trắc nghiệm mỗi lượt, đáp án khuyến nghị đứng đầu; điều repo hoặc DB trả lời được thì kit tự tra thay vì hỏi bạn. Khi thiết kế, kit kiểm module có "sâu" không: xoá module đi thì độ phức tạp có dồn về nơi gọi không, test được qua giao diện của nó không, và không thêm lớp trừu tượng khi mới có một cài đặt thật	Trả lời từng lượt câu hỏi. Chốt thiết kế, rồi duyệt spec trước khi kit ghi file. Kit dừng chờ bạn ở cả hai gate; mỗi lần duyệt chỉ duyệt đúng stage vừa trình bày. Đọc khối scope của research nếu có
3	Ground lại mọi tên trong spec vừa chốt	Đọc nếu có mâu thuẫn. Spec được sửa trước khi viết plan
4	Chạy /znf:scout (agent) tìm nơi phụ thuộc vào phần sắp đổi	Đọc báo cáo scout
5	Viết plan ở mức quyết định: mỗi bước ghi file, signature và assertion của test, không chép sẵn toàn bộ code. /znf:analyze chạy tư vấn, không chặn	Duyệt plan. Kit đưa đường dẫn plan cùng finding CRITICAL/HIGH của analyze và dừng chờ bạn; chỉ sau khi bạn đồng ý mới sang bước 6
6	Tạo worktree, chạy SDD: mỗi task một implementer (sonnet, viết test trước và chỉ chạy test tập trung cho file mình đổi — full suite do CI chạy trên PR, /znf:ship chạy test bị ảnh hưởng của branch; phần kết nối hoặc cấu hình không có giá trị kỳ vọng độc lập thì báo No TDD: <lý do> kèm output chạy thật thay cho cặp đỏ/xanh). Giá trị kỳ vọng của test lấy từ nguồn độc lập, không tính lại theo cách code tính; chỉ mock ở ranh giới hệ thống (API ngoài, thời gian, ngẫu nhiên), không mock module của chính mình; assert qua giao diện công khai. Reviewer của task soát cả các luật này	Theo dõi ledger .znf/sdd/<plan>/progress.md
7	Gọi /znf:ship	Đọc board ship, nhận PR

Stacked PR

Plan lớn (diff dự kiến vượt khoảng 600 dòng, hoặc task chia được thành các lớp tự build và test được) có thể ship thành một stack PR của GitHub thay vì một PR. Kit chỉ đề xuất; ở gate duyệt plan (bước 5) kit nêu số lớp và tiêu đề từng lớp, và bạn quyết định. Không duyệt thì plan không có khối ## Stack và đi luồng một PR như cũ.

Plan có ## Stack thì ở bước 6 SDD dựng từng lớp bằng gh stack (mỗi task thuộc đúng một lớp), và ship review từng lớp, rồi mở cả stack. Plan cần gh từ 2.90.0 và extension gh-stack; thiếu thì kit dừng trước task đầu và báo lệnh gh extension install github/gh-stack. Định dạng khối ## Stack nằm ở Spec, plan và kiểm tra.

Kết quả

Artifact	Đường dẫn
Spec	docs/specs/<repo>/YYYY-MM-DD-<topic>-design.md (knowledge store)
Plan	docs/plans/<repo>/YYYY-MM-DD-<topic>.md
Ledger tiến độ	.znf/sdd/<plan>/progress.md
Branch	<user>/feat/<slug>
PR	Mở, chưa merge. Plan có ## Stack: một PR mỗi lớp

Quyết định thuộc về bạn

• Chốt thiết kế và duyệt spec (hai gate ở bước 2), rồi duyệt plan (gate ở bước 5). Cook dừng chờ bạn ở cả ba.
• Merge PR sau khi ship xong.
• Mọi bước tay ngoài repo, ví dụ thao tác hạ tầng.

Ví dụ

Chính site tài liệu này được xây bằng /znf:cook. Yêu cầu ban đầu là "doc site cho zenify-kit". Kit ghi spec và plan vào knowledge store, tạo worktree .worktrees/kit-docs-site với branch namph/feat/kit-docs-site, rồi chạy SDD theo từng task. PR mở ở bước ship.

Lỗi thường gặp

Tránh	Nên làm
Bỏ spec vì việc nhỏ	Viết spec ngắn. Brainstorming cho phép spec vài câu với việc đơn giản, không cho phép bỏ hẳn
Tự gõ code trong lúc cook đang chạy SDD	Để implementer làm. Bạn đọc ledger và can thiệp ở ba gate
Merge PR ngay khi thấy PR mở	Đọc board ship trước. Review độc lập và verify hành vi nằm ở đó

Xem thêm

/reference/skills/cook, Worktree theo slug, Knowledge store, Chọn workflow