클로드 코드 하위 에이전트 실행 — 배경 자동 배치와 이름 붙일 때의 함정

일을 하위 에이전트에 떼어 맡기면 그 에이전트는 두 자리 중 하나에서 돕니다 — 본 대화를 멈춰 세우고 앞에서 돌거나, 같이 도는 뒤쪽에서 돌거나. 어느 쪽이냐에 따라 쓸 수 있는 도구도, 승인 창이 뜨는 모양도 달라집니다.

그런데 이 자리는 클로드가 그때그때 고르는 게 아닙니다. 정해진 순서대로 위에서부터 걸리는 조건 하나가 자리를 정하고, 요즘 대화형 세션에서는 클로드가 앞자리를 요청할 방법조차 없습니다. 이름을 붙이는 순간 아예 다른 것이 되기도 하고요.

📌 30초 요약

• 자리는 정해진 순서로 결정됩니다.
• 뒤에서 돌면 도구 묶음이 작아집니다.
• 승인 하나가 세션 전체로 번집니다.
• 이름을 붙이면 팀 동료로 튑니다.
• 동시 상한은 스무 개입니다.

1. 앞에서 도나, 뒤에서 도나

두 자리의 성격부터 갈라 두겠습니다. 앞에서 도는 쪽은 일이 끝날 때까지 본 대화를 막습니다. 승인이 필요한 순간이 오면 그대로 제 앞에 뜨고요. 뒤에서 도는 쪽은 제가 계속 다른 일을 하는 동안 나란히 돕니다. 승인 창은 본 세션에 뜨는데, 누가 묻고 있는지 이름이 함께 나옵니다. 허락하면 그 에이전트가 이어 가고, 빠져나오는 키를 누르면 그 호출 하나만 거절되고 에이전트는 안 멈춥니다.

자리가 정해지는 방식이 이 글의 본론입니다. 클로드가 판단하는 게 아니라 위에서부터 훑어 처음 걸리는 조건이 자리를 정합니다.

먼저 걸리는 조건	정해지는 자리
팀 동료가 띄운 것	앞자리 고정 — 정의에 배경을 적어 두면 아예 거부
배경 작업을 꺼 둠	모든 종류의 세션에서 앞자리
갈래 방식이 켜짐(대화형 기본)	무조건 뒷자리 — 클로드가 앞자리를 요청 못 함
갈래 방식이 꺼짐	기본은 뒷자리, 결과가 필요하면 앞자리

셋째 줄이 중요합니다. 대화형 세션은 갈래 방식이 기본으로 켜져 있으니, 평소 터미널에서 쓰시는 거의 모든 하위 에이전트는 뒷자리로 고정됩니다. 한 번에 돌리는 방식이나 개발 도구 모음에서는 꺼져 있어서 그쪽은 규칙이 다르고요. 특정 에이전트만 늘 뒤에 두고 싶다면 그 정의에 배경 표시를 적어 두면 클로드가 결과를 기다리고 싶어 해도 뒤에 남습니다. 돌아가는 중인 것을 손으로 뒤로 미는 단축키도 있습니다.

2. 뒤로 가면 달라지는 것들

뒷자리는 공짜가 아닙니다. 가장 먼저 뒤에서 도는 에이전트는 앞자리보다 작은 기본 도구 묶음으로 돕니다. 갈래로 떠난 것과 다시 불러 세운 앞자리 에이전트만 예외고요. 하위 에이전트에 건네지는 것이 문장 하나뿐이라는 점과 겹쳐 보면, 뒤로 보낸 일일수록 손에 쥔 게 적다는 뜻이 됩니다.

⚠️ 승인 하나가 세션 전체로 번집니다

뒤에서 도는 에이전트가 띄운 승인 창에서 「이번 한 번만」이 아닌 답을 고르면 — 이를테면 이 세션 동안 계속 허락한다는 쪽을 고르면 — 그 답이 세션 전체에 적용됩니다. 본 대화까지 포함해서요. 하위 에이전트한테만 열어 준 줄 알았던 권한이 제가 직접 시키는 작업에도 그대로 열려 있는 셈입니다. 뒤에서 도는 것이 여럿일 때는 누가 물었는지 이름을 보고 범위를 넓히는 선택을 할지 한 번 더 생각하시는 편이 좋습니다. 권한 모드와 보호 경로를 미리 잡아 두면 이 순간의 부담이 줄어듭니다.

결과가 돌아오는 방식도 다릅니다. 뒤에서 끝난 일은 나중 턴에 완료 알림으로 도착하고, 클로드는 그 알림을 받고서야 결과를 보고합니다. 그전에 「다 됐어?」라고 물으면 아직 돌고 있다고 답합니다. 뒤에서 도는 에이전트가 남긴 배경 명령이 자기 차례가 끝난 뒤에도 계속 돌 수 있는데, 그 명령이 끝나면 그 에이전트에게 알림이 갑니다.

화면에서 사라지는 모양도 갈립니다. 잘 끝나면 줄이 곧바로 없어지고 화면 아래에 30초 동안 안내가 뜹니다 — 그 사이에 작업 목록을 열면 대화 내용을 볼 수 있죠. 반대로 실패했거나 제가 멈춘 것은 줄이 30초 남습니다. 즉 줄이 바로 사라졌다면 성공, 남아 있다면 실패라는 신호로 읽으셔도 됩니다.

3. 이름 하나로 갈리는 신분

