도메인 1: 에이전트 아키텍처 및 오케스트레이션 (27%) — 심화편
비중: 전체 시험의 27% — 가장 높은 비중
태스크: 7개 (1.1 ~ 1.7)
교차 시나리오: 고객 지원 해결 에이전트, 멀티 에이전트 연구 시스템, 개발자 생산성
핵심 기술: Claude Agent SDK, Task 도구, 훅(hook),stop_reason,fork_session
이 도메인은 Claude Agent SDK를 사용하여 에이전트 시스템을 설계하고 운영하는 능력을 평가한다. 에이전트 루프의 동작 원리부터 멀티 에이전트 오케스트레이션, 코드 수준 강제, 태스크 분해, 세션 관리까지를 아우른다.
시험 비중이 27%로 가장 높은 이유가 있다. 에이전트 아키텍처는 나머지 4개 도메인의 기반이기 때문이다. 도구 설계(D2)는 에이전트가 도구를 어떻게 사용하는지를, Claude Code 구성(D3)은 에이전트가 운영되는 환경을, 문맥 관리(D5)는 에이전트의 장기 실행을 각각 다룬다. 이 도메인에서 형성한 사고 모델이 전체 시험을 관통한다.
이 장을 읽기 전에 Agent Loop 개념 문서를 먼저 보면, 뒤에 나오는 stop_reason, tool_use, 훅, 세션 관리가 훨씬 덜 추상적으로 읽힌다.
이 장을 읽을 때는 아래 세 질문을 계속 붙들고 가면 흐름이 잘 잡힌다.
- 에이전트는 언제 계속 실행하고 언제 종료하는가?
- 작업이 커지면 언제 단일 에이전트에서 멀티 에이전트로 넘어가는가?
- 규칙을 지키게 해야 할 때 프롬프트로 유도할지, 코드로 강제할지 어떻게 구분하는가?
Domain 1 Concept Primer
이 도메인의 출발점은 Agent Loop다. 에이전트가 한 번의 응답으로 끝나는 것이 아니라, 필요하면 도구를 호출하고 그 결과를 바탕으로 다시 판단하는 반복 실행 구조라는 감각을 먼저 잡아두면 좋다.
특히 아래 개념 문서를 함께 묶어서 읽으면 흐름이 훨씬 잘 잡힌다.
- Agent Loop: 완료될 때까지 판단과 실행을 반복하는 구조
- Subagent: 허브-앤-스포크 멀티 에이전트 구조와 explicit context passing
- Hooks & Enforcement: 프롬프트 지시와 코드 수준 강제의 구분
- Task Decomposition: 작업을 어떤 경계로 나눌지 설계하는 방법
- Session Management: 어떤 문맥을 이어가고 끊을지 판단하는 기준
먼저 읽고 돌아오면, 뒤에 나오는 멀티 에이전트 구조, 훅, 태스크 분해, 세션 관리가 훨씬 덜 추상적으로 읽힌다.
1.1 — 에이전트 루프는 어떻게 작동하는가
왜 중요한가
에이전트 루프(agentic loop)는 Claude가 자율적으로 태스크를 수행하는 핵심 메커니즘이다. 일반적인 API 호출과 달리, 에이전트 루프에서는 모델이 도구를 호출하고, 그 결과를 받아 다음 행동을 추론하는 과정이 반복적으로 일어난다. 이 루프를 올바르게 설계하지 않으면 에이전트가 무한히 반복하거나, 반대로 도구 실행을 조기에 종료하는 문제가 발생한다.
루프의 동작 흐름
에이전트 루프는 보통 아래 순서로 반복된다.
| 단계 | 처리 |
|---|---|
| 1 | Claude에 messages와 tools를 함께 보낸다. |
| 2 | 응답의 stop_reason을 확인한다. |
| 3a | tool_use이면 요청된 도구를 실행하고 결과를 대화 이력에 추가한 뒤 1단계로 돌아간다. |
| 3b | end_turn이면 루프를 종료하고 최종 응답을 반환한다. |
여기서 반드시 이해해야 할 점이 있다. 도구 결과를 대화 이력에 추가하는 단계는 단순한 로그 기록이 아니다. 이 결과가 다음 턴에서 모델이 추론의 근거로 사용하는 문맥이 된다. 도구 결과를 누락하면 모델은 이전 행동의 결과를 알 수 없으므로, 의미 있는 다음 판단을 내릴 수 없다.
짧은 실행 예시로 보면 더 직관적이다.
| 턴 | 모델 출력 | 런타임의 처리 |
|---|---|---|
| 1 | stop_reason: "tool_use" + search_docs("환불 정책") | search_docs 실행 후, 결과를 tool_result로 대화 이력에 추가 |
| 2 | stop_reason: "tool_use" + get_customer("C123") | 고객 조회 결과를 다시 이력에 추가 |
| 3 | stop_reason: "end_turn" + 최종 답변 | 루프 종료, 사용자에게 응답 반환 |
즉, 런타임이 해야 할 일은 “모델의 다음 행동을 추측”하는 것이 아니라, 구조화된 신호에 따라 루프를 이어 붙이는 것이다.
stop_reason 기반 제어 흐름
stop_reason | 의미 | 올바른 동작 |
|---|---|---|
"tool_use" | 모델이 도구 호출을 요청함 | 도구를 실행하고, 결과를 tool_result 블록으로 대화 이력에 추가한 뒤, 다음 요청을 전송 |
"end_turn" | 모델이 태스크를 완료했다고 판단함 | 루프를 종료하고, 어시스턴트 응답을 사용자에게 반환 |
핵심 원칙은 이것이다. 어떤 도구를 호출할지, 언제 작업을 끝낼지는 모델이 현재 문맥을 보고 판단한다. 사전에 고정된 결정 트리나 미리 짜 둔 도구 순서를 그대로 따르는 구조가 아니다.
안티패턴 — 시험에서 오답으로 자주 등장
이 세 가지는 시험에서 그럴듯한 오답 선택지로 설계될 가능성이 높다. 각각이 왜 잘못된지를 정확히 알아야 한다.
| 안티패턴 | 왜 틀린가 |
|---|---|
| 자연어 신호를 파싱하여 루프 종료를 감지 | 모델의 텍스트 출력은 비결정론적(non-deterministic)이므로 “완료되었습니다” 같은 문구에 의존하면 불안정하다. stop_reason이라는 구조화된 신호가 존재하는데 자연어를 파싱할 이유가 없다. |
| 임의의 반복 횟수 상한을 주요 종료 메커니즘으로 사용 | 반복 상한은 보조 안전장치로는 유용하지만, 주요 종료 메커니즘이 되어서는 안 된다. 주요 종료 조건은 stop_reason === "end_turn"이다. 상한만 있으면 태스크가 완료되기 전에 강제 종료될 수 있다. |
| 어시스턴트 텍스트 내용을 완료 표시자로 확인 | stop_reason이 "tool_use"인데 텍스트에 “작업이 완료되었습니다”가 포함된 경우가 발생할 수 있다. 텍스트 내용이 아니라 구조화된 stop_reason 필드를 신뢰해야 한다. |
1.2 — 멀티 에이전트: 허브-앤-스포크 구조
관련 개념 문서: Subagent
기본 구조
단일 에이전트 루프로도 해결할 수 있는 일은 많다. 하지만 한 번에 다뤄야 할 역할이 늘어나고, 서로 다른 전문성이 필요한 작업이 섞이기 시작하면 루프 하나에 모든 판단을 몰아넣는 방식이 금방 불안정해진다. 이때 단일 루프를 역할별로 분산한 형태가 멀티 에이전트 구조다.
멀티 에이전트 시스템의 기본 토폴로지는 **허브-앤-스포크(hub-and-spoke)**이다. 중앙의 코디네이터가 허브 역할을 하고, 전문화된 서브에이전트들이 스포크 역할을 맡는다.
| 구성 요소 | 역할 | 통신 방식 |
|---|---|---|
| 코디네이터(허브) | 요청을 분해하고 필요한 서브에이전트를 선택하며 최종 결과를 통합한다. | 사용자 요청을 받고, 모든 서브에이전트와 통신한다. |
| 웹 검색 에이전트 | 외부 웹 자료를 수집한다. | 코디네이터에게만 결과를 돌려준다. |
| 문서 분석 에이전트 | 수집한 문서에서 핵심 사실을 추린다. | 코디네이터에게만 결과를 돌려준다. |
| 종합 에이전트 | 앞선 결과를 묶어 최종 답변이나 보고서를 작성한다. | 코디네이터가 넘겨준 자료만 바탕으로 작업한다. |
여기서 가장 중요한 설계 원칙은, 모든 서브에이전트 간 통신이 코디네이터를 통해서만 이루어진다는 것이다. 서브에이전트 A가 서브에이전트 B에게 직접 데이터를 전달하지 않는다. 이 원칙이 존재하는 이유는 관측 가능성(observability), 일관된 에러 처리, 통제된 정보 흐름을 보장하기 위해서이다.
코디네이터의 5가지 책임
코디네이터는 단순한 라우터가 아니다. 다음의 역할을 모두 수행한다.
| 책임 | 설명 |
|---|---|
| 태스크 분해 | 질의의 복잡도를 분석하고, 어떤 서브에이전트를 호출할지 동적으로 결정. 단순한 질의에 전체 파이프라인을 돌리지 않아야 한다. |
| 위임 | 각 서브에이전트에게 구체적인 연구 범위와 기대 결과를 전달 |
| 결과 취합 | 서브에이전트들의 출력을 수집하고 종합 에이전트에게 전달 |
| 에러 라우팅 | 서브에이전트 실패 시 재시도, 대안 경로, 또는 부분 결과로의 진행을 결정 |
| 반복적 정제 | 종합 결과를 평가 → 커버리지 갭 식별 → 추가 조사를 위해 서브에이전트 재위임 → 재종합 |
마지막 항목이 특히 중요하다. 코디네이터는 서브에이전트의 결과를 한 번 받고 끝나는 것이 아니라, 종합 결과의 품질을 평가하고 부족한 부분을 추가 조사하는 반복 루프를 운영해야 한다. 예를 들어, “AI가 창작 산업에 미치는 영향”이라는 연구에서 종합 결과가 시각 예술만 다루고 있다면, 코디네이터는 음악, 글쓰기, 영화 제작에 대한 추가 조사를 지시해야 한다.
주의: 과도하게 좁은 태스크 분해
이 안티패턴은 시험에서 직접 출제된 적이 있다 (공식 샘플 문제 7번). 코디네이터가 넓은 주제를 너무 좁은 하위 태스크로 분해하면, 모든 서브에이전트가 자신에게 할당된 범위는 성공적으로 처리하지만 전체적인 주제 커버리지에 큰 공백이 생긴다.
시나리오: “AI가 창작 산업에 미치는 영향”이라는 주제로 연구 시스템을 실행했다. 각 서브에이전트는 성공적으로 완료되었으나, 최종 보고서가 시각 예술만 다루고 음악·글쓰기·영화 제작을 완전히 누락했다. 코디네이터 로그를 확인하니 태스크를 “AI 디지털 아트 제작”, “AI 그래픽 디자인”, “AI 사진”의 세 가지로 분해했다.
이 문제의 근본 원인은 서브에이전트나 종합 에이전트가 아니라 코디네이터의 태스크 분해가 너무 좁았던 것이다. 다른 에이전트들은 할당받은 범위 내에서 정확하게 작동했다.
서브에이전트 간 범위가 겹치지 않게 하려면
코디네이터는 서브에이전트 간의 연구 범위를 분배할 때 중복을 최소화해야 한다. 예를 들어, 서로 다른 하위 주제(subtopic)를 각 에이전트에게 할당하거나, 동일한 주제를 다른 유형의 출처(소스)에서 조사하도록 분배하는 방식이 있다.
1.3 — 서브에이전트에게 문맥을 전달하는 법
Task 도구와 allowedTools
서브에이전트를 생성하는 메커니즘은 Task 도구이다. 코디네이터가 서브에이전트를 생성하려면, 코디네이터의 allowedTools 설정에 "Task"가 반드시 포함되어 있어야 한다. 이것이 빠져 있으면 코디네이터는 서브에이전트를 생성할 수 없다.
여기서 Task는 일반 도구 호출과 같은 층위로 보면 헷갈리기 쉽다. 일반 도구는 검색, 조회, 계산처럼 즉시 결과를 돌려주는 기능 호출에 가깝다. 반면 Task는 새 에이전트를 띄워 별도의 목표와 도구 집합을 가진 작업 단위를 위임하는 메커니즘이다.
| 구분 | 일반 도구 호출 | Task 도구 |
|---|---|---|
| 무엇을 호출하는가 | 함수나 외부 도구 하나 | 별도의 서브에이전트 |
| 반환 방식 | 보통 단일 결과를 즉시 반환 | 서브에이전트가 자체 추론을 거친 뒤 결과 반환 |
| 왜 제한이 중요한가 | 오용 방지, 보안 | 어떤 역할에 어떤 서브에이전트를 만들 수 있는지 통제 |
각 서브에이전트는 AgentDefinition으로 구성되며, 여기에는 다음이 포함된다:
- description: 서브에이전트의 역할 설명
- 시스템 프롬프트: 서브에이전트의 행동 지침
- 도구 제한(tool restrictions): 해당 서브에이전트가 사용할 수 있는 도구 목록
문맥 전달의 핵심 원칙
이 원칙은 아무리 강조해도 지나치지 않다. 서브에이전트는 코디네이터의 문맥을 자동으로 상속받지 않는다. 공유 메모리도 없고, 이전 서브에이전트의 결과가 자동으로 전달되지도 않는다. 서브에이전트에게 필요한 모든 정보는 해당 서브에이전트의 프롬프트에 명시적으로 포함시켜야 한다.
이것이 실무적으로 의미하는 바를 구체적으로 살펴보자:
| 상황 | 올바른 접근 | 잘못된 가정 |
|---|---|---|
| 종합 에이전트가 웹 검색 결과를 필요로 함 | 웹 검색 결과를 종합 에이전트의 프롬프트에 직접 포함 | ”코디네이터가 이미 가지고 있으니 자동으로 전달될 것이다” |
| 문서 분석 에이전트의 결과를 종합 에이전트에 전달 | 분석 결과를 구조화된 형식으로 종합 에이전트 프롬프트에 삽입 | ”이전 서브에이전트의 출력이 다음 서브에이전트에 자동으로 이어진다” |
문맥을 넘길 때는 본문과 메타데이터를 분리하라
문맥을 전달할 때는 본문 내용(content)과 메타데이터(metadata)를 구조적으로 분리해야 한다. 이렇게 하면 다운스트림 에이전트(특히 종합 에이전트)가 출처 정보(attribution)를 보존할 수 있다.
메타데이터에 포함되어야 하는 항목:
- 출처 URL 또는 문서명
- 페이지 번호 또는 섹션 위치
- 발행일 또는 수집일
- 관련성 점수(relevance score) — 선택적
시험 관점에서는 아래처럼 구분해 생각하면 실수가 줄어든다.
| 본문에 둘 것 | 메타데이터에 둘 것 |
|---|---|
| 핵심 주장, 요약, 인용할 사실 | 출처 URL, 문서명, 발행일, 페이지 위치 |
| 다음 에이전트가 바로 추론에 써야 할 내용 | 출처 추적과 신뢰도 판단에 필요한 정보 |
본문과 메타데이터를 섞어 쓰면 종합 에이전트가 “무엇이 주장이고 무엇이 출처 정보인지”를 다시 해석해야 한다. 시험에서는 이 재해석 비용을 줄이는 구조화가 좋은 설계로 평가된다.
병렬 서브에이전트 실행
코디네이터가 단일 응답에서 여러 Task 도구 호출을 동시에 내보내면, 해당 서브에이전트들이 병렬로 실행된다. 이는 한 번에 하나씩 호출하는 순차 실행과 대비된다.
| 항목 | 순차 실행 | 병렬 실행 |
|---|---|---|
| 호출 방식 | 웹 검색 결과를 받은 뒤 문서 분석, 그다음 DB 조회를 호출한다. | 웹 검색, 문서 분석, DB 조회를 한 번에 호출한다. |
| 대기 방식 | 각 단계가 끝날 때마다 다음 단계로 넘어간다. | 가장 늦게 끝나는 작업까지만 기다리면 된다. |
| 총 지연시간 | 개별 작업 시간의 합에 가깝다. | 가장 오래 걸린 작업 시간에 가깝다. |
코디네이터 프롬프트에는 절차가 아니라 목표를 써라
코디네이터 프롬프트를 설계할 때 흔히 범하는 실수는 절차만 장황하게 나열하는 것이다. “먼저 웹 검색 에이전트를 호출하고, 다음으로 문서 분석을 실행하고…”라고 쓰기보다, 연구 목표와 품질 기준을 분명히 적는 편이 낫다. 그래야 코디네이터가 상황에 따라 적절한 서브에이전트를 선택하고 조합할 수 있다.
fork_session
fork_session은 공유된 분석 출발점에서 **독립적인 분기(branch)**를 생성하는 메커니즘이다. 예를 들어, 동일한 코드베이스 분석을 바탕으로 두 가지 서로 다른 테스트 전략을 비교하거나, 리팩터링 접근법을 나눠 실험할 때 유용하다. 각 분기는 독립적으로 진행되므로 한쪽의 결과가 다른 쪽에 영향을 주지 않는다.
1.4 — 규칙을 강제하는 법: 훅 vs 프롬프트
관련 개념 문서: Hooks & Enforcement
이 시험에서 가장 많이 출제되는 개념
지금부터는 “정보를 어떻게 전달할 것인가”가 아니라 “규칙을 어떻게 지키게 만들 것인가”로 초점이 바뀐다. 문맥 전달이 잘 되어도, 중요한 규칙을 오직 프롬프트에만 맡기면 시스템은 여전히 실패할 수 있다.
공식 시험 가이드의 준비 글과 합격 후기에서 공통적으로 언급하는 최다 출제 개념이 바로 “코드 수준 강제 vs 프롬프트 지시”의 구분이다. 이 기준이 시험 전반에서 반복 등장한다.
코드 수준 강제 vs 프롬프트 지시
| 차원 | 코드 수준 강제 | 프롬프트 지시 |
|---|---|---|
| 메커니즘 | 훅(hook), 사전 조건 게이트(prerequisite gate), 도구 호출 인터셉터 | 시스템 프롬프트의 지시문, few-shot 예시 |
| 보장 수준 | 결정론적 — 100% 강제 | 확률적 — 대부분 작동하지만 0이 아닌 실패율이 남음 |
| 적합한 상황 | 금융 거래, 신원 확인, 규정 준수, 정책 임계값 | 스타일 가이드, 톤 선호, 소프트 가이드라인 |
| 실패 시 결과 | 시스템이 실행을 차단 — 잘못된 행동이 발생하지 않음 | 모델이 지시를 무시할 수 있음 — 잘못된 행동이 발생 |
이 원칙을 시험 문제에 적용하는 공식은 단순하다:
“이 규칙이 지켜지지 않으면 금전적·법적 결과가 발생하는가?”
→ 예: 코드 수준 강제 (훅, 사전 조건)
→ 아니오: 프롬프트 지시로 충분
구체적 예시: 환불 처리 워크플로
시나리오 1(고객 지원 해결 에이전트)에서 자주 등장하는 패턴이다.
요구 사항: process_refund를 실행하기 전에 반드시 get_customer가 검증된 고객 ID를 반환해야 한다.
| 접근 | 구현 | 결과 |
|---|---|---|
| ✗ 프롬프트 지시 | 시스템 프롬프트에 “환불 전 반드시 고객 확인을 수행하세요” | 12%의 경우 건너뜀 → 오식별, 잘못된 환불 |
| ✗ Few-shot 예시 | 항상 get_customer를 먼저 호출하는 예시 5개 추가 | 실패율 감소하지만 0%로 만들 수 없음 |
| ✓ 코드 수준 사전 조건 | get_customer가 검증된 ID를 반환하기 전까지 lookup_order와 process_refund 호출을 코드 수준에서 차단 | 100% 보장 |
다중 관심사(Multi-Concern) 요청 처리
고객이 한 번의 메시지에서 여러 문제를 동시에 제기하는 경우가 있다. 예를 들어, “결함 상품 교환도 하고 싶고, 지난달 청구 오류도 확인해 주세요.” 이런 다중 관심사 요청에 대한 올바른 아키텍처 패턴은 다음과 같다:
- 분해: 요청을 개별 관심사(concern)로 분리
- 병렬 조사: 공유된 고객 문맥을 기반으로 각 관심사를 동시에 조사
- 통합 해결: 개별 조사 결과를 하나의 통합된 응답으로 종합
핸드오프 요약(Handoff Summary)
에이전트가 인간 상담원에게 에스컬레이션할 때, 인간 상담원은 에이전트의 대화 기록(transcript)에 접근할 수 없을 수 있다. 따라서 핸드오프 요약에는 다음이 반드시 포함되어야 한다:
- 고객 ID (검증 완료 여부 포함)
- 근본 원인(root cause) 분석
- 환불 금액 또는 관련 수치
- 권장 조치(recommended action)
1.5 — 훅의 두 가지 패턴
훅(Hook)이란 무엇인가
훅은 에이전트 루프의 특정 시점에 코드로 개입하는 메커니즘이다. 프롬프트 지시가 “이렇게 해 달라”고 요청하는 것이라면, 훅은 “이 조건이 충족되지 않으면 실행 자체를 막는다”고 강제하는 것이다.
두 가지 훅 패턴
| 훅 패턴 | 실행 시점 | 용도 | 구체적 사례 |
|---|---|---|---|
| PostToolUse | 도구가 결과를 반환한 직후, 모델이 처리하기 전에 | 이종 데이터 형식의 정규화 | MCP 도구 A는 Unix 타임스탬프를, 도구 B는 ISO 8601을, 도구 C는 숫자 상태 코드를 반환 → 모델에게 전달하기 전에 일관된 형식으로 변환 |
| 도구 호출 인터셉션 | 모델이 도구 호출을 요청한 직후, 도구가 실행되기 전에 | 정책 위반 차단 | $500 초과 환불 요청 시 process_refund 실행을 차단하고, 대신 escalate_to_human 워크플로로 리다이렉트 |
이 두 패턴의 차이를 단계별로 정리하면 다음과 같다.
- 모델이 도구 호출을 요청한다.
- 도구 호출 인터셉션 훅이 실행 전 단계에서 요청을 차단하거나 수정한다.
- 실제 도구가 실행된다.
- PostToolUse 훅이 결과를 정규화하거나 변환한다.
- 모델은 정리된 결과를 받아 다음 행동을 결정한다.
빠르게 고르는 기준은 이렇다.
- 실행 전에 막아야 하는 정책 위반이면
도구 호출 인터셉션 - 실행은 허용하되, 결과를 모델이 쓰기 좋은 형태로 바꿔야 하면
PostToolUse - 둘 다 필요하면 실행 전에는 차단, 실행 후에는 정규화를 각각 별도 훅으로 둔다
왜 훅이 프롬프트보다 나은가
다시 한번 강조하지만, 이것은 시험 전반에 걸쳐 등장하는 핵심 판별 기준이다.
| 메커니즘 | 보장 | 적합한 상황 |
|---|---|---|
| 훅 | 결정론적 — 코드가 실행을 차단하므로 우회 불가 | 비즈니스 규칙의 보장된 준수 |
| 프롬프트 지시 | 확률적 — “대부분” 작동하지만 예외 존재 | 행동의 일반적 가이드 |
시험에서의 판별 공식: “오류가 발생하면 금전적 결과가 있는가?” → 예 → 훅. 아니오 → 프롬프트로 충분할 수 있다.
1.6 — 태스크를 어떻게 쪼갤 것인가
관련 개념 문서: Task Decomposition
두 가지 분해 패턴
태스크 분해(task decomposition)는 복잡한 작업을 관리 가능한 단위로 나누는 것이다. CCAF 시험에서는 두 가지 분해 패턴을 구분해야 한다.
| 패턴 | 구조 | 적합한 작업 | 예시 |
|---|---|---|---|
| 프롬프트 체이닝 (고정 순차 파이프라인) | 단계가 미리 정해져 있고, 각 단계의 출력이 다음 단계의 입력이 됨 | 예측 가능한 다면 작업 | 코드 리뷰: 파일별 로컬 분석 → 파일 간 통합 분석 |
| 동적 적응형 분해 | 중간 결과에 따라 다음 단계가 결정됨 | 탐색적, 개방형 작업 | 레거시 코드베이스에 종합 테스트 추가 |
빠른 판별 기준도 함께 기억해 두면 좋다.
- 시작하기 전에 주요 단계를 거의 다 적을 수 있으면
프롬프트 체이닝 - 중간 발견에 따라 조사 방향이 자주 바뀌면
동적 적응형 분해 - “먼저 전부 훑어본 뒤 우선순위를 다시 정해야 한다”면 대체로 동적 분해에 가깝다
프롬프트 체이닝의 구체적 적용: 대규모 코드 리뷰
14개 파일을 수정하는 풀 리퀘스트를 단일 패스로 리뷰하면 어떤 일이 발생하는가? 공식 샘플 문제 12번에서 정확히 이 상황을 다룬다:
- 일부 파일에 대해서는 상세한 피드백, 다른 파일에는 피상적 코멘트
- 명백한 버그 누락
- 모순된 피드백 — 한 파일에서는 특정 패턴을 문제시하면서 같은 PR의 다른 파일에서 동일한 코드를 승인
이것은 주의 분산(attention dilution) 때문이다. 해결 패턴은 명확하다:
- 파일별 로컬 분석 패스: 각 파일을 개별적으로 분석 → 일관된 깊이 보장
- 파일 간 통합 패스: 별도로 실행하여 파일 간 데이터 흐름, 의존성, 통합 이슈를 검출
✗ 시험 함정: “더 큰 문맥 창을 가진 상위 모델로 전환한다”는 선택지는 문맥 크기(context size)와 주의 품질(attention quality)을 혼동하는 오답이다. 더 큰 문맥 창이 주의 분산 문제를 해결하지 않는다.
동적 분해의 구체적 적용: 레거시 코드베이스 탐색
개방형 태스크(예: “이 레거시 코드베이스에 종합 테스트를 추가하라”)는 사전에 전체 단계를 정의할 수 없다. 올바른 접근은 다음과 같다:
- 구조 파악: 먼저 코드베이스의 전체 구조를 매핑
- 고영향 영역 식별: 테스트가 가장 필요한 핵심 모듈을 찾기
- 우선순위화된 적응형 계획: 의존성이 발견될 때마다 계획을 조정하며 진행
이것이 “적응형(adaptive)“인 이유는, 1단계에서 발견한 내용이 2단계의 방향을 결정하고, 2단계의 결과가 3단계의 우선순위를 바꾸기 때문이다.
1.7 — 세션 이어가기, 분기, 정리
관련 개념 문서: Session Management
세션 관련 주요 명령
태스크를 잘게 나눌수록 실행 시간이 길어지고, 중간 산출물도 많아진다. 그래서 분해 전략 다음에는 자연스럽게 세션을 어떻게 이어가고, 언제 갈라서고, 언제 정리할지를 판단해야 한다. 좋은 분해 전략도 세션 관리가 약하면 금방 문맥 오염이나 오래된 결과 문제로 이어진다.
| 메커니즘 | 용도 | 구체적 사용 시점 |
|---|---|---|
--resume <session-name> | 특정 이름의 이전 세션을 이어서 진행 | 작업 세션 간에 이전 조사를 계속해야 할 때 |
fork_session | 공유된 기준선에서 독립적인 분기를 생성 | 두 가지 테스팅 전략이나 리팩터링 접근법을 비교해야 할 때 |
/compact | 확장된 세션에서 문맥 사용량을 축소 | 탐색 과정에서 장황한 도구 출력이 문맥을 가득 채웠을 때 |
이어갈 것인가, 새로 시작할 것인가
이것은 시험에서 판단력을 측정하는 전형적인 문항 유형이다.
| 상황 | 올바른 선택 | 이유 |
|---|---|---|
| 이전 문맥의 대부분이 여전히 유효함 | --resume으로 이전 세션 재개 | 축적된 문맥을 재활용할 수 있음 |
| 이전 도구 결과가 오래됨(stale) | 구조화된 요약과 함께 새 세션 시작 | 오래된 도구 결과에 기반한 추론은 신뢰할 수 없음 |
| 이전 세션 후 파일이 수정됨 | 세션 재개 + 변경 사항을 명시적으로 에이전트에 알림 | 에이전트가 변경된 파일만 대상으로 재분석하도록 유도 |
| 두 가지 접근법을 비교해야 함 | fork_session으로 분기 생성 | 각 분기가 독립적으로 진행되어 상호 영향 없음 |
핵심 원칙: 오래된 도구 결과가 있는 세션을 이어가는 것보다, 핵심 발견 사항을 구조화된 요약으로 정리하고 새 세션을 시작하는 것이 더 신뢰성 있다.
/compact는 언제 쓰는가
/compact는 확장된 탐색 세션에서 장황한 도구 출력(예: 대규모 코드베이스 탐색 중 Grep 결과)이 문맥을 가득 채웠을 때 사용한다. 이것은 문맥 창의 여유를 확보하여 에이전트가 새로운 정보를 처리할 수 있게 해준다.
그러나 /compact가 만능은 아니다. Anthropic의 “장기 실행 에이전트를 위한 효과적인 하니스” 문서에서 설명하듯, 컴팩션(compaction)만으로는 충분하지 않은 경우가 있으며, 특히 여러 문맥 창에 걸친 작업에서는 매니페스트 파일이나 진행 기록 파일(claude-progress.txt) 같은 외부 상태 저장 메커니즘이 필요할 수 있다.
자주 나오는 오답 패턴 정리
시험에서 오답 선택지로 등장할 가능성이 높은 안티패턴을 종합적으로 정리한다. 각각이 왜 틀린지를 이해하는 것이 정답을 외우는 것보다 효과적이다.
| # | 안티패턴 | 왜 틀린가 | 올바른 접근 |
|---|---|---|---|
| 1 | 자연어를 파싱하여 루프 종료 감지 | 비결정론적 출력에 의존 — stop_reason이라는 구조화된 신호가 존재 | stop_reason을 프로그래밍적으로 확인 |
| 2 | 반복 횟수 상한을 주요 종료 조건으로 사용 | 태스크 완료 전 강제 종료 가능 | stop_reason === "end_turn"이 주요 조건, 상한은 안전장치로만 |
| 3 | 어시스턴트 텍스트를 완료 표시자로 확인 | stop_reason이 "tool_use"인데도 완료 텍스트가 포함될 수 있음 | stop_reason 필드만 신뢰 |
| 4 | 코디네이터의 태스크 분해가 너무 좁음 | 서브에이전트가 성공해도 전체 커버리지에 공백 발생 | 넓은 범위의 분해 + 반복적 정제로 갭 보완 |
| 5 | Few-shot으로 도구 호출 순서를 강제 | 순서 보장은 규정 준수 문제 — 확률적 방법으로는 부족 | 프로그래밍적 사전 조건(hook)으로 강제 |
| 6 | 모든 서브에이전트에 전체 도구 접근 부여 | 역할 외 도구를 오용할 가능성 증가, 선택 신뢰도 저하 | 역할별로 필요한 도구만 할당 |
| 7 | 서브에이전트 실패 시 빈 결과를 성공으로 반환 | 에러를 조용히 억제 → 코디네이터가 복구할 수 없음 | 구조화된 에러 문맥을 반환 |
| 8 | 동일 세션에서 코드 생성 후 리뷰 | 생성 시의 추론 문맥이 남아 리뷰 편향 발생 | 독립적인 리뷰 인스턴스 사용 |
직접 해보기
공식 시험 가이드에서 권장하는 실습 과제(Exercise 1, 4)를 구체화한 것이다.
연습 1: 에스컬레이션 로직을 갖춘 멀티 도구 에이전트 구축
- 3~4개의 MCP 도구를 정의한다. 도구 설명을 상세하게 작성하되, 최소 2개는 유사한 기능을 가지도록 설계하여 설명의 차별화가 왜 중요한지 직접 확인한다.
- 에이전트 루프를 구현한다.
stop_reason이"tool_use"일 때 도구를 실행하고,"end_turn"일 때 최종 응답을 반환하는 제어 흐름을 구현한다. - 구조화된 에러 응답을 도구에 추가한다.
errorCategory(transient/validation/permission),isRetryable불리언, 설명 메시지를 포함한다. 에이전트가 각 에러 유형에 적절히 대응하는지 테스트한다. - 프로그래밍적 훅을 구현한다. 특정 금액 이상의 작업을 차단하고, 에스컬레이션 워크플로로 리다이렉트하는 도구 호출 인터셉션 훅을 만든다.
- 다중 관심사 메시지로 테스트한다. “반품도 처리하고, 지난달 청구도 확인해 주세요” 같은 메시지를 보내 에이전트가 요청을 분해하고, 각각 처리한 뒤, 통합된 응답을 생성하는지 확인한다.
연습 2: 멀티 에이전트 연구 파이프라인 설계
- 코디네이터 + 최소 2개 서브에이전트를 구축한다. 코디네이터의
allowedTools에"Task"가 포함되었는지 확인하고, 각 서브에이전트가 연구 결과를 프롬프트에 직접 전달받는지 검증한다. - 병렬 서브에이전트 실행을 구현한다. 코디네이터가 단일 응답에서 여러 Task 호출을 내보내도록 하고, 순차 실행 대비 지연 시간 개선을 측정한다.
- 구조화된 출력을 설계한다. 각 서브에이전트의 결과에서 주장(claim)과 메타데이터(출처 URL, 문서명, 발행일)를 분리한다. 종합 에이전트가 출처 정보를 보존하는지 확인한다.
- 에러 전파를 구현한다. 서브에이전트 타임아웃을 시뮬레이션하고, 코디네이터가 구조화된 에러 문맥(실패 유형, 시도한 쿼리, 부분 결과)을 받는지 테스트한다. 코디네이터가 부분 결과로 진행하고 최종 출력에 커버리지 갭을 주석으로 표시하는지 확인한다.
- 충돌 출처 테스트를 수행한다. 두 개의 신뢰할 수 있는 출처가 서로 다른 통계를 제시하는 경우를 만들어, 종합 결과가 양쪽 값을 출처와 함께 모두 보존하는지(임의로 하나를 선택하지 않는지) 확인한다.
참고 링크
| 주제 | 링크 |
|---|---|
| 에이전트 패턴 총론 | Building Effective Agents — Anthropic Research |
| 멀티 에이전트 시스템 사례 | Multi-Agent Research System — Anthropic Engineering |
| Agent SDK 구축 가이드 | Building Agents with Claude Agent SDK — Anthropic Engineering |
| Agent SDK 문서 | Claude Agent SDK Docs |
| Think Tool | Claude Think Tool — Anthropic Engineering |
| 장기 실행 에이전트 | Effective Harnesses for Long-Running Agents — Anthropic Engineering |
| 문맥 공학 | Effective Context Engineering — Anthropic Engineering |
| 공식 시험 가이드 PDF | CCAF Exam Guide |