Claude Code + Git Worktrees: Chạy Song Song Nhiều AI Agent Không Lo Xung Đột

Bạn đang build tính năng thanh toán mới. Đột nhiên Slack nổ: bug nghiêm trọng trên production, cần fix ngay. Bạn phải dừng lại, stash code, checkout branch khác, fix, rồi quay lại. Mất đứt 20 phút chỉ để chuyển context.

Với Claude Code và git worktrees, bạn không cần chọn. Bạn chạy cả hai cùng lúc — hai agent, hai branch, không đụng vào file của nhau.

Vấn Đề: Một Working Directory, Nhiều Việc Cần Làm

Khi bạn chạy hai instance Claude Code trên cùng một thư mục, chúng dùng chung file system. Agent A đang sửa src/auth/login.ts, agent B cũng muốn đọc file đó. Kết quả là conflict, file bị ghi đè, hoặc tệ hơn — agent làm việc dựa trên code đã bị thay đổi bởi agent kia mà không biết.

Đây không phải lỗi của Claude Code. Đây là giới hạn của git: mỗi working directory chỉ có thể checkout một branch tại một thời điểm.

Git worktrees giải quyết đúng vấn đề này.

Git Worktrees Là Gì?

Git worktrees cho phép bạn checkout nhiều branch cùng lúc trong các thư mục riêng biệt — nhưng tất cả đều chia sẻ chung một .git repository. Không phải clone mới, không tốn thêm disk space cho history.

PaymentAPI/                        ← worktree chính (branch: main)
PaymentAPI-feature-checkout/       ← worktree 2 (branch: feature/checkout)
PaymentAPI-fix-auth/               ← worktree 3 (branch: fix/auth-token)

Ba thư mục. Ba branch. Một .git. Mỗi thư mục hoàn toàn độc lập với nhau — bạn có thể chạy Claude Code trong từng cái mà không sợ xung đột.

Claude Code Hỗ Trợ Worktrees Thế Nào

Claude Code có tích hợp native support cho git worktrees. Khi bạn dùng lệnh EnterWorktree trong session, Claude Code tự động:

Tạo worktree mới trong .claude/worktrees/
Tạo branch mới từ HEAD hiện tại
Chuyển session sang thư mục worktree đó

Khi session kết thúc, Claude Code hỏi bạn có muốn giữ lại hay xóa worktree đi. Không cần dọn tay.

Cách 1: Dùng Worktree Tích Hợp Của Claude Code

Đây là cách đơn giản nhất. Bắt đầu session Claude Code bình thường, rồi nói với agent:

Bạn: "Tạo một worktree để làm feature checkout. Đừng đụng vào branch main."

Claude Code sẽ tạo worktree, tạo branch, và làm việc trong đó. Bạn mở terminal thứ hai, chạy Claude Code trong thư mục gốc để xử lý việc khác song song.

Cách này phù hợp khi bạn muốn Claude Code tự quản lý lifecycle của worktree.

Cách 2: Tạo Worktrees Thủ Công + Nhiều Claude Session

Cách này cho bạn kiểm soát nhiều hơn. Phù hợp khi bạn muốn tự quyết định tên branch, thư mục, và workflow.

Bước 1: Tạo các worktrees

# Từ thư mục project gốc
git worktree add ../PaymentAPI-feature-checkout -b feature/checkout
git worktree add ../PaymentAPI-fix-auth -b fix/auth-token

Expected output:

Preparing worktree (new branch 'feature/checkout')
HEAD is now at a3f1c2d Add payment gateway integration

Preparing worktree (new branch 'fix/auth-token')
HEAD is now at a3f1c2d Add payment gateway integration

Bước 2: Kiểm tra danh sách worktrees

git worktree list

/home/user/PaymentAPI                    a3f1c2d [main]
/home/user/PaymentAPI-feature-checkout   a3f1c2d [feature/checkout]
/home/user/PaymentAPI-fix-auth           a3f1c2d [fix/auth-token]

Bước 3: Mở Claude Code trong từng worktree

Terminal 1:

cd ../PaymentAPI-feature-checkout
claude

Terminal 2:

cd ../PaymentAPI-fix-auth
claude

Bây giờ bạn có hai agent chạy song song, mỗi cái trên branch riêng, không đụng vào nhau.

Ví Dụ Thực Tế: Build Hai Feature Cùng Lúc

Giả sử bạn đang làm một SocialApp với hai việc cần xong trong ngày: tính năng follow user và fix bug notification không hiển thị.

