Cách chạy song song nhiều Claude Code Agent

TL;DR: Để chạy song song nhiều agent Claude Code, hãy cấp cho mỗi phiên làm việc một git worktree riêng (chỉ cần một cờ claude -w <name> là xong), đưa các phiên bạn không theo dõi trực tiếp xuống chạy ngầm bằng claude --bg, và xác định thứ tự merge trước khi các agent hoàn thành công việc, bởi các nhánh độc lập vẫn có thể xung đột khi gộp lại. Khi hai phiên dùng chung một checkout, commit của agent này rất dễ gom nhầm code dở dang của agent kia. Hướng dẫn này dành cho các lập trình viên đang dùng Claude Code và muốn chạy cùng lúc từ 2 đến 5 phiên làm việc.

Mọi chuyện bắt đầu từ một cửa sổ terminal thứ hai. Claude Code đang tái cấu trúc module xác thực (auth) ở terminal thứ nhất, nên bạn mở thêm một terminal nữa và yêu cầu phiên mới sửa một bài test ngày tháng chập chờn (flaky date test). Rồi bạn mở tiếp terminal thứ ba để viết tài liệu. Hai mươi phút sau, cả ba phiên cùng ghi vào một thư mục làm việc, git status liệt kê hàng loạt file mà bạn không nhớ mình từng yêu cầu sửa, và chẳng ai biết phiên nào đã đụng vào config.ts.

Chạy nhiều agent Claude Code cùng lúc thì quá dễ: chỉ cần mở thêm terminal. Nhưng để chạy mà các phiên không làm hỏng thành quả của nhau thì cần đưa ra ba quyết định: file của từng phiên nằm ở đâu, bạn theo dõi các phiên chạy ngầm như thế nào, và các nhánh sẽ được merge theo thứ tự nào. Bài viết này sẽ giải quyết cả ba vấn đề bằng các lệnh tích hợp sẵn của Claude Code và phân tích hai lỗi điển hình mà chúng tôi đã tái hiện trên một repo thử nghiệm. Nếu chưa quen với worktree, bạn nên đọc trước hướng dẫn về git worktree cho AI coding agent hoặc xem tài liệu tham khảo về git worktree.

Vì sao chạy nhiều Claude Code agent trên cùng một checkout lại gây lỗi

Chạy song song nhiều agent Claude Code tức là có từ hai phiên trở lên cùng làm việc trên một repository tại một thời điểm, mỗi phiên đảm nhận một nhiệm vụ riêng và có context window riêng biệt. Các phiên làm việc này không hề biết đến sự tồn tại của nhau. Mỗi phiên đều đọc file, chỉnh sửa, chạy test và commit như thể nó đang làm việc một mình.

Một checkout chỉ có một working directory, một index và một HEAD, nên giả định "làm việc một mình" sẽ nhanh chóng đổ bể. Chúng tôi đã tái hiện trường hợp phổ biến nhất trên một repo Python mẫu, dùng hai script ghi shell đóng vai hai agent. Agent B lưu hàm truncate() đang viết dở vào textutils.py. Trong khi đó, Agent A hoàn thành tác vụ của mình ở một file khác và thực hiện commit theo cách mà nhiều câu prompt thường bảo: git add -A && git commit:

$ git show --stat --format='%an: %s' HEAD
agent-a: add slugify
 slug.py      | 2 ++
 textutils.py | 4 ++++
 2 files changed, 6 insertions(+)

$ python3 -m pytest -q
1 error in 0.09s

Commit của agent A đã kéo theo cả hàm đang viết dở của agent B, khiến bộ test không thể import được nữa. Không có file nào bị ghi đè cả. Vấn đề nằm ở chỗ index bị dùng chung, nên commit của A đã vô tình gom luôn phần việc dang dở của B, và lịch sử git giờ đây ghi nhận rằng chính agent A đã viết ra đoạn code lỗi đó. Tình huống tương tự xảy ra trên cùng một file được phân tích chi tiết trong bài điều gì xảy ra khi hai coding agent cùng chỉnh sửa một file.

