Gemini CLI 서브에이전트 실전 도입 가이드: 프롬프트를 더 길게 쓰기보다 작업 역할·컨텍스트 격리부터 분리해야 하는 이유

한 줄 문제 정의

핵심 요약: AI 코딩 CLI가 길게 일할수록 문제는 모델 성능보다 작업을 얼마나 잘 쪼개고 격리하느냐로 옮겨갑니다.

Gemini CLI로 큰 작업을 시키면 금방 부딪히는 문제가 있습니다. 메인 세션 하나에 조사, 코드 탐색, 문서 조회, 테스트 실행을 몰아넣으면 컨텍스트가 빨리 더러워지고, 중간 로그가 쌓이면서 판단이 흐려집니다. 특히 여러 파일을 동시에 건드리는 리팩터링이나 조사형 작업에서는 “잘 아는 척하지만 실제로는 문맥이 섞인 상태”가 가장 위험합니다.

이번 글은 2026년 4월 공개된 Gemini CLI 서브에이전트를 기준으로, 언제 단일 에이전트보다 서브에이전트를 써야 하는지, 어디까지 병렬화해야 하는지, 그리고 Codex식 장시간 작업과 비교하면 어떤 운영 기준이 필요한지를 실무 관점에서 정리합니다. 작은 일회성 수정이나 짧은 질의응답에는 오히려 과할 수 있다는 점도 함께 다룹니다.

먼저 결론

핵심 요약: 프롬프트를 더 길게 쓰는 것보다 역할·도구·컨텍스트를 분리하는 편이 더 안정적입니다.

Gemini CLI 서브에이전트는 코드베이스 조사, 문서 조회, 규칙 검토, 병렬 분석 같은 업무에서 특히 강합니다. 메인 에이전트는 목표와 최종 판단에 집중하고, 하위 에이전트는 분리된 컨텍스트 안에서 중간 작업을 처리하게 만드는 구조가 비용·속도·집중도 측면에서 유리합니다.

반대로 파일을 넓게 수정하는 병렬 코드 편집, 아직 작업 정의가 흐릿한 탐색 초반, 검증 체계 없이 “일단 많이 돌려보자” 식 운영에는 맞지 않습니다. 이런 경우에는 서브에이전트가 작업량을 줄여주기보다 충돌과 재작업을 늘릴 수 있습니다.

• 지금 바로 도입할 팀: 긴 코드 조사, 반복 검토, 멀티패키지 분석, 문서 기반 작업이 잦은 팀
• 조심해서 도입할 팀: 병렬 코드 수정이 잦고 검증 게이트가 약한 팀
• 아직 관찰이 나은 경우: 작업 대부분이 짧은 단일 파일 수정이거나, 에이전트 운영 기준이 전혀 없는 팀

핵심 구조 분해

핵심 요약: Gemini CLI 서브에이전트는 “보조 채팅창”이 아니라 분리된 실행 단위입니다.

Google이 2026년 4월 공개한 설명에 따르면, 서브에이전트는 각각 별도 컨텍스트 윈도우, 별도 시스템 지시, 선별된 도구 집합, 개별 MCP 서버 설정을 가질 수 있습니다. 메인 세션은 큰 목표를 잡고, 세부 작업은 하위 에이전트에 위임한 뒤 결과 요약만 다시 받아옵니다.

이 구조의 핵심은 중간 단계 전체를 메인 컨텍스트에 쌓지 않는다는 점입니다. 예를 들어 인증 흐름 조사, 테스트 실패 원인 분석, CLI 문서 조회를 한 세션에 모두 밀어 넣으면 메인 컨텍스트가 잡음으로 가득 찹니다. 서브에이전트는 이 중간 노이즈를 격리해 줍니다.

• 메인 에이전트: 목표 설정, 우선순위 판단, 최종 응답 작성
• 서브에이전트: 한정된 역할 안에서 조사·분석·실행
• 결과 전달 방식: 긴 로그 대신 요약된 응답으로 회수
• 관리 지점: @agent 호출, /agents 목록 확인, 전역/프로젝트별 .md 정의 파일

Google 문서 기준으로 내장 서브에이전트는 generalist, cli_help, codebase_investigator 등이 제공됩니다. 즉, 기능 추가보다도 역할 분리 운영이 먼저 내장된 셈입니다.

설계 의도 해설

핵심 요약: 서브에이전트의 목적은 “더 많은 에이전트”가 아니라 “메인 세션의 오염 방지”입니다.

Google은 서브에이전트의 장점으로 메인 세션을 빠르고 가볍게 유지하는 점을 직접 강조했습니다. 이는 단순 편의 기능이 아니라 비용과 신뢰성 문제를 같이 겨냥한 설계입니다. 메인 에이전트가 모든 검색 결과, 테스트 로그, 파일 조회 결과를 다 들고 있으면 이후 질문의 품질이 흔들리기 쉽습니다.

