Cách sử dụng Git Worktrees với AI Coding Agent

Chỉ cần trỏ hai AI coding agent vào cùng một checkout, thể nào cũng có một buổi chiều bị phá hỏng. Agent này viết lại một file mà agent kia đang chỉnh dở. Agent này đổi branch ngay dưới chân agent kia. Cả hai cùng chạy npm install trên cùng một node_modules và để lại một lockfile chẳng ai viết. Lỗi cứ âm thầm cho đến khi nó bùng nổ, và lúc đó bạn phải bisect một mớ hỗn độn mà không agent nào giải thích nổi.

Git worktree là cách khắc phục tiêu chuẩn. Một worktree cấp cho mỗi agent thư mục làm việc riêng và branch được checkout riêng, tất cả dựa trên một repository dùng chung, nhờ đó công việc song song không còn đụng nhau. Hướng dẫn này đi qua các lệnh thực tế, những cạm bẫy thực sự gây đau đầu khi dùng, và kỷ luật dọn dẹp mà chẳng ai nói với bạn. Sau đó, bài viết chỉ ra lúc nào những script worktree tự viết tay bắt đầu hết đất dụng võ, và cách Sharkly tự động chạy mỗi Task trong worktree riêng để kết quả quay về một bản ghi chung thay vì tản mát khắp các terminal.

Nếu bạn chỉ chạy một agent, bạn chưa cần những thứ này. Nhưng ngay khi chạy hai agent, cách ly không còn là tùy chọn nữa.

TL;DR

Git worktree là một thư mục làm việc thứ hai gắn với cùng một repository, có branch và index riêng. Cấp cho mỗi AI coding agent một worktree riêng, chúng có thể chỉnh sửa, build và test song song mà không ghi đè lên nhau hay tranh nhau branch hiện tại. Các lệnh thì đơn giản; thứ tăng lên chính là chi phí vận hành (cài đặt cho từng worktree, dọn dẹp, dung lượng đĩa, phối hợp). Sharkly xử lý chi phí đó bằng cách tự động chuẩn bị một worktree cách ly cho mỗi Task và trả từng kết quả về Task để review.

Vì sao một checkout không thể chứa hai agent

Một git checkout thông thường chỉ có đúng một thư mục làm việc, một index và một HEAD. Điều đó ổn với một người làm một việc. Nhưng nó sụp đổ ngay khi hai agent cùng làm việc, bởi cả ba thứ đó đều là trạng thái chia sẻ.

Hãy hình dung hai agent trên cùng một repo. Agent A đang refactor module auth trên branch tên auth-refactor. Agent B được giao sửa một bug logging và chạy git checkout -b fix-logging. Chỉ một lệnh đó đã di chuyển HEAD cho toàn bộ checkout. Những thay đổi chưa commit của Agent A giờ nằm đè lên sai branch, commit tiếp theo của nó rơi vào sai chỗ, và build bắt đầu fail vì những lý do mà nó sẽ dành hai mươi phút để “debug”. Không có gì crash cả. Trạng thái chỉ âm thầm sai đi.

Vấn đề còn tệ hơn với file. Cả hai agent dùng chung một thư mục làm việc, nên khi Agent B tạo lại một file config hay chạy lại formatter, những chỉnh sửa đang mở của Agent A bị ghi đè trên đĩa. Các coding agent không có mô hình nhận thức kiểu “thằng kia đang làm dở”. Chúng đọc file, xử lý rồi ghi lại. Hai người ghi, một file, không có lock. Bạn gặp đúng bài toán lost-update kinh điển, chỉ khác là những người ghi ở đây tự động và nhanh.

Đây chính là nỗi đau khiến từ khóa “git worktrees” cứ liên tục nổi lên. Người ta không tìm kiếm về worktree vì thấy branching thú vị. Họ tìm vì đã thử chạy agent song song và bị hố. Nếu đó là bạn, phần thực thi song song đã được đề cập kỹ trong hướng dẫn chạy nhiều Claude Code agent song song của chúng tôi; còn bài này nói về primitive cách ly nằm bên dưới.

Git worktree thực chất là gì

Đây là định nghĩa chuẩn, đáng để bạn ghi nhớ:

Git worktree là một thư mục làm việc bổ sung được liên kết với cùng một repository, có branch được checkout, index và HEAD riêng, nhưng dùng chung một object database.

