Chạy nhiều phiên Claude Code song song bằng git worktree mà không đè code nhau

Mở hai terminal chạy hai phiên Claude Code trên cùng thư mục là cách nhanh nhất để… hỏng cả hai: phiên A đang sửa auth.ts thì phiên B format lại file đó, test chạy trên trạng thái nửa vời, commit lẫn lộn. Giải pháp chuẩn là git worktree: mỗi phiên có một bản checkout riêng, nhánh riêng, nhưng chung lịch sử repo. Claude Code hỗ trợ sẵn bằng cờ --worktree, tự tạo, tự dọn và còn chặn phiên lỡ tay sửa vào bản chính. Bài này hướng dẫn quy trình làm việc song song an toàn.

Bắt đầu: một lệnh cho mỗi phiên

# terminal 1
claude --worktree feature-auth
# terminal 2
claude -w fix-billing-bug

• Worktree được tạo trong .claude/worktrees/<tên>/, trên nhánh mới worktree-<tên>.
• Bỏ trống tên thì Claude tự đặt (kiểu bright-running-fox).
• Repo phải có ít nhất một commit; nên thêm .claude/worktrees/ vào .gitignore.
• Muốn làm việc trên một PR: claude --worktree "#1234" sẽ fetch PR đó về worktree pr-1234.

Chuẩn bị môi trường cho worktree

Worktree là bản checkout "sạch", nên thiếu node_modules và các file bị gitignore như .env. Hai việc cần làm:

1. Nhờ Claude cài dependency ngay đầu phiên (hoặc tự chạy trong thư mục worktree).
2. Tạo file .worktreeinclude ở gốc repo, cú pháp giống .gitignore, liệt kê các file bị ignore cần copy sang mỗi worktree mới:

.env
.env.local
config/secrets.json

Chỉ file vừa khớp pattern vừa bị gitignore mới được copy, nên file đã track không bị nhân đôi.

Nhánh gốc: fresh hay head?

Dọn dẹp khi thoát

• Worktree sạch (không thay đổi, không commit mới) của phiên không đặt tên: tự xoá cả thư mục lẫn nhánh.
• Có thay đổi hoặc commit: Claude hỏi giữ hay xoá. Giữ thì lần sau quay lại bằng lệnh claude --worktree <tên> --resume được in ra khi thoát.
• Chạy -p (không tương tác) thì không có bước hỏi, nên phải tự dọn bằng git worktree remove.

Subagent mỗi con một worktree

Với việc sửa hàng loạt file, cho subagent chạy trong worktree riêng để các chỉnh sửa song song không đè nhau. Thêm isolation: worktree vào frontmatter của subagent:

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---
Apply the requested refactor, run the tests and report results.

Worktree của subagent tự xoá nếu không có thay đổi; có thay đổi thì được giữ đến khi dọn an toàn.

Claude Code bảo vệ bạn thế nào?

Khi phiên đang ở trong worktree, Claude Code chặn các thao tác edit nhắm vào bản chính, lệnh chạy với thư mục làm việc là bản chính, và lệnh git bị "chuyển hướng" về bản chính (git -C, GIT_DIR…). Lưu ý: lệnh shell ghi file trực tiếp (như cp) không bị các kiểm tra này chặn, mà vẫn đi theo quyền và sandbox thông thường.

Rủi ro và lưu ý

• Mỗi worktree là một bản code đầy đủ: cài dependency nhiều lần tốn đĩa và thời gian.
• Hai phiên sửa cùng vùng code vẫn sẽ xung đột khi merge; worktree chỉ tránh đè nhau lúc đang làm.
• Repo dùng Git LFS cài kiểu --local: worktree chứa file pointer, cần git lfs pull.
• Nhiều phiên song song = nhiều token song song; theo dõi hạn mức.

Áp dụng thế nào?

• Dev: Một tính năng dài ở terminal 1, các bug nhỏ ở terminal 2 bằng -w. Tạo .worktreeinclude ngay hôm nay.
• Tech Lead: Chuẩn hoá tên worktree theo ticket (-w JIRA-123), quy định mỗi worktree một PR nhỏ để review dễ.
• PM: Chia backlog thành các task độc lập về file. Task càng ít đụng nhau thì càng chạy song song được nhiều.