Triển khai công việc đã duyệt với ak:cook

Dùng ak:cook để biến yêu cầu rõ ràng hoặc implementation plan đã duyệt thành thay đổi code được kiểm thử và review. Skill kiểm tra project hiện tại, giữ implementation gắn với acceptance criteria có thể quan sát và báo cáo bằng chứng bạn cần để quyết định kết quả đã hoàn tất hay chưa.

Chọn ak:cook khi scope đã sẵn sàng

Dùng ak:cook khi

• Bạn có feature, refactor hoặc maintenance task với outcome đã xác định.
• Các constraint, non-goal và acceptance criteria quan trọng đã rõ.
• Bạn có plan đã duyệt và muốn thực thi plan đó trên codebase hiện tại.
• Bạn muốn kết hợp implementation, kiểm thử tập trung và code review trong một workflow được điều phối.

Chọn workflow khác khi

• Outcome hoặc solution mong muốn vẫn chưa rõ. Bắt đầu với ak:brainstorm, sau đó dùng ak:plan khi đã thống nhất hướng đi.
• Bạn đang điều tra một bug cụ thể, test thất bại hoặc lỗi CI. Dùng ak:fix, workflow yêu cầu bằng chứng root cause trước khi chọn cách sửa.
• Bạn chỉ cần verification độc lập. Dùng ak:test để kiểm thử hoặc ak:code-review để review mà không bắt đầu implementation mới.
• Bạn cần lời khuyên thay vì thay đổi workspace. Hãy dùng workflow tư vấn hoặc hỏi đáp trước.

Chuẩn bị project và runtime

Trước khi bắt đầu:

• Hoàn thành Làm quen và xác nhận Engineer Kit đã được cài cho đúng runtime cùng scope bạn đang dùng.
• Mở một project nơi bạn chấp nhận để assistant sửa tệp và chạy các lệnh validation của project.
• Giữ nguyên công việc không liên quan và nêu rõ ranh giới tệp hoặc module dự kiến.
• Cung cấp yêu cầu cụ thể hoặc đường dẫn tới plan đã duyệt.
• Đọc instruction của repository và mọi yêu cầu an toàn riêng của project sẽ chi phối lần chạy.

ak:cook được đóng package cho cả ba target Engineer được hỗ trợ:

Xem Runtime adapter để hiểu khác biệt về scope, cách phân phối và từng loại component.

Chạy Skill

Nếu không truyền cờ chế độ, Skill chạy ở mode interactive; bạn cũng có thể chọn rõ mode này bằng --interactive. Skill dừng tại các review gate chính để bạn kiểm tra phát hiện, duyệt plan, yêu cầu chỉnh sửa hoặc dừng workflow.

/ak:cook "Add POST /api/feedback with existing authentication, return 202, store no new data, add focused tests, and do not commit or deploy"

/ak:cook "Add POST /api/feedback with existing authentication, return 202, store no new data, add focused tests, and do not commit or deploy"

$ak:cook "Add POST /api/feedback with existing authentication, return 202, store no new data, add focused tests, and do not commit or deploy"

Bạn cũng có thể truyền đường dẫn tới plan đã duyệt. Dùng /ak:cook ./plans/feedback-endpoint/plan.md trong Claude Code hoặc Cursor và $ak:cook ./plans/feedback-endpoint/plan.md trong Codex. Skill dùng lại outcome cùng acceptance criteria của plan, rồi kiểm tra bằng chứng hiện tại trong project trước khi thay đổi.

Chọn mode thực thi có chủ đích

Dùng tùy chọn rõ ràng khi execution shape quan trọng. Đừng dùng --auto hoặc --no-test chỉ để vượt qua quyết định hay lỗi chưa được xử lý. Khi chọn --yagni, Skill chuyển nguyên flag này cho các Skill downstream và công việc được giao để opt-in tồn tại qua từng handoff.

Mô tả công việc rõ ràng

Một yêu cầu hữu ích cung cấp cho Skill năm điều:

• Outcome: Nêu hành vi người dùng hoặc hệ thống cần được cung cấp.
• Constraints: Nêu pattern, module, yêu cầu compatibility hoặc công cụ mà implementation phải giữ nguyên.
• Non-goals: Loại trừ công việc gần kề dễ làm scope phình ra.
• Acceptance criteria: Đưa ra phép kiểm tra có thể quan sát cho thành công, gồm cả lỗi dự kiến và edge case.
• Authority boundary: Nêu Git, publication, deployment, dịch vụ bên ngoài, dữ liệu nhạy cảm hoặc hành động phá hủy có nằm ngoài lần chạy hay không.

Với ví dụ feedback endpoint, input tốt sẽ yêu cầu dùng lại pattern xác thực và API hiện có, trả 202, không thêm persistence layer, bao phủ request được và không được xác thực, rồi dừng trước commit hoặc deploy. Input này hữu ích hơn “build a feedback API” vì nó xác định cả kết quả lẫn ranh giới.

Hiểu điều gì xảy ra trong một lần chạy

