요즘 클로드 코드를 활용해 다양한 업무를 자동화하고 있다. 메인 세션 하나에서 요청을 보내면 작업 성격에 맞게 분류하여 전용 에이전트에게 전달하는 흐름을 만들고 싶었다.
그래서 CLAUDE.md 파일에 '요청 접수·위임 규칙'을 새로 추가했다. GAS 디버깅, 테마 수정, 키워드 관리, 수익 전략, 워크로그 기록 등 5개 전용 에이전트를 지정하고 일을 나눠 맡기기 시작했다.
위임 규칙 추가 후 발생한 사용량 폭발 문제
시스템을 구축하고 나니 생각지도 못한 지점에서 막혔다. 에이전트들이 분깃을 받아 실행될 때마다 매번 사전 맥락이 없는 상태로 깨어났다.
그러다 보니 에이전트가 단 한 줄의 수정 작업을 위해서도 용량이 큰 .gs 파일이나 테마 파일 전체를 통째로 뒤지기 일쑤였다. 메인 세션과 서브에이전트 간 대화가 늘어날수록 토큰 사용량이 그야말로 폭발적으로 치솟았다.
단순히 역할을 분담한다고 해서 작업이 효율적이지 않았다. 에이전트가 매번 전체 프로젝트 파일을 읽지 않도록 읽기 범위를 제한하는 대책이 시급했다.
.claude/자료지도.md 파일로 읽기 범위 고정하기
삽질 끝에 내가 선택한 첫 번째 해결책은 읽어야 할 파일의 위치를 지정해 주는 것이었다. 업무별로 참조해야 하는 파일만 딱 집어주는 '.claude/자료지도.md' 문서를 새로 작성했다.
그리고 5개의 서브에이전트가 첫 번째 단계에서 무조건 본인 전용 자료지도 항목만 읽고 작업을 시작하도록 연결했다.
이렇게 자료지도를 도입하자 에이전트가 소스코드 전체를 탐색하는 무의미한 탐색 과정이 사라졌다. 불필요한 파일 스캔이 줄어들면서 토큰 소모량도 크게 낮출 수 있었다.
위임 지시 템플릿과 요약 스냅샷 구축
파일 범위를 제한한 것 외에도 대화 맥락을 넘겨주는 방식 자체를 다듬었다. 메인 세션에서 서브에이전트로 넘길 때 구체적인 구조를 갖춘 '위임 지시 템플릿'을 적용했다.
위임 지시문에는 '목표, 알게 된 것, 자료, 하지 말 것, 완료 기준'이라는 5가지 요소를 요약해서 넘겨주도록 규격화했다. 이렇게 하니 에이전트가 이전 대화 기록 전체를 파악할 필요 없이 핵심 목표에만 즉시 집중할 수 있었다.
또한 기존 claude.ai 프로젝트에만 존재하던 색인 문제, GA4, 링크허브, 점검 로그 등의 자료가 걸림돌이었다. 이 자료들은 필요할 때마다 가져오기 어려워 요약 스냅샷으로 만들어 작업 폴더에 직접 복사해 두었다.
Notion 실데이터로 카테고리 설정 정정하기
위임 시스템을 정비하던 중 문서마다 IssueLog와 IT Story 카테고리가 서로 다르게 설정되어 있는 문제를 발견했다. 어떤 카테고리가 실제 노션에 반영되고 있는지 불명확해서 작동에 혼선이 생겼다.
이 문제를 바로잡기 위해 노션의 실제 데이터를 직접 확인하는 작업을 진행했다. 데이터베이스 필드명을 점검한 뒤 올바른 값으로 CLAUDE.md 내 관련 규정을 정확하게 정정했다.
결과적으로 잘못된 카테고리 분류로 인해 발생하던 위임 오류와 불필요한 다시 쓰기 작업을 깔끔하게 정리할 수 있었다.
에이전트 팀 운영의 핵심은 맥락 전달 비용
여러 AI 에이전트를 마치 하나의 팀처럼 나누어 돌려보면서 중요한 깨달음을 얻었다. 에이전트 다변화 과정에서 발생하는 진짜 비용은 모델 자체의 성능 차이가 아니라 '맥락 전달 비용'에 있었다.
아무리 똑똑한 에이전트라도 매번 아무 맥락 없이 전체 코드를 읽게 만들면 사용량 부담을 감당하기 어렵다. 자료지도와 명확한 위임 템플릿, 그리고 정돈된 스냅샷을 적절히 배치하는 것만으로도 작업 속도와 효율을 비약적으로 끌어올릴 수 있었다.