Chạy song song nhiều Claude Code agent bằng cách cấp riêng một worktree cho mỗi phiên

Giải pháp ở đây là mỗi phiên làm việc phải có một working directory riêng, và Claude Code đã hỗ trợ sẵn điều này qua một tùy chọn dòng lệnh:

# interactive sessions, one task each, each in its own worktree
claude -w auth-refactor
claude -w flaky-date-test --tmux   # opens the session in its own tmux or iTerm2 pane

# fire-and-forget work: starts in the background and prints an id
claude --bg "update the README examples for the new config format"

Theo tài liệu về worktree, lệnh claude -w <name> sẽ tạo một worktree tại .claude/worktrees/<name>/ trên một nhánh mới có tên worktree-<name>, và khi mở terminal thứ hai với một tên khác, bạn sẽ có ngay một phiên làm việc độc lập thứ hai. Khi chạy thử, chúng tôi thấy git đánh dấu worktree mới là locked, giúp ngăn git worktree prune vô tình xóa nó trong lúc phiên làm việc đang chạy. Theo trang tài liệu về agent view, các phiên chạy ngầm được khởi động bằng --bg hoặc /bg cũng sẽ tự động chuyển vào worktree riêng dưới thư mục .claude/worktrees/ trước khi thực hiện bất kỳ chỉnh sửa nào.

Có ba lưu ý thiết lập quan trọng giúp bạn tránh mất hàng giờ gỡ lỗi:

1. Bỏ qua thư mục worktree. Các worktree nằm ngay bên trong repo, nên lệnh git status ở checkout chính sẽ hiển thị .claude/ là untracked cho đến khi bạn thêm .claude/worktrees/ vào .gitignore, đây cũng là điều tài liệu chính thức khuyến nghị.
2. Chuẩn bị cho một checkout hoàn toàn mới. Một worktree mới sẽ không có sẵn node_modules, virtualenv hay file .env. Hãy liệt kê các file bị gitignore mà bạn cần sao chép (như .env) vào file .worktreeinclude, đồng thời tính trước thời gian chạy cài đặt dependencies cho từng worktree.
3. Tự dọn dẹp các phiên chạy không giao diện (headless). Các phiên tương tác thường sẽ hỏi bạn có muốn xóa worktree khi thoát hay không. Tuy nhiên, các tiến trình chạy bằng claude -p không bao giờ tự dọn dẹp, vì vậy bạn cần chủ động xóa chúng bằng lệnh git worktree unlock rồi git worktree remove.

Các phiên chạy ngầm được quản lý trực tiếp từ shell. Những mô tả dưới đây được trích từ lệnh claude --help trên phiên bản 2.1.283:

Bạn không thể kết hợp --bg với -p. Để tự động hóa việc mở rộng nhiều tiến trình thông qua script, hướng dẫn sử dụng Claude Code hiệu quả của Anthropic đề xuất dùng vòng lặp shell gọi claude -p kèm cờ --allowedTools và --permission-mode dontAsk. Hãy kết hợp thêm cờ -w để mỗi tiến trình chạy trong một thư mục riêng biệt.

Các agent Claude Code dù chạy độc lập vẫn có thể xung đột khi merge

Worktree giúp các phiên làm việc không giẫm chân lên nhau trong lúc thực thi, nhưng không đảm bảo kết quả code của chúng sẽ tương thích với nhau. Chúng tôi đã thử cho hai nhánh worktree thực hiện cùng một kiểu thay đổi: mỗi bên thêm một hàm vào cuối file textutils.py, sau đó lần lượt merge cả hai vào:

$ git merge agent/slugify
Fast-forward
$ git merge agent/truncate
Auto-merging textutils.py
CONFLICT (content): Merge conflict in textutils.py
Automatic merge failed; fix conflicts and then commit the result.