Bạn nên thấy một tiến trình ngắn gọn thay vì một khối chỉnh sửa không được giải thích:

1. Skill xác nhận contract. Skill ghi nhận hoặc dùng lại outcome, constraint, non-goal cùng acceptance criteria và chỉ hỏi về quyết định quan trọng còn thiếu.
2. Skill kiểm tra project. Skill xác định stack, tệp liên quan, pattern hiện có, instruction của project, tài liệu gần đó và public contract có thể bị ảnh hưởng.
3. Skill tạo hoặc tải plan. Research được thực hiện khi mode đã chọn cần. Trong mode interactive, bạn review plan trước implementation.
4. Skill triển khai scope đã duyệt. Công việc theo thứ tự plan và quy ước project đã tìm thấy, còn tiến độ được đồng bộ với active plan khi có.
5. Skill xác minh thay đổi. Kiểm thử chạy theo mặc định và code review là bắt buộc trong mọi mode. Lỗi, regression hoặc thay đổi contract vẫn hiển thị thay vì bị lách qua âm thầm.
6. Skill hoàn tất bằng chứng. Skill đối chiếu tiến độ plan, đánh giá ảnh hưởng tới tài liệu, tóm tắt tệp cùng check và hỏi trước khi đi vào workflow Git riêng.

Workflow có thể dùng Agent chuyên biệt để kiểm tra, triển khai, test, debug hoặc review từng phần của task. Instruction nội bộ của chúng không phải deliverable; kết quả cho người dùng là thay đổi đúng scope cùng bằng chứng của nó.

Giữ quyền phê duyệt và an toàn ở bạn

Skill sẽ không quyết định các vấn đề sau thay bạn:

• Một requirement hay public contract đã đổi có chấp nhận được hay không.
• Một test thất bại hoặc bị bỏ qua có phải release risk chấp nhận được không.
• Một regression nên được sửa, revert, cô lập sau compatibility behavior hay chấp nhận rõ ràng.
• Credential hoặc dữ liệu nhạy cảm có được gửi tới dịch vụ bên ngoài không.
• Kết quả có nên được commit, push, mở pull request, merge, publish hay deploy không.

Nếu verification tìm thấy side effect ngoài ý muốn, lần chạy nên dừng và hiển thị điều đã thay đổi, nguyên nhân cùng lựa chọn khôi phục có giới hạn. Đừng dùng --no-test, --auto hay force operation diện rộng để che bằng chứng đó.

Xác minh kết quả

Một lần chạy hoàn tất nên cung cấp:

• Một implementation diff đúng scope và theo pattern hiện có của project.
• Test được thêm hoặc cập nhật khi cần, cùng lệnh và kết quả dùng để verification trừ khi bạn chủ động chọn --no-test.
• Phát hiện từ code review bắt buộc và cách xử lý từng blocker hoặc warning.
• Bằng chứng acceptance criteria đã được kiểm tra và behavior gần đó không regression.
• Tiến độ plan được cập nhật khi lần chạy bắt đầu từ hoặc tạo một plan.
• Báo cáo cuối ngắn gọn nêu tệp đã đổi, validation, rủi ro còn lại và hành động vẫn cần bạn phê duyệt.

Chỉ coi lần chạy hoàn tất khi acceptance criteria đã đạt, các test và repository check liên quan đã pass, code review không còn blocker chưa xử lý và bạn chấp nhận diff. Với --no-test, completion phải ghi rõ thiếu bằng chứng test; riêng code review không chứng minh implementation hoạt động.

Xử lý sự cố hoặc tiếp tục

Tiếp tục với Tổng quan Engineer Kit, so sánh Runtime adapter hoặc dùng Tham chiếu CLI để tra cứu lệnh lifecycle AgentKit chính xác.

Hiểu ranh giới của lời nhắc plan

Engineer chỉ export lời nhắc cook-after-plan trên wildcard Stop; lời nhắc này không có đăng ký SubagentStop được phát hành. Khi không có plan đang hoạt động, Hook trả mã 0 với stdout rỗng, bất kể model. Khi có plan, Hook emit JSON hợp lệ, không chặn với dạng {"continue":true,"systemMessage":"..."}. Stdin rỗng vẫn im lặng, còn stdin không rỗng nhưng malformed được xử lý fail-open thay vì chặn session.

Biết các giới hạn hiện tại

• Skill chỉ có thể dùng tool, credential, runtime và quyền truy cập project có trong session hiện tại.
• Runtime projection phụ thuộc từng capability. Cùng một workflow Skill không có nghĩa Hook, behavior của Agent, plan tooling hay UI giống nhau trên mọi runtime.
• Cách gọi Cursor bằng slash là bằng chứng do người dùng xác minh. Nó không thiết lập Cursor parity đầy đủ và statusline Engineer vẫn không khả dụng ở đó.
• Codex chạy Skill bằng native discovery, nhưng một số group Engineer Hook không thể được chuyển sang runtime và statusline không khả dụng.
• Projection Hook riêng theo runtime không thay đổi workflow của Skill này hoặc cấp cho lời nhắc quyền chặn hoàn tất.