Mệnh đề cuối đó chính là toàn bộ mẹo. Worktree không phải là clone. Clone nhân bản toàn bộ object store: mọi commit, mọi blob, mọi tag đều được copy sang một .git thứ hai. Worktree dùng chung một object store và chỉ thêm một thư mục làm việc thứ hai nhẹ nhàng. Commit của bạn hiển thị từ mọi worktree ngay khi được tạo, vì bên dưới chỉ có một lịch sử duy nhất. Thứ khác nhau giữa các worktree là phần checkout: branch nào đang được lấy ra, thứ gì đã stage, thứ gì đang dirty trên đĩa.

Với agent, điều này khớp gọn gàng với bài toán. Mỗi agent có một worktree. Mỗi worktree có branch và file riêng. Chúng không thể ghi đè lên nhau vì thực sự nằm ở các thư mục khác nhau, và không thể giật branch khỏi chân nhau vì mỗi worktree ghim HEAD của riêng nó. Xung đột được đưa về đúng chỗ của nó: lúc merge, có chủ đích, dưới sự review, thay vì xảy ra giữa lúc đang sửa một cách vô tình.

Những lệnh worktree bạn thực sự sẽ dùng

Hãy bắt đầu trong một repository thông thường. Mọi lệnh dưới đây đều chạy từ bên trong đó.

Tạo worktree với một branch mới. Đây là lệnh bạn sẽ dùng nhiều nhất:

git worktree add -b fix-logging ../myproject-fix-logging main

Lệnh này tạo thư mục tại ../myproject-fix-logging, tạo branch mới fix-logging bắt đầu từ main và checkout nó ở đó. Chỉ cho agent vào thư mục đó, và nó có một chỗ làm việc sạch sẽ, biệt lập.

Tạo worktree cho một branch đã tồn tại:

git worktree add ../myproject-auth auth-refactor

Liệt kê những gì đang mở:

git worktree list

/Users/you/myproject              9f3c1a2 [main]
/Users/you/myproject-fix-logging  9f3c1a2 [fix-logging]
/Users/you/myproject-auth         3b7e0d4 [auth-refactor]

Mỗi worktree một dòng, kèm đường dẫn, commit đang checkout và branch. Khi bạn vận hành cả một đội agent, danh sách này là nguồn chân lý để biết ai đang ở đâu.

Xóa worktree khi công việc đã merge hoặc bị bỏ:

git worktree remove ../myproject-fix-logging

Prune metadata cũ sau khi bạn xóa thủ công thư mục worktree (agent và script làm việc này nhiều hơn bạn muốn):

git worktree prune

Đó là toàn bộ bề mặt. Năm lệnh. Khó khăn không nằm ở các lệnh.

Những cạm bẫy thực sự cắn bạn

Các lệnh thì đơn giản. Thực tế vận hành mới là chỗ nuốt cả buổi chiều. Đây là những kiểu lỗi xuất hiện khi agent thật chạy trong worktree thật.

File untracked và bị gitignore không đi theo. Một worktree checkout các file được track tại branch bạn yêu cầu. Nó không copy node_modules, .env, venv, build cache hay bất cứ thứ gì khác mà git ignore. Vì vậy một worktree mới cho dự án Node sẽ không chạy được cho đến khi bạn cài đặt trong đó. Mỗi worktree phải tự trả giá cho việc cài dependency, file môi trường và build của riêng nó. Những agent mặc định rằng “repo đã sẵn sàng” sẽ fail ngay lệnh đầu tiên trong worktree mới cho đến khi bạn xử lý setup một cách rõ ràng.

Bạn không thể checkout cùng một branch hai lần. Git từ chối việc một branch được checkout ở hai worktree cùng lúc, và điều đó là đúng. Nếu hai agent đều cần main được checkout, một trong hai phải tạo branch. Đây là tính năng, không phải hạn chế, nhưng nó làm bất ngờ những ai tưởng worktree là những bản copy tự do.

Dung lượng đĩa tăng nhanh. Object store được chia sẻ nên lịch sử thì rẻ. Còn thư mục làm việc và các bản cài đặt thì không. Mười worktree của một dự án có node_modules 900 MB là 9 GB dependency bị nhân bản. Trên một chiếc laptop chạy vài agent, bạn sẽ cảm nhận được điều này ngay trước bữa trưa.

