`/ak-orchestrate` và `/ak-atoz`: giao việc xuyên đêm cho một đội agent, sáng dậy chỉ việc review PR

Bài 13 trong bộ onboarding AgentKit v3. Đọc khoảng 12 phút. Nên đọc bài 12 trước.

Từ ngày xài Opus 5.5 trong Claude Code (desktop app), cách làm việc của tui đổi hẳn. Tui không còn ngồi chat với một agent rồi đợi nó làm từng việc. Giờ tui mở một main session làm "nhạc trưởng", nó chia việc ra nhiều sub-session chạy song song, mỗi cái một worktree, một branch, một PR. Tui chỉ chốt yêu cầu ở đầu và review ở cuối.

Hai skill làm nên chuyện này là /ak-orchestrate và /ak-atoz. Bài này giới thiệu cả hai, kèm kinh nghiệm thật của tui, cả cái được lẫn cái phải cẩn thận.

1/ Sub-session khác subagent chỗ nào?

Hai thứ này nghe giống nhau mà bản chất khác:

Anthropic nói gì về chuyện này?

Hướng dẫn tích hợp sẵn trong Claude Code desktop app nói khá thẳng: subagent tốn hơn bạn tưởng. Nó chỉ biết những gì bạn viết trong prompt. Bạn chỉ thấy bản tóm tắt nó gửi lại, nên chi tiết rơi rớt ở cả hai đầu. Lỗi của nó cũng trả về với giọng tự tin y như kết quả đúng. Nguyên tắc ở đó là "khi phân vân thì đừng spawn". Việc vài tool call thì tự làm, chỉ giao subagent khi có việc độc lập chạy song song được, hoặc khi phải đọc qua nhiều file mà chỉ cần giữ lại kết luận.

Còn sub-session thì hướng dẫn đó dành cho một đầu việc của riêng nó: sống lâu hơn lượt hiện tại, người dùng muốn mở ra xem hay chỉnh riêng, và kết thúc bằng một thứ của riêng nó như branch, PR, hay thay đổi ở repo khác. Một mảnh nhỏ của việc đang làm (tìm kiếm, đọc file, test, review) thì vẫn ở lại session chính hoặc giao subagent.

Mấy bài test của cộng đồng cũng ra kết quả cùng hướng. Có một bài đo thấy dùng subagent cho việc nhỏ đẩy token từ khoảng 121 nghìn lên 513 nghìn, tức hơn 4 lần. Con số này chỉ từ một bài test nên coi để tham khảo thôi, nhưng hướng thì rõ: subagent không phải mặc định, nó là công cụ cho đúng loại việc.

Nên quy tắc tui xài:

• Mỗi GitHub issue, mỗi PR là một sub-session.

• Subagent chỉ dùng trong một việc: scout code, đọc docs, hoặc review độc lập để có góc nhìn không bị neo theo ý tui.

Opus 5.5 điều phối giỏi thật

Hồi các bản model trước, cho agent tự điều phối là kiểu đốt token vô nghĩa: spawn tràn lan, giao việc trùng nhau, rồi tốn thêm token đọc lại kết quả của nhau. Tới Opus 5.5 thì khác hẳn. Nó biết việc nào nên tự làm, việc nào nên tách ra, brief cho sub-session đủ rõ, và chịu kiểm tra diff thay vì tin báo cáo.

Nói vậy chứ đừng nghĩ nó hoàn hảo nha. Tui vẫn gặp sub-session báo "xong" mà CI còn đỏ, nên bước review ở cuối không bao giờ được bỏ.

2/ GitHub Issues là bảng công việc, là nguồn sự thật duy nhất

Đây là thay đổi lớn nhất trong thói quen của tui: mọi thứ nằm trên GitHub Issues. Plan, tiến độ, todo, trạng thái, quyết định, tất cả cập nhật ở đó, không nằm rải rác trong chat hay file tạm.

Tại sao? Vì khi có 5 tới 10 sub-session chạy cùng lúc, thứ dễ vỡ nhất là sự phối hợp. Hai agent làm trùng một việc, hoặc một agent sửa thứ agent khác vừa sửa xong. Issue trở thành chỗ để:

• Nhận việc: agent tự pickup issue, assign cho GitHub user của tui, gắn nhãn in progress. Agent khác thấy nhãn này thì biết là đã có người nhận.

