Bài 4 — Chạy song song an toàn với git worktree

Khi đã có các lô độc lập (Bài 3), câu hỏi tự nhiên là: chạy nhiều agent cùng lúc để rút ngắn thời gian? Được — nhưng nhiều agent sửa chung một thư mục làm việc sẽ giẫm chân nhau: file bị ghi đè, git index xung đột, verify của agent này bị agent kia làm hỏng. Giải pháp chuẩn là git worktree: mỗi agent một thư mục làm việc riêng, cùng chung một repo.

git worktree là gì

Một repo git có thể có nhiều working tree trỏ vào các branch khác nhau, dùng chung .git (lịch sử, object). Mỗi worktree là một thư mục độc lập trên đĩa: agent A sửa ở ../wt-billing, agent B sửa ở ../wt-reports, hoàn toàn cách ly.

# từ repo gốc
git worktree add ../wt-billing  migrate/billing
git worktree add ../wt-reports  migrate/reports
git worktree list
# /repo            abc123 [main]
# /wt-billing      def456 [migrate/billing]
# /wt-reports      789abc [migrate/reports]

Mỗi thư mục có node_modules, build cache, kết quả test riêng — agent chạy verify.sh trong worktree của mình không ảnh hưởng ai.

Bố trí một phiên chạy song song

• Một branch + một worktree cho mỗi lô độc lập:

for batch in billing reports auth; do
  git worktree add ../wt-$batch -b migrate/$batch main
done

• Cài dependency trong từng worktree (chúng không chia sẻ node_modules):

cd ../wt-billing && npm ci

• Giao mỗi agent đúng một worktree + đúng một lô trong manifest. Trong prompt ghi rõ đường dẫn worktree và phạm vi file được phép sửa.

• Mỗi agent tự verify độc lập trong worktree của nó rồi commit lên branch riêng.

• Gộp tuần tự về main, verify lại sau mỗi lần gộp (xem phần dưới).

Nguyên tắc chọn lô để song song hóa

Chỉ song song hóa các lô không đụng cùng file và không phụ thuộc nhau. Nếu lô A và lô B cùng sửa src/utils/date.ts, đừng chạy song song — sẽ xung đột merge nặng. Dùng manifest để kiểm tra giao nhau về phạm vi.

An toàn song song:  scope rời nhau (auth vs reports)
Không song song:    A đổi API mà B đang gọi -> phải tuần tự (leaf-first)

Gộp về main: tuần tự và verify từng bước

Đừng merge tất cả branch cùng lúc rồi verify một phát. Gộp từng branch một, verify sau mỗi lần:

git switch main
git merge --no-ff migrate/billing
./verify.sh                 # phải VERIFY_OK trước khi merge tiếp
git merge --no-ff migrate/reports
./verify.sh

Cách này khiến mọi lỗi tích hợp lộ ra ngay ở branch vừa gộp, dễ khoanh vùng.

Dọn dẹp worktree sau khi xong

git worktree remove ../wt-billing
git branch -d migrate/billing   # sau khi đã merge
git worktree prune              # dọn tham chiếu chết

Checklist chạy song song

[ ] Các lô đã chọn có scope RỜI NHAU (kiểm bằng manifest)?
[ ] Mỗi lô 1 branch + 1 worktree riêng
[ ] Mỗi worktree đã npm ci (node_modules riêng)
[ ] Mỗi agent chỉ được sửa trong scope của mình
[ ] Gộp tuần tự về main, verify sau MỖI merge
[ ] Dọn worktree + branch sau khi merge

Sai lầm thường gặp

• Chạy nhiều agent trên cùng một thư mục làm việc: ghi đè file, hỏng git index, verify nhiễu loạn.
• Song song hóa các lô phụ thuộc nhau: merge xong mới phát hiện lô dưới dùng API cũ → xung đột và lỗi tích hợp.
• Quên npm ci trong worktree mới: build đỏ không phải do code mà do thiếu node_modules.
• Merge tất cả rồi mới verify một lần: lỗi tích hợp trộn lẫn, không biết branch nào gây ra.
• Không dọn worktree: đĩa đầy, git worktree list rối, nhầm lẫn thư mục.

Song song giúp nhanh, nhưng nhanh mà sai thì vô nghĩa. Bài sau đi sâu vào verify — cách bắt lỗi ngữ nghĩa mà build xanh vẫn giấu được.