Không có agent nào làm sai cả. Cả hai đều thêm code vào cùng một vị trí và git không thể tự quyết định thứ tự ưu tiên. Trên một codebase thực tế khi chạy 4 hay 5 phiên, xung đột là chuyện thường tình đối với bất kỳ file nào mà tác vụ nào cũng cần đụng tới: route table, file export __init__.py, changelog, lockfile. Điểm khác biệt so với khi dùng chung một checkout là giờ đây xung đột hiện ra rõ ràng, tức thì và xác định được chính xác nguồn gốc. Ba thói quen sau sẽ giúp bạn hạn chế tối đa vấn đề này:

1. Chia việc theo file, thay vì chia theo tính năng. Nếu hai tác vụ đều cần chỉnh sửa file router, hãy gộp chúng thành một tác vụ duy nhất, hoặc chạy tác vụ này xong rồi mới chạy tiếp tác vụ kia.
2. Merge theo thứ tự cố định và rebase các nhánh còn lại. Hãy hoàn tất việc merge nhánh đầu tiên, sau đó yêu cầu phiên tiếp theo rebase theo main và chạy lại bộ test trước khi bạn review. Chính phiên agent vừa viết đoạn code đó mới có đủ ngữ cảnh để tự giải quyết xung đột của mình.
3. Đặt tên worktree theo đúng tên nhiệm vụ. Một cái tên rõ ràng như claude -w fix-date-test sẽ hữu ích hơn nhiều so với claude -w agent2 khi bạn nhìn lại danh sách git worktree list sau một tiếng làm việc.

Rào cản lớn nhất thường không nằm ở git, mà nằm ở việc chính bạn phải đọc và duyệt 5 bản diff cùng một lúc. Bài viết của chúng tôi về lý do việc con người review là nút thắt cổ chai khi chạy song song nhiều agent sẽ giúp bạn tính toán khối lượng hàng đợi này một cách hợp lý.

Nên chọn Subagent, Agent Team hay Phiên riêng biệt khi chạy nhiều Claude Code agent?

Claude Code hiện cung cấp nhiều cơ chế để chạy song song các tác vụ, và tài liệu tổng quan về parallel agent đã đặt chúng cạnh nhau để so sánh. Chúng không thể thay thế cho nhau một cách tùy tiện, và yếu tố quan trọng nhất cần cân nhắc chính là mức độ cô lập (isolation):

Với các tác vụ độc lập, hãy sử dụng các phiên riêng biệt kết hợp với worktree. Hãy dùng agent team khi các phần việc phụ thuộc lẫn nhau và các thành viên cần trao đổi, đồng thời nhớ phân công cho mỗi thành viên những file khác nhau, vì tài liệu về agent team đã cảnh báo rất rõ ràng: “Hai đồng đội cùng chỉnh sửa một file chắc chắn sẽ dẫn đến việc ghi đè lên nhau.” Dù chọn phương án nào, hạn mức sử dụng (quota) vẫn được dùng chung. Tài liệu về agent view đã nêu ngắn gọn: “chạy mười agent song song sẽ tiêu hao quota nhanh gấp mười lần so với chạy một agent.”

Sharkly đóng vai trò gì khi bạn chạy nhiều Claude Code agent

Nếu bạn chỉ chạy 2 hoặc 3 phiên làm việc trên máy tính cá nhân và tự mình review từng bản diff, những câu lệnh kể trên là hoàn toàn đủ và bạn có thể chưa cần đến Sharkly. Nhưng bài toán sẽ rất khác khi các phiên làm việc đó thuộc về nhiều người trong nhóm, hoặc khi thời gian trả lời câu hỏi “phiên nào đang giữ bản sửa lỗi date-test?” còn lâu hơn cả thời gian agent viết xong bản vá đó.

