AI 하위 에이전트에 일 맡기기 — 건네지는 건 문장 하나뿐입니다

파일 수십 개를 뒤지는 작업을 하위 에이전트에 떼어 맡기면 그 과정이 본 대화에 안 쌓입니다. 여럿을 동시에 돌릴 수도 있고요. 그런데 공식 문서를 보니 먼저 알아야 할 게 있었습니다 — 부모에서 하위로 넘어가는 건 프롬프트 문장 하나가 전부입니다. 대화 이력도, 방금 읽은 파일도 안 갑니다. 게다가 한 번 열어주면 몇 개를 띄울지 AI가 정하고, 하위가 또 하위를 낳습니다. 정리했습니다.

📌 30초 요약

• ★★건네지는 건 프롬프트 문장 하나뿐입니다.
• 중간 과정은 안 쌓이고 마지막 답만 올라옵니다.
• ★★한 번 열어주면 나무처럼 자랍니다.
• ⚠️ 깊이·동시 실행·지출 상한을 걸어야 합니다.
• ★목록에서 뺀 도구는 아예 없습니다 — 오류도 안 납니다.
• 하위가 낸 답을 부모가 읽기 전에 한 번 검사합니다.

건네지는 건 문장 하나뿐입니다

가장 먼저 오해하기 쉬운 지점입니다. 하위 에이전트는 자기만의 새 대화로 시작합니다. 그래서 부모의 대화 이력도, 부모가 방금 읽은 파일 내용도, 부모의 기본 지시문도 안 넘어갑니다. 넘어가는 건 일을 맡길 때 적어 보내는 문장 하나가 전부예요.

그러니 파일 경로, 오류 메시지, 앞에서 내린 결정 같은 걸 그 문장 안에 직접 다 적어 넣어야 합니다. "아까 그거 이어서 해줘"는 통하지 않아요. 반대로 이 단절이 바로 장점이기도 합니다 — 하위가 파일 수십 개를 뒤져도 그 내용이 본 대화에 안 쌓이고, 요약된 마지막 답만 올라오거든요.

📄 프로젝트 지시문은 따라갑니다

전부 단절인 건 아닙니다. 프로젝트 지시문 파일은 하위 쪽에도 실립니다 — 물론 불러올 출처를 켜둔 경우에요. 반대로 미리 불러둔 스킬 내용은 안 따라갑니다 — 하위에도 필요하면 그 에이전트 정의에 이름을 적어줘야 합니다. 도구 정의는 부모 것을 물려받거나 내가 지정한 것만 갑니다.

한 번 열어주면 나무처럼 자랍니다

여기가 비용 면에서 제일 조심할 대목입니다. 하위를 부르는 도구를 허용 목록에 한 번 넣어주면, 언제 몇 개를 띄울지는 AI가 알아서 정합니다. 하위 하나하나가 따로 요청을 보내 요금을 쓰고, 그 하위가 또 자기 하위를 낳을 수 있어요. 요청 하나가 에이전트 나무로 자라는 겁니다.

걸 수 있는 상한	한도에 닿으면
몇 겹까지 내려갈지	맨 아래 하위가 직접 일을 처리함
동시에 몇 개까지	더 안 띄우고 한도 도달을 알림 — 줄어들면 재개
얼마까지 쓸지	배경에서 돌던 것까지 멈추고 대화 종료
하위가 돌 차례 수	결과를 미완성으로 표시 — 이어받아 계속 가능

문서가 짚는 대목이 하나 더 있습니다. 요즘 상위 모델일수록 더 선뜻 일을 나눠 맡깁니다. 그래서 상한이 특히 중요한데, 기본 지시문 묶음을 그대로 쓰면 "시키지 않으면 나눠 맡기지 말라"는 줄이 자동으로 들어가지만, 내가 지시문을 직접 쓰면 그 줄이 없습니다. 어느 쪽이든 말로 타이르는 것일 뿐이니 숫자로 된 상한을 함께 걸어야 해요. 여러 에이전트를 한 화면에서 굴려본 적이 있다면 이 증식 속도가 낯설지 않을 겁니다.

목록에서 뺀 도구는 아예 없습니다

하위마다 쓸 수 있는 도구를 좁혀둘 수 있습니다. 문서를 훑기만 할 에이전트라면 읽기·검색만 주는 식이죠. 여기서 알아둘 동작이 있는데 — 목록에서 뺀 도구는 그 하위의 세션에 아예 존재하지 않습니다.

권한 창이 뜨는 것도 아니고, 오류가 나는 것도 아니에요. 그냥 없는 것처럼 일합니다. 그래서 "실수로 파일을 고칠 일이 없다"는 보장이 확실한 대신, 빼먹은 도구가 있어도 티가 안 나서 왜 일을 못 끝내는지 한참 헤맬 수 있습니다. 아무것도 안 적으면 하위에게 열려 있는 도구를 전부 물려받습니다.

하위가 낸 답을 한 번 검사합니다

