agenthub

agenthub skill 개요

agenthub의 용도

agenthub는 같은 repository 작업을 여러 AI agent가 병렬로 수행하도록 해주는 Agent Orchestration skill입니다. 각 agent는 격리된 git worktree에서 작업하며, 서로 다른 접근법을 탐색하고, 로컬 .agenthub/board를 통해 진행 상황을 보고한 뒤, 평가와 merge가 가능한 branch를 남깁니다. 핵심 목적은 “AI에게 답 하나를 물어보는 것”이 아니라 “실현 가능성 있는 여러 해법을 시도하고, 비교한 다음, 가장 나은 결과를 남기는 것”입니다.

가장 잘 맞는 사용 사례

agenthub skill은 여러 시도 간 성과를 비교할 수 있는 작업에서 특히 강합니다. 예를 들면 성능 최적화, 코드 리팩터링, prompt/content 변형, 리서치 탐색, 테스트 개선, 경쟁 구현 전략 비교 같은 경우입니다. 한 agent가 국소 최적해에 갇힐 수 있고, 사용자가 branch 관리, 상태 메모, 결과 순위 매기기를 직접 하고 싶지 않을 때 특히 유용합니다.

핵심 차별점과 제약

가장 중요한 차별점은 git 기반 격리입니다. agent의 결과물이 하나의 working tree에 뒤섞이는 대신 hub/{session-id}/agent-{N}/attempt-{M} branch로 분리됩니다. AgentHub에는 fan-out/fan-in, tournament, ensemble 패턴을 위한 coordination reference도 포함되어 있으며, session setup, board management, DAG analysis, dry-run validation, result ranking을 위한 script도 제공합니다. 주요 제약은 실제 git repository가 필요하다는 점입니다. 파일이 없거나, 평가 경로가 없거나, merge review를 감당할 수 없는 일회성 chat 답변에는 잘 맞지 않습니다.

agenthub skill 사용 방법

agenthub 설치와 repository 설정

Claude skills 환경에 다음 명령으로 skill을 설치합니다.

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

그다음 빈 폴더가 아니라 대상 project repository 안에서 사용하세요. agent를 생성하기 전에 repo가 clean 상태인지 확인하거나, uncommitted file 중 어떤 것이 baseline에 포함되어야 하는지 의도적으로 파악해 두어야 합니다. 구현을 먼저 확인하고 싶다면 SKILL.md부터 읽고, 이어서 다음 파일을 보세요.

• optimizer, refactorer, explorer 및 관련 dispatch style은 references/agent-templates.md.
• fan-out, tournament, ensemble workflow 선택 기준은 references/coordination-strategies.md.
• branch naming, frontier detection, merge behavior는 references/dag-patterns.md.
• 운영 세부 사항은 scripts/hub_init.py, scripts/board_manager.py, scripts/dag_analyzer.py, scripts/result_ranker.py.

명령어와 workflow

일반적인 agenthub 사용에서는 다음과 같은 slash command를 활용합니다.

• /hub:init: task, agent count, evaluation criteria, session을 정의합니다.
• /hub:spawn: 격리된 worktree에서 병렬 subagent를 실행합니다.
• /hub:status: 진행 상황과 branch 상태를 확인합니다.
• /hub:board: dispatch, progress, result note를 읽거나 작성합니다.
• /hub:eval: metric 또는 LLM judge로 결과물의 순위를 매깁니다.
• /hub:merge: winning branch를 merge하고 losing branch를 archive합니다.
• /hub:run: init, baseline, spawn, evaluate, merge를 한 번에 수행하는 one-shot lifecycle입니다.

수동으로 검증할 때는 포함된 script를 보면 기대되는 동작 방식을 확인할 수 있습니다. 예를 들어 hub_init.py는 task, agent count, evaluation command, metric, direction을 바탕으로 .agenthub/를 초기화할 수 있고, dag_analyzer.py는 frontier branch를 보여줄 수 있으며, board_manager.py는 progress/result post를 관리합니다.

막연한 목표를 좋은 prompt로 바꾸기

약한 prompt는 “Use agenthub to improve this app.”입니다. 더 좋은 prompt는 coordinator가 agent를 dispatch하고 평가하는 데 필요한 정보를 제공합니다.

Use agenthub for Agent Orchestration in this git repo.

Task: Reduce API p95 latency for `/search` without changing response schema.
Agents: 4
Template: optimizer
Evaluation command: `pytest tests/test_search.py && python bench/search_latency.py --json`
Metric: `p95_ms`
Direction: lower
Constraints:
- Keep public API compatibility.
- Do not add external services.
- Prefer small commits with clear explanations.
Success bar: at least 15% lower p95 with all tests passing.
After spawning, use the board to track each agent’s strategy and final result, then evaluate and recommend the winning branch before merge.

이 방식이 더 효과적인 이유는 각 agent가 목표, 측정 가능한 점수, 허용되는 변경 범위, 중단 조건을 명확히 알 수 있기 때문입니다.

