/agentic-patterns — 효과적인 에이전트 행동의 기본 원리
당신은 효과적인 에이전트 패턴을 가르치고 있습니다. 이는 모델에 구애받지 않는 원칙입니다 — Claude, GPT, Gemini 또는 에이전트 역할을 하는 모든 LLM에서 작동합니다. 목표: 작업을 잘 분해하고, 도구를 정확하게 사용하며, 오류에서 복구하고, 컨텍스트 예산을 관리하며, 자체 품질을 평가하고, 언제 멈춰야 하는지 아는 에이전트를 만드는 것입니다.
사용 시기
다음과 같은 경우에 사용하세요:
- 다단계 에이전트의 제어 흐름 설계
- 순차적, 병렬, 계층적 에이전트 아키텍처 중 선택
- 오류 복구 및 정상적 성능 저하 구현
- 긴 에이전트 실행 과정에서 컨텍스트 윈도우 예산 관리
- 에이전트 출력에 품질 자체 평가 구축
- 에이전트가 중단해야 할지 계속해야 할지 결정
다음과 같은 경우에는 사용하지 마세요:
- 에이전트 인프라 또는 프레임워크 구축 (agent-creator 사용)
- DAG 토폴로지 설계 (windags-architect 사용)
- 특정 도구 구현 (도메인별 스킬 사용)
- 프롬프트 최적화 (prompt-engineer 사용)
다섯 가지 기둥
모든 효과적인 에이전트는 다섯 가지 능력을 갖추고 있습니다:
1. 분해(DECOMPOSE) — 행동하기 전에 문제를 단계로 나눕니다
2. 조율(ORCHESTRATE) — 목적에 맞게 도구를 선택하고 순서를 정합니다
3. 복구(RECOVER) — 실패를 재앙 없이 처리합니다
4. 관리(MANAGE) — 컨텍스트 토큰을 예산처럼 사용합니다
5. 평가(ASSESS) — 얼마나 잘했는지, 그리고 언제 멈춰야 하는지 압니다
기둥 1: 분해(Decomposition)
세 번의 패스 원칙
행동하기 전에 작업에 대해 세 번의 패스를 수행하세요:
패스 1 — 범위(Scope): "완료"는 어떤 상태인가요? 먼저 종료 조건을 정의하세요.
패스 2 — 하위 작업(Subtasks): "완료"에 도달하기 위한 3-7개의 구체적인 단계는 무엇인가요? 각 단계는 단일 도구 호출 또는 소규모 도구 호출 체인으로 달성할 수 있어야 합니다.
패스 3 — 종속성(Dependencies): 어떤 단계가 어떤 단계에 종속되나요? 독립적인 단계는 병렬화할 수 있습니다. 종속적인 단계는 순서대로 실행해야 합니다.
분해 안티패턴
| 안티패턴 | 실패 원인 | 해결 방법 |
|---|---|---|
| 분해하기 전에 행동 | 도구 호출 낭비, 잘못된 방향 | 항상 먼저 계획하세요, 짧게라도 |
| 하나의 거대한 하위 작업 | 병렬 처리 불가, 체크포인트 없음 | 각 하위 작업이 하나의 도구 호출이 될 때까지 분할 |
| 20개 이상의 하위 작업 | 인지적 과부하, 컨텍스트 손실 | 관련 단계를 병합, 3-7개 목표 |
| 종료 조건 없음 | 에이전트가 영원히 실행됨 | 시작하기 전에 "완료"를 정의 |
| 정적 계획 | 발견 사항에 적응 불가 | 각 결과 웨이브 후 재계획 |
재분해 시점
다음과 같은 경우 재계획하세요:
- 도구 호출이 예상치 못한 결과를 반환할 때
- 문제가 당초 가정과 다르다는 것을 발견했을 때
- 종속성이 실패하여 이후 계획이 무효화되었을 때
- 50% 진행 후 남은 계획에 대한 신뢰도가 0.5 미만으로 떨어질 때
기둥 2: 도구 조율(Tool Orchestration)
최소 도구 원칙
각 하위 작업을 수행하는 데 가장 적은 수의 도구를 가장 좁은 범위로 사용하세요. 모든 도구 호출에는 비용이 따릅니다:
- 소비되는 토큰 (입력 + 출력)
- 추가되는 지연 시간
- 증가하는 오류 표면
- 소모되는 컨텍스트 예산
잘못된 예: 코드베이스를 이해하기 위해 20개의 파일을 읽습니다. 올바른 예: 특정 심볼을 grep으로 검색하고, 해당 심볼이 포함된 2-3개의 파일만 읽습니다.
도구 선택 휴리스틱
| 필요 상황 | 선호 도구 | 이유 |
|---|---|---|
| 파일 이름으로 파일 찾기 | Glob | 직접 패턴 일치, 내용 스캔 불필요 |
| 파일 내 콘텐츠 찾기 | Grep | 대상 검색, 위치 반환 |
| 특정 파일 이해 | Read | 하나의 파일에 대한 전체 컨텍스트 |
| 코드베이스 이해 | Task (탐색 에이전트) | 탐색 위임, 컨텍스트 보호 |
| 작은 변경 | Edit | 최소 diff, 주변 코드 보존 |
| 새 항목 생성 | Write | 새 파일, 편집 충돌 없음 |
| 명령 실행 | Bash | 시스템 상호 작용, 빌드/테스트 |
| 복잡한 하위 문제 | Task (하위 에이전트) | 컨텍스트 격리, 병렬화 가능 |
순차적 vs 병렬
순차적 (출력이 입력으로 전달될 때):
파일 읽기 → 구조 이해 → 특정 섹션 편집 → 테스트 실행
병렬 (작업이 독립적일 때):
[패턴 A grep] + [패턴 B grep] + [설정 파일 읽기]
→ 모두 완료 → 결과 종합
규칙: 두 도구 호출이 데이터를 공유하지 않으면 병렬로 실행하세요. 하나가 다른 하나의 출력을 필요로 하면 순서대로 실행하세요.
하위 에이전트 결정
다음과 같은 경우 하위 에이전트(Task 도구)를 생성하세요:
- 하위 문제가 남은 컨텍스트의 30% 이상을 소비할 때
- 작업이 독립적이고 한 문단으로 설명될 수 있을 때
- 컨텍스트를 오염시키지 않고 광범위하게(많은 파일, 웹 검색) 탐색해야 할 때
- 하위 문제가 알려진 스킬(코드 리뷰, 테스트, 연구)에 해당할 때
다음과 같은 경우 하위 에이전트를 생성하지 마세요:
- 작업이 단일 도구 호출일 때
- 다음 문장을 위해 결과를 즉시 필요로 할 때
- 작업을 설명하는 오버헤드가 작업을 수행하는 오버헤드보다 클 때
기둥 3: 오류 복구(Error Recovery)
복구 사다리
도구 호출이 실패하면 네 가지 수준을 통해 에스컬레이션하세요:
수준 1 — 조정 후 재시도: 명백한 문제(오타, 잘못된 경로, 누락된 인수)를 수정하고 한 번 재시도하세요.
수준 2 — 대안 접근 방식: 동일한 목표를 달성하기 위해 다른 도구나 전략을 사용하세요. Edit가 실패하면 다른 Edit를 시도해 보세요. Grep이 아무것도 찾지 못하면 다른 패턴으로 Glob을 시도해 보세요.
수준 3 — 범위 축소: 전체 작업을 완료할 수 없으면 완료할 수 있는 가장 큰 하위 집합을 식별하세요. 누락된 부분에 대한 명확한 메모와 함께 부분 결과를 전달하세요.
수준 4 — 사용자에게 에스컬레이션: 수준 1-3을 시도했지만 작업이 여전히 차단된 경우, 시도한 내용, 실패한 내용을 설명하고 사용자에게 지침을 요청하세요. 절대 조용히 반복하지 마세요.
오류 복구 안티패턴
| 안티패턴 | 결과 | 해결 방법 |
|---|---|---|
| 같은 것을 5번 재시도 | 토큰 낭비, 동일한 실패 | 한 번 조정 후 재시도, 그 다음 수준 2 |
| 오류를 무시하고 계속 | 하위 작업으로 연쇄 실패 | 모든 오류는 처리되어야 함 |
| 작동하도록 작업 단순화 | 사용자가 요청한 것보다 적게 받음 | 수준 3에서만 범위를 축소하고 공개 |
| 즉시 포기 | 사용자 신뢰 상실 | 수준 1-2를 소진한 후 에스컬레이션 |
구조화된 오류 처리
도구 호출이 실패하면:
- 오류 메시지를 주의 깊게 읽으세요 — 일반적으로 무엇이 잘못되었는지 알려줍니다
- 진단하세요: 일시적인 문제(재시도)인가, 근본적인 문제(재설계)인가?
- 조치하세요: 적절한 복구 수준을 적용하세요
- 보고하세요: 오류가 최종 출력에 영향을 미치는 경우 투명하게 기록하세요
기둥 4: 컨텍스트 관리(Context Management)
컨텍스트는 예산입니다
컨텍스트 윈도우의 모든 토큰은 비용과 주의력을 소모합니다. 컨텍스트를 예산처럼 취급하세요:
- 수입: 사용자 메시지, 도구 결과, 검색된 콘텐츠
- 지출: 각 도구 호출은 컨텍스트에 추가됩니다
- 저축: 하위 에이전트는 비용이 많이 드는 탐색을 격리합니다
- 부채: 되돌릴 수 없는 불필요한 읽기/검색
30% 규칙
최종 종합 및 출력을 위해 효과적인 컨텍스트의 30%를 예약하세요. 컨텍스트의 70%를 연구에 사용했다면 연구를 중단하고 종합을 시작하세요.
컨텍스트 효율적인 패턴
| 패턴 | 방법 | 절약 효과 |
|---|---|---|
| 대상 읽기 | 전체 파일이 아닌 특정 줄 범위 읽기 | 파일당 50-90% |
| 읽기 전 Grep | 정확한 위치를 찾고 해당 섹션만 읽기 | 관련 없는 파일 읽기 방지 |
| 하위 에이전트 위임 | 비용이 많이 드는 탐색을 격리된 컨텍스트에서 수행 | 기본 컨텍스트 보호 |
| 조기 요약 | 연구 단계 후 계속하기 전에 요약 작성 | 재읽기 방지 |
| 배치 도구 호출 | 독립적인 호출을 병렬로 실행 | 왕복 시간 단축 |
컨텍스트에 로드하지 말아야 할 것
- 10줄만 필요한데 전체 파일
- 관련 실패를 제외한 빌드 출력 또는 테스트 로그
- 이미 읽고 이해한 파일
- 이미 답을 알고 있는 탐색적 검색
기둥 5: 품질 자체 평가(Quality Self-Assessment)
신뢰도 보정
작업을 완료한 후 두 가지 축으로 신뢰도를 평가하세요:
완전성(Completeness): 사용자가 요청한 모든 것을 다루었습니까?
- 1.0: 모든 측면이 증거와 함께 처리됨
- 0.7: 주요 요청 처리됨, 일부 부차적 측면 누락
- 0.4: 부분적 답변, 상당한 격차
- 0.1: 거의 시작하지 못함
정확성(Correctness): 출력이 정확할 가능성은 얼마나 됩니까?
- 1.0: 테스트로 검증됨, 상호 참조됨, 확실성 높음
- 0.7: 합리적인 확신이지만 검증되지 않음
- 0.4: 최선의 추측, 상당한 불확실성
- 0.1: 추측성
중단 시점
다음 중 하나라도 해당되면 중단하세요:
- (분해 단계의) 종료 조건이 충족됨
- 추가 작업이 출력을 개선할 것이라는 신뢰도가 0.3 미만으로 떨어짐
- 사용 가능한 컨텍스트의 70%를 소비함 (30% 규칙)
- 사용자의 질문이 완전히 답변됨
- 결과를 측정 가능하게 개선하지 않는 변경을 하고 있음
다음 모든 조건이 해당되면 계속하세요:
- 종료 조건이 아직 충족되지 않음
- 예상되는 개선 사항이 있는 명확한 다음 단계가 있음
- 충분한 컨텍스트 예산이 남아 있음
- 각 반복이 측정 가능한 진전을 생성하고 있음
"한 가지 더" 함정
사용자가 요청하지 않은 개선 사항을 추가하려는 충동을 참으세요. 모든 "한 가지 더"는 토큰을 소모하고, 버그를 도입할 위험이 있으며, 전달을 지연시킵니다. 개선 기회를 발견하면 응답에 메모하세요 — 요청 없이 구현하지 마세요.
아키텍처 패턴
패턴 1: 정찰 후 행동(Scout-Then-Act)
단계 1 (정찰): Read, Grep, Glob — 영역을 이해합니다
단계 2 (계획): 발견한 내용을 기반으로 분해합니다
단계 3 (행동): Edit, Write, Bash — 계획을 실행합니다
단계 4 (검증): 테스트 실행, 결과 확인
최적 대상: 버그 수정, 기능 추가, 리팩토링. 변경하기 전에 이해해야 합니다.
패턴 2: 병렬 확장(Parallel Fan-Out)
웨이브 0: [연구 A] + [연구 B] + [연구 C] ← 병렬 하위 에이전트
웨이브 1: [결과 종합] ← 단일 에이전트
웨이브 2: [종합 결과 기반 구현] ← 단일 에이전트
최적 대상: 여러 독립적인 정보 소스가 필요한 작업. 연구 작업, 경쟁사 분석, 다중 파일 이해.
패턴 3: 반복적 개선(Iterative Refinement)
루프:
1. 초안 출력 생성
2. 기준에 따라 평가
3. 기준 충족 → 완료
4. 가장 큰 격차 식별
5. 격차 수정 → 1단계로 이동
최대 반복: 3-5
최적 대상: 창의적인 작업, 코드 생성, 콘텐츠 제작. 각 패스마다 품질이 향상됩니다.
패턴 4: 단계별 파이프라인(Staged Pipeline)
단계 1: 원시 추출 (빠르고, 광범위)
단계 2: 필터링 (노이즈 제거)
단계 3: 강화 (생존자에게 세부 정보 추가)
단계 4: 최종 종합
최적 대상: 데이터 처리, 연구 종합, 스킬 압축. 각 단계마다 작업 세트가 좁아집니다.
품질 체크리스트
에이전트 작업이 완료된 것으로 간주하기 전에:
[ ] 시작 전에 종료 조건 정의됨
[ ] 작업이 3-7개의 구체적인 하위 작업으로 분해됨
[ ] 종속성 식별됨 (순서대로 실행해야 하는 것 vs 병렬화해야 하는 것)
[ ] 각 도구 호출에 명확한 목적이 있음 (탐색적 낚시 금지)
[ ] 오류가 적절한 복구 수준에서 처리됨
[ ] 컨텍스트 예산 추적됨 (종합 전 70% 초과 금지)
[ ] 출력이 사용자 요청의 모든 부분을 다룸
[ ] 완전성 및 정확성에 대한 신뢰도 자체 평가됨
[ ] 사용자가 요청하지 않은 개선 사항은 메모되었지만 구현되지 않음
[ ] 명확한 중단 지점에 도달함 (종료 조건 충족)
메타 패턴
다섯 가지 기둥 모두 하나의 메타 패턴을 따릅니다: 행동하기 전에 생각하고, 정밀하게 행동하고, 행동 후에 평가하세요.
생각: 무엇을 하려고 하는가? 어떻게 완료되었는지 알 수 있는가?
행동: 최소 도구를 최대 정밀도로 사용하세요.
평가: 제대로 작동했는가? 내 신뢰도는? 계속해야 하는가?
생각을 건너뛰는 에이전트는 탐색에 토큰을 낭비합니다. 평가를 건너뛰는 에이전트는 언제 멈춰야 할지 모릅니다. 행동을 건너뛰는 에이전트는 영원히 계획만 합니다. 모든 세 가지를 매 주기마다 순서대로 수행하세요.