Worktree đang dirty thì khó xóa. git worktree remove sẽ từ chối nếu worktree có thay đổi chưa commit, điều này bảo vệ bạn khỏi việc vứt đi công việc mà agent chưa hoàn thành. Khi thực sự muốn xóa nó, dùng git worktree remove --force. Nhưng giờ bạn phải tự quyết định xem công việc chưa commit đó có quan trọng không, với từng worktree, bằng tay.

Thư mục bị xóa để lại bóng ma. Xóa thư mục worktree bằng rm -rf thì git vẫn liệt kê nó cho đến khi bạn chạy git worktree prune. Những script tạo worktree nhanh hơn tốc độ dọn dẹp sẽ tích tụ các entry cũ, và những entry này giữ lock khiến không thể dùng lại tên branch. Dọn dẹp không phải tùy chọn; nó chỉ dễ bị quên cho đến khi git worktree list trở thành một nghĩa địa.

Cache lồng nhau của agent không phải thứ bạn được xóa. Một số runtime giữ cache worktree riêng, ví dụ dưới ~/.claude/worktrees. Đừng trỏ script dọn dẹp của bạn vào đó. Hãy để công cụ sở hữu cache tự quản lý nó.

Riêng từng thứ thì không khó. Vấn đề là chúng cộng dồn lại. Hai worktree thì bạn quản lý bằng tay. Năm cái thì bạn viết script. Mười hai agent đang chạy trên hai repository, và script giờ đã thành một mẩu hạ tầng nhỏ với bug của riêng nó, còn bạn là người trực on-call cho nó.

Khi nào script hết khả năng mở rộng

Quá trình thực tế diễn ra như thế này. Bạn bắt đầu với một shell function bao quanh git worktree add, thả agent vào thư mục mới và chạy setup. Nó hoạt động. Bạn thêm quy tắc đặt tên để các thư mục không trùng nhau. Bạn thêm lệnh dọn dẹp. Rồi yêu cầu cứ chồng chất lên.

Bạn muốn biết agent nào đang ở worktree nào, và branch của nó đang ở trạng thái gì. git worktree list của bạn không biết gì về agent; nó chỉ biết về thư mục. Bạn gắn thêm một file mapping. Bạn muốn việc cài dependency cho từng worktree không làm nghẽn đĩa, nên bạn thêm logic caching. Bạn muốn output, diff và kết quả test của agent đáp xuống một chỗ mà con người có thể review, thay vì bị kẹt trong một terminal sẽ đóng lại. Giờ bạn đang viết một bộ thu thập kết quả. Bạn muốn hai agent không cùng giành một task trong hàng đợi. Giờ bạn đang viết một lock.

Đến một lúc nào đó, bạn đã tái hiện lại một lớp orchestration bằng shell script, và chẳng ai có nhiệm vụ duy trì nó. Đây chính là điểm nối mà câu chuyện vibe kanban alternative xoay quanh, và là lý do các team tìm đến một lớp quản lý thực thụ khi số lượng agent vượt qua một ngưỡng. Worktree chưa bao giờ là phần khó. Phối hợp nhiều lượt chạy biệt lập và đưa kết quả của chúng về một chỗ mới là khó.

Sharkly chạy mỗi Task trong worktree riêng như thế nào

Sharkly là một nền tảng chỉ huy và quản lý Agent tất-cả-trong-một. Nó không thay thế Claude Code, Codex hay những công cụ thực thi khác mà agent của bạn đang dùng; nó bổ sung lớp Task, Computer, context và review dùng chung xung quanh chúng. Cách ly worktree được tích hợp sẵn trong lớp đó, nên bạn không phải tự làm nữa.

Cơ chế rất trực tiếp. Mỗi Task nhận một thư mục biệt lập. Với công việc dựa trên repository, Sharkly chuẩn bị một worktree mới cho mỗi lượt chạy từ dữ liệu repository đã cache, nên nhiều Task có thể làm việc trên cùng một nguồn mà không bao giờ ghi vào một checkout chia sẻ. Bạn không phải chạy git worktree add. Bạn không phải viết quy tắc đặt tên, job dọn dẹp hay file mapping. Bạn giao một Task, và sự cách ly đã có sẵn.