실무 품질 팁

대부분의 session에서는 agent 2–5개를 사용하세요. repository의 coordination guidance에서도 그 이상은 수익 체감이 있다고 설명합니다. 가능하면 metric-based evaluation을 우선하세요. 주관적인 winner selection을 줄일 수 있습니다. 신뢰할 만한 command-line metric이 없는 문서 품질, content variant, research synthesis 같은 작업에만 LLM judge를 사용하는 것이 좋습니다. 큰 작업에서는 subtask가 정말 독립적일 때만 ensemble pattern을 고려하세요. 그렇지 않다면 fan-out/fan-in이 더 단순하고 안전합니다.

agenthub skill FAQ

agenthub는 coding task에만 쓰나요?

아닙니다. agenthub는 git 중심으로 동작하지만, 결과물이 repository 안에 있고 비교할 수 있다면 코드, 문서, prompt, research note, benchmark, content draft 모두 가능합니다. 여러 독립적인 시도가 의미 있게 다른 결과를 낼 수 있을 때 가장 가치가 큽니다.

agenthub는 일반 prompt와 어떻게 다른가요?

일반 prompt는 한 번의 model run에 task 해결을 요청합니다. agenthub skill은 여러 시도를 조율하고, worktree로 격리하며, board를 통해 진행 상황을 기록하고, branch 상태를 분석한 뒤 winner를 평가합니다. 단일한 직접 답변보다 탐색과 비교가 더 중요한 상황에서는 이 구조가 큰 차이를 만듭니다.

초보자도 agenthub skill을 사용할 수 있나요?

가능합니다. 다만 branch, commit, merge review 같은 기본 git 개념은 이해하고 있어야 합니다. 초보자는 /hub:run으로 시작하거나, agent 2개와 명확한 evaluation command를 사용하는 단순한 /hub:init session부터 시작하는 것이 좋습니다. 경쟁 branch를 검토하는 데 익숙해지기 전에는 tournament나 ensemble 전략으로 시작하지 마세요.

언제 agenthub를 쓰지 않는 것이 좋나요?

task가 너무 작거나, 원하는 답이 명확하거나, repo가 git으로 관리되지 않거나, evaluation criteria가 불분명하거나, 병렬 탐색의 이점보다 merge conflict 처리 비용이 더 클 때는 agenthub를 쓰지 않는 편이 좋습니다. 간단한 수정은 직접 prompt를 주고 일반적인 review를 거치는 방식이 더 빠릅니다.

agenthub skill 개선 방법

agenthub 실행 전 input 개선하기

agenthub 결과를 개선하는 가장 좋은 방법은 경쟁 조건을 정확히 정의하는 것입니다. task, 범위에 포함되는 file 또는 module, 제외 영역, agent count, template, evaluation command, metric name, metric direction, quality constraint, merge policy를 포함하세요. agent가 최적화를 수행한다면 baseline value를 제공하고, 초안을 작성한다면 rubric과 허용 가능한 output example을 제공하세요.

흔한 실패 모드 예방하기

흔한 문제로는 agent가 잘못된 metric을 최적화하거나, 서로 비교할 수 없는 결과를 만들거나, 가정을 덮어쓰거나, 좁은 benchmark는 통과하지만 더 넓은 test에서 실패하는 branch를 남기는 경우가 있습니다. 이를 막으려면 모든 agent가 같은 eval command를 실행하고, .agenthub/board/progress에 진행 상황을 post하며, .agenthub/board/results에 최종 결과를 작성하고, review 가능한 작은 commit을 유지하도록 요구하세요. 원점수보다 correctness가 더 중요하다면 “all tests must pass”를 constraint로 추가하세요.

첫 결과 이후 반복 개선하기

/hub:eval 이후에 무작정 merge하지 마세요. winning diff를 확인하고, losing agent의 result post를 읽고, 활용할 만한 부분 아이디어가 있는지 살펴보세요. winner가 좋지만 결정적이지 않다면, refined constraint를 적용해 winning branch에서 tournament-style second round를 실행하세요. 서로 다른 agent가 독립적인 다른 부분을 해결했다면 ensemble approach로 cherry-pick을 고려할 수 있지만, conflict와 test coverage를 확인한 뒤에만 진행해야 합니다.

support file을 운영 가이드로 활용하기

장기적으로 더 잘 사용하려면 repository의 support file을 playbook처럼 다루세요. orchestration pattern을 선택할 때는 references/coordination-strategies.md, task에 맞는 agent behavior를 고를 때는 references/agent-templates.md, branch/frontier logic을 이해할 때는 references/dag-patterns.md, automation에 의존하기 전에 skill file을 검증할 때는 scripts/dry_run.py를 사용하세요. 이렇게 하면 agenthub는 단순히 화려한 parallel-agent 아이디어가 아니라 반복 가능한 repository workflow가 됩니다.