시리즈: 클로드 코드 서브에이전트 완전정복 (총 9편) | 4편
서브에이전트 설계 원리 — 좋은 프롬프트보다 좋은 경계가 중요한 이유
서브에이전트가 엉뚱한 결과를 내놓는다면 프롬프트가 아니라 경계 설정이 문제예요. 이 글에서는 역할, 컨텍스트, 도구, 권한, 종료라는 5가지 경계를 설계하는 원칙부터 역할 설계 최소 스펙 7가지, 실전 체크리스트, 메모리 정책까지 빠짐없이 다뤄 드려요.
Summary
- "좋은 프롬프트"보다 "좋은 경계"가 서브에이전트 품질을 좌우해요
- 역할, 컨텍스트, 도구, 권한, 종료 — 5가지 경계를 명확히 그어야 해요
- 역할 설계에는 최소 7가지 항목(Name, Inputs, Outputs 등)을 채워야 해요
- 메모리 정책을 제대로 세우지 않으면 컨텍스트 오염이 생길 수 있어요
이 글의 대상
- 서브에이전트를 써봤는데 결과가 들쭉날쭉해서 고민인 분
- "프롬프트만 잘 쓰면 되는 거 아니야?"라고 생각했던 분
- 서브에이전트 설계를 체계적으로 배우고 싶은 개발자
목차
- 왜 경계가 프롬프트보다 중요한가
- 5가지 경계 상세 해부
- 역할 설계 최소 스펙 7가지
- description 필드의 숨겨진 역할
- 메모리 정책 — 기회와 위험 사이
- 경계 설계 실전 체크리스트
1. 왜 경계가 프롬프트보다 중요한가
프롬프트는 "무엇을 해줘"라는 요청이고, 경계는 "여기까지만 해"라는 울타리예요. 아무리 프롬프트를 정교하게 작성해도 울타리가 없으면 서브에이전트는 범위를 벗어나거든요.
예를 들어볼게요. "코드를 리뷰해줘"라는 프롬프트를 줬다고 가정해 봐요. 경계가 없으면 이 에이전트는 리뷰만 하는 게 아니라 직접 코드를 수정하거나, 관련 없는 파일까지 뒤적거리거나, 심지어 배포 스크립트를 실행할 수도 있어요.
| 구분 | 프롬프트 | 경계 |
|---|---|---|
| 역할 | "무엇을 해줘" | "여기까지만 해" |
| 실패 시 결과 | 답변 품질이 떨어짐 | 예상 못한 동작, 보안 사고 |
| 수정 비용 | 문구 조정 | 아키텍처 재설계 |
| 재현성 | 매번 달라질 수 있음 | 구조적으로 제한되어 일관적 |
경계가 잘 잡혀 있으면 프롬프트가 조금 부족해도 서브에이전트가 허용된 범위 안에서만 움직이니까 결과가 안정적이에요. 반대로 경계가 없으면 프롬프트를 아무리 다듬어도 결과를 예측하기 어려워요.
2. 5가지 경계 상세 해부
서브에이전트를 설계할 때 반드시 그어야 하는 경계는 다섯 가지예요.
2-1. 역할/목표 경계
이 에이전트가 무엇을 책임지고, 무엇을 하지 않는지 명확히 정해요. "코드 리뷰 담당"이라면 리뷰만 하고 수정은 안 하는 거예요. 책임 범위를 좁힐수록 품질이 올라가요.
2-2. 컨텍스트 경계
어떤 자료만 근거로 삼을 수 있는지 정해요. 예를 들어 리서치 에이전트한테 "프로젝트 내부 문서만 참조해"라고 한정하면 외부에서 엉뚱한 정보를 끌어오는 걸 막을 수 있어요.
2-3. 도구 경계
읽기, 쓰기, 실행 중 어디까지 허용할지 정해요.
| 권한 수준 | 허용 도구 예시 | 적합한 역할 |
|---|---|---|
| 읽기 전용 | Read, Grep, Glob | 리서치, 검증 |
| 읽기 + 쓰기 | Read, Write, Edit | 작성자, 편집자 |
| 읽기 + 실행 | Read, Bash, Task | 테스트, 통합 |
2-4. 권한 경계
도구를 쓸 수 있다고 해서 자동으로 실행되는 건 아니에요. 자동 수락, 승인 요청, 거부 세 가지 정책을 정해야 해요.
- 자동 수락: 안전한 읽기 작업은 매번 물어보지 않고 바로 실행
- 승인 요청: 파일 수정이나 외부 API 호출은 사람한테 확인받기
- 거부: 배포, 삭제 같은 고위험 작업은 아예 불가능하게
이걸 Claude Code에서는 permissionMode로 설정할 수 있어요. default, plan, bypassPermissions 같은 옵션이 있는데, 서브에이전트는 가능한 보수적으로 설정하는 게 좋아요.
2-5. 종료 경계
서브에이전트가 언제 멈출지를 정해요. 종료 조건이 없으면 무한 루프에 빠지거나 불필요하게 오래 돌 수 있어요.
- maxTurns: 대화 턴 수 제한 (예: 최대 10턴)
- 시간 박스: 타임아웃 설정
- 산출물 스키마: 정해진 형식의 결과물이 나오면 종료
3. 역할 설계 최소 스펙 7가지
서브에이전트 하나를 정의할 때 최소한 아래 7가지는 채워야 해요.
| 항목 | 설명 | 예시 |
|---|---|---|
| Name | 에이전트 이름 | code-reviewer |
| Description | Claude가 위임 판단할 때 보는 설명 | "PR의 코드 품질과 보안 이슈를 검토" |
| Inputs | 입력으로 받는 것 | PR diff, 코딩 컨벤션 문서 |
| Outputs | 출력으로 내보내는 것 | 리뷰 코멘트 목록 (JSON) |
| Allowed tools | 사용 가능한 도구 | Read, Grep, Glob |
| permissionMode | 권한 정책 | plan |
| maxTurns | 최대 턴 수 | 10 |
여기에 추가로 Memory policy(메모리 정책)까지 정해두면 더 좋아요. 이건 바로 다음 섹션에서 다뤄볼게요.
4. description 필드의 숨겨진 역할
description은 단순한 주석이 아니에요. Claude가 "이 작업을 어떤 서브에이전트한테 맡길까?" 판단할 때 description을 보고 결정하거든요.
그래서 description을 구체적으로 써야 해요.
| 나쁜 예 | 좋은 예 |
|---|---|
| "리뷰를 수행한다" | "PR diff를 읽고 보안 취약점, 성능 이슈, 코딩 컨벤션 위반을 찾아 코멘트 목록을 반환한다" |
| "문서 작성" | "ADR 템플릿에 맞춰 기술 결정 배경, 대안 비교, 검증 계획을 포함한 초안을 작성한다" |
description이 모호하면 Claude가 엉뚱한 에이전트한테 작업을 넘기거나, 아예 위임하지 않고 직접 처리하려 들 수 있어요.
5. 메모리 정책 — 기회와 위험 사이
Claude Code에는 세 가지 메모리 계층이 있어요.
| 메모리 유형 | 범위 | 예시 용도 |
|---|---|---|
| User memory | 사용자 전체 | 개인 선호, 코딩 스타일 |
| Project memory | 프로젝트 단위 | 용어집, ADR 규칙, 팀 컨벤션 |
| Local memory | 현재 세션 | 진행 중인 작업 맥락 |
메모리를 잘 활용하면 좋은 점이 많아요. 용어집이나 ADR 작성 규칙을 누적시켜 두면 매번 알려줄 필요 없이 일관된 결과를 얻을 수 있거든요.
하지만 위험도 있어요.
- 컨텍스트 오염: 프로젝트 A의 규칙이 프로젝트 B에 적용되는 경우
- 정책 누수: 보안 정책이나 권한 설정이 메모리를 통해 의도치 않게 변경되는 경우
- 오래된 정보 잔존: 업데이트된 규칙 대신 예전 메모리를 참조하는 경우
그래서 서브에이전트를 설계할 때 "이 에이전트가 어떤 메모리에 접근할 수 있는가", "메모리에 쓸 수 있는가"를 명확히 정해둬야 해요.
6. 경계 설계 실전 체크리스트
새로운 서브에이전트를 만들 때 아래 질문에 답해 보세요.
- 이 에이전트의 책임은 정확히 뭐야? (역할 경계)
- 어떤 자료만 근거로 써야 해? (컨텍스트 경계)
- 읽기/쓰기/실행 중 뭐까지 허용할 거야? (도구 경계)
- 자동 실행, 승인 요청, 거부 중 어떤 정책이야? (권한 경계)
- 언제 멈춰야 해? (종료 경계)
- description은 구체적으로 작성했어? (위임 판단용)
- 메모리 접근 범위는 정했어? (오염 방지)
이 질문들에 명확히 답할 수 없다면, 아직 설계가 덜 된 거예요. 코드를 작성하기 전에 이 체크리스트부터 채워보는 걸 추천해요.
핵심 정리
1. 서브에이전트 품질은 프롬프트가 아니라 경계가 결정한다
2. 5가지 경계: 역할, 컨텍스트, 도구, 권한, 종료
3. 역할 설계 최소 스펙 7가지를 빠짐없이 채워라
4. description은 Claude의 위임 판단 기준이니 구체적으로 작성하라
5. 메모리 정책을 정하지 않으면 컨텍스트 오염이 일어난다FAQ
Q. 경계를 너무 좁게 설정하면 오히려 비효율적이지 않나요?
A. 맞아요, 극단적으로 좁히면 에이전트 수만 늘어나고 오케스트레이션 비용이 커져요. 핵심은 "한 에이전트가 한 가지 책임"을 지되, 그 책임의 크기가 의미 있는 단위여야 한다는 거예요. "파일 하나 읽기" 수준은 너무 작고, "프로젝트 전체 리팩토링" 수준은 너무 커요.
Q. permissionMode는 어떤 값으로 시작하는 게 좋아요?
A. 처음에는 default(매번 승인 요청)로 시작하는 걸 추천해요. 동작이 안정적이라고 확인되면 점진적으로 plan이나 특정 도구만 자동 수락하도록 풀어가는 게 안전해요.
Q. maxTurns를 몇으로 설정해야 할지 모르겠어요.
A. 작업 복잡도에 따라 다르지만, 단순 리뷰는 510턴, 리서치+작성은 1520턴 정도로 시작해 보세요. 턴이 부족해서 작업이 중단되는 게 초과해서 무한 루프 도는 것보다 훨씬 안전해요. 로그를 보면서 조정하면 돼요.
Q. description을 영어로 써야 하나요, 한국어로 써도 되나요?
A. Claude는 한국어도 잘 이해하지만, description은 영어로 쓰는 걸 권장해요. Claude의 내부 위임 판단 로직이 영어 기반으로 더 안정적이거든요. 한국어로 써도 동작은 하지만 정확도 차이가 있을 수 있어요.
Q. 메모리 오염은 어떻게 감지할 수 있어요?
A. 서브에이전트가 맡은 프로젝트와 무관한 용어나 규칙을 적용하기 시작하면 의심해 봐야 해요. 정기적으로 메모리 내용을 확인하고, 프로젝트별로 메모리를 격리하는 게 가장 확실한 방법이에요.
Q. 경계를 코드로 정의하는 건가요, 문서로 정의하는 건가요?
A. 둘 다예요. Claude Code에서는 .claude/agents/ 같은 디렉토리에 YAML이나 Markdown으로 에이전트를 정의할 수 있어요. 이 정의 파일 자체가 경계를 코드화한 거예요. 8편에서 구체적인 파일 구조를 다룰 예정이에요.
참고 자료 (References)
데이터 출처
| 출처 | 설명 | 링크 |
|---|---|---|
| Claude Code 서브에이전트 문서 | 공식 서브에이전트 설정 가이드 | code.claude.com |
| Claude Code Overview | Claude Code 전체 아키텍처 개요 | code.claude.com |
| Claude Code Hooks | 훅을 통한 자동화 및 권한 제어 | code.claude.com |
핵심 인용
"Subagents operate in isolated contexts with their own tool permissions and conversation history, separate from the main agent."
— Claude Code 공식 문서
다음 편 예고
[5편] 리서치·문서화에 서브에이전트 활용하기 — Research→Write→Verify→Approve 패턴
- 생성자와 검증자를 분리하는 이유와 효과
- Research → Write → Verify → Approve 4단계 아키텍처 실전 구성
- 비결정적 생성(초안)과 결정적 검증을 나누는 하이브리드 패턴