Đây là sự tách bạch trách nhiệm khiến mọi thứ trở nên êm ả. Agent định nghĩa công việc nên được xử lý thế nào. Computer cung cấp host và tài nguyên cục bộ. Runtime thực hiện phiên agent thực tế. Task vẫn là bản ghi chung cho cả team. Vì mỗi lượt chạy nằm trong worktree riêng, frontend, backend, một bản sửa bug và coverage test mới đều có thể tiến song song mà không giẫm chân nhau — đúng kiểu song song mà cách làm thủ công đang nhắm tới.

Và kết quả có nơi để đi. Quá trình thực thi, các điểm tắc, kết quả và thảo luận tiếp theo đều quay về timeline của Task. Thay vì diff của agent nằm trong một terminal mà bạn phải nhớ để kiểm tra, bản tóm tắt thay đổi, output xác minh và các giới hạn đã biết đều quay về Task, nơi một người chấp nhận, yêu cầu sửa đổi hoặc quyết định merge. Context, tiến độ, điểm tắc, kết quả và review của con người luôn hiển thị từ lúc yêu cầu đến lúc phát hành, ở một nơi chia sẻ thay vì bị chia cắt giữa các prompt riêng tư và phiên terminal. Nếu bạn mới làm quen với mô hình này, giao Task đầu tiên cho một AI coding agent là con đường ngắn nhất để bắt đầu.

Bạn vẫn giữ những công cụ mình đang dùng. Việc sử dụng model tiếp tục qua các subscription hoặc API key đã cấu hình trong những công cụ đó; Sharkly bổ sung cách ly, phối hợp và review xung quanh chúng.

Worktree thủ công và lớp quản lý: so sánh

Cả hai cách đều dùng cùng một primitive. Khác biệt nằm ở chỗ ai gánh phần vận hành.

Hãy dùng worktree thủ công khi bạn là một developer chạy một hoặc hai agent và muốn toàn quyền kiểm soát shell. Cách đó thực sự ổn, và đáng để học vì cơ chế bên trong sẽ dạy bạn biết lớp phía trên đang làm gì. Hãy dùng một lớp quản lý khi số lượng tăng lên, khi có nhiều hơn một người cần xem công việc, hoặc khi việc mất kết quả của agent trong một terminal đã đóng thực sự khiến bạn tốn kém. Điều này phản ánh đúng nguyên tắc quyết định thẳng thắn trong hướng dẫn AI agent orchestration của chúng tôi: đừng thêm bộ máy phối hợp cho đến khi công việc song song là thật, và đừng tiếp tục tự làm bằng tay khi nó đã thành thật.

Giao kèo giữa người và agent vẫn giữ nguyên

Cách ly thay đổi nơi công việc diễn ra, chứ không thay đổi ai là người quyết định. Worktree cho phép các agent nghiên cứu, thực thi, test và báo cáo song song mà không va chạm. Con người vẫn định hướng, trao quyền và chấp nhận kết quả. Tự động hóa dừng lại ở nơi cần đến phán đoán của team. Một worktree mới cho mỗi agent là thứ khiến ranh giới đó có thể thực thi được: công việc của mỗi agent đến dưới dạng một thay đổi riêng biệt, có thể review, trên branch của chính nó, chứ không phải một chỉnh sửa không thể truy vết lẫn vào một checkout chia sẻ. Bạn review branch, không phải một mớ hỗn độn. Để có bức tranh rộng hơn về ý nghĩa của sự chuyển dịch này trong thực tế hằng ngày, bài giải thích về agentic coding của chúng tôi sẽ đặt bối cảnh, còn What is Sharkly bao quát toàn bộ nền tảng từ đầu đến cuối.

Vài cách làm hiệu quả cho worktree thủ công

Nếu tạm thời bạn vẫn làm thủ công, những thói quen này sẽ ngăn được phần lớn nỗi đau:

• Đặt tên thư mục worktree theo branch hoặc task, đừng đặt theo số thứ tự. myproject-auth-refactor cho biết đó là gì; myproject-wt3 thì không.
• Để worktree nằm ngang hàng với checkout chính, không lồng vào bên trong nó. Việc lồng nhau gây rối cho các công cụ duyệt cây thư mục và làm phình quy tắc ignore của bạn.
• Tự động hóa phần thiết lập từng worktree thành một script mà agent chạy đầu tiên, để một worktree mới có thể chạy được chỉ trong một bước thay vì fail vì thiếu bản cài đặt.
• Prune theo lịch, đừng prune tùy hứng. Chạy git worktree prune hằng ngày kèm việc xem lại git worktree list sẽ giữ các entry bóng ma ở mức thấp.
• Đừng bao giờ xóa cache runtime lồng nhau như ~/.claude/worktrees bằng script của bạn. Hãy để runtime tự sở hữu nó.
• Commit hoặc stash trước khi xóa. --force dành cho những lúc bạn chắc chắn, không phải mặc định.

