Claude Code 서브에이전트 역할 충돌 문제 해결법

Claude Code 활용법

Claude Code에서 서브에이전트를 여러 개 운영할 때 가장 먼저 부딪히는 문제, 역할 충돌.
프롬프트 분리부터 데이터 전달 설계까지, 에이전트 팀을 안정적으로 굴리는 실전 해결법을 정리했습니다.

📌 3줄 요약

• 서브에이전트 역할 충돌은 프롬프트에 역할 경계를 명시하지 않아서 발생한다.
• 에이전트별 프롬프트를 별도 파일로 분리하고, 중간 산출물의 파일 경로와 JSON 스키마를 사전 고정하면 대부분 해결된다.
• 모든 서브에이전트 호출은 반드시 오케스트레이터를 거치는 순차 구조가 가장 안정적이다.

📑 목차

• 1. 서브에이전트 역할이 겹치는 원인 파악하기
• 2. 에이전트별 프롬프트 분리로 충돌 방지하기
• 3. 서브에이전트 간 데이터 전달 오류 해결하기
• 4. 안정적인 에이전트 팀 점검 방법

서브에이전트 역할이 겹치는 원인 파악하기

Claude Code에서 서브에이전트(subagent)를 여러 개 만들면 가장 먼저 부딪히는 문제가 역할 충돌입니다. 예를 들어 코드 리뷰 에이전트와 테스트 작성 에이전트가 둘 다 코드를 수정하려 드는 상황이 생깁니다. 리뷰 에이전트가 "이 부분은 이렇게 고치는 게 낫겠다"고 판단해서 직접 파일을 편집해버리면, 테스트 에이전트가 같은 파일을 건드릴 때 충돌이 발생합니다. 이런 상황이 반복되면 어떤 에이전트의 결과가 최종 반영된 건지 추적하기 어려워지고, 전체 파이프라인의 신뢰성이 떨어집니다.

이런 문제는 대부분 에이전트별 프롬프트에 역할 경계를 명확히 적지 않아서 발생합니다. Claude Code의 Agent 도구로 서브에이전트를 호출할 때, prompt 파라미터에 "너는 리뷰만 하고 코드를 직접 수정하지 마"처럼 구체적 제한을 넣어야 합니다. 단순히 "리뷰해줘"라고만 적으면 에이전트는 리뷰 결과를 반영해서 코드까지 고치려 하는 경우가 많습니다. 역할 경계를 한 문장이라도 명시해 두면 이런 자율적 확장을 효과적으로 막을 수 있습니다.

 

🔍 에이전트 타입과 역할 충돌의 관계

역할이 겹치는 또 다른 원인은 에이전트 타입 선택을 잘못한 경우입니다. Agent 도구의 subagent_type 파라미터를 지정하지 않으면 범용(general-purpose) 에이전트가 실행되는데, 범용 에이전트는 모든 도구에 접근할 수 있어서 의도하지 않은 작업까지 수행합니다. 예를 들어 탐색만 시키고 싶은 에이전트가 범용 타입으로 실행되면 파일을 읽는 것을 넘어 편집까지 해버릴 수 있습니다. 반면 Explore 타입은 읽기 전용 도구만 사용할 수 있어서 의도치 않은 수정을 원천 차단합니다.

💬 제가 직접 에이전트 팀을 꾸려보니, 처음에는 역할 구분 없이 전부 범용 에이전트로 돌렸다가 서로 같은 파일을 동시에 편집하는 충돌이 반복됐습니다. subagent_type을 Explore처럼 읽기 전용 타입으로 바꾸자 문제가 즉시 사라졌습니다. 에이전트 타입 선택이 역할 충돌 방지의 첫 번째 방어선이라는 점을 꼭 기억해주세요.

에이전트별 프롬프트 분리로 충돌 방지하기

서브에이전트 팀을 안정적으로 운영하려면, 각 에이전트의 프롬프트를 별도 파일로 분리하는 것이 핵심입니다. .claude/agents/ 디렉토리 아래에 에이전트별 폴더를 만들고, 각각의 역할 정의 파일을 두는 구조가 권장됩니다. 이 방식의 장점은 프롬프트가 코드와 함께 버전 관리된다는 점입니다. 에이전트 규칙이 바뀌어도 git으로 변경 이력을 추적할 수 있어 팀 작업에서도 혼선이 줄어듭니다.

