Git Worktrees trong Claude Code — Phát triển song song không xung đột

Khi làm việc với Claude Code trên các dự án lớn, bạn thường cần xử lý nhiều tác vụ đồng thời — sửa bug khẩn cấp trong khi đang phát triển feature mới, hoặc chạy nhiều agent Claude Code song song trên các phần khác nhau của codebase. Git worktrees giải quyết vấn đề này bằng cách cho phép bạn có nhiều working directory cùng trỏ về một repository, mỗi directory ở một branch khác nhau. Kết hợp với Claude Code, đây là workflow mạnh mẽ cho phát triển song song thực sự.

Git Worktrees là gì?

Thông thường, một Git repository có duy nhất một working directory. Khi bạn muốn chuyển sang branch khác, bạn phải dùng git checkout hoặc git switch — và toàn bộ file trong thư mục sẽ thay đổi. Điều này gây ra nhiều bất tiện:

• Phải stash hoặc commit work-in-progress trước khi chuyển branch
• Dev server phải restart vì file thay đổi
• Không thể so sánh trực tiếp giữa hai branch trong file explorer
• Không thể chạy hai instance Claude Code trên hai branch cùng lúc

Git worktrees giải quyết tất cả các vấn đề trên. Mỗi worktree là một thư mục riêng biệt trên ổ đĩa, checkout một branch cụ thể, nhưng chia sẻ chung Git history và objects với repository gốc. Bạn có thể có 5 worktree cho 5 branch khác nhau, mỗi thư mục hoạt động độc lập.

So sánh workflow truyền thống và worktree

Workflow truyền thống khi cần sửa bug khẩn cấp giữa lúc đang code feature:

# Đang code feature-x, cần sửa hotfix
git stash                          # Lưu tạm work đang làm
git checkout main                  # Chuyển về main
git checkout -b hotfix/bug-123     # Tạo branch hotfix
# ... sửa bug, commit, push ...
git checkout feature-x             # Quay lại feature
git stash pop                      # Lấy lại work đang làm
# Hy vọng stash không conflict...

Workflow với worktree:

# Đang code feature-x trong ~/project/
# Tạo worktree mới cho hotfix — không ảnh hưởng gì đến thư mục hiện tại
git worktree add ../project-hotfix hotfix/bug-123 -b
# Mở terminal mới, cd vào ../project-hotfix
# Sửa bug, commit, push
# Xong thì xóa worktree
git worktree remove ../project-hotfix

Tại sao Claude Code sử dụng worktrees?

Claude Code hỗ trợ worktrees vì nhiều lý do kỹ thuật và thực tiễn:

Cách ly hoàn toàn giữa các tác vụ

Khi Claude Code làm việc trên một worktree, mọi thay đổi file đều nằm trong thư mục của worktree đó. Nếu Claude gây lỗi hoặc thay đổi sai hướng, bạn chỉ cần xóa worktree — repository gốc không bị ảnh hưởng.

Phát triển song song với nhiều agent

Bạn có thể chạy nhiều instance Claude Code cùng lúc, mỗi instance trên một worktree riêng. Ví dụ: một Claude sửa bug, một Claude viết test, một Claude refactor. Không instance nào ảnh hưởng đến instance khác vì chúng làm việc trên các thư mục vật lý khác nhau.

Review dễ dàng hơn

Sau khi Claude hoàn thành tác vụ trên worktree, bạn có thể review toàn bộ thay đổi trước khi merge về main. Nếu không hài lòng, xóa worktree và bắt đầu lại.

Các lệnh Git Worktree cơ bản

Tạo worktree mới

# Tạo worktree từ branch đã tồn tại
git worktree add ../my-worktree existing-branch

# Tạo worktree với branch mới (dựa trên HEAD hiện tại)
git worktree add ../my-worktree -b new-branch-name

# Tạo worktree với branch mới dựa trên branch cụ thể
git worktree add ../my-worktree -b new-branch origin/main

Lưu ý quan trọng: Mỗi branch chỉ có thể được checkout trong tối đa một worktree. Nếu branch feature-x đã được checkout ở worktree A, bạn không thể tạo worktree B cũng checkout feature-x.

Liệt kê worktrees

# Xem tất cả worktree đang tồn tại
git worktree list

# Output mẫu:
# /home/user/project          abc1234 [main]
# /home/user/project-feature  def5678 [feature-auth]
# /home/user/project-hotfix   ghi9012 [hotfix/bug-456]

Xóa worktree

# Xóa worktree (sau khi đã merge hoặc không cần nữa)
git worktree remove ../my-worktree

# Force xóa (nếu có uncommitted changes)
git worktree remove --force ../my-worktree

# Dọn dẹp worktree đã bị xóa thủ công (rm -rf thay vì git worktree remove)
git worktree prune

