Google은 2026년 4월 15일 Gemini CLI subagents를 발표했고, 각 subagent가 독립 context window, system instruction, tool set, MCP server를 가질 수 있다고 설명했다.
처음엔 이게 그냥 “Gemini CLI도 이제 여러 에이전트 돌린다” 정도로 보인다.
근데 운영자 입장에서 보면 포인트가 조금 다르다.
핵심은 병렬 실행 자체가 아니다.
핵심은 메인 세션의 context를 얼마나 깨끗하게 지키고, 어떤 작업을 격리된 전문가에게 넘기며, 그 전문가에게 어떤 도구만 줄지 정하는 일이다.
그래서 이 글은 출시 뉴스 요약이 아니다.
subagent 좋다에서 끝내면 너무 얇다.
진짜 질문은 이거다.
Gemini CLI subagents를 언제 쓰면 context 오염을 줄이고, 언제 쓰면 usage limit과 편집충돌만 더 빨리 맞을까?
나는 이 기능을 속도 기능보다 운영 분리 기능으로 먼저 본다.
속도는 따라오는 보너스다.
분리 기준이 없으면 보너스보다 사고가 먼저 온다.
특히 코드베이스에서 병렬 subagent를 바로 켜는 순간, “빨라졌다”와 “누가 뭘 덮어썼지?”가 한 화면에 같이 뜰 수 있다.
운영자는 여기서 웃으면 안 된다.
웃긴 한데, 일단 로그부터 봐야 한다.
한 줄로 먼저 적으면 이렇다.
Gemini CLI subagents는읽기·조사·분석·검증처럼 context를 분리할수록 좋아지는 작업에 먼저 쓰고,동시에 같은 파일을 고치는 작업에는 ownership과 제한을 정한 뒤 써야 한다.
지금 답
Gemini CLI subagents는 큰 작업을 작은 전문가 작업으로 나누는 기능이다.
공식 발표와 문서 기준으로 subagent는 독립된 context loop를 가진다.
각 subagent는 별도 system prompt와 persona를 가질 수 있다.
도구도 제한하거나 특화할 수 있다.
MCP 서버도 subagent별로 붙일 수 있다.
메인 Gemini agent는 자동으로 subagent를 고르거나, 사용자가 @agent 문법으로 특정 subagent를 강제로 지정할 수 있다.
기본 내장 subagent도 있다.
공식 문서는 codebase_investigator, cli_help, generalist를 주요 built-in으로 설명한다.
발표 글은 generalist, cli_help, codebase_investigator를 바로 쓸 수 있는 built-in으로 소개했다.
subagent 정의 파일은 Markdown 파일이다.
YAML frontmatter로 이름, 설명, 도구, 모델, 실행 제한을 적는다.
프로젝트 공유용은 .gemini/agents/*.md에 둔다.
개인용은 ~/.gemini/agents/*.md에 둔다.
여기까지 보면 꽤 예쁘다.
문제는 병렬 실행이다.
공식 발표도 병렬 subagent가 여러 요청을 동시에 보내므로 usage limit에 더 빨리 닿을 수 있다고 경고한다.
또 무거운 코드 편집 작업에서 여러 agent가 동시에 수정하면 충돌이나 덮어쓰기가 생길 수 있다고 적는다.
그러니까 도입 순서는 단순하다.
- 읽기 전용 조사 subagent부터 만든다.
- 편집 권한은 나중에 준다.
- 병렬 편집은 파일 ownership을 먼저 나눈다.
/agents list와/stats model로 상태와 사용량을 본다.- 같은 파일을 만질 가능성이 있으면 병렬보다 순차가 낫다.
왜 context 분리가 핵심인가
AI 코딩 세션이 길어질수록 성능을 갉아먹는 건 모델 하나만이 아니다.
대화 기록도 무거워진다.
중간 조사도 쌓인다.
터미널 출력도 들어온다.
실패한 접근도 남는다.
그 상태에서 다음 의사결정을 시키면, 모델은 본론보다 잡음을 같이 들고 간다.
이걸 나는 context 오염이라고 본다.
Gemini CLI subagents는 이 문제를 꽤 정면으로 건드린다.
subagent가 깊은 코드 탐색을 한다.
파일을 많이 읽는다.
테스트 로그를 본다.
여러 tool call을 실행한다.
그리고 최종 요약만 메인 agent로 돌려준다.
그러면 메인 세션은 “어떤 결정을 할지”에 집중하기 쉬워진다.
이 구조는 특히 TECHTAEK식 운영 글감과 잘 맞는다.
우리가 실제로 에이전트 워크플로를 굴릴 때도, 탐색과 수정과 검증을 한 대화에 다 넣으면 금방 탁해진다.
처음엔 편하다.
한 창에서 다 되니까.
근데 시간이 지나면 질문 하나가 느려지고, 답변 하나가 길어지고, 모델이 방금 정한 기준을 다시 묻는다.
그때 필요한 건 더 큰 모델이 아니라 역할 분리일 때가 많다.
subagent의 첫 가치는 여기 있다.
메인 agent는 목표, 우선순위, 최종 판단을 잡는다.
subagent는 제한된 작업을 수행한다.
끝나면 요약만 남긴다.
이게 잘 되면 context가 정돈된다.
안 되면 agent만 늘고 혼란도 늘어난다.
멋진 기능인데, 잘못 쓰면 책상 위에 서류철만 다섯 개 더 생기는 느낌이다.
서류철은 늘었는데 누가 결재하는지 모르면, 그건 자동화가 아니라 사무실 미로다.
공식 구조를 짧게 풀면
공식 Google Developers Blog는 subagent를 전문 agent로 설명한다.
메인 Gemini CLI 세션이 넓고 복잡한 작업을 받으면, 적절한 subagent에 하위 작업을 위임하는 구조다.
각 subagent는 별도 context window를 가진다.
각 subagent는 자체 system instruction을 가진다.
각 subagent는 자체 tool set을 가질 수 있다.
각 subagent는 자체 MCP server 구성을 가질 수 있다.
subagent 실행은 독립적으로 진행된다.
그리고 실행 결과는 하나의 응답으로 메인 agent에 돌아온다.
이 말은 운영적으로 꽤 중요하다.
subagent의 중간 삽질은 메인 세션을 덜 더럽힌다.
반대로 말하면, subagent가 뭘 했는지 추적하려면 요약 품질과 로그 습관이 더 중요해진다.
자동 위임도 가능하다.
Gemini CLI는 subagent 설명을 보고 적절하다고 판단하면 자동으로 호출할 수 있다.
명시 위임도 가능하다.
사용자는 프롬프트 앞에 @codebase_investigator처럼 agent 이름을 붙일 수 있다.
공식 문서는 이 @ 문법을 특정 subagent를 바로 쓰고 싶을 때의 방법으로 설명한다.
예를 들면 이런 식이다.
@codebase_investigator Map out the authentication flow.
이건 사소해 보이지만 실무에서는 꽤 크다.
자동 라우팅은 편하다.
명시 라우팅은 재현성이 좋다.
블로그 파이프라인, 코드 리뷰, 장애 분석처럼 같은 흐름을 반복하려면 명시 라우팅이 더 낫다.
왜냐하면 나중에 “어떤 전문가에게 맡겼는지”가 프롬프트에 남기 때문이다.
built-in 3종을 어떻게 봐야 하나
처음부터 custom agent를 만들 필요는 없다.
공식 발표 기준으로 Gemini CLI에는 바로 쓸 수 있는 built-in subagent가 있다.
첫째는 codebase_investigator다.
이 agent는 코드베이스 탐색, 아키텍처 매핑, 버그 원인 분석, 시스템 의존성 이해에 맞다.
처음 시도하기 가장 좋은 타입이다.
이유는 간단하다.
대부분 읽기 중심 작업이기 때문이다.
읽기 중심 작업은 병렬로 돌려도 사고 확률이 낮다.
예를 들어 인증 흐름을 조사하게 한다.
결제 모듈 의존성을 조사하게 한다.
테스트 실패 원인을 추적하게 한다.
이런 일은 메인 agent의 context를 많이 먹지만, 파일을 바로 덮어쓰지 않아도 된다.
그래서 codebase_investigator는 첫 주차 테스트용으로 좋다.
둘째는 cli_help다.
이 agent는 Gemini CLI 자체 문서와 기능을 묻는 용도다.
CLI 옵션, 설정, command reference, subagent 구성 같은 질문을 분리해서 던질 수 있다.
이것도 사고 확률이 낮다.
실무에서는 의외로 이런 agent가 유용하다.
새 기능을 쓰다가 메인 작업이 자꾸 문서 찾기로 새면 흐름이 끊긴다.
그때 문서 확인만 cli_help에 넘기면 메인 세션이 덜 흔들린다.
셋째는 generalist다.
공식 문서는 이 agent를 넓은 작업, 많은 단계, 큰 출력, multi-file modification 같은 작업에 적합하다고 설명한다.
여기서부터는 조심해야 한다.
generalist는 강력하다.
하지만 강력하다는 말은 보통 권한도 넓다는 뜻이다.
특히 여러 파일 수정, refactor, 테스트 실행처럼 많은 행동을 할 수 있는 agent는 꼭 ownership이 필요하다.
어떤 파일을 만질 수 있는지 정해야 한다.
어떤 명령을 실행해도 되는지 정해야 한다.
어디서 멈춰야 하는지 정해야 한다.
그 기준 없이 @generalist 이거 다 고쳐줘를 여러 개 날리면, 빠른 협업이 아니라 빠른 혼란이 된다.
괜히 멀티에이전트가 멋있어 보이는 날일수록, 제일 먼저 파일 범위를 적어야 한다.
손이 여러 개면 설거지도 빨라지지만, 싱크대 하나에 다 몰리면 그냥 물난리다.
custom subagent 파일은 팀 계약서다
custom subagent는 Markdown 파일로 정의한다.
공식 문서 기준으로 파일은 YAML frontmatter로 시작해야 한다.
본문은 agent의 system prompt가 된다.
위치는 두 곳이다.
프로젝트 공유용은 .gemini/agents/*.md다.
개인용은 ~/.gemini/agents/*.md다.
팀에서 쓸 agent는 프로젝트 안에 두는 편이 낫다.
그래야 코드와 함께 리뷰된다.
누가 어떤 agent를 쓸 수 있는지 보인다.
수정 이력도 남는다.
개인용 agent는 나만 쓰는 습관, 개인 조사 루틴, 개인 문체 도우미에 더 잘 맞는다.
예시를 아주 작게 줄이면 이런 모양이다.
---
name: docs-reader
description: Read official documentation and return a concise operator summary. Use this for docs lookup before implementation.
kind: local
tools:
- read_file
- grep_search
- web_fetch
model: inherit
max_turns: 8
timeout_mins: 5
---
You read official docs first.
Return only verified facts, links, risks, and one recommended next action.
Do not edit files.
여기서 중요한 건 멋진 persona가 아니다.
description이다.
공식 문서도 main agent가 subagent description을 보고 관련성을 판단한다고 설명한다.
description이 흐리면 agent가 잘 안 불린다.
description이 너무 넓으면 아무 데나 불린다.
둘 다 문제다.
좋은 description은 세 가지를 포함한다.
언제 쓰는지.
무엇을 잘하는지.
무엇을 하지 않는지.
특히 마지막이 중요하다.
Do not edit files 같은 금지 문장은 생각보다 운영 비용을 많이 줄인다.
agent에게 하지 말아야 할 일을 안 적으면, 언젠가 해준다.
AI는 친절해서 문제다.
친절한데 권한까지 넓으면, 그날은 커피가 더 필요해진다.
도구 제한은 선택이 아니라 기본값이다
subagent가 독립 context를 가진다는 말은 좋다.
하지만 context만 분리하고 도구를 전부 열어두면 반쪽짜리다.
공식 Gemini CLI 문서는 subagent 도구 격리를 설명한다.
frontmatter의 tools 목록으로 agent가 쓸 수 있는 도구를 제한할 수 있다.
mcpServers 객체로 subagent 전용 MCP 서버를 붙일 수도 있다.
도구 wildcard도 있다.
*는 전체 도구 접근이다.
mcp_*는 모든 MCP 도구 접근이다.
특정 MCP 서버 도구만 여는 패턴도 가능하다.
하지만 처음부터 wildcard를 쓰는 건 권하지 않는다.
특히 팀 환경에서는 더 그렇다.
처음 subagent는 읽기 도구만 준다.
그 다음 grep, file read, docs fetch 정도를 준다.
shell 실행은 따로 분리한다.
write 권한은 마지막에 준다.
MCP 서버는 더 천천히 붙인다.
왜냐하면 MCP는 외부 시스템과 이어지는 경우가 많기 때문이다.
문서 서버 정도면 괜찮다.
이슈 트래커, 배포 시스템, 데이터베이스, 결제, 클라우드 콘솔이면 완전히 다른 얘기다.
subagent별 MCP 서버는 강력한 구조다.
하지만 강력한 구조일수록 “이 agent가 이 서버를 왜 가져야 하지?”라는 질문을 남겨야 한다.
답이 없으면 빼는 게 맞다.
도구를 줄이면 agent가 답답해 보인다.
근데 운영은 답답함을 조금 사고, 사고 확률을 크게 줄이는 게임이다.
답답한 agent는 고칠 수 있다.
권한이 넓어서 이미 밀어버린 파일은 마음이 조금 아프다.
usage limit은 병렬에서 빨리 온다
Gemini CLI 공식 발표는 병렬 subagent의 장점을 분명히 말한다.
여러 topic 조사나 서로 다른 component refactor를 동시에 맡기면 전체 시간이 줄 수 있다.
그런데 바로 이어서 경고도 한다.
병렬 subagent는 요청을 동시에 보내므로 usage limit에 더 빨리 닿을 수 있다.
이 문장은 실사용에서 꽤 중요하다.
AI 도구 비용 사고는 보통 한 번의 큰 요청에서만 오지 않는다.
작은 요청이 동시에 많이 나가도 온다.
특히 subagent는 중간 tool call, 파일 검색, 테스트 실행, 재질문을 각자 수행할 수 있다.
메인 세션에서 보면 “한 번 맡겼다”처럼 보인다.
하지만 실제 사용량은 subagent 수만큼 갈라져 늘어난다.
공식 quota 문서는 인증 방식별 일일 요청 제한도 제시한다.
Google account 기반 Gemini Code Assist Individual은 하루 1,000 requests로 설명되어 있다.
Gemini API key unpaid free tier는 하루 250 requests로 설명되어 있다.
Google AI Pro, Ultra, Workspace Code Assist 계층은 더 높은 한도를 제공한다.
단, 요청은 사용자별 분당 제한도 있고, 서비스 수요 상황의 영향을 받을 수 있다고 문서가 말한다.
그러니까 병렬 subagent를 켜기 전에 질문해야 한다.
이 작업은 5명이 동시에 뛰어야 할 만큼 급한가?
아니면 1명이 잘 읽고 요약해도 되는가?
코드 수정 전에 조사만 병렬화해도 충분한가?
무료 계정으로 실험 중인가?
팀 계정이나 유료 계정의 사용량 모니터링이 붙어 있는가?
Gemini CLI 문서는 /stats model로 현재 session token usage와 quota 관련 정보를 볼 수 있다고 설명한다.
병렬 작업 전후로 이걸 확인하는 습관이 필요하다.
subagent가 잘못됐다는 뜻이 아니다.
병렬은 좋다.
다만 병렬은 공짜 점심이 아니다.
먹는 속도가 빨라질 뿐, 계산서는 온다.
편집충돌은 기능 문제가 아니라 운영 문제다
공식 발표의 또 다른 경고는 편집충돌이다.
무거운 코드 편집 작업에서 여러 agent가 동시에 수정하면 conflict나 overwrite가 생길 수 있다는 내용이다.
이건 Gemini CLI만의 문제가 아니다.
Claude Code subagents든, Codex worker든, 사내 AI agent든 같은 문제가 나온다.
코드베이스는 공유된 물리 공간이다.
agent가 context를 따로 가져도 파일 시스템은 하나다.
여기서 사고가 난다.
agent A가 src/auth.ts를 수정한다.
agent B도 같은 파일을 수정한다.
agent C는 테스트를 고치면서 import를 바꾼다.
각자 자기 context에서는 말이 된다.
하지만 합쳐 보면 한쪽 변경이 다른 쪽 전제를 깨뜨린다.
그래서 병렬 편집의 기본 규칙은 ownership이다.
파일 ownership이 있어야 한다.
모듈 ownership이 있어야 한다.
역할 ownership이 있어야 한다.
그리고 merge 전 검수 ownership도 있어야 한다.
가장 단순한 분리표는 이렇다.
| 작업 | 병렬 subagent 적합도 | 이유 | 권장 제한 |
|---|---|---|---|
| 코드베이스 구조 조사 | 높음 | 읽기 중심이고 context가 커짐 | read, grep, list 중심 |
| 공식 문서 확인 | 높음 | 메인 흐름을 덜 끊음 | web_fetch, docs 요약 |
| 테스트 로그 분석 | 중간 | 출력이 길고 반복 가능 | 명령 실행 제한 |
| 서로 다른 패키지 수정 | 중간 | ownership이 나뉘면 가능 | 패키지 단위 파일 범위 |
| 같은 파일 동시 수정 | 낮음 | overwrite와 conflict 위험 | 순차 처리 |
| 배포·삭제·계정 작업 | 매우 낮음 | 외부 영향이 큼 | 별도 승인 |
이 표가 재미없어 보여도, 실제로는 이런 표가 팀을 살린다.
AI 자동화에서 제일 위험한 문장은 “알아서 나눠서 해줘”다.
알아서 나누면 멋져 보인다.
근데 나중에 누가 뭘 했는지 모르면 그건 팀워크가 아니라 추리물이다.
추리물은 주말에 보는 걸로 충분하다.
처음 도입할 때의 순서
내 기준으로 Gemini CLI subagents는 아래 순서로 넣는 게 제일 안전하다.
첫째, built-in agent부터 확인한다.
/agents list로 현재 agent 목록을 본다.
문서 기준으로 이 명령은 built-in, local, remote agent를 보여준다.
새 custom agent를 만들기 전에 이미 있는 도구를 확인하는 게 먼저다.
둘째, codebase_investigator를 읽기 전용 작업에 써본다.
예를 들어 “인증 흐름을 지도처럼 설명해줘” 같은 요청이다.
수정하지 말라고 명시한다.
결과는 파일 목록, 주요 함수, 의존성, 모르는 점으로 받는다.
셋째, cli_help로 Gemini CLI 설정 질문을 분리한다.
subagent 설정, /agents reload, usage 확인, policy 관련 질문을 메인 작업에서 떼어낸다.
넷째, custom docs-reader 같은 작은 agent를 만든다.
도구는 읽기와 web fetch 정도만 준다.
본문 system prompt에는 공식 문서 우선, 추측 금지, 수정 금지를 적는다.
다섯째, 팀 공유 agent는 .gemini/agents/에 둔다.
이 파일은 코드처럼 리뷰한다.
description 변경도 리뷰한다.
tools 변경은 더 꼼꼼히 리뷰한다.
여섯째, 병렬 실행은 조사 작업에서만 시작한다.
예를 들어 3개 패키지의 구조 조사 정도다.
각 subagent는 읽기만 한다.
메인 agent가 결과를 모아 판단한다.
일곱째, 편집 subagent는 한 번에 하나부터 시작한다.
여기서 바로 병렬 편집으로 넘어가면 마음이 급한 거다.
급한 마음은 보통 좋은 설계자가 아니다.
여덟째, usage를 확인한다.
/stats model로 session 사용량을 본다.
무료 계정인지, 유료 계정인지, API key인지, Workspace인지도 같이 확인한다.
아홉째, 실패 로그를 남긴다.
subagent가 잘못 불렸다면 description을 고친다.
너무 많이 불렸다면 description을 좁힌다.
도구가 부족했다면 하나만 더한다.
도구가 과했다면 줄인다.
열째, 팀 rule로 승격한다.
이 단계까지 통과하면 그제야 “우리 팀에서 이 subagent는 이런 작업에 쓴다”라고 문서화한다.
처음부터 멋진 agent 팀을 만들려고 하지 않아도 된다.
작은 agent 하나가 제대로 굴러가면 그게 더 강하다.
작고 얌전한 agent는 귀엽다.
그리고 운영에서는 귀여운 쪽이 오래 산다.
@agent 위임을 언제 쓰나
자동 위임은 편하다.
하지만 반복 가능한 workflow에는 명시 위임이 더 낫다.
@agent 문법은 이런 상황에서 쓰면 좋다.
첫째, 결과를 재현해야 할 때다.
예를 들어 매번 codebase_investigator로 구조를 먼저 읽고, 그 다음 main agent가 수정 계획을 세우게 할 수 있다.
둘째, main agent가 자꾸 엉뚱한 도구를 쓰는 경우다.
명시적으로 전문가를 지정하면 라우팅 흔들림이 줄어든다.
셋째, prompt 자체를 운영 기록으로 남기고 싶을 때다.
@security-auditor Read only. Find risks in auth files.라고 남기면 나중에 의도를 알 수 있다.
넷째, 새 subagent를 테스트할 때다.
자동 호출만 기다리면 description이 잘 작동하는지 판단하기 어렵다.
처음엔 명시 호출로 품질을 본다.
다섯째, 작업 경계를 강하게 주고 싶을 때다.
예를 들어 이렇게 쓸 수 있다.
@docs-reader Read the official Gemini CLI subagents docs.
Return only verified configuration fields, limits, and open questions.
Do not edit files.
또는 이렇게 쓸 수 있다.
@codebase_investigator Map the payment module.
Read only.
Return files, call graph, risk points, and tests to inspect.
반대로 이런 요청은 위험하다.
@generalist Fix everything related to auth and update all tests in parallel.
이 문장은 너무 넓다.
범위가 넓다.
권한도 넓다.
완료 기준도 흐리다.
무엇보다 “everything”은 대부분의 자동화에서 사고 예약어다.
everything을 쓰고 싶어지는 순간, 커피 한 모금 마시고 범위를 줄이는 게 낫다.
custom agent를 만들 때 적을 것
custom subagent 파일에는 최소한 아래 항목을 넣는다.
name은 짧고 정확해야 한다.
공식 schema 기준으로 name은 agent tool name으로 쓰이는 고유 식별자다.
소문자, 숫자, hyphen, underscore를 쓰는 편이 안전하다.
description은 라우팅의 핵심이다.
main agent가 이 설명을 보고 언제 호출할지 판단한다.
그래서 “helpful assistant” 같은 설명은 거의 도움이 안 된다.
kind는 local 또는 remote다.
대부분 처음에는 local이면 충분하다.
remote subagent나 A2A는 도입 난도가 더 높다.
tools는 가급적 좁게 시작한다.
read, grep, list 정도로 시작하고 필요할 때 늘린다.
mcpServers는 정말 그 agent만 써야 하는 서버가 있을 때 붙인다.
문서 검색 agent라면 문서 MCP만 붙인다.
DB 분석 agent라면 읽기 전용 DB proxy부터 생각한다.
model은 inherit로 시작해도 된다.
특정 agent가 더 싸거나 더 빠른 모델로 충분하면 나중에 나눈다.
temperature는 분석·검수 agent에선 낮게 둔다.
창의적 글쓰기 agent라면 다르게 볼 수 있다.
max_turns는 꼭 본다.
공식 문서는 기본값을 30으로 설명한다.
작은 docs-reader가 30턴까지 갈 필요는 없다.
timeout_mins도 중요하다.
무한히 물고 늘어지는 agent는 귀엽지 않다.
실무에서는 timeout이 친절이다.
나는 agent 파일을 만들 때 아래 질문을 붙이는 편이 좋다고 본다.
이 agent는 어떤 입력을 받는가?
이 agent는 무엇을 절대 하지 않는가?
이 agent는 어떤 형식으로 끝내는가?
이 agent가 실패하면 사용자는 무엇을 봐야 하는가?
이 네 개가 없으면 agent라기보다 분위기 좋은 프롬프트 조각에 가깝다.
프롬프트 조각은 시작은 쉬운데, 팀에 들어오면 이름표가 자꾸 떨어진다.
subagent별 policy를 봐야 하는 이유
Gemini CLI 문서는 subagent-specific policy도 설명한다.
Policy Engine의 TOML 설정에서 특정 subagent에만 rule을 적용할 수 있다는 내용이다.
예를 들어 pr-creator라는 agent에게만 git push를 허용하는 식이다.
반대로 특정 subagent 자체를 deny할 수도 있다.
이건 팀 환경에서 꽤 중요하다.
왜냐하면 “전체 Gemini CLI는 허용하지만 특정 agent는 막는다”가 가능해지기 때문이다.
모든 agent에게 같은 권한을 주면 관리가 쉽다.
하지만 관리가 쉽다는 말이 항상 안전하다는 뜻은 아니다.
조사 agent에게 push 권한은 필요 없다.
문서 agent에게 shell 권한도 대체로 필요 없다.
테스트 runner에게 네트워크 권한은 상황에 따라 필요 없을 수 있다.
policy는 이런 차이를 코드화하는 장치다.
처음 개인 실험에서는 과해 보일 수 있다.
하지만 팀 공유 agent가 늘어나면 policy가 없을수록 사람이 기억해야 할 규칙이 많아진다.
사람이 기억해야 하는 규칙은 바쁠 때 깨진다.
바쁜 날 깨지는 규칙은 원래 규칙이 아니라 소원에 가깝다.
그래서 agent를 팀에 공유할 거라면 적어도 이런 기준은 남긴다.
읽기 전용 agent는 write 도구를 갖지 않는다.
리뷰 agent는 수정하지 않는다.
수정 agent는 파일 범위를 받지 않으면 멈춘다.
push agent는 별도 승인이나 policy를 요구한다.
브라우저나 외부 서비스 agent는 allowed domain과 action limit을 둔다.
이건 멋있어서 하는 게 아니다.
나중에 “왜 이 agent가 이걸 했지?”를 줄이기 위한 최소 보험이다.
Claude Code subagents와 비교해서 보는 기준
이 글을 TECHTAEK에 쓰는 이유는 단순하다.
Gemini CLI subagents는 Google 생태계 소식이지만, 문제 구조는 Claude Code subagents와 비슷하다.
context를 분리한다.
전문 역할을 만든다.
도구 권한을 제한한다.
여러 agent를 병렬로 돌릴 수 있다.
그리고 운영 기준이 없으면 느려지거나 꼬인다.
이미 TECHTAEK에서는 Claude Code subagents 늘릴수록 왜 더 느려질까 2026에서 context 분리와 ownership 문제를 다뤘다.
Gemini CLI도 같은 기준으로 보면 편하다.
도구 이름은 다르다.
설정 파일 위치도 다르다.
기본 agent 구성도 다르다.
하지만 운영 질문은 같다.
누가 읽는가?
누가 고치는가?
누가 검수하는가?
누가 최종 판단하는가?
누가 비용을 확인하는가?
누가 실패하면 멈추는가?
이 질문에 답이 없으면 subagent가 늘어도 생산성이 안정적으로 늘지 않는다.
처음 하루는 빨라진다.
둘째 날은 뿌듯하다.
셋째 날부터 “이 변경 누가 했더라”가 나온다.
그래서 Gemini CLI subagents도 Claude Code처럼 ownership이 먼저다.
agent 이름보다 파일 범위가 먼저다.
persona보다 완료 기준이 먼저다.
parallel보다 merge 규칙이 먼저다.
이 순서를 지키면 subagent는 꽤 좋은 도구가 된다.
이 순서를 건너뛰면 subagent는 매우 성실한 혼란 제조기가 된다.
성실한 혼란은 더 무섭다.
쉬지도 않고 혼란을 만든다.
읽기 전용부터 시작해야 하는 이유
첫 custom subagent는 읽기 전용이 좋다.
이건 겁이 많아서가 아니다.
학습 데이터가 깨끗해지기 때문이다.
읽기 전용 agent는 실패해도 피해가 작다.
잘못 요약하면 다시 물어보면 된다.
파일을 안 건드렸으니 복구도 쉽다.
게다가 좋은 읽기 전용 agent는 나중에 수정 agent의 input이 된다.
예를 들어 이런 흐름이다.
@codebase_investigator가 구조를 읽는다.- 메인 agent가 변경 계획을 세운다.
- 수정 agent 하나가 좁은 파일 범위만 고친다.
- 검수 agent가 diff를 읽는다.
- 메인 agent가 최종 판단한다.
이 구조는 느려 보인다.
하지만 실제로는 사고를 줄인다.
특히 큰 코드베이스에서는 조사와 수정을 섞지 않는 것만으로도 많은 문제가 줄어든다.
조사 agent는 “이 파일도 볼까요?”라고 넓어진다.
수정 agent는 “그럼 고쳐볼게요”라고 움직인다.
둘을 같은 agent에 넣으면 읽다 고치고, 고치다 읽고, 어느 순간 작업 범위가 커진다.
그래서 처음엔 역할을 쪼갠다.
docs-reader.
codebase-reader.
test-log-reader.
security-reviewer.
이런 agent들이 먼저다.
이들이 충분히 안정되면 그 다음에 writer나 fixer를 만든다.
subagent는 능력치 게임이 아니다.
권한 배치 게임이다.
권한을 잘 배치하면 작은 agent도 일을 잘한다.
권한을 잘못 배치하면 큰 agent가 크게 흔든다.
병렬 실행을 켜도 되는 작업
병렬 subagent가 빛나는 작업은 있다.
첫째, 독립된 조사다.
예를 들어 frontend, backend, infra 세 영역의 구조를 각각 읽게 하는 경우다.
각 agent는 자기 영역만 본다.
결과는 같은 템플릿으로 반환한다.
메인 agent가 합친다.
둘째, 후보 비교다.
예를 들어 세 개 라이브러리의 공식 문서를 각각 읽고 장단점을 정리하게 한다.
이런 작업은 서로 파일을 건드리지 않는다.
속도 이점이 크다.
셋째, 대량 로그 요약이다.
테스트 로그, 빌드 로그, CI 로그를 범위별로 나눠 읽게 할 수 있다.
단, 명령 실행은 제한해야 한다.
넷째, 서로 다른 패키지의 읽기 전용 audit이다.
package A, B, C를 각각 점검하게 한다.
각 agent는 수정하지 않는다.
위험 지점만 보고한다.
다섯째, 문서화 초안 비교다.
같은 기능을 product docs, ops runbook, release note 관점으로 나눠 초안을 받는 건 괜찮다.
서로 같은 파일을 수정하지 않으면 위험이 낮다.
반대로 병렬 실행을 늦춰야 하는 작업도 있다.
공통 타입 파일 수정.
shared config 수정.
database migration 수정.
auth, billing, permission 같은 민감 영역 수정.
대량 rename.
formatter와 refactor가 같이 들어가는 작업.
이런 건 한 agent가 끝낸 뒤 검수하고 다음 agent로 넘기는 게 낫다.
병렬은 모든 문제의 답이 아니다.
병렬은 독립성이 높을 때만 답에 가까워진다.
독립성이 낮은데 병렬을 켜면, 속도가 아니라 충돌 확률을 병렬화한다.
이건 별로 사고 싶지 않은 상품이다.
Gemini CLI subagents 도입 전 체크리스트
아래 항목 중 7개 이상에 답할 수 있으면 도입해도 된다.
답이 5개 이하면 built-in 읽기 전용 agent부터 써보는 게 낫다.
- 이 subagent의 입력은 무엇인가?
- 이 subagent의 출력 형식은 무엇인가?
- 이 subagent가 절대 하지 말아야 할 일은 무엇인가?
- 이 subagent에게 필요한 최소 도구는 무엇인가?
- write 권한이 정말 필요한가?
- shell 권한이 정말 필요한가?
- MCP 서버가 정말 필요한가?
- 이 agent는 프로젝트 공유용인가, 개인용인가?
- agent 정의 파일은
.gemini/agents에 둘 것인가? - description은 자동 라우팅에 충분히 구체적인가?
@agent로 명시 호출할 대표 prompt가 있는가?- 병렬 실행 시 파일 ownership이 나뉘는가?
- usage limit을 확인할 방법이 있는가?
- 실패했을 때 멈추는 조건이 있는가?
- 결과를 누가 검수하는가?
- 메인 agent가 최종 판단을 유지하는가?
내 기준에서 가장 중요한 건 세 가지다.
도구 제한.
파일 ownership.
usage 확인.
이 세 개가 없으면 subagent 도입은 아직 이르다.
아니, 기능은 쓸 수 있다.
근데 팀 운영으로 쓰기엔 덜 익었다.
덜 익은 자동화는 겉보기엔 신선하지만, 배포 직전에 배가 아프다.
실제 workflow 예시
예를 들어 큰 repo에서 로그인 오류를 잡는다고 해보자.
나쁜 흐름은 이렇다.
@generalist Find and fix the login bug. Run in parallel if needed.
이 요청은 넓다.
조사, 수정, 테스트, 판단이 섞여 있다.
파일 범위도 없다.
병렬 조건도 없다.
좋은 흐름은 이렇게 나눈다.
@codebase_investigator Read only.
Map the login flow from route to session creation.
Return files, call graph, likely failure points, and tests to run.
그 다음 메인 agent가 계획을 세운다.
Based on the investigator report, propose a 3-step fix plan.
Do not edit files yet.
Include file ownership and test commands.
그 다음 수정은 좁힌다.
@generalist Edit only src/auth/session.ts and src/auth/session.test.ts.
Implement step 1 and step 2 from the approved plan.
Do not touch routes or shared config.
마지막은 검수다.
@codebase_investigator Read the diff only.
Check whether the change matches the approved plan.
Flag missing tests or risky side effects.
Do not edit files.
이 흐름은 길어 보인다.
하지만 실제로는 훨씬 추적 가능하다.
누가 읽었는지 보인다.
누가 고쳤는지 보인다.
어디까지 고쳤는지 보인다.
검수가 분리된다.
그리고 메인 agent가 최종 판단을 유지한다.
subagent는 팀원이다.
팀원에게 일감을 줄 때도 “그냥 다 해줘”보다 “이 범위 맡아줘”가 낫다.
AI라고 갑자기 조직론이 사라지지 않는다.
오히려 더 필요해진다.
실수 TOP 7
첫 번째 실수는 subagent를 너무 많이 만드는 것이다.
agent가 많아질수록 멋져 보인다.
하지만 description 품질이 낮으면 라우팅이 흔들린다.
처음엔 2개면 충분하다.
docs-reader와 codebase-reader 정도다.
두 번째 실수는 모든 agent에게 모든 도구를 주는 것이다.
* wildcard는 편하다.
하지만 편한 권한은 나중에 비용이 된다.
세 번째 실수는 병렬을 기본값으로 두는 것이다.
병렬은 옵션이다.
기본값은 순차가 낫다.
네 번째 실수는 usage limit을 안 보는 것이다.
subagent가 여러 개면 요청도 여러 갈래로 나간다.
무료 tier나 개인 계정에서는 특히 빨리 체감된다.
다섯 번째 실수는 같은 파일을 여러 agent에게 맡기는 것이다.
이건 공식 발표가 직접 경고한 지점이다.
파일 ownership 없이 병렬 편집하면 conflict나 overwrite 위험이 올라간다.
여섯 번째 실수는 결과 형식을 안 정하는 것이다.
subagent가 긴 서사를 반환하면 메인 context가 다시 무거워진다.
요약, 파일 목록, 리스크, next action처럼 고정 형식이 필요하다.
일곱 번째 실수는 실패 조건을 안 적는 것이다.
권한이 없으면 멈춘다.
파일 범위가 없으면 묻는다.
테스트가 실패하면 수정하지 않고 보고한다.
이런 조건이 있어야 agent가 안정된다.
실수 대부분은 모델 문제가 아니다.
운영 계약 문제다.
계약이 흐리면 똑똑한 agent도 애매하게 움직인다.
애매한 자동화는 진짜 은근히 무섭다.
아무 일도 안 한 것 같은데, 뭔가 바뀌어 있다.
작은 팀에서의 추천 세팅
개인 또는 2-3명 팀이면 처음 세팅은 아주 작게 간다.
프로젝트에는 .gemini/agents/docs-reader.md 하나를 둔다.
또는 .gemini/agents/codebase-reader.md 하나를 둔다.
둘 다 읽기 전용으로 시작한다.
tools는 read, grep, web fetch 정도로 제한한다.
max_turns는 8-12 정도로 둔다.
timeout_mins는 5-10 정도로 둔다.
출력 형식은 네 줄로 고정한다.
verified facts.
files inspected.
risks.
recommended next action.
그 다음 팀 문서에 대표 prompt를 남긴다.
예를 들면 이렇다.
@docs-reader Read the official docs for this feature.
Return only verified facts, constraints, and open questions.
Do not suggest implementation until the facts are listed.
그리고 아래 규칙을 둔다.
읽기 agent는 수정하지 않는다.
수정 agent는 파일 범위를 요구한다.
병렬 수정은 기본적으로 금지한다.
병렬 조사는 허용한다.
usage는 작업 전후로 확인한다.
이 정도면 충분히 시작할 수 있다.
처음부터 remote subagents, A2A, policy까지 전부 깔 필요는 없다.
물론 팀이 커지면 필요해진다.
하지만 작은 팀은 작게 시작하는 게 진짜 이득이다.
자동화도 근육이다.
처음부터 100kg 들면 멋있어 보이지만, 내일 문 손잡이도 못 잡는다.
큰 팀에서의 추천 세팅
큰 팀은 조금 다르게 봐야 한다.
subagent 파일은 코드 리뷰 대상이 되어야 한다.
tools 변경은 보안 리뷰 대상이 되어야 한다.
MCP 서버 추가는 별도 승인 대상이 되어야 한다.
policy 파일은 agent 이름 기준으로 나눠야 한다.
프로젝트 agent와 개인 agent를 구분해야 한다.
remote subagent는 운영 ownership이 있어야 한다.
usage monitoring도 팀 단위로 봐야 한다.
특히 유료 tier나 pay-as-you-go를 섞는 팀은 비용 추적이 중요하다.
공식 quota 문서는 pay-as-you-go에서 token/call 기반 비용이 생길 수 있고, 많은 작은 call이 비용을 만들 수 있다고 설명한다.
subagent 병렬은 바로 이 지점과 연결된다.
작은 call이 많이 생긴다.
여러 agent가 동시에 움직인다.
한 사람이 실행했지만 사용량은 팀 예산에 찍힌다.
그래서 큰 팀에서는 agent마다 예산 태그나 로그 관례가 필요하다.
예를 들어 prompt 첫 줄에 작업 ID를 넣는다.
agent 결과에 작업 ID를 다시 남기게 한다.
PR description에 어떤 agent를 썼는지 적는다.
테스트 실행 agent와 수정 agent를 분리한다.
deploy agent는 별도 승인 없이는 만들지 않는다.
이건 귀찮다.
하지만 큰 팀의 자동화는 귀찮음을 줄이는 게 아니라, 위험한 귀찮음과 안전한 귀찮음을 바꾸는 일에 가깝다.
안전한 귀찮음은 체크리스트다.
위험한 귀찮음은 장애 회고다.
둘 중 하나만 골라야 한다면, 나는 체크리스트를 고른다.
장애 회고는 커피가 맛없어진다.
Gemini CLI subagents와 Gemini in Chrome Skills는 다르다
이름에 Gemini가 같이 붙어도 용도는 다르다.
이전에 쓴 Gemini in Chrome Skills 2026는 브라우저 안에서 반복 프롬프트를 재사용하는 쪽에 가깝다.
Gemini CLI subagents는 터미널 기반 작업에서 역할과 context를 나누는 쪽에 가깝다.
Chrome Skills는 “반복 prompt를 workflow로 승격할지”가 핵심 질문이다.
CLI subagents는 “작업자를 분리하고 권한을 어디까지 줄지”가 핵심 질문이다.
둘 다 자동화를 편하게 만든다.
하지만 위험 위치가 다르다.
Chrome Skills는 탭 context, 브라우저 권한, 반복 prompt 품질을 봐야 한다.
CLI subagents는 파일 시스템, shell, MCP, usage limit, merge conflict를 봐야 한다.
그래서 둘을 같은 기준으로 묶으면 안 된다.
브라우저 반복 작업은 사용자 흐름이 중요하다.
CLI subagent 작업은 repo 상태와 권한 경계가 중요하다.
이 차이를 모르면 “Gemini 자동화”라는 큰 단어에 다 뭉개진다.
뭉개지면 판단이 흐려진다.
흐려진 판단은 보통 tool을 더 붙인다.
그리고 tool을 더 붙이면 더 흐려진다.
이 순환은 생각보다 중독성이 있다.
그래서 일부러 기능별로 경계를 그어야 한다.
언제 아직 안 써도 되나
Gemini CLI subagents를 안 써도 되는 경우도 많다.
작은 파일 하나 고치는 작업이면 필요 없다.
문서 한 페이지 요약이면 필요 없다.
실험 repo에서 단발성으로 수정하는 작업이면 필요 없다.
사용량 제한이 빡빡한 계정으로 급한 일을 하는 중이면 필요 없다.
agent description을 관리할 사람이 없으면 아직 이르다.
팀이 파일 ownership을 안 나누는 문화라면 병렬 편집은 더 이르다.
MCP 서버와 shell 권한을 아무나 붙이는 상태라면 subagent보다 권한 정리가 먼저다.
즉, subagent는 “더 복잡한 일을 하기 위한 기능”이기도 하지만, 동시에 “복잡성을 관리할 준비가 된 팀을 위한 기능”이기도 하다.
준비가 덜 된 팀이 쓰면 기능이 문제가 아니라 운영이 먼저 무너진다.
개인 작업자도 마찬가지다.
내가 하루에 한두 번 Gemini CLI를 쓰고, 대부분 작은 질문만 한다면 subagent 파일을 만들 필요는 없다.
그냥 메인 세션에서 충분하다.
반대로 매일 코드베이스를 읽고, 공식 문서를 확인하고, 테스트 로그를 요약하고, 반복적으로 같은 agent 역할을 만들고 있다면 이제 분리할 때다.
반복이 생기면 agent가 된다.
권한이 생기면 policy가 된다.
병렬이 생기면 ownership이 된다.
이 순서로 보면 과한 도입을 피하기 쉽다.
도구는 문제보다 조금 늦게 들어오는 게 좋다.
문제보다 먼저 온 도구는 대체로 자기가 문제를 만든다.
FAQ
Gemini CLI subagents는 Claude Code subagents와 같은 건가?
완전히 같지는 않다.
설정 위치, built-in agent, command, policy 구조가 다르다.
하지만 운영 질문은 비슷하다.
context를 어떻게 분리할지, 어떤 도구를 줄지, 병렬 작업의 ownership을 어떻게 정할지가 핵심이다.
@agent 문법은 꼭 써야 하나?
꼭은 아니다.
Gemini CLI는 자동 위임도 할 수 있다.
다만 반복 workflow, 검수, 팀 규칙에서는 @agent로 명시 호출하는 편이 추적하기 쉽다.
나중에 prompt만 봐도 어떤 전문가를 불렀는지 알 수 있다.
.gemini/agents와 ~/.gemini/agents 중 어디에 둬야 하나?
팀과 공유할 agent는 .gemini/agents가 낫다.
repo에 들어가므로 리뷰와 변경 이력이 남는다.
개인 루틴이면 ~/.gemini/agents가 낫다.
팀 표준으로 착각될 위험이 줄어든다.
병렬 subagent는 언제부터 써도 되나?
읽기 전용 조사부터 시작하는 게 좋다.
서로 다른 모듈을 읽고 요약하는 작업은 병렬에 잘 맞는다.
같은 파일을 동시에 수정하는 작업은 늦게 가야 한다.
공식 발표도 무거운 코드 편집의 병렬 실행은 conflict와 overwrite 위험이 있다고 경고한다.
usage limit은 어떻게 확인하나?
Gemini CLI 공식 quota 문서는 /stats model 명령으로 현재 session token usage와 quota 관련 정보를 확인할 수 있다고 설명한다.
또 인증 방식별 일일 요청 한도가 다르다.
병렬 subagent는 여러 요청을 동시에 보내므로 limit에 더 빨리 닿을 수 있다.
custom subagent에 모든 도구를 줘도 되나?
가능은 하지만 처음부터 추천하지 않는다.
읽기 전용 agent는 read와 grep 중심으로 시작한다.
shell, write, MCP 서버는 필요할 때 하나씩 더한다.
도구가 늘면 agent 능력만 늘지 않고 사고 반경도 늘어난다.
policy까지 꼭 써야 하나?
개인 실험이면 처음부터 필수는 아니다.
하지만 팀 공유 agent, write 권한, shell 권한, 외부 서비스 MCP가 붙으면 policy를 봐야 한다.
subagent별 policy는 “이 agent만 이 도구를 쓸 수 있다” 또는 “이 agent는 금지한다” 같은 통제를 가능하게 한다.
remote subagents와 A2A도 바로 봐야 하나?
처음엔 아니다.
local subagent와 built-in agent로도 배울 게 많다.
remote subagent는 인증, 네트워크, 소유권, 관찰 가능성 문제가 더 붙는다.
local에서 역할 분리와 도구 제한이 안정된 뒤 보는 편이 낫다.
관련 글
- Gemini in Chrome Skills 2026 — 반복 프롬프트를 one-click workflow로 바꿀 때 먼저 정할 5가지
- Claude Code subagents 늘릴수록 왜 더 느려질까 2026 — context 분리와 ownership 설계 체크리스트
- OpenAI Agents SDK sandbox는 언제 쓰고 언제 과한가 2026 — Manifest·격리실행·복구성 분기표
공식 출처
- Google Developers Blog, Subagents have arrived in Gemini CLI, 2026년 4월 15일 발표.
- Gemini CLI Docs, Subagents, custom agent 파일, built-in agent, tool isolation, policy, disabling 기준.
- Gemini CLI Docs, Gemini CLI: Quotas and pricing, 인증 방식별 요청 제한과
/stats model확인 기준. - Gemini CLI Docs, CLI commands,
/agents list,/agents reload,/agents enable,/agents disable,/agents config명령. - Google Gemini CLI GitHub, google-gemini/gemini-cli, 설치 방식과 공식 문서 연결 확인.
마무리 판단
Gemini CLI subagents는 “에이전트를 많이 만든다”는 기능으로 보면 반만 보인다.
진짜 가치는 context를 분리하고, 도구 권한을 제한하고, 반복 작업을 전문가 단위로 묶는 데 있다.
그래서 처음 도입 기준은 화려하면 안 된다.
읽기 전용부터.
작은 description부터.
좁은 tools부터.
명시 @agent부터.
병렬 조사는 허용.
병렬 편집은 보류.
usage는 확인.
이 정도만 지켜도 subagent는 꽤 실용적인 운영 레이어가 된다.
반대로 이 기준 없이 병렬 편집부터 켜면 빠르게 움직일 수는 있다.
다만 어디로 움직였는지 나중에 다시 찾아야 한다.
그건 자동화라기보다 보물찾기다.
재밌을 수는 있는데, 배포 전엔 별로다.