예시 디렉토리 구조는 이렇습니다. .claude/agents/reviewer/에는 리뷰 기준과 금지 행동을, .claude/agents/writer/에는 작성 규칙과 출력 형식을 따로 정의합니다. 각 폴더 안에 references/ 하위 폴더를 두면 해당 에이전트만 참조하는 규칙 문서도 깔끔하게 관리할 수 있습니다. 폴더 단위로 분리하면 나중에 에이전트를 추가하거나 제거할 때도 다른 에이전트에 영향을 주지 않습니다.

 

💡 프롬프트에 반드시 포함해야 하는 3가지 항목

첫째 "이 에이전트가 해야 하는 일", 둘째 "절대 하지 말아야 하는 일", 셋째 "출력 형식"입니다. 이 세 가지만 명확하면 에이전트 간 역할이 겹칠 확률이 크게 줄어듭니다. 특히 "하지 말아야 하는 일"을 빠뜨리면 에이전트가 자율적으로 범위를 확장하기 때문에 꼭 넣어야 합니다. 실제로 "파일을 수정하지 마라"는 금지 규칙 하나만 추가해도 리뷰 에이전트가 코드를 건드리는 문제가 완전히 사라집니다.

💬 제가 실제로 4개 에이전트를 운영해본 결과, 프롬프트 파일을 분리하기 전에는 매번 prompt 파라미터에 긴 지시를 반복 입력해야 했습니다. 파일로 분리한 뒤에는 호출 코드가 깔끔해지고, 규칙 수정도 한 곳에서만 하면 되어 관리가 훨씬 편해졌습니다. 무엇보다 에이전트마다 동일한 지시를 복사·붙여넣기 하다가 한쪽만 수정하는 실수가 사라진 것이 가장 큰 효과였습니다.

서브에이전트 간 데이터 전달 오류 해결하기

에이전트 팀에서 가장 많이 발생하는 실행 오류는 데이터 전달 실패입니다. 오케스트레이터(orchestrator)가 A 에이전트의 결과를 B 에이전트에 넘겨야 하는데, 중간 파일이 없거나 형식이 맞지 않으면 파이프라인 전체가 멈춥니다. 특히 에이전트가 결과를 저장하지 않고 텍스트로만 반환하는 경우, 오케스트레이터가 해당 결과를 파일로 저장하는 중간 단계를 빠뜨리면 다음 에이전트가 읽을 데이터가 없어집니다. 이런 오류는 실행 시점에서야 드러나기 때문에 사전에 데이터 흐름을 설계해 두는 것이 중요합니다.

이 문제를 방지하려면 중간 산출물의 파일 경로와 JSON 스키마를 사전에 고정해야 합니다. 예를 들어 A 에이전트는 반드시 output/step1_result.json에 {"title": "...", "category": "..."} 형식으로 저장하도록 프롬프트에 명시합니다. B 에이전트의 프롬프트에도 "step1_result.json을 읽어서 title 필드를 사용하라"고 구체적으로 적어줍니다. 이렇게 입력과 출력의 계약(contract)을 명확히 하면, 에이전트가 바뀌더라도 파이프라인이 깨지지 않습니다. JSON 스키마를 문서로 정리해두면 새로운 에이전트를 추가할 때도 어떤 형식을 따라야 하는지 바로 확인할 수 있어 편리합니다.

 

⚠️ 서브에이전트 간 직접 호출 금지

흔한 실수 하나가 더 있습니다. 서브에이전트끼리 직접 호출하는 구조를 만드는 것인데, 이렇게 하면 실행 순서를 제어할 수 없어 디버깅이 극도로 어려워집니다. A 에이전트가 B를 직접 호출하면 오케스트레이터는 B의 실행 여부조차 알 수 없게 됩니다. 에러가 발생해도 어느 단계에서 문제가 생겼는지 추적이 불가능해집니다.

모든 서브에이전트 호출은 반드시 오케스트레이터를 거치도록 설계해야 합니다. 오케스트레이터가 A 결과를 확인하고 → B를 호출하고 → B 결과를 확인하고 → C를 호출하는 순차 구조가 가장 안정적입니다. 이 구조에서는 각 단계마다 결과를 검증할 수 있어서, 문제가 생겨도 정확한 실패 지점을 바로 파악할 수 있습니다.