이건 알아두면 안심되는 장치입니다. 하위가 낸 마지막 답을 부모가 읽기 전에 한 번 훑어서, 지시문처럼 생긴 패턴을 찾아 무력화합니다. 하위가 어딘가에서 읽어온 내용에 "이제부터 이렇게 해라" 같은 문장이 섞여 있어도 그게 부모에게 명령으로 먹히지 않게 하는 거죠.

방식이 섬세합니다 — 지우거나 고쳐 쓰지 않고, 표시만 살짝 바꿔 흉내를 못 내게 합니다. 대화 차례를 가장하는 줄도 같은 식으로 처리되고요. 무엇이 걸렸는지 부모가 볼 수 있게 한 줄 붙여 줍니다. 다만 부모가 하위 답을 자기 말로 요약해버릴 수는 있으니, 원문 그대로 보여주고 싶다면 "그대로 옮기라"고 지시해두세요.

📜 자제 지시가 들어가느냐는 지시문 설정에 달렸습니다

상위 모델이 더 선뜻 위임한다고 했는데, 기본 지시문을 어떻게 잡았느냐에 따라 자제 지시가 들어가기도 하고 안 들어가기도 합니다. 아무것도 안 적으면 도구 호출만 다루는 최소한이 붙고 안전 지시가 통째로 빠져요. 터미널에서 돌릴 때와 기본값이 달라서, 옮겨온 코드가 다르게 구는 원인이 되기도 합니다.

자주 묻는 질문 (FAQ)

Q. 정의해뒀는데 AI가 안 부릅니다.

세 가지를 확인하세요. 첫째, 하위를 부르는 도구가 허용 목록에 없으면 매번 승인 절차로 빠지거나 아예 거부됩니다. 둘째, 이름을 프롬프트에 직접 대면 자동 판단을 건너뛰고 그 에이전트를 씁니다. 셋째, "언제 쓰는 것인지" 설명을 구체적으로 적어야 AI가 상황을 알아봐요. 설명이 두루뭉술하면 직접 처리해버립니다.

Q. 파일로 만든 에이전트가 안 잡힙니다.

가장 흔한 원인은 폴더가 세션 시작 뒤에 생긴 경우입니다. 지켜보는 대상이 세션이 시작될 때 존재하던 폴더뿐이라, 새로 만든 폴더의 첫 파일은 세션을 다시 시작해야 잡혀요. 그 밖에 앞머리 설정이 잘못됐거나 이름이 겹치는 경우, 그리고 코드로 정의한 같은 이름이 파일 쪽을 덮어쓰는 경우도 있습니다. 나중에 추가한 작업 폴더 안의 파일도 지켜보지 않으니 재시작이 필요합니다.

Q. 하위가 도중에 죽으면 알 수 있나요?

요청 한도 같은 오류로 일찍 끝나면 그 사실이 결과로 전달되지 않습니다. 부모 입장에서는 답이 부실하게 왔을 뿐이라 원인을 모르죠. 그래서 차례 수 상한에 걸려 멈춘 경우와 구분이 필요합니다 — 이쪽은 결과에 미완성 표시가 붙어 이어받아 계속할 수 있어요. 하위는 각자 기록이 따로 저장되니, 이어받을 때는 같은 세션으로 들어가야 합니다.

🧾 정직하게 밝혀둘 것

• 제가 대규모로 굴려본 실측이 아닙니다. 공식 문서의 구조·상한·주의 사항을 우리말로 정리했습니다.
• ★설정 항목 이름·환경 변수·기본값 수치·판올림 번호는 옮기지 않았습니다. 실제로 상한을 걸 때는 원문 표를 보세요.
• ★"빼먹은 도구 때문에 헤맬 수 있다"는 제 관찰이고, 문서는 빠진 도구가 세션에 없다는 사실만 밝힙니다.
• 기본값과 동작은 판올림에 따라 바뀝니다. 배경 실행 여부처럼 최근에 바뀐 항목이 있습니다.

✨ 정리하면

하위에 일을 맡기면 중간 과정이 본 대화에 안 쌓이고 마지막 답만 올라옵니다. 대신 건네지는 건 문장 하나뿐이라 필요한 정보를 거기 다 담아야 해요. 비용 쪽이 진짜 함정인데 — 한 번 열어주면 몇 개를 띄울지 AI가 정하고 하위가 또 하위를 낳으니, 깊이·동시 실행·지출 상한을 숫자로 걸어야 합니다. 설정이 어디까지 따라오는지는 설정 불러오기 정리, 여러 에이전트를 한 화면에서 굴리는 도구는 cmux 소개, 하위 글자가 실시간으로 안 흐르는 이유는 실시간 출력 정리, 전체 비용 흐름은 AI 지출 관리 허브에 모아뒀습니다.

※ 출처: Claude 에이전트 개발 도구의 하위 에이전트 공식 문서(2026년 8월 31일 열람). 기본값과 상한은 판올림마다 달라질 수 있습니다.