OpenAI가 2026년 2월 Codex 장시간 작업 사례에서 보여준 방향도 비슷합니다. 핵심은 “한 번에 똑똑한 프롬프트”보다 계획 → 실행 → 검증 → 복구 루프를 외부 상태와 문서로 고정하는 것이었습니다. Gemini CLI 서브에이전트는 같은 문제를 다른 방향에서 풉니다. Codex가 장시간 루프의 지속성을 강조했다면, Gemini는 문맥 분리와 전문가 위임을 전면에 둔 셈입니다.

즉, 둘의 차이는 모델 우열보다 운영 철학에 가깝습니다.

• Gemini CLI 서브에이전트: 역할 분리, 컨텍스트 격리, 병렬 조사
• Codex 장시간 작업: 장기 지속성, 명시적 계획 문서, 검증 루프

실무에서는 둘 중 하나만 택하기보다, 장기 작업에는 Codex식 상태 문서화, 세부 탐색에는 Gemini식 서브에이전트 분리를 함께 쓰는 편이 더 현실적입니다.

근거 및 비교

핵심 요약: 서브에이전트는 단일 프롬프트 확장보다 낫지만, 아무 병렬화나 허용하는 만능 해법은 아닙니다.

접근	언제 유리한가	장점	한계
단일 메인 에이전트에 전부 몰기	작고 짧은 작업	설정이 단순하고 시작이 빠름	컨텍스트 오염이 빠르고 중간 로그가 누적됨
Gemini CLI 서브에이전트	조사·분석·문서조회·병렬 탐색	컨텍스트 격리, 도구 제한, 역할 명확화	병렬 편집 시 충돌 가능, 사용량 증가
Codex 장시간 단일 러닝 세션	명세가 분명한 장기 구현 작업	계획-검증-복구 루프가 길게 유지됨	좋은 상태 문서와 검증 게이트가 없으면 드리프트 위험

Google의 Agent Bake-Off 회고에서는 멀티에이전트 구조를 도입한 팀이 처리 시간을 1시간에서 10분까지 줄인 사례를 소개합니다. 다만 같은 Google 문서도 병렬 서브에이전트가 무거운 코드 편집에는 충돌을 일으킬 수 있고 사용량 한도를 더 빨리 소진할 수 있다고 경고합니다. 즉, “병렬 = 무조건 빠름”이 아니라 읽기·분석 병렬화에 우선 적용하는 것이 맞습니다.

제 판단 기준은 아래 4가지입니다.

1. 작업 분리성: 서로 결과를 덮어쓰지 않고 독립적으로 끝낼 수 있는가
2. 검증 가능성: 각 하위 작업이 끝났는지 명확한 확인 기준이 있는가
3. 컨텍스트 민감도: 메인 세션에 중간 로그를 남기면 이후 품질이 떨어지는가
4. 재조합 비용: 여러 결과를 메인 에이전트가 다시 합치는 비용이 낮은가

실제 동작 흐름 / 단계별 실행 방법

핵심 요약: “바로 병렬 실행”보다 먼저 역할 파일부터 만든 뒤 읽기 중심 업무에 적용해야 합니다.

실무에서 가장 안전한 시작 방법은 프로젝트별 서브에이전트 정의를 먼저 고정하는 것입니다.

mkdir -p .gemini/agents
cat > .gemini/agents/codebase-investigator-lite.md <<'EOF'
---
name: codebase-investigator-lite
description: 인증 흐름과 의존성 경로만 조사하는 분석 전용 에이전트
tools:
  - read_file
  - grep_search
  - glob
  - list_directory
model: inherit
---

당신의 역할은 수정이 아니라 분석입니다.
인증 흐름, 환경변수 사용 위치, 외부 API 호출 경로만 정리하세요.
코드 수정 제안은 가능하지만 직접 편집은 하지 마세요.
EOF

그다음 메인 세션에서 아래처럼 씁니다.

@codebase-investigator-lite 로그인 이후 토큰 갱신 경로와 실패 시 분기 조건만 추적해 주세요.
결과는 파일 경로, 함수명, 위험 지점 3개 형식으로 요약하세요.

추천 도입 순서는 다음과 같습니다.

1. 읽기 전용 조사형 서브에이전트부터 만든다
2. 반복 질문이 많은 문서 전용 에이전트를 분리한다
3. 검증 스크립트 실행 전용 에이전트를 만든다
4. 마지막에만 제한적 병렬화를 붙인다

여기서 중요한 운영 습관은 두 가지입니다. 첫째, 수정 권한이 꼭 필요하지 않으면 도구를 열지 않는다. 둘째, 메인 에이전트는 최종 병합자 역할만 맡긴다. 이 구조가 잡히면 컨텍스트 낭비가 확실히 줄어듭니다.

실수/함정(Pitfalls)

핵심 요약: 실패의 대부분은 모델이 아니라 분리 기준이 모호해서 생깁니다.

1. 읽기 작업과 쓰기 작업을 같은 서브에이전트에 넣는 실수

