merge

merge skill 개요

merge skill의 용도

merge skill은 멀티 에이전트 코딩 세션이 끝난 뒤, 가장 우수한 에이전트 결과를 Git의 기준 브랜치에 반영하기 위한 AgentHub 워크플로 skill입니다. /hub:merge 명령에 맞춰 설계되었으며, 선택된 승자 결과를 병합하고, 나머지 시도는 나중에 검토할 수 있도록 보존하며, 세션 worktree를 정리하고, 병합 후 요약을 작성하는 하나의 실무 작업에 집중합니다.

Git Workflow에 가장 잘 맞는 경우

저장소가 세션 ID, 에이전트 브랜치, 평가 순위, 임시 worktree를 사용하는 AgentHub 패턴을 따를 때 이 merge skill을 사용하면 좋습니다. 특히 /hub:eval 이후, 어떤 에이전트가 가장 좋은 해법을 냈는지 이미 알고 있고 브랜치를 직접 checkout하고, merge하고, 패배한 브랜치에 tag를 달고, worktree를 삭제하는 대신 반복 가능한 Git Workflow가 필요할 때 유용합니다.

일반적인 merge 프롬프트와 다른 점

일반 프롬프트는 “가장 좋은 브랜치를 merge해” 정도로 끝날 수 있습니다. 반면 이 skill은 명확한 운영 규칙을 담고 있습니다. --agent가 지정되지 않으면 최상위 순위의 에이전트를 사용하고, --no-ff로 merge하며, 승자가 아닌 브랜치는 hub/archive/... tag로 보관하고, 해당 branch ref를 삭제한 뒤 .agenthub/board/results/merge-summary.md를 생성합니다. 이런 구조는 정리 단계의 모호함을 줄여 줍니다. 멀티 에이전트 Git 세션이 복잡해지는 지점이 보통 바로 이 cleanup 단계이기 때문입니다.

설치 전 도입 시 확인할 점

이 skill은 프로젝트에 이미 hub/{session-id}/{agent-id}/attempt-1 같은 AgentHub 스타일 브랜치와 승자를 식별할 수 있는 평가 결과가 있다고 가정합니다. 팀에서 AgentHub를 사용하지 않는다면, 이 merge 가이드는 구조화된 cleanup의 참고 모델로는 읽을 수 있지만, 안전하게 사용하려면 적용 전에 조정이 필요합니다.

merge skill 사용 방법

merge 설치와 먼저 확인할 파일

GitHub skill 저장소에서 다음 명령으로 skill을 설치합니다.

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

그다음 아래 소스 파일을 확인합니다.

engineering/agenthub/skills/merge/SKILL.md

이 skill은 SKILL.md 안에 자체적으로 구성된 것으로 보입니다. skill 디렉터리 미리보기에는 별도의 rules/, resources/, scripts/ 폴더가 보이지 않습니다. 다만 upstream 지침에서 session_manager.py를 언급하므로, 자동 cleanup에 의존하기 전에 로컬 AgentHub 환경에서 해당 스크립트가 어디에 있는지 확인해야 합니다.

기본 merge 사용법

일반적인 호출 방식은 다음과 같습니다.

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

가장 최근에 평가된 세션이 대상이라면 /hub:merge를 사용합니다. AgentHub 세션이 여러 개라면 세션 ID를 함께 제공합니다. --agent는 최상위 /hub:eval 결과를 의도적으로 덮어써야 할 때만 추가하세요. 예를 들어 최고 점수를 받은 결과가 보안, 호환성, 제품 요구사항 중 하나를 놓쳤고 사람이 리뷰 과정에서 이를 발견한 경우가 해당됩니다.

skill에 필요한 입력

merge를 안정적으로 사용하려면 에이전트에 다음 정보가 필요합니다.

• 대상 base branch. 보통 승자 결과를 반영하려는 브랜치입니다.
• AgentHub session ID. 가장 최근 세션이 명확하지 않다면 반드시 필요합니다.
• 승자 정보. 최신 평가 순위에서 가져오거나 --agent로 지정합니다.
• 예상 형식의 기존 branch ref: hub/{session-id}/{agent-id}/attempt-1.
• merge commit, tag, branch deletion을 생성하는 Git 작업을 실행할 권한.

더 좋은 프롬프트 예시는 다음과 같습니다. “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.” 이렇게 요청하면 skill이 추측에 의존하지 않고 작업할 수 있는 운영 맥락이 충분히 제공됩니다.

실행 전후의 실무 워크플로

