merge

Tổng quan về merge skill

merge skill dùng để làm gì

merge skill là một AgentHub workflow skill dùng để đưa kết quả thắng cuộc của agent vào một Git base branch sau một phiên coding đa agent. Skill này được thiết kế cho lệnh /hub:merge và tập trung vào một nhiệm vụ rất thực tế: merge kết quả được chọn, giữ lại các lượt thử không thắng để kiểm tra sau, dọn dẹp session worktrees, và ghi một bản tóm tắt sau merge.

Phù hợp nhất với Git Workflows

Hãy dùng merge skill khi repository của bạn đi theo mô hình AgentHub với session ID, agent branches, evaluation rankings, và temporary worktrees. Skill này hữu ích nhất sau /hub:eval, khi bạn đã biết agent nào tạo ra lời giải tốt nhất và muốn có một Git Workflow lặp lại được, thay vì tự checkout branch, merge, gắn tag cho các branch không thắng và xóa worktrees theo cách thủ công.

Điểm khác biệt so với một merge prompt chung chung

Một prompt chung chung có thể chỉ nói “merge the best branch”, nhưng skill này mã hóa một quy ước vận hành cụ thể: dùng agent được xếp hạng cao nhất trừ khi có --agent, merge bằng --no-ff, lưu trữ các branch không thắng bằng tag hub/archive/..., xóa branch refs của chúng, và tạo .agenthub/board/results/merge-summary.md. Cấu trúc này giúp giảm mơ hồ trong bước dọn dẹp — thường là nơi các phiên Git đa agent trở nên lộn xộn.

Lưu ý trước khi cài đặt

Skill này giả định project của bạn đã có các branch theo kiểu AgentHub như hub/{session-id}/{agent-id}/attempt-1 và có output đánh giá đủ để xác định winner. Nếu team của bạn không dùng AgentHub, hướng dẫn merge này vẫn có thể tham khảo như một mô hình dọn dẹp có cấu trúc, nhưng cần được điều chỉnh trước khi dùng an toàn.

Cách sử dụng merge skill

Cài đặt merge và các file nên kiểm tra trước

Cài skill từ GitHub skill repository bằng:

npx skills add alirezarezvani/claude-skills --skill merge

Sau đó kiểm tra source tại:

engineering/agenthub/skills/merge/SKILL.md

Skill này có vẻ được đóng gói tự thân trong SKILL.md; trong phần preview thư mục skill không thấy các thư mục đi kèm như rules/, resources/, hoặc scripts/. Vì hướng dẫn upstream có nhắc đến session_manager.py, hãy xác minh script đó nằm ở đâu trong thiết lập AgentHub local của bạn trước khi phụ thuộc vào việc dọn dẹp tự động.

Cách gọi merge cơ bản

Các cách gọi thường gặp là:

/hub:merge
/hub:merge 20260317-143022
/hub:merge 20260317-143022 --agent agent-2

Dùng /hub:merge khi mục tiêu là session đã được đánh giá gần nhất. Cung cấp session ID khi có nhiều AgentHub sessions. Chỉ thêm --agent khi bạn cố ý ghi đè kết quả đứng đầu từ /hub:eval, chẳng hạn khi kết quả điểm cao nhất bỏ sót một yêu cầu về bảo mật, tương thích hoặc sản phẩm mà reviewer phát hiện.

Các input mà skill cần

Để dùng merge đáng tin cậy, agent cần:

• Target base branch, thường là branch mà bạn muốn đưa phần việc thắng cuộc vào.
• AgentHub session ID, trừ khi session mới nhất hoàn toàn rõ ràng.
• Winner, lấy từ evaluation ranking mới nhất hoặc từ --agent.
• Các branch refs hiện có theo đúng định dạng kỳ vọng: hub/{session-id}/{agent-id}/attempt-1.
• Quyền chạy các Git operations tạo merge commits, tags, và xóa branch.

Một prompt tốt hơn là: “Run /hub:merge 20260317-143022 --agent agent-2 into main. Before merging, confirm the working tree is clean, show the winning branch ref, tag losing branches for archive, and write the merge summary.” Prompt này cung cấp đủ ngữ cảnh vận hành để skill không phải đoán.

Quy trình thực tế trước và sau khi chạy

