[AI] 클로드코드 sub agent 개념 (claude code, 서브 에이전트)

 

sub agent란?

• 메인 에이전트가 복잡한 작업을 수행할 때, 특정 역할에 특화된 '가상의 전문가'를 별도의 세션으로 띄워 작업을 위임하는 기능
• 메인 세션의 컨텍스트(대화 기록)가 너무 무거워지는 것을 방지하고, 특정 도구나 지침에만 집중하게 할 때 사용
  • 독립된 컨텍스트: 메인 대화와 분리된 깨끗한 창에서 작업하므로 토큰 소모가 효율적임
  • 전문화된 지침: .agent 파일에 적힌 전용 시스템 프롬프트를 따름
  • 도구 제한: 보안이나 정확도를 위해 특정 도구(예: 읽기 전용)만 사용하도록 제한 가능

사용방법

• 프로젝트 루트의 .claude/agents/ 디렉토리에 마크다운(.md) 파일을 만들어 에이전트를 정의

ex) 파일명: .claude/agents/swift-reviewer.md

---
name: swift-reviewer
description: Swift 및 SwiftUI 코드의 품질을 검토하고 성능 최적화 방안을 제시하는 전문 리뷰어
tools: [ls, read_file, grep]
---

# 시스템 프롬프트
너는 10년 차 시니어 iOS 개발자임. 다음 원칙을 준수하여 코드를 리뷰함:
1. 메모리 누수 방지를 위해 `[weak self]` 사용 여부를 철저히 검사함
2. SwiftUI View 내 비즈니스 로직은 ViewModel로 분리할 것을 권고함
3. 가독성을 위해 한 함수는 30줄을 넘지 않도록 제안함

호출 방법

• 1) 자동 호출
  • 메인 에이전트에게 작업을 시키면, 에이전트가 판단하여 .agent 파일의 description과 일치하는 작업일 경우 서브에이전트를 생성함

"방금 수정한 LoginView.swift 파일을 swift-reviewer로 검토해줘"

• 2) 에이전트 관리 (/agents 커맨드)
  • 터미널에 /agents를 입력하면 현재 사용 가능한 내장/커스텀 에이전트 목록을 확인하고, UI를 통해 새 에이전트를 생성하거나 편집할 수 있음

주의) Agent와 Skill 개념 구분

• 에이전트: "로그인 페이지의 버그를 고쳐줘"라는 요청을 받으면 '파일 검색 -> 코드 분석 -> 수정 -> 테스트'라는 전체 과정을 주도
• 스킬: 에이전트가 "파일을 읽어라"라고 시키면 수행하는 read_file이나, "테스트를 돌려라"라고 할 때 쓰는 run_terminal_command 같은 개별 함수

요약

• .skill은 함수를 정의하고, .agent는 지능의 성격과 규칙을 정의
• 서브에이전트는 작업이 끝나면 결과를 메인 에이전트에게 보고하고 사라지는 일회성 분신임
• 팀 공통 규칙은 프로젝트 내 .claude/agents/에, 개인 선호 규칙은 ~/.claude/agents/에 저장하여 사용

* 참고

- https://code.claude.com/docs/ko/sub-agents