분석 전용이어야 할 에이전트에 편집 도구까지 열어 두면, 조사 도중 성급한 수정이 섞입니다. 예방책은 간단합니다. 처음에는 읽기 도구만 열고, 수정은 별도 에이전트로 분리하십시오. 이미 섞였다면 해당 결과를 폐기하고 다시 조사하는 편이 낫습니다.

2. 병렬 편집을 너무 빨리 허용하는 실수

Google도 무거운 코드 편집의 병렬 실행은 충돌 위험이 있다고 경고했습니다. 여러 에이전트가 같은 모듈을 건드리면 충돌 해결 비용이 절약 시간보다 커집니다. 예방책은 “병렬은 읽기, 직렬은 쓰기” 원칙입니다.

3. 메인 에이전트가 다시 장황한 로그를 모두 끌어안는 실수

서브에이전트를 쓴 뒤 결과를 그대로 복붙해 다시 메인 세션을 더럽히면 효과가 사라집니다. 결과 포맷을 미리 제한해야 합니다. 예: 파일 경로 5개, 원인 3개, 추천 순위 1개.

4. 완료 기준 없이 위임하는 실수

“좀 살펴봐 주세요”는 사람에게도 나쁜 지시입니다. 에이전트에게는 더 나쁩니다. 반드시 범위, 출력 형식, 종료 조건을 같이 줘야 합니다.

강점과 한계

핵심 요약: 서브에이전트는 복잡성 제거 도구가 아니라 복잡성을 분산 관리하는 도구입니다.

강점은 분명합니다. 메인 세션이 덜 오염되고, 역할이 분리되며, 잘 설계하면 조사 속도가 빨라집니다. 특히 문서 조사, 코드베이스 매핑, 규칙 점검처럼 중간 산출물이 많은 작업에서 체감 차이가 큽니다.

하지만 한계도 분명합니다. 첫째, 정의 파일과 역할 설계를 게을리하면 그냥 “복잡한 호출 체계”가 됩니다. 둘째, 병렬 수를 늘릴수록 사용량과 통합 비용이 같이 증가합니다. 셋째, 장시간 구현을 안정적으로 끝내는 능력은 서브에이전트만으로 해결되지 않습니다. 그 부분은 OpenAI Codex 사례처럼 명세 문서, 계획 파일, 검증 명령, 상태 기록이 별도로 필요합니다.

즉, 서브에이전트는 컨텍스트 관리 계층이고, 장시간 완주력은 운영 루프 계층입니다. 둘을 혼동하면 기대 대비 실망이 커집니다.

더 깊게 공부할 포인트

핵심 요약: 기능 설명보다 운영 규칙 문서를 먼저 읽어야 실제 팀 적용이 됩니다.

• Gemini CLI 서브에이전트 문서에서 자동 위임, @호출, 도구 격리, 재귀 보호 항목을 먼저 확인하십시오.
• Google Agent Bake-Off 회고에서 멀티에이전트 분해, 프로토콜 사용, 결정론적 코드 실행 패턴을 읽으십시오.
• OpenAI Codex 장시간 작업 사례에서 spec / plan / implement / documentation 4문서 구조를 보십시오.
• 팀 적용 시에는 서브에이전트 정의 파일을 코드 리뷰 대상에 포함시키는 것이 좋습니다.

실행 체크리스트 + 작성자 관점

핵심 요약: 첫 주에는 기능 확장보다 역할 분리 규칙을 팀 표준으로 고정하는 것이 먼저입니다.

• 메인 에이전트가 맡을 일과 서브에이전트가 맡을 일을 문서로 분리했는가
• 조사형 에이전트에 편집 도구가 열려 있지 않은가
• 병렬 실행 대상이 서로 다른 파일·영역으로 분리되는가
• 각 서브에이전트의 출력 형식이 3~5줄 요약으로 제한되는가
• 검증 명령(lint, test, typecheck 등)이 메인 루프에 연결되어 있는가
• 실패 시 재시도보다 중단 후 재정의가 필요한 조건을 정했는가

Definition of Done: 최소 2개의 반복 조사 업무를 서브에이전트로 분리했고, 메인 세션 토큰/로그 오염이 눈에 띄게 줄었으며, 병렬 충돌 없이 같은 결과를 재현할 수 있는 상태.

제 추천은 명확합니다. Gemini CLI 서브에이전트는 “코딩을 더 많이 시키는 기능”이 아니라 “메인 세션을 덜 망치기 위한 운영 도구”로 도입해야 합니다. 그래서 첫 적용 대상은 코드 생성보다 조사·검토·문서 업무가 맞습니다. 반대로 “한 번에 여러 에이전트가 다 고쳐주겠지”라는 기대는 버리는 편이 좋습니다. 그 단계는 검증 체계가 갖춰진 뒤에야 열어야 합니다.

참고자료

• Google Developers Blog - Subagents have arrived in Gemini CLI (2026-04-15)
• Gemini CLI Docs - Subagents
• Google Developers Blog - Build Better AI Agents: 5 Developer Tips from the Agent Bake-Off (2026-04-14)
• OpenAI Developers - Run long horizon tasks with Codex (2026-02-23)