using-git-worktrees

Tổng quan về skill using-git-worktrees

Skill using-git-worktrees làm gì

using-git-worktrees giúp agent tạo một Git worktree riêng cho công việc mới thay vì tái sử dụng checkout hiện tại của bạn. Giá trị thực của skill này không chỉ là “chạy git worktree add”, mà còn nằm ở việc chọn thư mục hợp lý, kiểm tra xem các thư mục worktree cục bộ đã được ignore an toàn chưa, và tránh làm lẫn công việc mới vào workspace chính.

Ai nên cài skill này

Skill này phù hợp nhất với những ai thường xuyên:

• bắt đầu làm feature mới nhưng vẫn muốn giữ nguyên các thay đổi hiện tại
• review hoặc triển khai nhiều branch song song
• muốn workflow code với AI an toàn hơn, ít rủi ro do chuyển branch liên tục
• cần một cách lặp lại được để tạo workspace tách biệt giữa nhiều project

Nếu bạn hay yêu cầu assistant kiểu “bắt đầu phần này ở branch riêng” hoặc “làm mà đừng đụng vào tree hiện tại của tôi”, thì using-git-worktrees là lựa chọn rất đáng cân nhắc.

Công việc thực sự mà skill này giải quyết

Người dùng thường chỉ quan tâm một kết quả: bắt đầu triển khai trong một workspace tách biệt với ít lỗi thiết lập nhất có thể. using-git-worktrees hữu ích vì nó thêm một bước ra quyết định trước khi tạo worktree:

• ưu tiên dùng thư mục worktree sẵn có của project nếu đã tồn tại
• tuân theo ưu tiên được ghi rõ trong CLAUDE.md nếu có
• hỏi người dùng khi không có lựa chọn mặc định nào đủ an toàn
• kiểm tra hành vi ignore trước khi tạo worktree nằm trong project

Vì vậy, nó đáng tin hơn một prompt chung chung lao thẳng vào lệnh shell.

Điểm khác biệt so với một prompt thông thường

Một prompt thông thường có thể biết khái niệm Git worktree, nhưng vẫn dễ bỏ sót các chi tiết thiết lập riêng của repo. Skill này cung cấp cho agent một trình tự thao tác và các bước kiểm tra an toàn rõ ràng, đặc biệt quanh vị trí thư mục và cách xử lý .gitignore. Đây là khác biệt chính của using-git-worktrees for Git Workflows: giảm việc phải đoán khi thiết lập, chứ không phải bổ sung thêm lý thuyết Git.

Khi nào skill này không phù hợp

Bạn nên bỏ qua using-git-worktrees nếu:

• bạn luôn làm việc trong một branch và một thư mục duy nhất
• môi trường của bạn không cho phép tạo thêm working directory
• bạn chỉ cần chuyển branch nhanh, không cần môi trường thực thi tách biệt
• team của bạn đã có wrapper script cố định thay thế hoàn toàn logic ra quyết định này

Trong các trường hợp đó, một lệnh shell đơn giản hoặc workflow nội bộ có thể nhanh hơn.

Cách dùng skill using-git-worktrees

Ngữ cảnh cài đặt cho using-git-worktrees

Cài từ bộ skill obra/superpowers:

npx skills add https://github.com/obra/superpowers --skill using-git-worktrees

Sau khi cài, hãy dùng skill này khi bạn sắp bắt đầu một công việc không nên tái sử dụng checkout hiện tại.

Người dùng thực tế gọi skill này như thế nào

Repo ghi rất rõ rằng agent nên thông báo việc sử dụng skill ngay từ đầu. Trong thực tế, yêu cầu của bạn nên thể hiện rõ nhu cầu tách biệt môi trường, ví dụ:

• “Use using-git-worktrees and set up an isolated workspace for this feature.”
• “Before implementing, create a worktree for branch feature/auth-refresh.”
• “Use the using-git-worktrees skill so my current changes stay untouched.”

Cách nói này làm tăng khả năng agent thực sự đi theo skill thay vì tự ứng biến.

Skill này cần đầu vào gì

Để có kết quả tốt, bạn nên cung cấp:

• tên branch mục tiêu
• đây là branch mới hay branch đã có sẵn
• bạn muốn lưu worktree trong project hay ở vị trí global
• các ràng buộc riêng của repo, ví dụ “phải nằm dưới project root”

Đầu vào tối thiểu hữu ích:

• tên branch/task
• quyền tạo worktree

Đầu vào tốt hơn:

• tên branch
• chính sách thư mục mong muốn
• checkout hiện tại có thay đổi chưa commit hay không
• sau khi setup xong thì cần làm gì tiếp, ví dụ “sau đó bắt đầu triển khai”

Logic chọn thư mục được tích hợp sẵn

using-git-worktrees skill có giá trị nhất ở workflow chọn thư mục. Thứ tự ưu tiên của nó là:

1. dùng .worktrees nếu thư mục này đã tồn tại
2. nếu không thì dùng worktrees nếu đã tồn tại
3. nếu vẫn chưa có thì kiểm tra CLAUDE.md để tìm ưu tiên đã được ghi lại
4. nếu vẫn không có thì hỏi người dùng chọn giữa:
   • .worktrees/
   • ~/.config/superpowers/worktrees/<project-name>/

Điều này quan trọng vì nếu mỗi phiên tự nghĩ ra một vị trí mới, các worktree sẽ nhanh chóng trở nên rải rác và khó quản lý.

Kiểm tra an toàn trước khi tạo worktree trong project

Một chi tiết rất đáng chú ý khi triển khai: nếu worktree nằm bên trong repo, skill yêu cầu phải xác minh thư mục đó đã được ignore trước khi tạo. Điều này giúp tránh vô tình track các thư mục worktree hoặc làm rối git status.

Đây là lợi thế thực tế so với cách dùng ngẫu hứng. Nếu team của bạn muốn đặt worktree trong project, hãy chắc chắn .worktrees/ hoặc worktrees/ đã được Git ignore trước khi dựa vào workflow này.

Mẫu prompt hiệu quả cho using-git-worktrees

Prompt yếu:

• “Start working on OAuth cleanup.”

Prompt mạnh hơn:

• “Use using-git-worktrees to create an isolated workspace for new branch feature/oauth-cleanup. Prefer .worktrees/ if safe and ignored. After setup, begin implementation without touching my current checkout.”

Vì sao cách này tốt hơn:

• gọi đích danh skill
• nêu rõ branch mục tiêu
• nói rõ ưu tiên thư mục
• cho agent biết bước tiếp theo là gì

Workflow nên dùng sau khi tạo xong

Một trình tự thực tế cho using-git-worktrees usage:

1. yêu cầu agent dùng skill
2. xác nhận vị trí worktree và tên branch
3. để agent chuyển công việc sang workspace mới
4. chỉ sau đó mới bắt đầu sửa code, chạy test hoặc lập kế hoạch triển khai

Trình tự này đặc biệt hữu ích khi checkout hiện tại của bạn đã có thay đổi chưa commit.

Những file nên đọc trước trong repository

Ở đây chỉ có một file nguồn thực sự đáng đọc: SKILL.md.

Hãy đọc file này để nắm:

• đúng thứ tự ưu tiên khi chọn thư mục
• prompt mà skill sẽ dùng để hỏi người dùng khi chưa có ưu tiên
• yêu cầu xác minh ignore
• cách kích hoạt buộc agent phải thông báo việc dùng skill

Skill này khá gọn, nên câu hỏi chính trước khi áp dụng là logic đó có khớp với workflow Git của team bạn hay không.

Những giới hạn thực tế cần biết trước khi phụ thuộc vào skill này

Skill này được thiết kế có chủ đích để làm một việc hẹp. Có vẻ nó không cung cấp:

• wrapper script
• helper tự động hóa
• cơ chế ép quy ước đặt tên branch
• routine dọn dẹp worktree cũ
• fallback riêng cho từng nền tảng

Vì vậy, using-git-worktrees install mang lại hướng dẫn ra quyết định, chứ không phải một hệ thống quản lý worktree đầy đủ. Nếu bạn cần tự động hóa toàn bộ vòng đời worktree, hãy kết hợp thêm shell tooling riêng.

Câu hỏi thường gặp về skill using-git-worktrees

using-git-worktrees có phù hợp cho người mới không?

Có, nếu người mới đó đã hiểu cơ bản về branch và muốn một workflow an toàn hơn theo kiểu “đừng đụng vào workspace hiện tại của tôi”. Đây không phải hướng dẫn Git cho người mới; nó là một skill thiết lập có cấu trúc. Người hoàn toàn mới vẫn có thể cần được giải thích worktree là gì và nó khác clone ở điểm nào.

Skill này giải quyết vấn đề gì tốt hơn prompt thông thường?