Bạn đã có sẵn các coding agent; Sharkly sẽ kết nối chúng lại thành một đội ngũ ăn ý. Mỗi phần công việc trở thành một Task. Bạn chỉ định Task đó cho một Agent chạy trên Claude Code Runtime tại một trong những Máy tính của mình, và khi gán Assignee, tiến trình sẽ tự động kích hoạt. Với tùy chọn thư mục làm việc mặc định, Create temporary directory, mỗi Task sẽ được cấp một thư mục riêng và các lần chạy gắn với repository sẽ có một git worktree hoàn toàn cô lập: cơ chế cô lập giống hệt claude -w mà không ai phải tự tay đặt tên worktree. Khi một Agent cần tái sử dụng môi trường đã có sẵn trên Máy tính cục bộ, tùy chọn Run in isolated worktrees sẽ trả kết quả của từng Task về nhánh riêng dạng agent/<agent>/<task>. Thiết lập Max concurrency (assigned tasks) trên Agent sẽ giới hạn số tiến trình chạy đồng thời — đây chính là giới hạn review vừa đề cập ở trên, được hiển thị minh bạch cho cả đội ngũ cùng theo dõi.

Tiến độ, lịch sử thực thi và kết quả cuối cùng đều được cập nhật trở lại Task, còn bất cứ vấn đề nào cần con người can thiệp sẽ xuất hiện ngay trong Inbox. Sẽ không có chuyện tự động merge bừa bãi: con người sẽ review các thay đổi trên worktree, lựa chọn giữ lại, merge hay hủy bỏ, rồi chuyển trạng thái Task sang Done. Chi phí thực thi vẫn được tính vào gói Claude Code của bạn vì Sharkly không bán token. Trang tính năng Agents sẽ hướng dẫn cách thiết lập cụ thể, và bài viết cách Sharkly vận hành các agent song song sẽ đi sâu hơn vào khía cạnh thực thi.

Khi nhu cầu của bạn đã vượt quá con số 3 terminal và bạn muốn toàn bộ kết quả từ các phiên Claude Code được tập hợp về một nơi duy nhất để người kiểm duyệt dễ dàng thao tác, đó chính là bài toán mà Sharkly được sinh ra để giải quyết.

Câu hỏi thường gặp (FAQ)

Tôi có thể chạy tối đa bao nhiêu agent Claude Code cùng lúc? Tài liệu chính thức không giới hạn số lượng các phiên riêng biệt. Với subagent, con số mặc định chạy đồng thời là 20, còn trang hướng dẫn agent team gợi ý nên bắt đầu với khoảng 3 đến 5 đồng đội. Giới hạn thực tế nằm ở quota của gói dịch vụ bạn đăng ký, CPU và RAM của máy tính, cũng như số lượng kết quả mà bạn có thể review trong một ngày; bạn rất nên cân nhắc bài toán năng lực review trước khi quyết định mở đến phiên làm việc thứ sáu.

Các phiên Claude Code chạy song song có dùng chung hạn mức không? Có. Trên các gói Pro và Max, hạn mức sử dụng được chia sẻ chung giữa Claude và Claude Code, tính theo khung cửa sổ 5 giờ và giới hạn tuần; mọi phiên chạy song song đều trừ vào cùng một quỹ hạn mức này. Nếu bạn thiết lập biến môi trường ANTHROPIC_API_KEY, Claude Code sẽ tính phí trực tiếp qua API thay thế.

Cờ claude --worktree có sao chép file .env và các thư viện phụ thuộc sang không? Không. Mỗi worktree là một checkout hoàn toàn mới. Bạn cần đưa các file bị gitignore mà mình cần (như .env) vào .worktreeinclude và chạy bước cài đặt dependencies trong từng worktree.

Tôi có thể chạy song song cả Claude Code lẫn Codex trên cùng một repo không? Hoàn toàn được, chỉ cần tuân thủ đúng nguyên tắc: mỗi phiên dùng một worktree riêng và xác định trước thứ tự merge. Bài viết hướng dẫn chạy song song Claude Code và Codex trên cùng một codebase của chúng tôi sẽ hướng dẫn chi tiết cách điều phối công việc giữa hai bên.