💬 제가 겪은 사례를 공유하면, 처음에 에이전트 A가 JSON 대신 마크다운으로 결과를 출력해서 B 에이전트가 파싱에 실패한 적이 있었습니다. 프롬프트에 "반드시 JSON으로만 출력하라, 마크다운 코드 블록으로 감싸지 마라"는 한 줄을 추가하고 나서야 해결됐습니다. 이처럼 출력 형식을 강제하는 지시는 아무리 사소해 보여도 반드시 포함시키는 것이 좋습니다.

안정적인 에이전트 팀 점검 방법

에이전트 팀을 배포하기 전에 반드시 점검해야 할 체크리스트가 있습니다. 하나라도 빠지면 실행 중간에 파이프라인이 멈추거나 예상과 다른 결과가 나옵니다. 실제 작업에 투입하기 전에 이 네 가지를 모두 확인하는 습관을 들이면 운영 중 발생하는 문제를 대부분 예방할 수 있습니다.

1

각 에이전트의 프롬프트에 역할·금지사항·출력형식이 모두 포함되어 있는지 확인합니다.

2

중간 산출물 파일의 경로와 형식이 앞뒤 에이전트 간에 일치하는지 대조합니다. 경로가 하나라도 어긋나면 다음 에이전트가 파일을 찾지 못해 즉시 실패하기 때문에 꼼꼼히 대조해야 합니다.

3

서브에이전트 스폰(spawn) 수가 동시 실행 제한을 초과하지 않는지 확인합니다. Claude Code는 동시에 실행 가능한 서브에이전트 수에 제한이 있으므로, 병렬 실행이 필요하면 순차 호출로 전환하거나 배치를 나누어야 합니다. 동시 실행 제한을 초과하면 에이전트가 대기 상태에 빠지거나 타임아웃이 발생해서 전체 워크플로우가 중단됩니다. 따라서 병렬로 돌려야 하는 에이전트가 몇 개인지 미리 세어보고, 제한을 넘긴다면 2~3개씩 배치를 나누어 순차적으로 실행하는 것이 안전합니다.

 

4

실패 시 재시도 로직을 넣어두어야 합니다. 서브에이전트가 타임아웃되거나 잘못된 출력을 반환할 경우, 오케스트레이터가 최대 1~2회 재호출하도록 설계하면 전체 파이프라인의 안정성이 올라갑니다. 재시도할 때는 이전 실패 원인을 프롬프트에 포함시키면 같은 실수를 반복하지 않도록 유도할 수 있습니다. 예를 들어 "이전 호출에서 JSON 형식이 아닌 출력을 반환했으니, 이번에는 반드시 JSON만 출력하라"처럼 구체적 피드백을 넣어주는 것이 효과적입니다.

💡 시운전으로 설정 오류 사전 차단

이 네 가지를 점검하는 가장 빠른 방법은 테스트용 더미 입력으로 전체 파이프라인을 한 번 돌려보는 것입니다. 실제 작업 전에 빈 프로젝트에서 시운전하면 대부분의 설정 오류를 미리 잡을 수 있습니다. 시운전 결과를 로그 파일로 남겨두면 나중에 문제가 생겼을 때 정상 실행과 비교하기도 편리합니다.

💬 제가 4개 에이전트 팀을 운영하면서 느낀 점은, 처음 세팅에 시간을 들이면 이후 수십 번의 실행에서 수작업이 거의 사라진다는 것입니다. 특히 프롬프트 파일 분리와 중간 파일 스키마 고정, 이 두 가지만 제대로 하면 에이전트 팀 운영의 80%는 해결됩니다. 나머지 20%는 재시도 로직과 로그 관리인데, 이것도 한 번 구축해두면 계속 재사용할 수 있으니 초기 투자 대비 효율이 매우 높습니다.

✍️ 마치며

서브에이전트 역할 충돌은 프롬프트 설계 단계에서 거의 완벽하게 예방할 수 있습니다. 역할 경계 명시, 프롬프트 파일 분리, 중간 산출물 스키마 고정, 오케스트레이터 중심 순차 호출 — 이 네 가지 원칙만 지키면 여러 에이전트가 한 팀으로 안정적으로 협업할 수 있습니다. 처음에 조금 번거롭더라도 구조를 잡아두면 이후 운영이 훨씬 편해지니, 오늘 소개한 방법을 하나씩 적용해 보시길 바랍니다.

#ClaudeCode #서브에이전트 #에이전트팀 #역할충돌 #프롬프트설계 #오케스트레이터 #AI자동화