• Báo tiến độ: label đi theo vòng đời in progress → in review → done (PR đã mở) → shipped (đã merge).

• Ghi lại phát hiện: gặp bug hay gap không thuộc phạm vi thì mở issue riêng, gắn nhãn ai-handle, không sửa lan man trong lần chạy hiện tại.

• Giữ lại lịch sử: mai mốt bạn (hay một agent khác) đọc issue là biết vì sao quyết định như vậy.

Thú vị nhất là các sub-session tự nhắn cho nhau để phối hợp. Ví dụ session làm API nhắn session làm website: "endpoint mới đã lên, schema đổi field này". Tui không phải làm người chuyển lời nữa 😂

3/ Quy trình của tui, từng bước

Bước 1: mở một main session mới, với environment chứa tất cả thư mục dự án liên quan.

Ví dụ với AgentKit, tui add hết vô một session: repo kit và skill, website, MCP server, AK Vault, AK Render... Main session cần nhìn thấy toàn cảnh thì mới chia việc đúng.

Main session "TOSE - Development" (khung đỏ) mở 8 sub-session PR batch (khung vàng bên trái). Mỗi lần nó muốn mở session mới, app hỏi "Allow once". Cột phải là environment chứa đủ các thư mục dự án.

Bước 2: chốt việc cần làm. Một đầu việc rõ thì dùng /ak-atoz (mục 5). Một danh sách issue đã có sẵn thì giao thẳng cho /ak-orchestrate:

/ak-orchestrate xử lý các issue có nhãn ai-handle trong bestagentkits/agentkit,
mỗi issue một sub-session trong worktree riêng, review độc lập trước khi mở PR

Bước 3: để main session điều phối. Nó lên kế hoạch, chia việc theo nhóm file không chồng nhau, mở sub-session, theo dõi, gom kết quả. Việc phụ thuộc thì chờ việc trước xong mới chạy.

Bước 4: sáng dậy review PR. Mỗi PR đã qua một vòng review trong context sạch. Việc của tui là đọc, hỏi lại chỗ nghi ngờ, rồi merge.

4/ /ak-orchestrate: điều phối, kể cả agent runtime khác

/ak-orchestrate là skill điều phối. Skill lo phần phán đoán: việc nào giao ai, model nào, mức rủi ro nào. Còn ak orchestrate (CLI) lo phần chắc chắn: trạng thái kế hoạch, giám sát process, lưu bằng chứng để chạy lại được.

Mấy điểm đáng biết:

• Session-first. Mỗi worker là một session thật, có context, model và vòng đời riêng, hoặc một process headless có giám sát. Subagent lồng bên trong không được tính là worker, trừ trường hợp runtime không cho mở session vì thiếu quyền. Lúc đó skill được fallback và phải ghi rõ trong báo cáo.

• Mặc định chỉ dùng runtime đang chạy. Muốn kéo thêm runtime khác (Codex, Pi...) thì bật --cross-runtime, hoặc gọi tên runtime trong yêu cầu. Runtime được kéo vào phải qua kiểm tra thật: cài chưa, đăng nhập chưa, còn quota không, chi phí ra sao. Không qua thì job báo blocked kèm bằng chứng, chứ không âm thầm đổi sang chỗ khác.

• Chạy lại được. Mọi lần chạy có thư mục kết quả riêng, dừng giữa chừng thì --resume từ đó.

• Có trọng tài cuối. Kết quả được một "arbiter" độc lập soát lại trước khi giao.

/ak-orchestrate "research ba cách triển khai và so sánh"
/ak-orchestrate "chạy ba scout bằng pi session, rồi một arbiter"
/ak-orchestrate plans/orchestrate-jobs.yaml --cross-runtime
/ak-orchestrate --resume plans/reports/orchestrate-<timestamp>

Cái tui thích nhất: một nhạc trưởng chỉ huy được nhiều dàn nhạc. Main session là Claude Code, nhưng có job chạy bằng Codex hay Pi khi nó hợp việc đó hơn hoặc rẻ hơn.

5/ /ak-atoz: một lần nói chuyện, rồi để nó chạy xuyên đêm

Nỗi khổ quen thuộc khi giao việc dài cho agent: đi ngủ, sáng dậy thấy nó dừng từ 11 giờ tối để hỏi một câu lẽ ra tự quyết được 😩