Workflow thực tế: Claude Code với Worktrees

Dưới đây là các workflow thực tế kết hợp Claude Code và git worktrees.

Workflow 1: Feature development song song

Giả sử bạn cần phát triển 2 feature độc lập cùng lúc:

# Terminal 1: Setup worktree cho feature A
cd ~/projects/my-app
git worktree add ../my-app-feature-a -b feature/user-auth origin/main

# Mở Claude Code trong worktree feature A
cd ../my-app-feature-a
claude

# Trong Claude Code:
# "Implement JWT authentication with refresh tokens.
#  Create auth middleware, login/register endpoints,
#  and token refresh logic."

# Terminal 2: Setup worktree cho feature B
cd ~/projects/my-app
git worktree add ../my-app-feature-b -b feature/payment-integration origin/main

# Mở Claude Code trong worktree feature B
cd ../my-app-feature-b
claude

# Trong Claude Code:
# "Integrate Stripe payment processing.
#  Create checkout flow, webhook handling,
#  and subscription management."

Hai Claude Code instance chạy song song, mỗi instance trên thư mục riêng, branch riêng. Không có xung đột file, không cần stash, không cần chuyển branch.

Workflow 2: Hotfix trong khi đang develop

# Đang develop feature trên ~/projects/my-app (branch: feature/dashboard)
# Nhận báo bug production cần fix gấp

# Tạo worktree cho hotfix
git worktree add ../my-app-hotfix -b hotfix/critical-fix origin/main

# Mở Claude Code mới cho hotfix
cd ../my-app-hotfix
claude

# "Fix the null pointer exception in UserService.getProfile()
#  that occurs when user has no avatar set."

# Sau khi fix xong:
git add -A && git commit -m "fix: handle null avatar in UserService.getProfile()"
git push origin hotfix/critical-fix

# Tạo PR, merge, xong
# Quay lại feature development — không mất gì cả
cd ~/projects/my-app
# Claude Code vẫn đang chạy, work vẫn nguyên

# Dọn dẹp worktree hotfix
git worktree remove ../my-app-hotfix

Workflow 3: Multi-agent parallel development

Đây là workflow nâng cao nhất — chạy nhiều agent Claude Code đồng thời, mỗi agent phụ trách một phần của dự án.

# Tạo 3 worktrees cho 3 agent
git worktree add ../app-agent-1 -b task/api-endpoints origin/main
git worktree add ../app-agent-2 -b task/frontend-components origin/main
git worktree add ../app-agent-3 -b task/test-suite origin/main

# Agent 1: Backend API
cd ../app-agent-1 && claude
# "Create REST API endpoints for user management:
#  CRUD operations, pagination, filtering, validation."

# Agent 2: Frontend components
cd ../app-agent-2 && claude
# "Build React components for user management UI:
#  UserList, UserForm, UserProfile, with proper state management."

# Agent 3: Test suite
cd ../app-agent-3 && claude
# "Write comprehensive test suite for user management:
#  unit tests for API, integration tests, component tests."

Điểm quan trọng: Các agent phải làm việc trên các phần tách biệt của codebase. Nếu Agent 1 và Agent 2 cùng sửa file routes.ts, bạn sẽ gặp merge conflict. Hãy phân chia tác vụ sao cho overlap tối thiểu.

Merge kết quả từ nhiều worktrees

Sau khi các agent hoàn thành, bạn cần merge kết quả về branch chính. Có nhiều chiến lược merge:

Chiến lược 1: Merge tuần tự

# Merge từng branch theo thứ tự ưu tiên
git checkout main
git merge task/api-endpoints       # Merge backend trước
git merge task/frontend-components  # Merge frontend
git merge task/test-suite           # Merge tests

# Nếu có conflict, giải quyết tại mỗi bước

Chiến lược 2: Rebase trước khi merge

# Rebase mỗi branch lên main trước khi merge
# Giúp giữ history sạch

cd ../app-agent-2
git rebase main  # Rebase frontend lên main (đã có backend)
# Giải quyết conflict nếu có

cd ../app-agent-3
git rebase main  # Rebase tests
# Giải quyết conflict nếu có

# Merge vào main (fast-forward)
git checkout main
git merge task/frontend-components
git merge task/test-suite

Chiến lược 3: Dùng Claude Code để merge

# Trong main branch, yêu cầu Claude giúp merge
cd ~/projects/my-app
claude

# "I have 3 branches that need to be merged into main:
#  - task/api-endpoints (backend API)
#  - task/frontend-components (React UI)
#  - task/test-suite (tests)
#
#  Please merge them one by one, resolving any conflicts.
#  Prioritize API code over frontend when there are conflicts
#  in shared files."

Dọn dẹp worktrees

