하위 에이전트 우선 · 주 에이전트는 직접 나서지 않는다
주 에이전트의 주의력은 사용자에게 속하며, 작업에 속하지 않는다. 여러 번의 도구 호출이 예상되는 작업은 모두 하위 에이전트에게 백그라운드로 위임하고, 주 에이전트는 분해, 위임, 검증, 마무리만 담당하며 항상 사용자에게 즉시 응답할 수 있는 상태를 유지한다.
많은 AI 에이전트가 어색하게 사용되는 근본 원인은 모델이 충분히 강력하지 않아서가 아니라, 주 에이전트가 무거운 작업에 발목 잡혀 있기 때문이다: 사용자가 한마디를 보내면 주 에이전트는 20번의 도구 호출을 수행하는 동안 응답도, 방향 전환도 할 수 없고 사용자는 그저 기다려야 한다. 마침내 작업을 마치면 요구 사항이 이미 변경되어 있을 수 있다.
이 스킬이 제공하는 것은 작업 규율(作業紀律)이다. 즉, '언제 위임해야 하는지, 어떻게 위임하는지, 어떻게 검증하는지'를 감이 아닌 판단 가능한 규칙으로 만드는 것이다. 이 규율은 플랫폼에 독립적이다: 하위 에이전트/백그라운드 작업을 지원하는 모든 AI 에이전트(Claude Code, Codex, Cursor, WorkBuddy, Hermes 및 기타 유사 도구)에 적용되며, 차이는 도구 이름에만 있다. 매핑은 이 문서의 '도구 이름 대응표' 섹션을 참조한다.
특정 플랫폼에 적용 시 실시간 차이: Hermes의 필드 이름, 동시 실행 상한, 백그라운드 의미 및 비용 관련 사항은
references/hermes-runtime-reality.md에 정리되어 있다(예시 구현이며, 다른 플랫폼은 무시 가능). 본문은 규율만 다루며, 해당 페이지에 의존하지 않는다.
트리거 조건
다음 중 하나라도 발생하면, 이 스킬에 따라 작업을 수행해야 한다(직접 처리하지 않음):
- 작업이 2-3회 이상의 도구 호출이 예상됨: 예를 들어 '파일 8개를 읽고 요약하기', '검색 후 정리하기'.
- 한 번에 여러 개의 독립적인 단위를 처리해야 함: 여러 파일, 디렉토리, URL, 데이터, 후보군.
- 장기 연구/장기 검색: 반복적인 검색, 가져오기, 비교가 필요하며 시간이 몇 분 단위로 소요됨.
- 배치 처리: 동일한 작업 집합을 여러 입력에 대해 수행(정리, 변환, 항목별 확인, 항목별 생성).
- 사용자가 명시적으로 병렬 실행 또는 '여러 작업 동시 수행'을 요청함.
- 주 에이전트가 사용자와의 대화 중임: 사용자가 언제든지 질문, 요구 사항 변경, 새 작업을 지시할 수 있음.
- 하위 작업이 서로 의존하지 않고 동시에 시작 가능: 전형적으로 '세 개의 문서를 각각 교정하고 마지막에 결론을 통합'하는 경우.
- 무거운 작업이 백그라운드에서 실행되는 동안 사용자가 다른 대화를 계속하고 싶어함(이것이 이 스킬의 주요 이점 시나리오).
반대 트리거 조건: 한 번의 도구 호출로 완료할 수 있고, 사용자가 메시지를 보낸 후 더 이상 대화하지 않는다면 직접 수행한다. 억지로 하위 에이전트에 위임하면 오히려 더 느려진다. 판단 기준은 다음 섹션의 의사 결정 트리를 참조한다.
핵심 원칙
- 주 에이전트는 무거운 작업에 직접 나서지 않는다. 주 에이전트는 분해 → 위임 → 마무리 요약 → 사용자와의 대화 네 가지만 수행한다. 항상 '즉시 응답 가능'한 상태를 유지해야 한다.
- 무거운 작업은 반드시 하위 에이전트에 위임한다(강제). 위의 트리거 조건이 충족되면 반드시 위임해야 하며, '내가 빠르니까 그냥 해도 돼'라는 생각은 금물이다. 판단 기준은 작업 속성이지 주 에이전트의 자신감이 아니다.
- 자체 보고는 사실이 아니다. 하위 에이전트가 '완료'했다고 말하는 것은 단지 주장일 뿐이다. 검증되지 않은 산출물은 모두 미완료로 간주한다(자세한 내용은 '검증 체크리스트' 참조).
- 컨텍스트는 반드시 자체 포함되어야 한다. 하위 에이전트는 사용자와의 대화 기록을 볼 수 없다. 당신이 머릿속에 가지고 있는 배경 정보를 전혀 받을 수 없다. 위임 작업 지시가 불완전하면 반드시 잘못된 방향으로 진행될 것이다. 이는 하위 에이전트가 멍청해서가 아니라 당신이 정보를 제대로 전달하지 않았기 때문이다.
- 병렬 실행에는 경계가 있다. 의존성이 없는 작업만 병렬로 실행하고, 순서 의존성이 있는 작업은 반드시 직렬로 실행하거나 상위 산출물을 하위 작업에 전달해야 한다.
- 사용자 결정이 필요한 작업은 위임하지 않는다. 사용자 확인, 되돌릴 수 없는 결과, 즉각적인 감독이 필요한 작업은 주 에이전트가 직접 처리한다.
- 세션을 초과하는 장기 작업은 메커니즘을 변경한다. 현재 세션을 넘어서 지속되어야 하는 작업(지속적인 모니터링, 정기적 트리거, 상주 프로세스)은 플랫폼의 정기/상주 메커니즘(크론 작업, 예약 작업, 백그라운드 프로세스)을 사용하고, 하위 에이전트는 사용하지 않는다. 하위 에이전트의 수명 주기는 단일 위임에 연결된다.
- 실패 시에는 다운그레이드하고, 지어내지 마라. 하위 에이전트가 실패, 시간 초과, 부적격 산출물을 생성한 경우: 직접 처리하거나 경로를 변경하여 다시 위임한다. '얻지 못한 결과'를 '얻었다'고 절대 작성해서는 안 된다.
이 원칙들은 공학적으로 잘 알려진 fork-join/fan-out-fan-in 패러다임에 해당한다: 작업을 여러 실행 단위로 분기(fork)한 후 결과를 수집(join)한다(Java의
ForkJoinPool, Dean과 Ghemawat이 OSDI 2004에서 제안한 MapReduce가 이 개념의 구체적인 구현이다). 이 스킬은 새로운 개념을 발명하지 않고, 에이전트 시나리오에 적용 가능한 작업 규율로 구체화한다.
의사 결정 트리: 무엇이 무거운 작업이고, 무엇을 직접 할 것인가
다음 질문에 순서대로 답하고, 처음으로 '예'인 분기가 결론이다.
질문 1: 이 작업을 한 번의 도구 호출로 완료할 수 있는가?
| 판단 항목 | 판단 기준 |
|---|---|
| 도구 호출 횟수 | 직접 셀 수 있으며, ≤ 1회 |
| 여러 파일을 읽어야 하는가 | 아니오(0–1개) |
| 반복문이 있는가 | 아니오('각각에 대해' 없음) |
| 예상 소요 시간 | 초 단위 |
네 항목 모두 충족 → 직접 수행. 하나라도 충족되지 않으면 질문 2로 이동.
질문 2: 이 작업에 사용자 결정이 필요한가?
- 사용자가 여러 옵션 중 하나를 선택해야 함 → 직접 수행(또는 먼저 정보만 수집하여 옵션을 사용자에게 제시).
- 되돌릴 수 없는 작업(데이터 삭제, 외부 발행, 결제, 타사 메시지 발송)이 포함되고 즉각적인 감독이 필요함 → 직접 수행.
- 단지 '사용자가 알 필요가 있는' 정도이며, 과정 중 사용자 결정이 필요하지 않음 → 위임 가능하지만, 요약 시 명확히 설명해야 함.
질문 3: 이 작업이 현재 세션을 넘어서 지속되어야 하는가?
- 예(정기적 트리거, 지속적 모니터링, 상주 서비스) → 플랫폼의 정기/상주 메커니즘(크론 작업, 예약 작업, 백그라운드 프로세스)을 사용하고, 하위 에이전트는 사용하지 않음.
- 아니오, 현재 세션 내에서 완료하면 됨 → 질문 4로 이동.
질문 4: 서로 의존하지 않는 여러 블록으로 분할할 수 있는가?
- 가능 → 여러 하위 에이전트에 병렬로 위임, 각각 자체 파일/디렉토리/URL/데이터셋을 담당하고 마지막에 주 에이전트가 병합.
- 불가능하지만 명확한 순서가 있음 → 직렬로 위임, 또는 단일 하위 에이전트가 전체 체인을 실행(직접하는 것보다 효율적).
- 분할할 수 없고 작업이 길지 않음 → 질문 1로 돌아가 다시 확인, 대부분 직접 수행.
정량적 빠른 참조표
| 작업 유형 | 일반 소요 시간 | 처리 방법 |
|---|---|---|
| 특정 값 확인, 파일의 특정 부분 읽기 | 초 | 직접 수행 |
| 한 곳의 문구 수정, 명령어 하나 실행 | 초 | 직접 수행 |
| 3개 파일 읽고 요약 | 1-2분 | 직접 또는 위임 가능; 사용자가 기다리고 있을 때 위임 |
| 8개 파일 읽고 각각 요약 | 수 분 | 위임 |
| 다중 소스 검색 + 교차 비교 | 수 분에서 십여 분 | 위임(블록별 병렬 가능) |
| N개 입력 배치 처리 (N ≥ 5) | N에 따라 증가 | 위임(슬라이스 병렬) |
| 사용자가 옵션을 선택해야 함 | 불규칙 | 직접 수행(수집 + 옵션 제시) |
| 매일 정해진 시간에 한 번 실행 | 세션 초과 | 크론 작업(하위 에이전트 아님) |
5단계 프로세스
1단계: 분해
작업을 경계가 명확한 단위로 자른다. 각 단위는 다음 세 가지 질문에 독립적으로 답할 수 있어야 한다:
- 입력은 무엇인가: 파일 경로, 디렉토리, URL 목록, 데이터셋 이름, 매개변수까지 구체적으로.
- 산출물은 무엇인가: 파일 이름, 형식, 경로까지 구체적으로.
- 완료는 어떻게 판단하는가: 판단 가능한 기준이어야 하며, '잘 끝내면 됨'이 아니다.
분할 시 두 가지를 지킨다:
- 파일 쓰기 충돌 금지: 두 하위 에이전트가 절대 동일한 파일에 써서는 안 된다. 각자 자신의 파일을 쓰고 마지막에 주 에이전트가 병합하거나, 직렬로 실행한다.
- 의존성 명시: A의 산출물이 B에 제공되어야 하는 경우 병렬로 위임할 수 없다. 직렬로 실행하거나 단일 하위 에이전트가 A+B를 모두 처리하도록 해야 한다.
완료 판단 기준(항목별 체크)
- 각 단위에 입력(특정 경로/목록 포함)이 명시되었는가
- 각 단위에 산출물(파일 이름 + 형식 + 저장 위치)이 명시되었는가
- 각 단위에 판단 가능한 완료 기준이 있는가
- 두 단위가 동일한 파일에 쓰지 않는가
- 모든 의존 관계가 표시되었는가(어느 것이 직렬로 실행되어야 하는지)
2단계: 위임
플랫폼의 하위 에이전트/백그라운드 작업 도구를 사용하여 각 단위를 위임한다(Hermes에서는 delegate_task, 다른 플랫폼은 '도구 이름 대응표'에 따라 매핑). 작업 지시는 '4요소'에 따라 작성한다(다음 섹션 참조). 핵심:
- 하나의 하위 에이전트는 하나의 명확한 작업만 맡기고, 관련 없는 세 가지 일을 하나의 작업 지시에 넣지 않는다.
- 작업 지시에 배경 정보를 완전히 작성한다. 하위 에이전트는 사용자와의 대화를 볼 수 없다.
- 산출물이 어느 경로에 저장될지와 무엇을 보고해야 하는지(파일 경로? 줄 수? 명령어 출력?) 명확히 지시한다.
- 검증 가능한 것만 보고하도록 명확히 요구한다: 어떤 명령어를 실행했는지, 어떤 출력을 얻었는지; 달성하지 못한 것은 솔직히 말하도록 한다.
- 플랫폼이 구조화된 보고/출력 검증(예: JSON 스키마로 하위 에이전트의 최종 응답 검증)을 지원한다면, 자유 텍스트보다 구조화된 형식을 사용한다.
완료 판단 기준
- 각 작업 지시에 4요소(목표/배경/출력 구조/검증 방식)가 모두 포함되었는가
- 각 작업 지시에 출력 경로가 지정되었는가
- 각 작업 지시에 검증 가능한 증거(명령어 + 실제 출력)를 보고하도록 요구했는가
- 작업 지시에 '알잖아', '전처럼' 같은 불완전한 참조가 없는가
3단계: 병렬 스케줄링
- 병렬 가능한 것은 병렬로 위임한다: 서로 의존하지 않는 단위는 한 번에 모두 위임하고, 줄서서 기다리게 하지 않는다.
- 의존성이 있는 것은 직렬로 실행한다: 상위 단위가 검증을 통과할 때까지 기다린 후, 그 산출물을 하위 작업 지시의 컨텍스트로 제공한다.
- 병렬 실행에는 상한을 둔다: 너무 많이 동시에 열면 서로 자원을 빼앗고, 주 에이전트의 수집 부담도 증가한다. 한 번에 3~5개가 일반적인 적정 범위이다. 그 이상은 배치를 고려한다(상한 초과 시 결과는 각 플랫폼에 따라 다르며, '도구 이름 대응표'와 플랫폼 실시간 페이지 참조).
- 위임 후 즉시 사용자 곁으로 돌아간다: 하위 에이전트를 기다리며 그 자리에 있지 않는다. 이것이 바로 이 규율의 목적이다. 사용자가 당신을 기다리고 있을 때, 당신은 응답할 수 있어야 한다.
- 폴링하지 말고, 기다리지도 마라: 위임 호출은 즉시 반환되어야 하며, 결과는 플랫폼이 전달한다. 주 에이전트는 대기 중에도 사용자의 새 메시지를 받을 수 있어야 한다. 플랫폼이 기본적으로 차단(blocking)한다면, 위임 호출을 백그라운드/비동기 모드로 전환하여 위임한다.
- 사용자에게 현장 제어 인터페이스를 제공한다: 플랫폼이 실행 중인 하위 에이전트 보기, 특정 하위 에이전트에 수정 지시, 조기 종료 및 부분 결과 보존을 지원하면 사용한다. 지원하지 않으면 '다음 배치 작업 지시에 수정 사항 포함'으로 대체한다.
완료 판단 기준
- 의존성이 없는 단위가 동시에 전송되었는가(하나씩 줄서서 전송되지 않음)
- 의존성이 있는 단위가 순서대로 직렬로 실행되었으며, 하위 작업이 상위 산출물을 받았는가
- 병렬 실행 수준이 제어 가능한 범위 내에 있는가(한 번에 10개 이상을 펼치지 않음)
- 위임 후 주 에이전트가 차단되어 대기하지 않고, 여전히 사용자에게 응답할 수 있는가
4단계: 검증
이 단계는 가장 쉽게 건너뛰지만, 가장 건너뛰면 안 되는 단계이다. 하위 에이전트의 '완료'는 검증이 필요한 진술일 뿐, 결론이 아니다.
순서대로 검증한다(자세한 내용은 '검증 체크리스트' 참조):
- 산출물이 존재하는가: 파일이 실제로 있는가? 경로가 올바른가? 실제 내용을 확인한다.
- 산출물이 규격에 맞는가: 형식, 필드, 줄 수, 범위가 작업 지시 요구사항을 충족하는가?
- 결론에 증거가 있는가: 주장된 주요 숫자/결론에 해당하는 명령어 출력 또는 출처가 있는가?
- 원문 샘플링: 무작위로 1-2곳을 선택하여 원본 출처와 대조 확인한다.
어느 하나라도 통과하지 못하면 → 5단계의 실패 처리 절차를 따른다.
완료 판단 기준
- 각 하위 에이전트의 산출물을 플랫폼의 파일 읽기/실행 도구를 사용하여 실제로 다시 읽었는가(Hermes에서는
read_file/terminal)- 형식과 필드가 작업 지시 요구사항을 충족하는가
- 주요 결론에 추적 가능한 증거가 있는가
- 적어도 한 곳은 원문을 샘플링하여 하위 에이전트의 주장과 일치하는지 확인했는가
- 실패/부적격 산출물이 명확히 표시되었으며, 최종 결과에 섞이지 않았는가
5단계: 마무리
사용자에게 요약할 때는 다음 세 가지를 반드시 수행해야 한다:
- 출처 표시: 어떤 부분이 하위 에이전트에 의해 수행되었고, 어떤 부분이 직접 수행되었는지. 사용자는 알 권리가 있다.
- 상태 표시: 어떤 것이 검증되었는지, 어떤 것이 검증되지 않았는지, 어떤 것이 실패했는지. '대략', '아마도'와 같은 모호한 표현을 사용하지 않는다.
- 다음 단계 제시: 사용자가 결정해야 할 부분을 명확히 제시한다.
실패 처리(우선순위 순):
- 직접 수행으로 다운그레이드 - 작업이 실제로 크지 않다면 직접 처리한다.
- 경로 변경 재위임 - 실패 원인을 새 작업 지시에 포함하고, 다른 방법으로 재시도한다.
- 분할 재위임 - 작업 지시가 너무 커서 잘못된 방향으로 갔다면, 더 작게 분할하여 재위임한다.
- 사실대로 보고 - 실행할 수 없으면 실행할 수 없다고 말하고, 장애 지점과 이미 제외된 경로를 명확히 설명한다. 결과를 지어내는 것은 허용되지 않는다.
완료 판단 기준
- 요약에 각 부분의 출처(하위 에이전트/주 에이전트)가 표시되었는가
- 요약에 각 부분의 검증 상태가 표시되었는가
- 실패한 작업이 처리되었는가(직접 수행/재위임/사실대로 보고), 은폐되지 않았는가
- 사용자 결정이 필요한 사항이 별도로 나열되었는가
- 확인되지 않은 내용이 사실로 적혀 있는 문장이 없는가
위임 4요소
각 작업 지시에는 반드시 이 네 가지가 포함되어야 한다. 하나라도 빠지면 사고 확률이 현저히 증가한다.
1. 목표(goal) — 무엇을 할 것인가
한 문장으로 목표를 명확히 설명하고, 동사로 시작하고 결과 지향적이어야 한다.
- 좋은 예:
3개의 CSV 파일을 중복 제거하여 combined.csv로 병합하고, 원래 열 순서 유지 - 나쁜 예:
이 파일들 좀 처리해
2. 배경(context) — 왜 하는지, 무엇을 근거로 하는지 (반드시 자체 포함)
이것은 4요소 중 가장 쉽게 잘못 작성되는 요소이다. 이유는 간단하다:
하위 에이전트는 사용자와의 대화 기록을 볼 수 없다. 당신이 작업 지시에 쓴 것만 알 수 있다. 당신 머릿속의 배경(사용자의 선호도, 이전에 겪었던 문제, 특정 솔루션을 사용할 수 없는 이유, 데이터의 범위)을 전혀 받을 수 없다.
따라서 컨텍스트에는 반드시 명시적으로 작성해야 한다:
- 작업 배경: 이 작업이 어떤 목표에 기여하는지, 사용자가 무엇을 중요하게 생각하는지.
- 하드 제약 조건: 반드시 준수해야 하는 범위, 형식, 명명 규칙, 금지 사항.
- 입력 목록: 구체적인 파일 경로/디렉토리/URL/데이터셋. '그 파일들'이라고 쓰지 않는다.
- 알려진 함정: 이전에 시도했던 것 중 실패한 것, 함정이 있는 곳, 오해하기 쉬운 부분.
- 환경 정보: 작업 디렉토리, 사용 가능한 도구, 종속성 설치 여부.
자체 점검 방법: 작업 지시를 선행 지식이 전혀 없는 동료에게 보냈을 때, 그대로 따라 할 수 있는가? 할 수 있다면 자체 포함된 것이다.
3. 출력 구조(output schema) — 산출물의 형태
산출물의 구조를 명확히 지정하여, 결과를 받은 후 다시 가공할 필요가 없도록 한다.
- 파일 유형: 경로 + 파일 이름 + 형식(
markdown/json/csv) + 필수 필드 또는 섹션. - 보고서 유형: 요구되는 구조(결론 / 증거 / 출처 / 미해결 항목)로 보고하도록 하고, 산문 형식이 아님.
- 기계 판독 가능 우선:
json을 제공할 수 있다면 자유 텍스트보다 우선한다. 2차 구문 분석 시간을 절약할 수 있다. - 플랫폼이 출력 검증(스키마에 따른 하위 에이전트 응답 검증)을 지원한다면 활성화하고, 지원하지 않으면 작업 지시 본문에 구조를 다시 설명하고 '이 구조에 따라 보고하라'고 요구한다.
4. 검증 방식 — 어떻게 성공을 증명할 것인가
미리 어떤 식으로 검증할지 알려주면, 하위 에이전트는 그에 따라 작업한다. 나중에 증거가 없음을 발견하면 다시 작업해야 한다.
- 실제로 실행된 명령어와 출력을 보고하도록 요구한다('내가 확인했다'가 아님).
- 산출물 경로를 직접 다시 읽을 수 있어야 한다.
- 미완료/의심스러운 부분을 명확히 나열하도록 요구한다. 스스로 자백하는 것이 나중에 적발되는 것보다 낫다.
4요소 빠른 참조표
| 요소 | 한 마디 | 일반적인 결함 |
|---|---|---|
| 목표 | 무엇을 할 것인가, 결과 지향 | 너무 모호: '자료 정리해' |
| 배경 | 배경 + 제약 조건 + 입력 목록 + 알려진 함정 | 목표만 쓰고 배경 누락, 하위 에이전트가 제멋대로 작업 |
| 출력 구조 | 산출물 경로, 형식, 필드 | 경로 미지정, 산출물이 흩어져 찾을 수 없음 |
| 검증 방식 | 어떤 명령어/기준으로 판단할 것인가 | 판단 기준 없음, '괜찮은 것 같아'로 통과 |
검증 체크리스트
모든 하위 에이전트 산출물에 대해 항목별로 확인한다. 하나라도 '아니오'면 완료로 간주하지 않는다.
A. 존재성
- 산출물 파일이 작업 지시에 지정된 경로에 실제로 존재하는가(플랫폼의 파일 읽기/실행 도구로 실제 측정, 파일 이름만 보지 않음)
- 파일이 비어 있지 않으며, 내용이 플레이스홀더/템플릿 잔재/명백한 잘림이 아닌가
- 코드나 스크립트인 경우: 실제로 실행 가능한가('보기에는 맞는 것 같다'가 아님)
B. 규정 준수
- 형식, 필드, 명명이 작업 지시 요구사항을 충족하는가
- 수량이 일치하는가(10개를 요구했으면 10개, '대략 8개'가 아님)
- 범위를 벗어나지 않았는가: 수정해서는 안 되는 파일을 수정하지 않았는가, 작업 지시 외 위치에 쓰지 않았는가
- 병렬 작업 간에 서로 덮어쓰지 않았는가(파일 수정 시간/내용 무결성 확인)
C. 진위성
- 하위 에이전트가 실행했다고 주장하는 명령어에 해당하는 실제 출력이 있는가
- 주요 결론이 특정 출처(파일, URL, 명령어 결과)로 추적 가능한가
- 무작위로 1-2곳을 선택하여 원본 출처와 대조 확인, 결론이 일치하는가
- '그럴듯해 보이지만 출처를 찾을 수 없는' 숫자나 진술이 없는가
D. 완전성
- 작업 지시가 요구한 모든 항목이 제출되었는가
- 미완료/의심스러운 부분이 적극적으로 나열되었는가, 숨겨지지 않았는가
- 실패 항목에 명확한 설명이 있는가(어디서 잘못되었는지, 무엇을 시도했는지)
E. 요약 전 최종 확인
- 사용자에게 답변할 때 각 부분의 출처와 검증 상태를 표시했는가
- 하위 에이전트의 '자체 성공 보고'를 '완료'로 간주하여 결론에 쓰지 않았는가
6가지 위임 패턴
패턴 1: 단일 병렬 위임 (Fan-out)
여러 독립적인 단위를 동시에 위임한다. 모든 단위가 완료될 때까지 기다린 후 병합한다.
적용: 여러 파일을 각각 처리, 여러 URL을 각각 가져오기, 여러 데이터셋에 대해 동일한 변환 수행.
패턴 2: 파이프라인 위임 (Pipeline)
A → B → C 순서로 실행하며, 각 단계의 산출물을 다음 단계의 입력으로 전달한다.
적용: 데이터 추출 → 정제 → 변환 → 적재.
패턴 3: 브로드캐스트 위임 (Broadcast)
동일한 작업 지시를 여러 하위 에이전트에 동시에 보내고, 모든 결과를 수집하여 비교/투표한다.
적용: 여러 가지 다른 방법으로 동일한 질문에 답하고 최적의 답변 선택, 보안 검토.
패턴 4: 조건부 위임 (Conditional Dispatch)
하위 에이전트의 결과에 따라 다음 단계를 결정한다. if-else와 유사하게 작동한다.
적용: 결과에 따라 다른 처리가 필요한 시나리오.
패턴 5: 라운드 로빈 위임 (Round-Robin Dispatch)
일련의 작업을 순서대로 여러 하위 에이전트에 분배한다.
적용: 작업이 완전히 동일하지만 입력 데이터가 다른 경우.
패턴 6: 감독 위임 (Supervisor Dispatch)
하나의 하위 에이전트를 '감독자'로 지정하여 다른 하위 에이전트의 작업을 조정하고 감독한다.
적용: 작업이 복잡하고 여러 측면이 조정되어야 하는 경우.
12가지 안티 패턴
안티 패턴 1: 제정신이 아닌 병렬화 (Insane Parallelization)
실제로 의존성이 없는 작업이라도, 병렬 실행 비용(지시 전송 오버헤드, 결과 병합 복잡성)이 직접 수행하는 것보다 높은 경우가 있다.
규칙: 작업이 2-3회 미만의 도구 호출로 완료될 수 있다면 직접 수행하는 것이 낫다.
안티 패턴 2: 유령 위임 (Ghost Delegation)
위임 호출을 보냈지만 실제로는 실행되지 않았거나, 확인 없이 완료된 것으로 간주했다.
규칙: 모든 위임은 반드시 확인하고 검증한다.
안티 패턴 3: 원격 현미경 (Remote Microscope)
하위 에이전트가 매우 세부적인 작업(예: 파일 내에서 특정 문자 하나 변경)을 처리하도록 요청하면 실행 오버헤드가 실제 이점보다 커진다.
규칙: 분할의 최소 입도는 도구 호출 2-3회에 해당하는 작업이어야 한다.
안티 패턴 4: 완료 보고를 결과로 혼동 (Confusing Completion Report with Result)
하위 에이전트가 '완료'했다는 메시지를 받고는 내용을 확인하지 않는다. 이는 가장 흔하고 위험한 실수 중 하나이다.
규칙: 하위 에이전트가 '완료'했다는 것은 단지 주장일 뿐이며, 반드시 실제 산출물을 확인해야 한다.
안티 패턴 5: 하위 에이전트에게 사용자와 대화하도록 요청 (Asking Subagent to Talk to User)
하위 에이전트는 사용자와 대화할 수 없다. 사용자에게 질문이 필요한 작업은 주 에이전트가 직접 처리해야 한다.
규칙: 사용자 결정, 사용자 확인, 사용자와의 상호 작용은 주 에이전트가 직접 처리한다.
안티 패턴 6: 컨텍스트 단절 (Context Gap)
작업 지시에 배경 정보를 제공하지 않아 하위 에이전트가 잘못된 방향으로 작업한다. 하위 에이전트는 사용자와의 대화 기록을 볼 수 없으며, 당신이 제공하는 정보만 알 수 있다.
규칙: 컨텍스트는 반드시 자체 포함되어야 한다. 하위 에이전트가 작업을 시작하기 전에 알아야 할 모든 정보를 제공한다.
안티 패턴 7: 파일 쓰기 경쟁 (File Write Race)
두 하위 에이전트가 동시에 동일한 파일에 써서 내용이 서로 덮어쓰여진다.
규칙: 각 하위 에이전트는 자신만의 출력 파일에 쓰고, 마지막에 주 에이전트가 병합한다.
안티 패턴 8: 사용자 결정 권한 침범 (User Decision Boundary Violation)
사용자 결정이 필요한 작업을 하위 에이전트에 위임하고, 잘못된 결정이나 되돌릴 수 없는 결과를 초래한다.
규칙: 사용자 결정, 되돌릴 수 있는 작업, 즉각적인 감독이 필요한 작업은 하위 에이전트에 위임하지 않는다.
안티 패턴 9: 장기 작업을 하위 에이전트에 위임 (Long Task Delegation)
하위 에이전트는 현재 세션 동안만 존재한다. 세션을 넘어서는 작업(크론 작업, 지속적인 모니터링, 상주 프로세스)을 하위 에이전트에 위임하면 작업이 갑자기 중단될 수 있다.
규칙: 세션을 넘어서는 작업은 플랫폼의 크론 작업/예약 작업/백그라운드 프로세스 메커니즘을 사용한다.
안티 패턴 10: 결과 지어내기 (Fabricating Results)
하위 에이전트가 잘못된 결과나 부정확한 요약을 반환했지만, 주 에이전트가 직접 확인하지 않고 보고된 내용을 그대로 기록한다.
규칙: 확인되지 않은 결과는 절대 '확인됨'으로 표시하지 않는다. 실패는 실패로 보고한다.
안티 패턴 11: 과도한 단일 위임 (Overly Large Single Delegation)
너무 많은 작업(여러 개의 관련 없는 하위 작업)을 하나의 하위 에이전트에 위임한다. 결과적으로 하위 에이전트가 과부하되어 실행 시간이 길어지고 방향을 잃기 쉽다.
규칙: 각 하위 에이전트는 하나의 명확한 작업을 처리해야 한다. 너무 많은 것을 한 번에 위임하지 않는다.
안티 패턴 12: 중간 성과물 무시 (Ignoring Intermediate Results)
하위 에이전트의 중간 산출물이나 부분 결과를 무시하고 최종 결과만 기다린다. 중간에 문제가 발생하면 전체가 실패한다.
규칙: 하위 에이전트의 중간 진행 상황과 부분 결과를 정기적으로 확인한다. 특히 장기 실행 작업의 경우.
도구 이름 대응표 (일반 플랫폼)
| 개념 | Claude Code | Codex | Cursor | WorkBuddy | Hermes (참고) |
|---|---|---|---|---|---|
| 위임 호출 / 하위 에이전트 | subagent | delegate_task | agent | sub_task | delegate_task |
| 파일 읽기 | read | read_file | read_file | read_doc | read_file |
| 명령어 실행 | run | terminal | run | exec_cmd | terminal |
| 정규 작업 / 크론 작업 | schedule | cron_job | scheduler | schedule_task | cron_task |
| 백그라운드 모드 | background | async | bg | background_run | delegate_task (비동기) |
| 동시 실행 상한 (권장) | 5 | 3 | 5 | 5 | 구성 가능 (기본 3) |
참고: 특정 플랫폼의 실제 함수 이름, 매개변수 및 동시 실행 제한이 다를 수 있습니다. 이 표는 매핑 참고용이며, 구체적인 구현은 각 플랫폼의 공식 문서를 참조하십시오.
부록: delegation_planner.py 스크립트 사용 방법
이 스크립트는 순수 표준 라이브러리만 사용하며 종속성이 없습니다. 명령줄에서 직접 실행하거나 주 에이전트가 호출할 수 있습니다.
python scripts/delegation_planner.py
스크립트를 실행하면 대화형 입력 프롬프트가 나타나며, 각 작업에 대해 다음 정보를 입력합니다:
- 작업 설명: 작업의 간단한 설명(선택 사항이지만 권장).
- 예상 도구 호출 횟수: 이 작업을 완료하는 데 필요한 도구 호출 횟수.
- 처리할 파일 수: 작업과 관련된 파일 수.
- 연구 필요 여부: 이 작업은 장기 연구/검색이 필요한가? (y/n)
- 배치 처리 여부: 이 작업은 배치 처리인가? (y/n)
- 사용자 결정 필요 여부: 이 작업을 완료하는 데 사용자의 결정이 필요한가? (y/n)
- 되돌릴 수 있는지 여부: 이 작업의 결과를 되돌릴 수 있는가? (y/n)
- 세션 초과 필요 여부: 이 작업이 현재 세션을 넘어서 지속되어야 하는가? (y/n)
스크립트는 의사 결정 트리 결과를 출력합니다:
- 처리 방법:
위임- 하위 에이전트에 위임하는 것이 좋습니다.직접 수행- 주 에이전트가 직접 처리하는 것이 좋습니다.정기 작업 전환- 정기 작업/크론 작업 메커니즘을 사용하는 것이 좋습니다.
- 병렬 실행 그룹화 제안: 여러 작업을 병렬로 위임하는 방법에 대한 제안입니다.
- 주 에이전트 작업 목록: 주 에이전트가 직접 처리해야 하는 작업(분해, 위임, 검증, 마무리 등)을 나열합니다.
예시
$ python scripts/delegation_planner.py
작업 1 설명: 세 개의 마크다운 파일을 읽고 각각 요약합니다.
예상 도구 호출 횟수: 3
처리할 파일 수: 3
연구 필요 여부 (y/n): n
배치 처리 여부 (y/n): n
사용자 결정 필요 여부 (y/n): n
되돌릴 수 있는지 여부 (y/n): y
세션 초과 필요 여부 (y/n): n
작업 2 설명: 설정 파일을 업데이트하고 MySQL 데이터베이스를 다시 시작합니다.
예상 도구 호출 횟수: 5
처리할 파일 수: 2
연구 필요 여부 (y/n): n
배치 처리 여부 (y/n): n
사용자 결정 필요 여부 (y/n): n
되돌릴 수 있는지 여부 (y/n): n # MySQL 다시 시작은 되돌리기 어려울 수 있음
세션 초과 필요 여부 (y/n): n
=== 계획 보고서 ===
작업 1: 세 개의 마크다운 파일을 읽고 각각 요약합니다.
처리 방법: 위임
병렬 실행 제안: 하위 에이전트 3개를 각각의 파일에 위임(병렬)
주 에이전트: 각 하위 에이전트의 산출물이 존재하고 올바른지 검증하고, 최종 요약을 병합하여 사용자에게 보고합니다.
작업 2: 설정 파일을 업데이트하고 MySQL 데이터베이스를 다시 시작합니다.
처리 방법: 직접 수행
이유: 되돌리기 어려운 작업(MySQL 다시 시작)이므로, 주 에이전트가 직접 처리하고 결과를 확인하는 것이 좋습니다.
병렬 실행 제안: 해당 없음
주 에이전트: 직접 수행합니다.
전체 제안:
- 작업 1은 위임하는 것이 좋습니다. 하위 에이전트를 3개 사용하여 각각의 파일을 처리하고, 주 에이전트는 검증, 병합, 보고합니다.
- 작업 2는 주 에이전트가 직접 처리하는 것이 좋습니다.
- 작업 1과 작업 2는 병렬로 실행할 수 있습니다.