/ak-atoz sinh ra để giải quyết đúng cái đó. Nó có 3 cửa, đi theo thứ tự:

Cửa 1: Lock, khoá phạm vi. Chạy phỏng vấn của /ak-advise, ra bản brief có Objective, Done means, Out of scope, Constraints. Bạn phải bấm Confirm rõ ràng thì mới qua cửa. Sau đó brief là hợp đồng, agent không được tự ý thu hẹp hay nới rộng.

Cửa 2: Prepare, gom hết đồ nghề một lần. Trước khi đụng vào code, nó rà brief từ đầu tới cuối rồi liệt kê mọi thứ không tự lấy được: CLI nào cần đăng nhập, biến môi trường nào phải có, quyền repo nào... Secret thì bạn bỏ vào environment hoặc vault, không dán vào chat. Mấy lựa chọn đảo ngược được thì nó tự quyết luôn và ghi lại như mặc định để bạn sửa nếu muốn. Bạn báo "đủ rồi", nó kiểm tra lại từng thứ rồi mới chạy.

Cửa 3: Execute, tự chạy tới đích. Main session thành nhạc trưởng: plan, chia việc ra sub-session theo worktree, theo dõi, nhắc session bị kẹt, kiểm tra diff thay vì tin báo cáo. Tiến độ cập nhật trên GitHub issue. Review cuối luôn chạy trong một sub-session context sạch, không để chính nhạc trưởng tự chấm bài mình.

Nó chỉ dừng lại hỏi khi gặp một trong mấy chuyện sau:

• hành động phá huỷ hoặc không đảo ngược được mà brief không nhắc tới (xoá dữ liệu, force-push, sửa dữ liệu production);

• thay đổi làm lệch một mục Done means đã chốt, hoặc đi ra ngoài phạm vi hay repo đã chốt;

• tiêu tiền hoặc gửi tin nhắn thay bạn mà brief không cho phép;

• lỗi đã chẩn đoán và hỏi cố vấn rồi mà vẫn không giải thích được.

Ngoài mấy chuyện đó, nó tự quyết và ghi lý do một dòng vào báo cáo cuối.

/ak-atoz "thêm thanh toán Polar cho trang pricing, giữ Stripe cho khách cũ"

6/ Kinh nghiệm xương máu

• Brief tốt là 80% thành công. Chạy xuyên đêm mà Done means mơ hồ thì sáng dậy bạn có một đống PR làm đúng cái bạn nói, chứ không phải cái bạn muốn.

• Canh quota. 10 sub-session chạy song song đốt usage rất nhanh. Việc máy móc giao model rẻ, việc cần thiết kế giao model mạnh, và giới hạn số session chạy cùng lúc theo usage còn lại.

• Dọn máy. Mỗi worktree có dev server, watcher riêng. Không dọn thì sáng dậy máy đầy process mồ côi, RAM cạn.

• Report không phải bằng chứng. Luôn kiểm tra diff và CI trước khi tin một sub-session báo "xong".

• Việc nhỏ thì đừng orchestrate. Sửa một dòng mà mở 3 sub-session là lấy dao mổ trâu giết gà. Tinh thần y như ở bài 12: linh hoạt.

Tóm lại

1/ Sub-session cho mỗi đầu việc có PR riêng. Subagent cho mấy mảnh nhỏ trong một việc.

2/ GitHub Issues là nguồn sự thật duy nhất: nhận việc, tiến độ, phát hiện, lịch sử.

3/ /ak-orchestrate điều phối nhiều session, kể cả runtime khác với --cross-runtime.

4/ /ak-atoz: chốt một lần, gom đồ nghề một lần, rồi chạy xuyên đêm và chỉ dừng khi thật sự cần.

Nguồn

• Mô tả và tài liệu skill ak-orchestrate (v2.0.0) và ak-atoz (v1.0.0) trong kit ak 3.0.0.

• Hướng dẫn tích hợp trong Claude Code desktop app về khi nào dùng subagent và khi nào mở session riêng (xem 11/2026).

• MindStudio: Claude Code subagents cost tokens

• MindStudio: Agent teams vs sub agents

• wmedia.es: Claude Code subagents, cheaper at low effort

• bestagent.dev: Claude Code agent teams, worth the tokens?