Worktrees chiếm dung lượng ổ đĩa (mỗi worktree là một bản copy đầy đủ của working directory, dù chia sẻ Git objects). Cần dọn dẹp thường xuyên:

# Xem tất cả worktree hiện có
git worktree list

# Xóa worktree đã merge xong
git worktree remove ../app-agent-1
git worktree remove ../app-agent-2
git worktree remove ../app-agent-3

# Xóa branch đã merge (nếu không cần nữa)
git branch -d task/api-endpoints
git branch -d task/frontend-components
git branch -d task/test-suite

# Dọn dẹp worktree "mồ côi" (thư mục đã bị xóa nhưng Git chưa biết)
git worktree prune

Script dọn dẹp tự động

#!/bin/bash
# cleanup-worktrees.sh
# Xóa tất cả worktree đã merge vào main

MAIN_BRANCH="main"

for worktree in $(git worktree list --porcelain | grep "^worktree " | sed 's/worktree //'); do
  branch=$(git -C "$worktree" branch --show-current 2>/dev/null)
  if [ "$branch" != "$MAIN_BRANCH" ] && [ -n "$branch" ]; then
    # Kiểm tra branch đã merge vào main chưa
    if git branch --merged "$MAIN_BRANCH" | grep -q "$branch"; then
      echo "Removing merged worktree: $worktree (branch: $branch)"
      git worktree remove "$worktree"
      git branch -d "$branch"
    else
      echo "Keeping unmerged worktree: $worktree (branch: $branch)"
    fi
  fi
done

git worktree prune
echo "Cleanup complete."

Các lỗi thường gặp và cách xử lý

Lỗi: Branch already checked out

# Lỗi: fatal: 'feature-x' is already checked out at '/path/to/worktree'
# Nguyên nhân: Mỗi branch chỉ được checkout trong 1 worktree

# Giải pháp 1: Dùng branch khác
git worktree add ../new-worktree -b feature-x-v2 feature-x

# Giải pháp 2: Xóa worktree cũ trước
git worktree remove /path/to/old-worktree

Lỗi: Worktree thư mục đã tồn tại

# Lỗi: fatal: '/path/to/worktree' already exists
# Nguyên nhân: Thư mục đã tồn tại (có thể từ lần trước chưa dọn)

# Giải pháp: Dọn dẹp và thử lại
git worktree prune
rm -rf /path/to/worktree  # Cẩn thận, chỉ xóa nếu chắc chắn
git worktree add /path/to/worktree branch-name

Lỗi: node_modules và dependencies

# Mỗi worktree cần install dependencies riêng
# vì node_modules nằm trong working directory, không chia sẻ

cd ../my-worktree
npm install  # hoặc yarn install, pnpm install

# Mẹo: Dùng pnpm với shared store để tiết kiệm ổ đĩa
# pnpm dùng hard link nên không duplicate packages

Quy ước đặt tên worktree

Để quản lý nhiều worktree hiệu quả, nên có quy ước đặt tên rõ ràng:

# Quy ước: {project}-{purpose}
# Ví dụ:
git worktree add ../myapp-feature-auth -b feature/auth
git worktree add ../myapp-hotfix-login -b hotfix/login-crash
git worktree add ../myapp-experiment-new-ui -b experiment/new-ui
git worktree add ../myapp-agent-backend -b task/agent-backend

Worktrees kết hợp với Claude Code Hooks

Nếu bạn đã cấu hình hooks trong .claude/settings.json (xem bài viết về Claude Code Hooks), hooks sẽ tự động hoạt động trong worktree vì file settings.json nằm trong repository và được chia sẻ giữa tất cả worktrees. Điều này cực kỳ tiện lợi — mọi worktree đều có cùng auto-format, lint, test pipeline.

Cấu hình đặc biệt cho multi-agent workflow

# Tạo script khởi tạo worktree tự động
# File: scripts/create-agent-worktree.sh

#!/bin/bash
TASK_NAME=$1
BASE_BRANCH=${2:-main}

if [ -z "$TASK_NAME" ]; then
  echo "Usage: ./create-agent-worktree.sh  [base-branch]"
  exit 1
fi

WORKTREE_DIR="../$(basename $(pwd))-$TASK_NAME"
BRANCH_NAME="task/$TASK_NAME"

# Tạo worktree
git worktree add "$WORKTREE_DIR" -b "$BRANCH_NAME" "$BASE_BRANCH"

# Install dependencies
cd "$WORKTREE_DIR"
if [ -f "package.json" ]; then
  npm install --silent
fi

echo "Worktree created at: $WORKTREE_DIR"
echo "Branch: $BRANCH_NAME"
echo "Ready to run: cd $WORKTREE_DIR && claude"

Worktrees trong thực tế: Case study