Prompt thông thường hay bỏ qua phần rắc rối nhất: nên đặt worktree ở đâu và thư mục cục bộ trong project đã được ignore an toàn chưa. using-git-worktrees guide được mã hóa trong skill giúp giảm các lỗi thiết lập kiểu này và khiến hành vi của agent nhất quán hơn.

Tôi có bắt buộc phải dùng worktree trong project không?

Không. Skill có thể điều hướng sang vị trí global nếu không có thư mục local nào sẵn có và repo cũng không ghi rõ ưu tiên. Nhờ vậy, nó vẫn dùng tốt ngay cả khi bạn không muốn có thêm thư mục bên trong repository.

Tôi có thể dùng using-git-worktrees cho branch đã tồn tại không?

Có. Workflow này vẫn hữu ích khi checkout một branch có sẵn vào workspace riêng. Giá trị chính nằm ở việc tách biệt môi trường làm việc, không chỉ ở khâu tạo branch mới.

Khi nào không nên dùng using-git-worktrees?

Không nên dùng khi:

• bạn chỉ sửa một thay đổi rất nhỏ ngay trên branch hiện tại
• team của bạn cấm các vị trí worktree không được quản lý
• bạn đã có tooling nội bộ mang tính xác định cao để xử lý vị trí và quy tắc ignore
• repo của bạn có những ràng buộc Git khác thường mà skill này không biết

Skill này có thay thế hiểu biết về Git không?

Không. using-git-worktrees skill cải thiện cách gọi và kỷ luật thiết lập, nhưng bạn vẫn cần phán đoán Git ở mức cơ bản cho việc đặt tên branch, rebase, dọn dẹp và chiến lược merge.

Cách cải thiện skill using-git-worktrees

Nêu rõ ý định về branch và vị trí thư mục

Cải thiện lớn nhất về chất lượng là nói cho agent biết cả branch mục tiêu lẫn chính sách thư mục mong muốn. Ví dụ:

“Use using-git-worktrees for branch fix/cache-invalidation. If .worktrees/ exists and is ignored, use it; otherwise ask before using a global location.”

Điều này loại bỏ nguồn mơ hồ phổ biến nhất.

Ghi lại ưu tiên trong CLAUDE.md

Vì skill có kiểm tra CLAUDE.md, bạn có thể cải thiện kết quả về sau bằng cách ghi rõ:

• thư mục worktree ưu tiên
• có cho phép worktree nằm trong project hay không
• quy ước đặt tên branch hoặc thư mục

Như vậy, những phần người dùng phải lặp đi lặp lại sẽ được nâng thành chính sách ở cấp repo.

Cấu hình sẵn quy tắc ignore cho thư mục local

Nếu team của bạn muốn dùng .worktrees/ hoặc worktrees/ bên trong project, hãy thêm quy tắc ignore từ trước. Điều này giúp luồng using-git-worktrees for Git Workflows trơn tru hơn vì bước xác minh an toàn sẽ vượt qua ngay, thay vì phải dừng giữa chừng để trao đổi.

Theo dõi các lỗi thường gặp

Các kiểu lỗi chính khá dễ đoán:

• agent tạo worktree ở vị trí không được chấp nhận
• các thư mục worktree cục bộ chưa được ignore
• tên branch bị suy đoán sai từ một yêu cầu tính năng quá mơ hồ
• việc triển khai bắt đầu trên checkout gốc trước khi hoàn tất tách biệt môi trường

Phần lớn các lỗi này xuất phát từ prompt chưa đủ rõ, không phải từ chính skill.

Yêu cầu xác nhận trước khi bắt đầu code

Một prompt cải thiện đơn giản:

• “Use using-git-worktrees, then report the final path and branch before making edits.”

Cách này giúp bắt lỗi sớm và đặc biệt hữu ích trong các repo có nhiều thư mục lồng nhau hoặc chính sách khác thường.

Tinh chỉnh sau lần chạy đầu tiên

Nếu đầu ra đầu tiên chấp nhận được nhưng chưa tối ưu, hãy tinh chỉnh cách làm việc thay vì viết lại toàn bộ:

• chốt vị trí thư mục bạn muốn dùng
• thêm ghi chú trong CLAUDE.md
• chuẩn hóa cách đặt tên branch trong prompt
• yêu cầu xác nhận rõ ràng trước khi sửa code

Nhờ vậy, using-git-worktrees usage sẽ dễ đoán hơn theo thời gian và giảm bớt ma sát lặp đi lặp lại ở khâu thiết lập.