서브에이전트 22개에서 17개로: 늘리기는 쉬운데 줄이기는 왜 이렇게 어려울까
한 줄 요약
Claude Code로 여러 프로젝트를 굴리던 한 개발자가 필요할 때마다 서브에이전트를 하나씩 만들다 보니 어느새 22개까지 불어났고, 지난달 이를 17개로 정리한 경험을 공유했습니다. 핵심은 "에이전트를 줄이는 법"이 아니라 "왜 접었는지 기록해두지 않으면 3개월 뒤 아무도 모른다"는, 아주 현실적인 운영의 교훈입니다.
왜 22개까지 늘어났을까
늘릴 때는 이유가 항상 분명합니다. 지금 당장 필요하니까 만드는 거죠. 문제는 접을 차례가 됐을 때입니다. "혹시 나중에 쓸지도 몰라"라는 생각이 계속 발목을 잡고, 쓸모없다는 확신이 서지 않으니 그냥 놔두게 됩니다. 그렇게 쌓인 게 22개였습니다.
돌아보니 근본 원인은 하나였습니다. "이건 에이전트가 아니라 그냥 도구여야 하는데"를 판단하는 게이트가 없었던 것입니다. 절차가 고정돼 있고 맥락 판단이 필요 없는 반복 작업이라면, 그건 에이전트가 아니라 스킬이나 스크립트로 만들면 됩니다. 토큰도 안 쓰고, 재현성도 100%고, 세션이 바뀌어도 잊어버리지 않으니까요. 이 게이트가 없으면 결국 모든 게 에이전트로 만들어집니다.
접은 5개, 처분은 4가지 유형
정리 과정에서 처분 방식이 자연스럽게 네 갈래로 나뉘었습니다.
- 애초에 에이전트가 아니었어야 하는 것: 절차가 완전히 고정된 콘텐츠 작성 작업. 스킬 2개로 대체하고 "복원 금지"로 못박았습니다.
- 역할이 겹치는 것 (3개): 보안 점검-코드 감사, 크론 감시-헬스 체크, 기획-실행처럼 같은 영역·같은 권한을 가진 에이전트들. 여기서 얻은 기준이 인상적입니다. "둘 다 필요하긴 하다"는 감각이 아니라, 분리를 유지하는 관리 비용이 그 이득을 넘는지를 물어야 한다는 것입니다.
- 아무도 안 쓰는 것: 70일간 트래픽 0건. 이건 폐지가 아니라 "휴면" 처리해서, 서비스가 재개되면 그대로 복원할 수 있게 남겨뒀습니다.
숫자를 적을 때 배운 것
22 → 17이라는 숫자를 문서화하다가 재밌는 함정을 발견했습니다. 이 숫자는 파일 개수가 아니라 운용 중인 에이전트 수였는데, 디렉토리 밖에 정의된 것도 하나 있어서 파일만 세면 21과 16이 나옵니다. 그래서 문서 맨 앞에 "이 숫자가 무엇을 세는 숫자인지"부터 명시하고, git ls-tree로 검증한 결과까지 같이 남겼습니다. 숫자를 보고할 때는 정의와 검증 방법을 함께 적어야 나중에 "셈이 안 맞는데요"로 끝나지 않는다는 교훈입니다.
접을 때 지키기로 한 4가지 규칙
- 폐지 사유를 그 자리에서 파일에 기록한다 — 안 적으면 3개월 뒤 역산해야 합니다. 실제로 그랬습니다.
- 삭제 대신 rename으로 이동한다 — 내용이 100% 보존되어 원본 그대로 복원 가능합니다.
- 복원 금지 항목을 명시한다 — 안 적으면 언젠가 누군가 되살립니다.
- 복원 절차에 "흡수처의 중복 역할 제거"를 포함한다 — 이걸 빼먹으면 되살렸을 때 둘이 다시 같은 일을 하게 됩니다.
덤으로 공개된 4년치 운영 규칙
이번 정리를 계기로 저장소 전체 운영 원칙도 함께 공개됐습니다. 몇 가지만 짚어보면:
- 몰래 우회 금지: 제약에 막히면 뚫지 말고 보고하게 만듭니다. 오판으로 보이는 차단이어도 임의 우회 대신 근거를 정리해 확인을 받고, 차단이 규칙 자체의 결함이라면 그 결함을 고치는 것까지가 대응입니다.
- FAIL을 PASS로 쓰지 않는다: 실측 상태를 있는 그대로 적고 재오픈 조건을 남깁니다. 에이전트는 기본적으로 성공 보고를 하려는 압력을 받기 때문에, 규칙으로 막아둬야 합니다.
- 자율성을 정량 임계값으로 정의: "수정 허용/금지" 이분법 대신 1파일만, 5줄 미만, 상위 등급 파일 아님, 임팩트 점수 임계값 미만을 모두(AND) 충족해야 자율 수정을 허용합니다. 애매하면 무조건 위임 요청입니다.
- 판정과 집행의 분리: 검증·조사는 읽기 전용 서브에이전트로 병렬 처리하고, 실제 파일·DB 수정은 오케스트레이터가 중앙에서 직렬로 처리합니다. 느려지는 걸 알면서도 충돌보다는 낫다는 판단입니다.
왜 눈여겨볼 만한가
에이전트를 '늘리는' 이야기는 흔하지만 '줄이는' 이야기는 의외로 드뭅니다. 특히 혼자 만든 에이전트조차 3개월 뒤엔 왜 접었는지 기억이 안 났다는 대목은, 여러 개의 서브에이전트나 워크플로를 굴리고 있는 개발자라면 누구나 공감할 법한 지점입니다. 저장소는 마크다운 파일 몇 개로 구성되어 있어 설치 없이 .claude/agents/ 아래 템플릿을 두고 필요한 부분만 채우면 됩니다. 하나의 정답이라기보다 특정 환경에서 4년간 검증된 방식이니, 팀 규모나 프로젝트 성격에 맞게 취사선택하면 좋을 것 같습니다.