코딩 에이전트에는 기본적으로 하나의 성격이 있습니다. 바로 '유능한 제너럴리스트'입니다. 인증 흐름을 검토해 달라고 하면 그럴듯하지만 별로 기억에 남지 않는 조언을 내놓습니다. 반면 위협 모델과 체크리스트를 갖춘 보안 리뷰어에게 물어보면 실제 발견 사항이 나옵니다. 이 차이를 만드는 데 드는 비용은 마크다운 파일 하나뿐이며, 그래서 agency-agents가 149,312개의 스타를 받았습니다.
이 라이브러리는 정말로 유용합니다. 그런데 동시에 한 대의 머신에 놓인 파일 폴더일 뿐이고, 여러 사람이 역할을 쓸모 있게 만들고 싶어 하는 순간 한계가 됩니다. 이 글에서는 무엇을 얻을 수 있는지, 원하는 부분만 설치하는 방법, 그리고 역할 정의와 팀이 업무를 할당할 수 있는 Agent의 차이를 다룹니다.
TL;DR
이 글은 코딩 에이전트를 확장하는 오픈 소스 도구를 정리한 라운드업에서 다룬 다섯 개 심층 분석 중 하나입니다.
agency-agents는 약 20개 카테고리에 걸쳐 300개가 넘는 에이전트 역할 정의를 모아 놓은 컬렉션으로, MIT 라이선스이며, 명령어 하나로 Claude Code, Cursor, Codex, Gemini CLI, OpenCode 등 약 12개 이상의 도구에 설치할 수 있습니다. 각 파일에는 정체성, 작업 프로세스, 산출물, 그리고 완료 기준이 담겨 있습니다. 역할은 에이전트가 과제를 바라보는 틀을 바꾸지만, 에이전트가 갖지 못한 정보를 제공하지는 않으며 세션이 끝나면 사라집니다. 하나의 디비전을 설치하고, 여러분의 스택에 맞게 파일을 수정하고, 매주 손이 가는 역할은 팀이 할당할 수 있는 저장된 구성으로 승격하세요.
설치하게 되는 것
2026년 9월 1일 저장소 트리 기준으로, 20개의 최상위 카테고리 폴더 아래에 312개의 마크다운 파일이 있습니다. 저장소 README에는 여전히 "230+"라고 적혀 있는데, 이는 오래된 정보입니다.
| Division | Files | Division | Files |
|---|---|---|---|
| engineering | 59 | testing | 9 |
| specialized | 58 | paid-media | 7 |
| marketing | 36 | project-management | 7 |
| game-development | 21 | academic | 6 |
| integrations | 18 | spatial-computing | 6 |
| strategy | 16 | support | 6 |
| gis | 13 | finance | 5 |
| security | 12 | product | 5 |
| design | 10 | healthcare | 3 |
| sales | 9 | examples | 6 |
대부분의 팀이 시작하는 곳은 engineering 디비전이고, 여기 담긴 구체성은 일반적인 프롬프트 모음이 보통 도달하는 수준보다 훨씬 높습니다. Frontend Developer, Backend Architect와 함께 Cisco IOS-XE와 Juniper Junos를 다루는 Network Engineer, ESP32 및 STM32 타깃을 위한 Embedded Firmware Engineer, 포스트모템과 온콜 대응 준비를 담당하는 Incident Response Commander, 그리고 저장소를 읽기 전용으로 탐색하며 변경을 제안하기보다 사실을 서술하도록 작성된 Codebase Onboarding Engineer가 있습니다.
마지막에 언급한 역할이 이 패턴이 실제로 작동함을 보여줍니다. 편집 금지가 명시된 읽기 전용 역할은 기본 에이전트와는 다른 도구이며, 비용은 파일 하나뿐입니다.
필요한 것만 설치하기
git clone https://github.com/msitarzewski/agency-agents.git
cd agency-agents
./scripts/install.sh # interactive
./scripts/install.sh --tool claude-code --division engineering,security
./scripts/install.sh --tool cursor --agent frontend-developer
./scripts/install.sh --list teams
./scripts/install.sh --tool opencode --division engineering --dry-run
저장소에는 문서화되어 있지만 대부분의 글이 건너뛰는 경고가 하나 있습니다. OpenCode의 런타임은 약 119개의 에이전트만 등록하고 나머지는 조용히 버립니다. --division으로 일부만 설치하면 이 한도를 넘지 않을 수 있고, 선택한 범위가 한도를 넘으면 설치 프로그램이 경고합니다. 조용한 잘림 현상은 가능한 실패 모드 중 최악입니다. 원하던 역할이 빠져 있는데도 아무것도 알려주지 않기 때문입니다.
이 버그가 없더라도 300개를 전부 설치하는 것은 실수입니다. 기억할 수 없는 명단은 쓰지 않게 되는 명단입니다. 자신이 일하는 디비전을 설치하고, 파일 다섯 개를 읽고, 팀이 일하는 방식과 맞지 않는 것은 삭제하세요.
역할 정의가 멈추는 지점
역할은 하나의 틀입니다. 에이전트가 무엇을 찾아야 하는지, 어떤 형식으로 산출할지, 무엇을 완료로 간주할지 정합니다. 이는 들리는 것보다 가치가 큽니다. 에이전트 출력이 약해지는 이유는 대개 모델이 틀려서가 아니라, 모델이 잘못된 형태의 답을 향해 최적화하기 때문입니다.
역할이 할 수 없는 두 가지가 있습니다.
첫째, 모델이 갖고 있지 않은 정보를 제공할 수 없습니다. Backend Architect 역할은 추론한 인터페이스에 맞춰 잘 정돈된 코드를 만듭니다. 역할은 구조를 개선했지만, 결과를 정확하게 만들지는 못했습니다.
둘째, 세션 이후까지 남지 않습니다. 역할을 활성화하고, 작업을 수행하고, 터미널이 닫힙니다. 다음 날 다시 활성화 명령을 입력합니다. 이 저장소의 디비전 중 아홉 개는 조직 안에서만 존재하는 직무를 서술하는데, 그것을 설치하는 도구에는 조직이라는 개념 자체가 없습니다. 할당도 없고, 지난 화요일에 보안 리뷰어가 무엇을 찾았는지에 대한 기록도 없으며, 동료가 그것을 볼 방법도 없습니다.
역할 정의에서 할당 가능한 Agent로
역할 정의는 다시 입력해야 하는 프롬프트입니다. Sharkly의 Agent는 지침, 런타임, 스킬, 저장소, 환경을 담은 저장된 구성입니다. 이것이 ~/.claude/agents/ 안의 파일이 지향하는 것의 지속 가능한 버전입니다.
각 구성 요소는 저마다의 역할이 있습니다. Agent는 작업을 어떻게 처리해야 하는지 정의합니다. Computer는 호스트와 로컬 리소스를 제공합니다. Runtime은 팀이 이미 설치한 코딩 도구를 사용해 실제 에이전트 세션을 수행합니다. Task는 공유 기록으로 남습니다.
Sharkly는 Claude Code, Codex 또는 이 저장소의 역할들을 대체하는 것이 아닙니다. 그 주위에 공유 Task, Computer, 컨텍스트, 제어, 검토 계층을 더하는 것입니다. 모델 사용은 해당 도구에 구성된 구독이나 API 키를 통해 계속 이뤄집니다.
디비전 개념은 그대로 대응됩니다. Crew는 하나의 리더 Agent가 조율하는, 재사용 가능한 People과 Agents의 그룹입니다. Crew는 리더 우선 방식으로 실행됩니다. 리더가 Task 컨텍스트를 읽고, 어떤 멤버를 참여시킬지 결정하고, 그 결과를 하나의 Task로 다시 가져옵니다. 모든 전문가가 동시에 시작하는 방식이 아닙니다. 이것이 바로 agency-agents가 여덟 개의 디비전으로 암시하면서도 실행할 수 없는 것입니다. 파일 폴더에는 리더도 없고, 돌아갈 공유 Task도 없기 때문입니다.
실행, 장애 요소, 결과, 후속 논의는 Task 타임라인으로 돌아옵니다. 보안 리뷰어가 무엇을 찾았는지 누군가 묻는다면, 답은 Task에 있습니다.
저장소를 팀이 아니라 라이브러리로 사용하세요
혼자서 로컬에서 작업하고 오늘의 업무에 더 나은 틀을 원한다면 agency-agents를 바로 사용하세요. 디비전 하나를 설치하고, 파일을 읽고, 20분 안에 가치를 얻을 수 있습니다.
역할을 여러 사람이 재사용해야 하거나, 결과가 인정받기 전에 검토가 필요하거나, 석 달 뒤에 어떤 역할이 무엇을 왜 만들어냈는지 누군가 물어볼 상황이라면 저장된 Agent를 사용하세요. 기준은 팀 규모가 아닙니다. 역할이 세션보다 오래 살아남아야 하는지 여부입니다.
실용적인 워크플로는 저장소를 원재료로 취급하는 것입니다. 진짜로 재사용 가능한 부분인 파일 구조를 가져다가, 일반적인 내용은 여러분의 스택과 완료 기준으로 바꾸고, 일주일에 두 번 손이 가는 것은 저장된 구성으로 승격하세요. 좋은 파일들은 모두 같은 형태를 공유합니다. 정체성, 미션, 순서가 있는 프로세스, 형식을 갖춘 산출물, 성공 기준입니다. 7단계 프로세스를 갖춘 리뷰 역할은 세션을 넘나들며 일관된 결과를 냅니다. 그것이 없는 역할은 그날 모델이 끌리는 대로 아무거나 내놓습니다.
에이전트는 조사하고, 실행하고, 테스트하고, 보고합니다. 사람은 방향을 정하고, 권한을 부여하고, 결과를 받아들입니다.
자주 묻는 질문
agency-agents는 Claude Code 외의 도구에서도 작동하나요? 네. 변환 스크립트가 도구별 통합 파일을 생성하고, install.sh --tool로 하나를 지정합니다. Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Copilot, Windsurf, Aider, Kimi Code 등이 지원 대상입니다. macOS, Linux, Windows용 데스크톱 앱도 있습니다.
300개 역할을 모두 설치해야 하나요? 아닙니다. OpenCode에서는 할 수 없습니다. 약 119개만 등록되고 나머지는 경고 없이 버려지기 때문입니다. 다른 도구에서는 할 수는 있겠지만 대부분은 쓰지 않게 됩니다. 디비전 단위로 설치하세요.
역할이 에이전트를 더 유능하게 만드나요? 더 잘 이끌리게 만듭니다. 일관성과 출력 형식이 좋아집니다. 모델이 한 번도 가진 적 없는 사실에 대한 지식은 변하지 않습니다.
이것은 에이전트 프레임워크와 같은 건가요? 아닙니다. 프레임워크는 코드로 런타임 오케스트레이션을 제공합니다. agency-agents는 기존 에이전트의 동작 방식을 바꾸는 마크다운 파일을 제공합니다. 계층이 다르고 겹치는 부분도 없습니다.
Sharkly Skills와는 어떤 관계인가요? Skill은 Agent 구성에 붙이는 기능이라, 머신마다 다시 설치할 필요 없이 그 Agent와 함께 재사용됩니다. 이 저장소의 역할 정의는 Skill을 작성할 때 좋은 원재료가 됩니다.
요약
agency-agents는 하나의 아이디어에 대해 지금까지 나온 가장 좋은 구현입니다. 에이전트는 자신이 어떤 역할을 하는지 알 때 더 나은 일을 합니다. 디비전 하나를 설치하고, 파일을 읽고, 팀에 맞게 수정하세요.
그다음 경계를 분명히 하세요. 역할은 모델이 한 번도 받은 적 없는 사실을 알지 못하며, 팀이 보고 검토할 수 있는 어떤 것으로도 지속되지 않습니다. 명단은 좋은 시작입니다. 그것은 조직이 아닙니다. Sharkly가 나머지 절반을 담당합니다. Task는 공유 기록이고, 실행은 이미 비용을 지불하고 있는 런타임을 통해 연결한 Computer에서 이뤄지며, 결과는 사람이 검토하고 수락할 수 있는 곳으로 돌아옵니다.
