무엇인가
The Agency(저장소 이름 agency-agents)는 전문 분야가 뚜렷한 AI 에이전트 정의를 부서(division)별로 모아 둔 오픈소스 저장소입니다. 2025년 가을 레딧 r/ClaudeAI에 올라온 "AI를 만능 도우미 하나가 아니라 전문가 캐릭터로 나눠 쓰면 어떨까"라는 글에서 시작했습니다. 코어닷투데이가 다룬 2026년 7월 기준으로 에이전트 232개, 부서 16개, GitHub 별 12만 2천 개였습니다.
에이전트 하나는 마크다운 파일 하나입니다. 프론트엔드 개발자, 펜테스터, 레딧 커뮤니티 빌더, 그리고 Reality Checker(현실 점검관)·Whimsy Injector(엉뚱함 주입기) 같은 이름의 파일이 한 명의 "취업 명세서" 역할을 합니다. README는 이것을 "개발자처럼 행동해 줘 같은 두루뭉술한 프롬프트가 아니라, 성격과 프로세스를 갖춘 깊은 전문화"라고 설명합니다.
어떻게 동작하나
에이전트 파일은 공통 골격을 따릅니다.
성격은 장식이 아니라 압축된 행동 제약입니다. "코드 리뷰해 줘"보다 "문제를 3~5개 반드시 찾고 증거를 요구하는 점검관"이 출력을 더 일관되게 묶습니다.
팀으로 엮는 방법은 엔지니어링 부서의 Multi-Agent Systems Architect 파일이 따로 정리합니다. 에이전트 팀을 분산 시스템처럼 다루라는 관점이고, 다섯 가지 위상(topology)을 비교합니다.
| 위상 | 언제 쓰나 | 주된 위험과 규칙 |
|---|---|---|
| 순차 사슬 | 리서치 → 초안 → 검토 → 발행처럼 선형인 일 | 한 단계가 죽으면 전체가 멈춘다. 사슬은 5개 이하, 에이전트 사이엔 구조화된 출력 |
| 병렬 팬아웃/팬인 | 독립적인 관점 여러 개를 동시에 | 부분 결과 처리 필수. 병렬 폭은 7개 이하 |
| 계층형(오케스트레이터-서브에이전트) | 하위 작업이 미리 정해지지 않은 복잡한 일 — 기본값 | 오케스트레이터 병목. 작업 원장을 두고 서브에이전트 결과는 요약으로 받는다 |
| 평가자-최적화자 | 점수로 잴 수 있는 반복 개선 | 무한 루프. 최대 횟수를 걸고 생성자와 평가자를 다르게 둔다 |
| 메시(피어) | 협상·합의가 꼭 필요할 때만 | 컨텍스트 폭발과 교착. 중재자와 종료 조건 필수 |
이 파일은 위상 외에도 컨텍스트 예산("필수 맥락을 조용히 잘라내지 말고, 안 들어가면 멈추고 사람에게 넘겨라"), 실패 분류와 폴백 사슬, 회로 차단기, 에이전트별 최소 권한, 외부 콘텐츠를 적대적으로 다루는 프롬프트 인젝션 방어, 사람 개입 게이트(신뢰도 0.7 미만 등)를 다룹니다. README와 examples/에는 이 부품들을 조합한 시나리오(4주 스타트업 MVP, 마케팅 캠페인 등)가 있습니다.
빠른 시작
README가 가장 먼저 권하는 길은 데스크톱 앱(Agency Agents)입니다. macOS에서는 Homebrew로 깔 수 있습니다.
brew install --cask msitarzewski/agency-agents/agency-agents
명령줄로 Claude Code에 설치하려면 저장소를 받아 설치 스크립트를 돌리거나, 필요한 부서만 복사합니다.
git clone https://github.com/msitarzewski/agency-agents && cd agency-agents
./scripts/install.sh --tool claude-code # 전체
./scripts/install.sh --tool claude-code --division engineering,security # 부서만
cp engineering/*.md ~/.claude/agents/ # 직접 복사
그다음 Claude Code 세션에서 "Frontend Developer 모드로 React 컴포넌트를 만들어 줘"처럼 부릅니다. Cursor·Codex·Gemini CLI·OpenCode·Aider·Windsurf 등 다른 도구용 파일은 ./scripts/convert.sh로 만든 뒤 ./scripts/install.sh --tool <도구>로 설치합니다.
에이전트 파일 머리말은 이런 모양입니다(Multi-Agent Systems Architect 원문).
---
name: Multi-Agent Systems Architect
emoji: 🕸️
description: Systems architect specializing in the design, coordination, and governance of multi-agent AI pipelines — covering topology selection, context management, inter-agent trust, failure recovery, human-in-the-loop gating, and observability for production-grade agent systems.
color: cyan
vibe: Treats a team of AI agents like a distributed system — if it only survives the demo and not production load, ambiguous inputs, and cascading failures, it isn't architecture yet.
---
언제 쓰고, 언제 피하나
- 잘 맞는다: 서브에이전트를 처음 설계할 때 역할 정의의 본보기가 필요할 때, 리뷰·QA·보안처럼 관점이 분명한 검증 역할을 따로 두고 싶을 때, 같은 정의를 여러 코딩 도구에서 함께 쓰고 싶을 때(평문 마크다운이라 14개 이상의 도구로 변환된다). 멀티 에이전트 설계를 공부하는 교재로도 좋다 — Architect 파일의 "기본값은 계층형" 결론은 2025~2026년 업계가 수렴한 오케스트레이터 + 격리된 서브에이전트 구조와 같다.
- 다른 방법을 먼저 본다: 일이 파일 두세 개 고치는 수준이면 에이전트를 나눌 이유가 없다. 전부 설치하기보다 필요한 부서와 에이전트만 고른다. 위상·폴백·권한 같은 아키텍처는 이 저장소가 대신 만들어 주지 않는다 — 에이전트 정의를 주는 것이지 오케스트레이션 런타임이 아니다.
한계와 주의
- 규모 수치는 시점마다 다르다. 2026년 7월 코어닷투데이 기사 기준 232개·16개 부서·별 12만 2천 개였고, 2026-10-24 확인 시 부서 목록(
divisions.json)은 Healthcare·Research가 더해져 18개, 별은 약 16만 3천 개다. 개수를 인용할 때 날짜를 함께 적는다. - OpenCode는 약 119개만 등록하고 나머지를 조용히 버린다(README가 밝힌 상류 버그).
--division으로 일부만 설치한다. - "사슬 5개 이하", "병렬 7개 이하", "신뢰도 0.7" 같은 수치는 실무 경험칙이다. 에이전트 파일이 제시한 기준이지 실험으로 검증된 값이 아니다.
- 페르소나가 사실 정확도를 보장하지 않는다. 성격은 행동을 묶는 장치이고, 사실 확인은 검색·도구·별도 검증 에이전트에 맡긴다.
- 한국어 커뮤니티 번역판(jnMetaCode/agency-agents-ko)은 원본 에이전트 184개를 번역한 독립 저장소라 원본과 버전이 어긋날 수 있다.