Dưới đây là một kịch bản thực tế minh họa sức mạnh của worktrees với Claude Code.

Kịch bản: Refactor module authentication trong 1 ngày

Bạn cần refactor toàn bộ module authentication — từ session-based sang JWT. Tác vụ này bao gồm thay đổi backend API, update frontend, viết test, và cập nhật tài liệu. Nếu làm tuần tự, cần 2-3 ngày. Với worktrees và multi-agent:

# Bước 1: Tạo 4 worktrees song song
git worktree add ../app-auth-api -b refactor/auth-api main
git worktree add ../app-auth-frontend -b refactor/auth-frontend main
git worktree add ../app-auth-tests -b refactor/auth-tests main
git worktree add ../app-auth-docs -b refactor/auth-docs main

# Bước 2: Khởi chạy 4 agent Claude Code đồng thời

# Agent 1 — Backend API (Terminal 1)
cd ../app-auth-api && claude
# Prompt: "Refactor authentication from session-based to JWT.
#  Update all auth endpoints, middleware, and database schema.
#  Keep backward compatibility during migration."

# Agent 2 — Frontend (Terminal 2)
cd ../app-auth-frontend && claude
# Prompt: "Update all frontend authentication logic to use JWT.
#  Implement token storage, refresh logic, and update API calls.
#  Handle auth state in React context."

# Agent 3 — Tests (Terminal 3)
cd ../app-auth-tests && claude
# Prompt: "Write comprehensive test suite for JWT authentication.
#  Cover: login, register, refresh token, expired token,
#  invalid token, role-based access."

# Agent 4 — Documentation (Terminal 4)
cd ../app-auth-docs && claude
# Prompt: "Update API documentation for new JWT authentication.
#  Include: endpoint changes, request/response examples,
#  migration guide for existing clients."

# Bước 3: Merge theo thứ tự (sau khi tất cả agent hoàn thành)
git checkout main
git merge refactor/auth-api          # Backend trước
git merge refactor/auth-frontend     # Frontend cần backend
git merge refactor/auth-tests        # Tests cần cả hai
git merge refactor/auth-docs         # Docs cuối cùng

# Bước 4: Dọn dẹp
git worktree remove ../app-auth-api
git worktree remove ../app-auth-frontend
git worktree remove ../app-auth-tests
git worktree remove ../app-auth-docs

Kết quả: Tác vụ 2-3 ngày rút xuống còn vài giờ. Mỗi agent tập trung vào phần việc riêng, không cản trở nhau.

Khi nào nên và không nên dùng worktrees

Worktrees mạnh mẽ nhưng không phải lúc nào cũng cần thiết:

Nên dùng khi

• Cần làm việc song song trên nhiều branch (feature + hotfix)
• Chạy nhiều instance Claude Code đồng thời trên cùng repo
• Cần so sánh code giữa hai branch bằng file explorer
• Muốn cách ly hoàn toàn work của Claude Code khỏi branch chính
• CI/CD pipeline cần build nhiều branch đồng thời
• Tác vụ refactor lớn cần chia thành nhiều phần độc lập

Không cần dùng khi

• Chỉ làm việc trên một tác vụ tại một thời điểm
• Dự án nhỏ, chuyển branch nhanh và không có work-in-progress
• Ổ đĩa hạn chế — mỗi worktree chiếm dung lượng working directory
• Tác vụ đơn giản mà git stash đã đủ
• Các tác vụ phụ thuộc lẫn nhau chặt chẽ — merge sẽ conflict nhiều

Mẹo thực hành

• Giới hạn số worktree: Tối đa 3-5 worktree cùng lúc. Nhiều hơn sẽ khó quản lý và tốn tài nguyên
• Dùng tmux hoặc terminal tabs: Mỗi worktree một tab, đặt tên tab theo tác vụ để dễ theo dõi
• Commit thường xuyên trong worktree: Nhắc Claude commit theo từng milestone nhỏ, không đợi hoàn thành toàn bộ
• Review trước khi merge: Dùng git diff main..task-branch để review toàn bộ thay đổi trước khi merge
• Shared CLAUDE.md: Đặt hướng dẫn chung trong CLAUDE.md ở root repo — tất cả worktree đều thấy file này

Bước tiếp theo

Git worktrees kết hợp với Claude Code tạo nên workflow phát triển song song hiệu quả — đặc biệt khi bạn muốn tận dụng tối đa khả năng của AI agent bằng cách chạy nhiều instance đồng thời. Bắt đầu bằng việc thử tạo một worktree cho hotfix tiếp theo, trải nghiệm cảm giác không phải stash và chuyển branch. Khi đã quen, thử workflow multi-agent với 2-3 worktree song song. Tìm hiểu thêm các kỹ thuật nâng cao tại Thư viện Nâng cao Claude.