Thiết lập:

git worktree add ../SocialApp-feature-follow -b feature/follow-system
git worktree add ../SocialApp-fix-notif -b fix/notification-display

Terminal 1 — Feature follow:

cd ../SocialApp-feature-follow
npm install
claude

Prompt cho agent 1:

Build tính năng follow/unfollow user. Schema database đã có trong prisma/schema.prisma.
Cần: API endpoints, service layer, và unit tests. Không sửa gì ngoài phạm vi này.

Terminal 2 — Fix notification:

cd ../SocialApp-fix-notif
npm install
claude

Prompt cho agent 2:

Fix bug: notification không hiển thị sau khi user login lại.
Bắt đầu từ src/notifications/NotificationService.ts.
Reproduce bug trước, rồi mới fix.

Hai agent chạy song song. Bạn có thể theo dõi cả hai, trả lời câu hỏi khi cần, hoặc làm việc khác trong khi chờ. Không có gì block nhau.

Khi xong, merge vào main:

git checkout main
git merge feature/follow-system
git merge fix/notification-display

Dọn dẹp:

git worktree remove ../SocialApp-feature-follow
git worktree remove ../SocialApp-fix-notif

Khi Nào Dùng Worktrees vs. Session Đơn

Tình huống	Dùng gì
Một task, không cần song song	Session đơn trong thư mục gốc
Fix bug khẩn trong khi đang build feature	Worktree
Review PR của đồng nghiệp mà không stash code	Worktree
Build hai module độc lập cùng lúc	Worktree
Experiment mà không muốn ảnh hưởng main	Worktree
Tasks có nhiều file chung, cần đồng bộ liên tục	Session đơn (tránh conflict phức tạp)

Rule of thumb: nếu hai task có thể làm độc lập và merge cuối, dùng worktrees. Nếu chúng phụ thuộc vào nhau chặt chẽ, làm tuần tự trong một session sẽ an toàn hơn.

Tips Và Lưu Ý Quan Trọng

Không checkout cùng một branch trong hai worktree. Git không cho phép điều này. Mỗi branch chỉ được checkout ở một nơi tại một thời điểm.

# Lỗi: branch 'feature/checkout' đã được checkout ở worktree khác
git worktree add ../another -b feature/checkout  # ❌ sẽ báo lỗi

Mỗi worktree cần install dependencies riêng. node_modules không được chia sẻ giữa các worktrees.

cd ../PaymentAPI-feature-checkout
npm install  # Phải chạy riêng trong mỗi worktree

Worktrees rẻ hơn clone rất nhiều. Git objects (history, blobs) được chia sẻ. Bạn chỉ tốn thêm disk space cho working files, không phải toàn bộ repository.

Dùng tên thư mục có ý nghĩa. PaymentAPI-feature-checkout rõ ràng hơn PaymentAPI-2. Khi có nhiều worktrees, tên tốt giúp bạn không bị nhầm.

Claude Code tự dọn worktree khi dùng EnterWorktree. Nếu bạn tạo worktree thủ công, nhớ dọn thủ công:

git worktree remove ../PaymentAPI-feature-checkout
# Hoặc nếu có untracked changes:
git worktree remove --force ../PaymentAPI-feature-checkout

Kiểm tra worktrees còn sót:

git worktree prune  # Xóa entries của worktrees đã bị xóa thư mục
git worktree list   # Xem tất cả worktrees hiện tại

Kết: Biến Thời Gian Tuyến Tính Thành Song Song

Trước đây, làm hai việc cùng lúc có nghĩa là context switch liên tục — stash, checkout, làm, checkout lại, unstash. Mỗi lần tốn 5-10 phút và làm đứt mạch tư duy.

Git worktrees thay đổi điều đó. Bạn tạo môi trường riêng cho mỗi task, chạy Claude Code độc lập trong từng cái, và để các agent làm việc song song trong khi bạn focus vào những gì quan trọng hơn.

Không phải mọi task đều cần worktrees. Nhưng khi bạn có hai việc thực sự độc lập — một feature mới và một hotfix, hai module riêng biệt, một experiment và một refactor — worktrees là công cụ đúng đắn.

Thử ngay với project hiện tại của bạn:

git worktree add ../my-project-experiment -b experiment/new-approach
cd ../my-project-experiment
claude

Bạn sẽ ngạc nhiên vì sao mình không dùng cái này sớm hơn.