Trước khi gọi merge, hãy chạy git status, xác nhận bạn không có thay đổi local không liên quan, và review diff của winner. Sau khi merge, kiểm tra merge commit message, xác nhận archive tags đã được tạo, và xác minh .agenthub/board/results/merge-summary.md phản ánh đúng session, task, và winner. Nếu có conflict, xử lý như conflict Git thông thường; skill cung cấp cấu trúc workflow, không thay thế cho code review.

FAQ về merge skill

merge có chỉ dành cho AgentHub không?

Có, về thực tế là vậy. merge skill được viết xoay quanh các quy ước đặt tên, đánh giá và dọn dẹp của AgentHub. Nó có thể gợi ý một Git Workflow thủ công cho các thử nghiệm nhiều branch khác, nhưng để dùng trực tiếp thì cần các AgentHub session branches và result metadata.

merge có tự động chọn code tốt nhất không?

Skill sẽ chọn agent bạn chỉ định bằng --agent, hoặc nếu không có thì chọn agent đứng đầu từ lần /hub:eval gần nhất. Điều đó có nghĩa là chất lượng của merge phụ thuộc vào chất lượng của bước đánh giá trước đó. Nếu tiêu chí đánh giá của bạn chưa đầy đủ, hãy review winner thủ công trước khi merge.

Điều gì xảy ra với các branch không thắng?

Workflow dự kiến sẽ lưu trữ mỗi losing agent branch bằng một Git tag, ví dụ hub/archive/{session-id}/{agent-id}, rồi xóa branch ref. Cách này giữ cho các commit vẫn truy xuất được, đồng thời giảm bớt sự lộn xộn trong danh sách branch. Các team có chính sách lưu giữ cần xác nhận quy ước đặt tên archive tag trước khi áp dụng skill.

Khi nào không nên dùng skill này?

Không dùng merge nếu tên branch không theo quy ước AgentHub, nếu base branch chưa chắc chắn, nếu winner chưa được review, hoặc nếu repository của bạn không cho phép xóa branch tự động. Skill này cũng không phù hợp lắm với workflow chỉ dùng squash, trừ khi bạn điều chỉnh merge command, vì pattern mặc định của skill dùng git merge --no-ff.

Cách cải thiện merge skill

Cải thiện kết quả merge bằng ngữ cảnh rõ hơn

merge skill hoạt động tốt nhất khi request của bạn nêu rõ session ID, winner, base branch, và mọi ràng buộc chính sách. Ví dụ: “Merge session 20260317-143022, winner agent-2, into develop; keep losing branches archived with tags, do not delete remote branches, and stop if tests fail.” Cách này tốt hơn “merge the winner” vì nó tách rõ các quyết định về lựa chọn, đích đến, dọn dẹp và quy tắc an toàn.

Các lỗi thường gặp cần chú ý

Các rủi ro chính gồm session mới nhất không rõ ràng, thiếu evaluation results, working tree chưa sạch, branch refs không khớp pattern kỳ vọng, và các cleanup commands phụ thuộc vào file nằm ngoài thư mục skill này. Một rủi ro quan trọng khác là merge một winner tuy pass về mặt kỹ thuật nhưng sai về sản phẩm. Hãy xem /hub:eval là input để lựa chọn, không phải thứ thay thế cho review cuối cùng.

Điều chỉnh merge theo chính sách repository của bạn

Nếu team của bạn yêu cầu squash merges, signed commits, protected branches, pull requests, CI gates, hoặc giữ lại remote branches, hãy chỉnh workflow trước khi dùng trong production. Các điểm có khả năng cần tùy biến nhất là merge strategy, archive tag format, việc xóa branch có chỉ áp dụng local hay không, và những trường bắt buộc trong merge-summary.md.

Lặp lại và kiểm chứng sau lần chạy đầu tiên

Sau output đầu tiên, hãy yêu cầu agent xác minh thay vì tiếp tục một cách mù quáng: “Show the merge commit, list archive tags for this session, confirm no AgentHub worktrees remain, and summarize any conflicts or skipped cleanup.” Cách này biến hướng dẫn merge thành một Git Workflow có thể audit được và giúp phát hiện dọn dẹp chưa hoàn tất trước khi session bị quên.