agency-agents의 마크다운 파일만으로 자율 에이전시가 만들어지는 것은 아니며 실제 실행과 도구 호출은 Claude Code나 Cursor 같은 호스트가 맡아야 합니다. 원문 기준 120여 개 역할 문서는 정체성, 역량과 의사결정 기준을 묶은 작업 명세에 가깝습니다. 따라서 이 저장소의 가치는 완성 실행 프레임워크보다 반복 업무의 역할 정의를 빠르게 가져와 검증하는 데 있습니다.
마크다운 직무 기술서만으로 서브 에이전트가 될까? agency-agents의 실제 역할
역할 문서가 해결하는 것은 실행보다 판단 기준이다
좋은 역할 문서는 세 층으로 읽을 수 있습니다. Identity는 담당 범위와 관점을 정하고, Capabilities는 사용할 수 있는 기술과 산출물을 적으며, Decision Framework는 품질과 위험 사이에서 무엇을 우선할지 정합니다. 같은 모델도 이 기준을 받으면 답변의 범위와 검토 순서가 더 일관돼집니다.
반면 파일 자체에는 프로세스를 띄우거나 작업을 배분하는 런타임이 없습니다. 서브 에이전트를 생성하고 문맥을 전달하며 결과를 합치는 기능은 사용하는 코딩 도구에 달려 있습니다. 그러므로 이 저장소를 “파이썬 없는 완성형 멀티 에이전트 프레임워크”로 소개하면 기대가 어긋납니다.
설치보다 먼저 저장소와 호스트의 연결 방식을 확인한다
본문에서 안내하는 프로젝트는 msitarzewski의 저장소이며, Claude의 에이전트 디렉터리를 연결하는 방식이 소개됩니다. 다만 사용자 홈 아래의 설정 경로는 호스트 버전과 설치 방식에 따라 달라질 수 있습니다.
따라서 원문의 복사 명령을 그대로 실행하기보다 세 가지를 먼저 확인해야 합니다. 실제로 받을 저장소가 어느 쪽인지, 현재 도구가 사용자 정의 에이전트를 어느 디렉터리에서 읽는지, 기존 설정과 같은 이름의 문서가 충돌하지 않는지입니다. Claude Code의 현재 구조는 원문에 있던 공식 문서와 대조하는 편이 안전합니다.
한 역할부터 평가해야 토큰 낭비를 볼 수 있다
처음부터 역할 120개를 모두 노출할 필요는 없습니다. 자주 반복되는 업무 하나를 골라 역할 문서 한 개를 연결하고, 일반 프롬프트와 결과를 비교하는 편이 낫습니다. 평가할 항목은 답의 길이보다 요구 사항 누락, 검토 기준의 일관성, 잘못된 도구 호출, 전달 과정에서 늘어난 토큰입니다.
여러 역할을 동시에 쓰면 전문성이 자동으로 합쳐지지 않습니다. 서로 다른 문서가 상충하는 기준을 내놓을 수 있고, 라우터가 잘못된 역할을 고르면 오히려 문맥만 길어집니다. 최종 결정을 내릴 한 역할과 중단 조건을 미리 정해야 합니다.
기억과 책임 경계는 저장소 밖에서 설계한다
이 문서들은 기본적으로 정적인 텍스트입니다. 과거 작업을 검색하는 벡터 메모리, 장기 상태, 권한 승인, 실행 기록은 별도 시스템이 담당해야 합니다. 세션이 바뀌면 무엇을 기억해야 하는지, 파일 수정이나 배포 전에 누가 승인하는지도 역할 문서만으로 해결되지 않습니다.
결론적으로 agency-agents는 직무별 프롬프트를 처음부터 쓰는 시간을 줄이는 참고 라이브러리로 보면 유용합니다. 자율 실행 플랫폼으로 기대하기보다, 사용 중인 호스트가 지원하는 기능과 한계를 확인한 뒤 필요한 역할만 골라 검증하는 것이 현실적인 도입 방법입니다.
역할 하나에는 무엇을 넣어야 할까
담당 범위, 필요한 입력, 만들어야 할 산출물, 판단 순서와 제외 조건을 분명히 적습니다. “보안 전문가”처럼 넓은 정체성만 주기보다 어떤 코드와 위협을 검토하고 무엇은 법률, 운영 담당자에게 넘길지 경계를 둡니다. 사용할 수 없는 도구나 확인할 수 없는 사실을 추측하지 말라는 실패 규칙도 필요합니다.
좋은 역할 문서는 말투보다 반복 가능한 검토 항목을 제공합니다. 같은 요청 묶음에서 일반 프롬프트와 역할 문서를 비교해 누락된 요구, 과도한 조언, 산출물 형식과 근거가 개선되는지 봅니다. 설명이 길어졌지만 실제 결정 기준이 늘지 않았다면 토큰만 추가된 것입니다.
여러 역할의 결과는 어떻게 합칠까
서브 에이전트마다 같은 문제를 독립적으로 풀게 할지, 순서대로 결과를 넘길지 먼저 정합니다. 병렬 검토는 서로 다른 관점을 얻을 수 있지만 중복 작업이 많고 상충 결론이 생길 수 있습니다. 순차 작업은 앞 단계의 오류가 뒤 역할로 전파될 수 있습니다. 역할 간 입력과 출력 계약을 명시해야 합니다.
최종 합성자는 의견 수로 결론을 고르기보다 근거, 담당 범위와 불확실성을 비교해야 합니다. 보안 역할이 차단을 권하고 제품 역할이 출시를 권할 때 누가 최종 위험을 승인하는지 사람 책임을 남깁니다. 각 결과의 출처를 유지해야 합성 과정에서 없는 합의가 만들어지지 않습니다.
권한은 역할 이름과 어떻게 분리할까
“데이터베이스 전문가”라는 문서가 있다고 실제 쓰기 자격 증명을 자동으로 줄 필요는 없습니다. 필요한 작업에서 읽기 전용 도구부터 제공하고 스키마, 환경을 제한합니다. 파일 수정, 명령 실행, 외부 메시지와 배포는 역할별 승인 규칙을 호스트에서 강제해야 합니다.
외부 문서나 이슈는 신뢰할 수 없는 입력이며 역할 지침보다 우선하지 않아야 합니다. 도구 호출 인수와 결과를 기록하고 금지된 경로, 명령이 실제로 차단되는지 시험합니다. 프롬프트에 “하지 마라”고 쓰는 것은 런타임 권한 격리를 대신하지 않습니다.
토큰과 품질은 어떤 표로 비교할까
같은 업무를 일반 프롬프트, 단일 역할, 여러 역할 구성으로 반복합니다. 요구 사항 충족률, 근거 오류, 사람 수정 시간, 읽은 문서와 호출 수를 함께 기록합니다. 여러 역할이 품질을 조금 올렸지만 비용과 합성 시간이 크게 늘면 중요한 검토 단계에만 제한할 수 있습니다.
역할 문서가 업데이트될 때는 변경 이유와 평가 사례를 함께 버전 관리합니다. 사용되지 않는 역할, 같은 책임을 가진 문서와 오래된 도구 예시를 제거합니다. 역할 수가 아니라 실제 작업에서 반복 가능한 판단과 검토 시간을 줄였는지가 성과입니다.
역할 문서는 언제 직접 고쳐야 할까
저장소의 문서는 범용 출발점이므로 팀의 코드베이스, 위험 수준과 승인 절차를 자동으로 알지 못합니다. 실제 도구 이름과 산출물 형식, 금지 작업이 다르면 원본을 그대로 복사하기보다 필요한 부분만 가져와 팀 문서로 관리합니다. 특정 모델의 말투나 오래된 제품 경로처럼 결과에 불필요한 내용은 줄일 수 있습니다.
수정 전후에 같은 요청 세트를 실행해 요구 누락과 잘못된 도구 선택이 실제로 줄었는지 확인합니다. 역할이 너무 많은 책임을 가지면 개발, 보안, 배포 결정을 한 문서에서 섞지 말고 검토 단계로 나눕니다. 반대로 항상 함께 쓰이는 작은 역할을 무리하게 분리하면 전달 토큰과 합성 오류만 늘 수 있습니다.
실패할 때는 어떤 정보를 남길까
에이전트가 필요한 파일이나 권한에 접근할 수 없고 근거가 부족한 경우에는 추측해서 산출물을 완성하지 않도록 합니다. 어떤 입력이 빠졌는지, 어디까지 확인했는지와 사람이 선택해야 할 내용을 구조화해 반환하게 합니다. 실패를 정상 결과처럼 장황하게 포장하면 다음 역할이나 합성자가 오류를 알아채기 어렵습니다.
도구 오류, 역할 라우팅 오류, 역할 지침 자체의 오류를 구분해 기록합니다. 올바른 역할이 선택됐지만 권한이 없어 실패한 경우와 엉뚱한 역할이 선택된 경우의 개선책은 다릅니다. 이 로그가 쌓이면 새 역할을 추가할지 기존 설명을 고칠지 판단할 수 있습니다.
함께 읽으면 이해가 이어지는 글
- pxpipe: AI 에이전트의 컨텍스트를 이미지로 변환해 토큰 비용을 줄이는 완벽 가이드 — pxpipe는 방대한 텍스트 컨텍스트를 고밀도 이미지(PNG)로 변환하여 LLM의 비전 채널을 통해 전달함으로써, 입력 토큰 비용을 최대 70%까지 절감하는 오픈소스 로컬 프록시 도구의 원리와 실전 활용법을 심층 분석합니다.
- OfficeCLI: AI 에이전트가 마이크로소프트 오피스 문서를 직접 읽고 쓰는 원리와 구조 — AI 코딩 에이전트가 Microsoft Office 없이도 Word, Excel, PowerPoint를 완벽하게 제어할 수 있게 해주는 C# 기반의 단일 바이너리 도구, OfficeCLI의 아키텍처와 작동 원리를 깊이 있게…
- 컨텍스트 문제는 압축, 검색, 메모리 중 무엇일까? 스킬 선택 순서 — 긴 작업의 실패를 지시 손실, 검색 과부하, 메모리 오염으로 나누고, Agent Skills for Context Engineering에서 맞는 절차를 고르는 순서를 안내합니다.
자주 묻는 질문
agency-agents 저장소만 설치하면 여러 에이전트가 자동으로 협업하나요?
아닙니다. 저장소는 역할 지침 모음이며 에이전트 생성, 도구 호출, 작업 배분과 결과 합성은 Claude Code나 Cursor 같은 호스트가 담당해야 합니다.
120여 개 역할을 모두 한 번에 노출하는 것이 좋은가요?
대부분의 경우 필요하지 않습니다. 후보가 많으면 라우팅 충돌과 토큰 비용이 늘 수 있으므로 자주 쓰는 역할 하나부터 결과를 비교하며 확대하는 편이 좋습니다.
역할 문서가 있으면 별도 권한 설정이 필요 없나요?
필요합니다. 역할 문서는 행동 기준이지 런타임 보안 경계가 아니므로 파일, 명령, 외부 시스템 권한과 승인 규칙은 호스트에서 별도로 제한해야 합니다.
표지 1 —
←→ 키와 좌우 스와이프를 지원합니다. 읽던 페이지는 이 기기에 저장됩니다.
이 기사는 저작권자의 CC BY 4.0 라이센스를 따릅니다.