파일 하나로 AI 직원 60명이 일한다는 말, 어디까지 사실일까요
파일 하나로 AI 직원 수십 명을 굴린다는 이야기를 본 분께 필요한 글입니다. 서브에이전트를 파일로 구성하는 방식이 공식 문서 기준으로 어디까지 가능한지 짚었습니다.
서브에이전트를 마크다운 파일로 정의하고 플러그인으로 묶는 것은 공식 문서로 확인됩니다. 다만 "60명"이라는 규모와 "알아서 일한다"는 자율성은 공식 문서로 확인되지 않는 부분이라, 그대로 믿기보다 나눠서 봐야 합니다.
내 프로젝트에서 반복되는 일을 역할별로 나눠 줘. 각 역할마다 서브에이전트 파일 초안(.claude/agents/ 폴더용)을 만들어 줘. - 파일 하나에는 역할 하나만 - 이름, 역할, 쓸 도구, 모델을 적기 - 작업 시작 전에 브리프(작업 지시서)부터 읽게 하기 만든 뒤 결과를 사람이 확인해야 하는 지점도 같이 알려 줘.
"파일 하나로 AI 직원 60명이 알아서 일한다"는 문장을 여러 번 봤습니다. "60명"이라는 구체적 수치와 실제 구성 방식은 공식 문서에서 확인되지 않습니다.
그래서 이 글은 특정 사례를 반박하는 대신, 파일 기반으로 여러 에이전트를 구성하는 것이 실제로 어디까지 가능한지를 공식 문서 기준으로 짚었습니다.
파일로 구성한다는 것 자체는 사실입니다
서브에이전트는 마크다운 파일로 정의됩니다. 공식 문서에 따르면 .claude/agents/(프로젝트용) 또는 ~/.claude/agents/(공용) 폴더에 파일을 만들면, 그 안에서 이름·역할·도구·모델을 지정할 수 있습니다.
플러그인(스킬·서브에이전트·훅·MCP 서버 설정 같은 것을 하나로 묶어 배포하는 단위)도 비슷한 구조입니다. 공식 문서는 플러그인 하나에 여러 서브에이전트와 자동 실행 규칙(훅)까지 담을 수 있다고 설명합니다.
그러니 "파일 몇 개로 여러 에이전트를 한 번에 구성한다"는 것 자체는 실제로 가능한 이야기입니다.
"60명"과 "알아서"가 걸리는 지점
다만 두 가지가 과장되기 쉽습니다.
첫째는 숫자입니다. 파일 하나에 60개의 서브에이전트 정의를 다 넣을 수 있는지, 실제로 그렇게 쓰는 게 실용적인지는 공식 문서에서 확인되지 않습니다. 서브에이전트는 보통 하나의 파일이 하나의 역할을 맡는 구조라, "파일 하나"라는 표현과 "60명"이라는 규모가 정확히 어떻게 연결되는지는 공식 문서만으로는 분명하지 않습니다.
둘째는 "알아서 일한다"는 표현입니다. 공식 문서는 여러 곳에서 사람의 확인과 구체적 지시가 필요하다는 점을 반복해서 안내합니다. Claude는 병렬 처리에 기본적으로 보수적이고, 요청이 구체적일수록 잘 작동한다는 설명이 대표적입니다. "알아서"라는 표현과는 결이 다릅니다.
우리 방식과 비교
저희도 서브에이전트 여러 개를 파일로 정의해 두고 씁니다. 다만 파일 하나에 몰아넣지 않고, 역할별로 파일을 나눕니다.
그리고 "브리프부터 읽게 한다"는 원칙을 정해 뒀습니다. 브리프(작업 지시서) 없이 그냥 풀어 두면 결과가 산으로 간다는 걸 겪어 봤기 때문입니다.
저는 처음엔 파일 몇 개만 잘 짜 두면 나머지는 알아서 될 줄 알았습니다. 실제로는 파일을 잘 짜는 것보다, 무엇을 시킬지 매번 구체적으로 정해 주는 쪽이 결과에 더 큰 영향을 줬습니다.
한계
자주 하는 실수
결과를 확인하는 사람 없이 "알아서" 돌아가게 두면, 잘못된 결과가 여러 단계를 거쳐 굳어질 위험이 있습니다. 서브에이전트 수가 늘어날수록 토큰(처리 비용 단위) 사용량도 함께 늘어난다고 공식 문서에 안내돼 있으니, 규모를 키우기 전에 확인 절차부터 두는 것이 좋습니다.
같은 자원(같은 파일 등)을 여러 에이전트가 동시에 건드리면 결과가 충돌할 수 있습니다. 역할별로 파일을 나누고, 맡는 범위가 겹치지 않게 정해 두는 편이 안전합니다.
자주 묻는 질문
파일 하나로 정말 여러 에이전트를 구성할 수 있나요?
서브에이전트를 파일로 정의하는 것, 플러그인으로 여러 요소를 묶는 것 모두 공식 문서로 확인됩니다. 다만 "파일 하나"에 몇 개까지 담는 게 실용적인지는 공식 문서에서 확인되지 않습니다.
정말 사람 개입 없이 알아서 돌아가나요?
공식 문서는 반복해서 사람의 확인과 구체적 지시가 필요하다고 안내합니다. "알아서"라는 표현과는 거리가 있습니다.
우리도 이렇게 구성해 볼 만한가요?
역할별로 서브에이전트를 나눠 파일로 정의하는 방식 자체는 유용합니다. 다만 규모를 키우기 전에 결과를 확인하는 절차부터 갖추는 게 순서입니다.
정리
파일로 여러 에이전트를 구성하는 것 자체는 사실입니다. "60명"이라는 규모와 "알아서 일한다"는 자율성은 공식 문서로 확인되지 않으므로 그대로 믿기 어렵습니다.