Claude Code Deep Dive - 2(Agents)
0 views
블로그 불러오는 중...
문의 보내기
남겨주면 블로그 주인에게 바로 전달돼요.
Subagent는 특정 유형의 작업을 처리하는 특화된 AI 어시스턴트 이다.
subagent는 자체 컨텍스트 윈도우에서 실행되며 사용자 정의 시스템 프롬프트, 특정 도구 액세스 및 독립적인 권한을 가진다.
파일 내용이나 테스트 로그처럼 대량의 출력이 메인 컨텍스트에 계속 쌓이면 모델이 참고해야 할 정보가 많아진다. Subagent를 사용하면 이러한 탐색 과정과 출력을 별도의 컨텍스트에 격리하고, 필요한 결과만 메인 Agent로 돌려받을 수 있다.
다시 사용하지 않을 출력은 낭비이고, 모델의 주의가 분산된다.
추가로 프롬프트를 작성해서 역할을 정의하고 해당 부분에 최적화 된 업무를 진행할 수 있다.
예를 들어, 시니어 데브옵스 Role 을 가진 Agent, 시니어 Backend Engineer 역할과 회사에서의 코드 규칙에 따른 리뷰에 최적화 된 형태로 진행할 수 있다.
아래 링크의 공식 문서에 클로드 코드 빌트인 서브에이전트에 대해 작성되어 있다.
https://code.claude.com/docs/ko/sub-agents#built-in-subagents
Claude Code에는 Claude가 적절할 때 자동으로 사용하는 내장 subagent가 포함되어 있습니다. 각각은 추가 도구 제한이 있는 부모 대화의 권한을 상속합니다.
Explore와 Plan은 연구를 빠르고 저렴하게 유지하기 위해 CLAUDE.md 파일과 부모 세션의 git 상태를 건너뜁니다.
간단하게 최우형 님께서 만든 PPT 의 내용을 첨부한다. Built-in Subagent 의 경우에는 공식문서를 보면서 규칙 등을 알아보면 좋을 것 같다.
그러나 서브 에이전트는 마냥 좋은 것은 아니다.
서브 에이전트의 경우 새 컨텍스트에서 진행하므로 상황 파악에 시간이 들고, 결과 회수도 토큰을 사용한다. 아래와 같이 적합/비적합의 경우를 정리해 보았다.
적합한 경우
적합하지 않은 경우
다음과 같이 서브에이전트를 정의해 본다.
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer.
When invoked, analyze the code and provide specific,
actionable feedback on quality, security,
and best practices.서브에이전트의 폴더는 작업중인 워크스페이스에 아래와 같은 폴더에 저장해 보았다.
.claude/
└── agents/
└── code-reviewer.mdFrontmatter는 Markdown 문서 상단에 작성하는 메타데이터 영역으로, Claude Code에서는 Subagent의 이름, 호출 조건, 사용 도구, 모델 등의 설정을 정의한다.
위에 예시에 따라 아래에 간단한 설명을 남긴다
name: 에이전트 이름
description: description 섹션을 보고 클로드가 Subagent 를 사용할지 사용하지 않을 지 결정하기 때문에, description 을 언제 사용하는지, 무엇을 하는지 잘 정의해 줘야 한다.
tools: tools에는 해당 Agent가 사용할 수 있는 도구를 지정한다.
위의 code-reviewer는 코드 리뷰만 수행하도록 Read, Glob, Grep만 허용했다. Write, Edit 권한이 없기 때문에 코드를 직접 수정하지 않고 읽고 분석하는 역할로 제한할 수 있다.
tools를 지정하지 않으면 메인의 도구를 상속하고, 지정하면 허용한 도구만 사용할 수 있다. 최소 권한을 Agent 마다 주게끔 처리가 가능하다.
model: subagent 가 사용할 모델을 정의한다.
Subagent는 memory 옵션을 통해 세션이 종료된 이후에도 이전 작업에서 발견한 내용을 기억하도록 설정할 수 있다.
예를 들어 코드 리뷰를 반복해서 수행하는 Agent라면 프로젝트에서 사용하는 코딩 컨벤션이나 반복적으로 발견되는 문제를 기록하고, 다음 리뷰에서 이를 다시 참고할 수 있다.
hooks는 Subagent가 도구를 실행할 때 추가적인 검증 로직을 실행할 수 있도록 하는 기능이다.
파일을 직접 수정하는 Subagent의 경우에는 isolation: worktree 옵션을 사용할 수 있다.
---
name: test-writer
description: >
Test coverage specialist.
Use proactively when new code lacks tests or coverage drops.
tools: Read, Write, Edit, Bash, Grep, Glob
model: sonnet
isolation: worktree
maxTurns: 40
---위와 같이 frontmatter 에 isolation 규칙을 줄 수 있다. 테스트 코드 작성, 리팩터링, 마이그레이션처럼 실제 코드를 변경하고 검증해야 하는 작업을 Subagent에게 위임할 때 유용할 것 같다.
일단 만든 에이전트를 호출해 본다. 호출은 여러 방법이 있다.
Subagent를 호출하는 방법은 크게 세 가지가 있다.
1. 자연어
"code-reviewer 서브에이전트로 변경사항을 리뷰해줘"
2. @mention
"@agent-code-reviewer 변경사항을 리뷰해줘"
3. --agent
claude --agent code-reviewer각각의 호출 방식에는 다음과 같은 차이가 있다.
자연어 : Claude가 Subagent 사용 여부를 판단한다.
@mention : 이번 작업에서 특정 Subagent를 명시적으로 호출한다.
--agent : 세션 자체를 해당 Agent 설정으로 실행한다.나의 경우엔 멘션으로 테스트 해 보겠다.
아래 에이전트가 두개로 나눠져서 병렬로 실행되는 것을 볼 수 있다. 쉘에서 에이전트를 클릭하면 에이전트가 무엇을 하는지도 볼 수 있다.
Subagent가 작업한 내용을 메인 에이전트에서 문서로 만들어 달라고 했다.
아래는 서브 에이전트가 조사한 내용을 메인 에이전트가 파일로 만든 내용의 일부이다.
위에 문서를 클로드 코드가 만들어 줬는데, 실제로 에러들을 잡아내는 것을 보니 신기했다.
이러한 내용이 메인 에이전트 내에 그대로 쌓였다면, 코드 탐색 과정이나 리뷰 결과, 각종 로그까지 모두 메인 컨텍스트를 차지했을 것이다.
하지만 Subagent를 사용하면 실제 탐색과 분석은 별도의 컨텍스트에서 처리되고, 메인 Agent에는 필요한 결과만 요약되어 돌아온다.
이번 테스트에서도 두 개의 code-reviewer가 각각 독립적으로 코드를 분석하고, 메인 Agent는 각 Subagent의 결과를 받아 최종 문서로 정리하는 역할만 수행했다.
즉, Subagent는 단순히 작업을 나누는 기능이라기보다 탐색이나 테스트처럼 출력이 많은 작업을 메인 컨텍스트에서 격리하고, 서로 독립적인 작업을 병렬로 수행하기 위한 기능으로 이해하면 될 것 같다.