클로드는 하위 에이전트에 이름을 붙일 수 있습니다. 이름이 있으면 나중에 그 이름으로 말을 걸거나 다시 불러 세울 수 있어 편하죠. 다만 클로드가 먼저 묻지 않고 스스로 이름을 붙이기도 합니다.

여기서 생각지 못한 일이 벌어집니다. 에이전트 팀 기능이 켜진 대화형 세션에서 본 대화가 이름을 붙여 하위 에이전트를 띄우면, 그건 하위 에이전트가 아니라 팀 동료로 출발합니다. 갈래로 떠나는 경우이거나 호출 자체에 격리 값을 적은 경우만 예외고요. 정의 파일에 적어 둔 격리 값으로는 이걸 막지 못합니다. 그렇게 출발한 팀 동료는 본 세션의 작업 폴더에서 돕니다.

응답이 중간에 끊겼을 때의 처리도 알아 둘 만합니다. 글자는 나왔는데 도구 호출이 없는 상태로 끊기면 클로드 코드는 그 자리에서 끝내지 않고 이어 가라고 다시 밀어 넣습니다. 그 이어붙이기를 다 쓰고 나서야 오류로 끝나고요. 요금 한도나 서버 문제로 끝난 경우에는 앞자리면 이미 나온 글과 함께 「끝까지 못 했다」는 메모가 돌아오고, 뒷자리면 실패 표시와 함께 마지막 출력이 붙어 옵니다. 어느 쪽이든 하던 일이 통째로 사라지지는 않는 셈이죠. 모델을 갈아탈 사슬을 걸어 두셨다면, 사슬이 감당하는 실패일 때는 아예 다른 모델로 바꿔 계속 돕니다.

4. 스무 개라는 선과 자리 다툼

동시에 돌릴 수 있는 수에도 선이 있습니다. 한 세션에서 스무 개가 돌고 있으면 그다음 것을 띄우려는 시도가 실패하고, 오류가 클로드에게 다시 시도하지 말라고 일러 줍니다. 돌던 것이 줄어들면 다시 띄울 수 있고요. 세션 동안 통틀어 몇 개를 띄웠는지는 안 셉니다 — 어디까지나 동시에 도는 수만 봅니다.

까다로운 대목은 「선에 걸리는 것」과 「자리를 차지하는 것」이 다르다는 점입니다.

어떤 실행인가	선과의 관계
클로드가 띄우는 하위 에이전트	자리를 차지하고 선에 걸립니다
세션 안에서 떠나보낸 갈래	자리는 차지하되 절대 막히지 않습니다
끝난 것을 다시 부르기	선을 안 보고 새 자리를 가져갑니다
흐름이나 팀이 돌리는 것	각자 다른 선을 따릅니다

셋째 줄이 특히 눈에 띕니다. 다시 부르는 것은 선을 확인하지 않으므로, 돌고 있는 수가 선을 넘어설 수 있습니다. 즉 스무 개라는 숫자는 상한이라기보다 「새로 띄우기를 막는 문턱」에 가깝습니다. 수백 개를 한 스크립트로 지휘하는 방식이 이 선과 무관하게 도는 것도 같은 이유입니다. 노력 수준을 끝까지 올린 세션은 이 선을 아예 적용받지 않고요. 선을 손보고 싶으면 환경 변수에 원하는 수를 적어 두면 됩니다.

자주 묻는 질문 (FAQ)

Q. 앞에서 돌게 하고 싶은데 방법이 없나요

대화형 세션은 갈래 방식이 기본으로 켜져 있어 클로드가 앞자리를 요청할 수 없습니다. 배경 작업 자체를 끄는 환경 변수를 켜면 모든 종류의 세션에서 앞자리로 돌지만, 그건 배경 기능을 통째로 끄는 선택입니다.

Q. 승인 창이 떴는데 누가 묻는 건지 모르겠습니다

뒤에서 도는 에이전트가 물으면 어느 에이전트인지 이름이 함께 나옵니다. 빠져나오는 키를 누르면 그 호출 하나만 거절되고 에이전트는 계속 돕니다. 다만 이 세션 내내 허락하는 쪽을 고르면 본 대화까지 함께 열립니다.

Q. 하위 에이전트로 띄웠는데 팀 동료가 됐습니다

에이전트 팀이 켜진 세션에서 이름을 붙여 띄우면 팀 동료로 출발합니다. 갈래이거나 호출에 직접 격리 값을 적은 경우만 예외이고, 정의 파일의 격리 값으로는 막히지 않습니다.

Q. 스무 개를 넘겨 돌고 있는 것 같은데요

가능합니다. 끝난 것을 다시 부르는 경우는 선을 확인하지 않고 새 자리를 가져갑니다. 세션 안 갈래도 자리는 차지하되 막히지 않고요. 선은 새로 띄우기를 막는 문턱이지 돌고 있는 수의 천장이 아닙니다.

정리하면

• 자리는 순서대로 정해집니다.
• 대화형은 뒷자리 고정입니다.
• 뒤에서는 도구가 적습니다.
• 승인은 세션 전체로 번집니다.
• 이름은 신분을 바꿉니다.
• 스무 개는 문턱일 뿐입니다.

※ 공개된 하위 에이전트 문서를 읽고 정리했습니다. 환경 변수와 설정 항목 이름은 우리말로 풀어 적었으니 실제 표기는 원문에서 확인하세요.

※ 동시 실행 수와 도구 묶음은 판올림에 따라 달라질 수 있고, 여기 적은 동작에는 최소 판올림 조건이 붙은 것도 있습니다. 원문과 대조해 확인하세요.