개념 ④ 수동 지목 — "@이름으로 콕 찍어서 시킨다"
🏠 일상 비유
팀장의 판단을 기다리지 않고, 직접 담당자에게 찾아가는 것입니다. "김대리, 이거 처리해줘"라고 직접 말하는 것과 같습니다.
⚙️ 실제 작동 방식
@에이전트이름을 앞에 붙이면 됩니다.
@content-marketer 블로그 글 써줘. 주제는 "AI 활용법"이야. @product-dev 로그인 페이지에서 에러가 나는데 원인 분석해줘. @cs-ops "비밀번호를 잊었어요" 고객 문의 답변 템플릿 만들어줘. @admin-support 프리랜서 계약서 초안 작성해줘.
💡 자동 위임 vs 수동 지목, 언제 뭘 쓸까?
| 상황 | 추천 방식 | 이유 |
|---|---|---|
| 누가 해야 할지 명확할 때 | @에이전트이름 (수동) | 팀장의 판단 과정을 건너뛰어서 빠름 |
| 누가 해야 할지 애매할 때 | 그냥 자연어로 요청 (자동) | 메인 AI가 판단해서 최적 에이전트에게 넘겨줌 |
| 여러 에이전트가 동시에 필요할 때 | 메인 AI에게 전체 지시 (자동) | 메인 AI가 알아서 여러 에이전트에게 분배 |
출처: Gemini CLI 공식 문서 — Forcing a subagent
개념 ⑤ 병렬 실행 — "4명이 동시에 일한다"
🏠 일상 비유
식당에서 주문을 받으면, 셰프 1명이 모든 메뉴를 순서대로 만드는 것보다 파스타 담당, 스테이크 담당, 디저트 담당이 동시에 요리하는 게 훨씬 빠릅니다.
⚙️ 실제 작동 방식
서브에이전트를 여러 개 동시에 실행할 수 있습니다.
예시 요청:
"런칭 준비를 병렬로 처리해줘:
1) product-dev: 랜딩페이지 만들기
2) content-marketer: 블로그 글 쓰기
3) cs-ops: FAQ 작성
4) admin-support: 이용약관 초안"
| 방식 | 소요 시간 (예시) | 비유 |
|---|---|---|
| 순차 실행 (종전) | 10분 + 10분 + 10분 + 10분 = 40분 | 1명이 4개를 순서대로 |
| 병렬 실행 (서브에이전트) | 4개 동시 진행 = 약 10~15분 | 4명이 동시에 각자 1개씩 |
/stats model로 남은 사용량을 확인하는 습관이 중요합니다.
출처: Google Developers Blog (2026.4.15)
개념 ⑥ 커스텀 에이전트 만들기 — "마크다운 파일 하나면 충분하다"
🏠 일상 비유
새 직원을 채용할 때 채용 공고를 쓰는 것과 같습니다. "직무명, 역할 설명, 필요 기술, 업무 원칙"을 적으면 됩니다. Gemini CLI에서는 이 채용 공고가 마크다운 파일(.md) 하나입니다.
⚙️ 파일 구조 (채용 공고에 빗대어)
| 파일 영역 | 채용 공고에 비유하면 | 들어가는 내용 |
|---|---|---|
상단 (---로 감싸진 부분) | 📋 채용 조건표 | 이름, 역할 설명, 사용 가능한 도구, 모델, 창의성 수준, 최대 작업 시간 |
| 하단 (마크다운 본문) | 📄 상세 직무기술서 | "당신은 OOO 전문가입니다. 이런 원칙으로 일합니다."라는 구체적인 지시 |
💡 실제 예시: 마케팅 전문가 에이전트
--- name: content-marketer description: 콘텐츠 마케팅 전문가. 블로그 작성, SNS 기획, 광고 문구 담당. tools: - read_file - write_file - google_web_search - web_fetch temperature: 0.7 --- 당신은 스타트업 전문 콘텐츠 마케터입니다. 블로그, SNS, 뉴스레터 콘텐츠를 만들 때 항상 타겟 독자를 먼저 확인하고, CTA(Call to Action)를 반드시 포함합니다.
각 설정값 쉬운 설명
| 설정 | 뜻 | 쉬운 비유 |
|---|---|---|
name | 에이전트의 이름 (호출할 때 사용) | 사원증에 적힌 이름 |
description | 무엇을 잘하는지 설명 | 채용 공고의 직무 요약 |
tools | 사용 가능한 도구 목록 | 이 직원에게 주는 열쇠 목록 |
temperature | 창의성 수준 (0=보수적, 1+=창의적) | 0.3 = 교과서대로, 0.7 = 자유롭게 |
model | 사용할 AI 모델 | inherit = 팀장과 같은 모델 사용 |
max_turns | 최대 작업 단계 수 | "30번까지만 시도하고 보고해" |
timeout_mins | 최대 작업 시간 (분) | "10분 안에 끝내" |
💡 파일을 어디에 넣나요?
| 위치 | 효과 | 비유 |
|---|---|---|
.gemini/agents/ (프로젝트 폴더 안) | 이 프로젝트에서만 사용 | 이 프로젝트 전용 파견 직원 |
~/.gemini/agents/ (홈 폴더) | 모든 프로젝트에서 사용 | 회사 전체에서 일하는 정규직 |
출처: Gemini CLI 공식 문서 — Creating custom subagents
4. 기본 내장 에이전트 4종 상세 소개
직접 에이전트를 만들지 않아도, Gemini CLI를 설치하면 바로 쓸 수 있는 에이전트가 4개 있습니다.
① generalist — "만능 사원"
한 줄 요약: 메인 AI가 할 수 있는 모든 일을 똑같이 할 수 있는 복사본.
언제 쓰나요? 여러 파일을 한꺼번에 수정할 때 · 출력이 엄청나게 많은 명령어를 실행할 때 · 코드 검색 + 수정을 동시에 해야 할 때
비유: "뭐든 시키면 하는 팀내 올라운더. 대신 특화된 전문성은 없음."
② cli_help — "Gemini CLI 사용설명서를 외우고 있는 직원"
한 줄 요약: Gemini CLI 자체에 대한 질문에 답하는 전문가.
언제 쓰나요? "이 명령어 뭐야?" · "설정 파일 어디서 바꿔?" · "프록시 연결은 어떻게 해?"
비유: "IT 헬프데스크. 도구 사용법을 물어보면 즉답해주는 사람."
③ codebase_investigator — "코드 탐정"
한 줄 요약: 프로젝트의 코드를 분석하고 구조를 파악하는 전문가.
언제 쓰나요? "인증 시스템이 어떻게 작동하는지 파악해줘" · "이 버그의 근본 원인을 추적해줘" · "이 파일이 다른 어떤 파일에 영향을 주는지 알려줘"
비유: "셜록 홈즈. 코드의 미궁 속에서 원인을 추적하는 탐정."
④ browser_agent — "웹 브라우저를 직접 조작하는 직원" (실험적)
한 줄 요약: 실제 Chrome 브라우저를 열고, 클릭하고, 폼을 채우고, 정보를 추출하는 에이전트.
언제 쓰나요? "이 웹사이트에서 가격표를 추출해줘" · "구글 폼에 테스트 데이터를 입력해줘" · "로그인 페이지가 제대로 작동하는지 확인해줘"
비유: "모니터 앞에 앉아서 마우스와 키보드를 직접 조작하는 로봇 직원."
출처: Gemini CLI 공식 문서 — Built-in subagents
5. 관리하는 방법 — /agents 명령어
서브에이전트를 관리하는 것도 간단합니다. Gemini CLI 안에서 /agents 명령어를 치면 됩니다.
| 명령어 | 하는 일 | 쉬운 비유 |
|---|---|---|
/agents list | 현재 등록된 모든 에이전트 목록 확인 | 팀원 명단 보기 |
/agents enable 이름 | 비활성화된 에이전트 다시 활성화 | 휴가 보냈던 직원 복귀시키기 |
/agents disable 이름 | 특정 에이전트 비활성화 (자동 위임에서 제외) | 특정 직원을 잠시 대기 상태로 |
/agents config 이름 | 에이전트 설정 변경 | 직원의 업무 범위 조정 |
/agents reload | 에이전트 파일을 다시 읽어들임 | 인사 변경 사항 즉시 반영 |
출처: Gemini CLI 공식 문서 — Managing subagents
6. 전체 그림을 한 장으로
정리
| # | 개념 | 한 줄 요약 |
|---|---|---|
| ① | 격리된 작업 공간 | 각 팀원이 자기 방에서 일하고, 결과만 보고한다 |
| ② | 전문 도구 제한 | 마케터에게 서버 열쇠를 주지 않는다 |
| ③ | 자동 위임 | 팀장이 description을 보고 적임자에게 알아서 넘긴다 |
| ④ | 수동 지목 | @이름으로 콕 찍어서 시킨다 |
| ⑤ | 병렬 실행 | 4명이 동시에 일하면 시간이 1/4로 줄어든다 |
| ⑥ | 커스텀 에이전트 | 마크다운 파일 하나로 나만의 전문가를 만든다 |
이 여섯 가지만 이해하면, 서브에이전트의 핵심은 전부 파악한 겁니다. 나머지는 전부 응용입니다.