Kết luận

Git worktree là primitive cách ly giúp các AI coding agent chạy song song một cách an toàn. Những ý cốt lõi đáng ghi nhớ:

• Một checkout chỉ có một branch, một index, một HEAD và không thể chứa hai agent cùng lúc.
• Một worktree thêm thư mục làm việc thứ hai trên cùng một lịch sử chia sẻ, nên mỗi agent có branch và file riêng.
• Năm lệnh (add, list, remove, prune và --force khi bạn thực sự muốn) đều đơn giản.
• Thứ tăng lên chính là chi phí vận hành (cài đặt từng worktree, đĩa, dọn dẹp, phối hợp, thu thập kết quả).
• Worktree thủ công phù hợp với một hoặc hai agent; một lớp quản lý sẽ đáng có khi số lượng và mức độ quan trọng tăng lên.
• Sharkly tự động chuẩn bị một worktree mới cho mỗi Task và trả từng kết quả về Task để con người review.

Hãy học các lệnh thủ công trước; chúng dạy bạn biết lớp phía trên đang làm gì. Khi việc ghi chép bắt đầu tốn kém hơn cả công việc, Sharkly sẽ gánh phần worktree, phối hợp và review khỏi vai bạn. Kết nối một Computer, tạo một Agent và giao cho nó một việc nhàm chán.

FAQ

Git worktree hiểu đơn giản là gì? Đó là thư mục làm việc thứ hai gắn với cùng một repository, có branch được checkout riêng và các thay đổi đã stage/chưa stage riêng. Nó dùng chung một lịch sử commit với checkout chính, nên nhẹ hơn nhiều so với một clone. Với AI agent, điều đó nghĩa là mỗi agent có một chỗ làm việc riêng mà không đụng đến file của ai khác.

Vì sao AI coding agent cần worktree? Vì hai agent dùng chung một checkout sẽ ghi đè file của nhau và đổi branch của nhau. Mỗi agent một worktree sẽ đẩy xung đột về thời điểm merge, nơi chúng hiển thị rõ và có thể review, thay vì xảy ra giữa lúc đang sửa, nơi chúng âm thầm làm hỏng trạng thái. Xem hướng dẫn chạy nhiều Claude Code agent song song của chúng tôi để biết toàn bộ cách thiết lập song song.

Worktree có giống clone không? Không. Clone copy toàn bộ object database sang một repository riêng. Worktree dùng chung một object database và chỉ thêm một thư mục làm việc mới cùng branch được checkout. Commit tạo ở bất kỳ worktree nào đều hiển thị tức thì từ mọi worktree khác, và dung lượng đĩa dùng ít hơn nhiều.

Hai worktree có thể checkout cùng một branch không? Không. Git từ chối checkout một branch ở hai worktree cùng lúc, để bảo vệ bạn khỏi việc ghi xung đột lên cùng một branch. Nếu hai agent đều cần branch đó làm nền, một trong hai phải tạo một branch mới từ nó.

Làm sao dọn worktree một cách an toàn? Trước tiên hãy commit hoặc stash mọi công việc, sau đó chạy git worktree remove <path>. Nếu bạn đã xóa thủ công thư mục worktree, hãy chạy git worktree prune để xóa metadata cũ. Đừng bao giờ trỏ script dọn dẹp vào cache riêng của runtime như ~/.claude/worktrees.

Khi nào tôi nên ngừng quản lý worktree bằng tay? Khi bạn đang phối hợp nhiều hơn vài agent, khi có nhiều hơn một người cần xem công việc, hoặc khi một kết quả bị mất trong terminal đã đóng từng khiến bạn tốn thời gian. Đến lúc đó, một lớp quản lý tự cô lập và theo dõi từng lượt chạy sẽ xứng đáng với chi phí. Hướng dẫn AI agent orchestration của chúng tôi sẽ nói khi nào nên thực hiện bước nhảy đó.