merge를 호출하기 전에 git status를 실행하고, 관련 없는 로컬 변경사항이 남아 있지 않은지 확인한 뒤, 승자 diff를 검토하세요. merge 이후에는 merge commit message를 확인하고, archive tag가 생성되었는지 확인하며, .agenthub/board/results/merge-summary.md에 세션, 작업, 승자가 제대로 반영되었는지 검증합니다. 충돌이 발생하면 일반적인 Git conflict와 동일하게 해결하면 됩니다. 이 skill은 워크플로 구조를 제공할 뿐, 코드 리뷰를 대체하지는 않습니다.

merge skill FAQ

merge는 AgentHub 전용인가요?

실무적으로는 그렇습니다. merge skill은 AgentHub의 naming, evaluation, cleanup 규칙을 전제로 작성되어 있습니다. 다른 멀티 브랜치 실험에서도 수동 Git Workflow의 참고 자료로 활용할 수는 있지만, 그대로 사용하려면 AgentHub session branch와 결과 metadata가 필요합니다.

merge가 가장 좋은 코드를 자동으로 고르나요?

지정한 --agent를 선택하거나, 지정하지 않은 경우 가장 최근 /hub:eval에서 최상위 순위에 오른 에이전트를 선택합니다. 따라서 merge 품질은 이전 평가의 품질에 좌우됩니다. 평가 기준이 불완전했다면 merge 전에 승자 결과를 직접 검토해야 합니다.

패배한 브랜치는 어떻게 되나요?

의도된 워크플로는 각 패배 에이전트 브랜치를 hub/archive/{session-id}/{agent-id} 같은 Git tag로 보관한 뒤 branch ref를 삭제하는 방식입니다. 이렇게 하면 commit은 계속 도달 가능하게 유지하면서 브랜치 목록의 혼잡을 줄일 수 있습니다. 보존 정책이 있는 팀은 이 skill을 도입하기 전에 archive tag naming을 확인해야 합니다.

이 skill을 사용하지 말아야 할 때는 언제인가요?

브랜치 이름이 AgentHub 규칙을 따르지 않거나, base branch가 불명확하거나, 승자 결과를 아직 리뷰하지 않았거나, 저장소에서 자동 branch deletion을 금지하는 경우에는 merge를 사용하지 마세요. 또한 squash-only 워크플로에는 잘 맞지 않습니다. 이 skill의 기본 패턴은 git merge --no-ff를 사용하므로, 그런 환경에서는 merge 명령을 조정해야 합니다.

merge skill 개선 방법

더 명확한 맥락으로 merge 결과 개선하기

merge skill은 요청에 session ID, winner, base branch, 정책 제약이 포함될 때 가장 잘 작동합니다. 예를 들어 “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.” 같은 요청이 좋습니다. “merge the winner”보다 나은 이유는 선택, 대상, cleanup, 안전 규칙을 분리해서 명확히 전달하기 때문입니다.

주의해야 할 일반적인 실패 유형

주요 위험은 최신 세션이 모호한 경우, 평가 결과가 없는 경우, working tree가 dirty한 경우, branch ref가 예상 패턴과 맞지 않는 경우, cleanup 명령이 이 skill 디렉터리 밖의 파일에 의존하는 경우입니다. 또 하나 중요한 위험은 기술적으로는 통과했지만 제품 요구에는 맞지 않는 승자를 merge하는 것입니다. /hub:eval은 선택을 위한 입력으로 다루고, 최종 리뷰를 대체하는 것으로 보지 마세요.

저장소 정책에 맞게 merge 조정하기

팀에서 squash merge, signed commit, protected branch, pull request, CI gate, remote branch retention을 요구한다면 프로덕션에서 사용하기 전에 워크플로를 수정해야 합니다. 가장 조정 가능성이 높은 지점은 merge strategy, archive tag format, branch deletion을 local-only로 제한할지 여부, merge-summary.md에 필수로 들어가야 하는 field입니다.

첫 실행 후 반복 점검하기

첫 결과가 나온 뒤에는 무작정 계속 진행하게 하지 말고, 에이전트에 검증을 요청하세요. “Show the merge commit, list archive tags for this session, confirm no AgentHub worktrees remain, and summarize any conflicts or skipped cleanup.” 이렇게 하면 merge 가이드를 감사 가능한 Git Workflow로 바꿀 수 있고, 세션을 잊어버리기 전에 cleanup이 일부만 끝난 상황을 잡아내는 데 도움이 됩니다.