클로드 코드 워크플로 동시 에이전트 — 지침은 조언·진짜 벽은 네 가지

에이전트 여러 개를 한 번에 펼쳐 돌리는 기능을 쓰다 보면 규모를 어디서 조이는지가 헷갈립니다. 설정에 개수 항목이 있으니 거기서 막히겠거니 싶은데요.

그런데 그 설정은 상한이 아니라 조언입니다. 실제로 막는 벽은 따로 있고, 넘치는 실행을 알려 주는 경고도 멈추지는 않습니다. 셋을 갈라 두면 규모를 다루기가 훨씬 쉬워집니다.

📌 30초 요약

• 크기 설정은 조언입니다. 요청이 더 크면 그냥 넘어갑니다.
• 진짜 벽은 동시 열여섯 · 한 호출 사천 · 한 실행 천입니다.
• 경고가 떠도 멈추거나 줄이지 않습니다.
• 펼친 에이전트들이 일부러 5초 늦게 출발하는 이유가 있습니다.

1. 고르는 숫자는 상한이 아닙니다

설정에서 고르는 크기 지침은 네 단계입니다. 이 값이 하는 일은 「대략 이 정도로 잡아라」라고 클로드에게 일러 주는 것뿐입니다. 문서가 표현을 분명히 합니다 — 상한이 아니라 조언으로 전달된다고요.

고르는 값	겨냥하는 에이전트 수
제한 없음	지침을 안 줌 · 클로드가 일에 맞춰 정함
작게	다섯 개 미만
보통 (기본값)	열다섯 개 미만
크게	쉰 개 미만

그러니 「작게」로 두었는데 스무 개가 도는 일이 생길 수 있습니다. 고장이 아닙니다. 내가 부탁한 일이 그만큼을 요구하면 지침을 넘어서 잡는 것이 설계된 동작입니다. 규모를 정말 줄이고 싶다면 설정이 아니라 부탁하는 범위를 좁히는 쪽이 맞습니다.

값을 바꾸는 자리는 두 곳입니다. 설정 화면에서 고를 수도 있고 설정 파일에 키로 적을 수도 있는데, 파일에 적은 값이 화면 선택을 이깁니다. 파일이 값을 주고 있으면 화면에서는 그 줄이 아예 숨겨집니다. 팀에 같은 규모를 강제하고 싶을 때 쓸 자리죠. 이 기능 자체가 처음이라면 워크플로 완전정리를 먼저 보시는 편이 좋습니다.

2. 진짜 벽 네 가지

지침과 달리 실행 환경이 무조건 지키는 제약이 있습니다. 이쪽은 조언이 아니라 벽입니다.

제약	이유
동시에 열여섯 개까지	내 컴퓨터 자원을 묶기 위해 · 코어가 적으면 더 줄어듦
한 호출에 사천 개까지	넘치면 오류로 거부 · 말없이 자르면 일부가 빠지니까
한 실행에 천 개까지	멈추지 않고 늘어나는 고리를 막기 위해
중간에 사람이 못 끼어듦	멈출 수 있는 건 권한 확인창뿐
파일과 셸에 직접 손 못 댐	읽고 쓰는 건 에이전트가 · 스크립트는 조율만
바깥 꾸러미 못 불러옴	불러오기가 들어 있으면 시작 전에 실패

넷째 줄이 실무에서 제일 걸립니다. 단계마다 사람이 확인하고 넘어가는 구성을 만들 수 없다는 뜻이거든요. 문서가 주는 해법은 단순합니다 — 단계를 각각 별개의 실행으로 쪼개라는 것입니다. 한 번에 다 돌리려다 중간 승인을 못 넣는 것보다, 승인 지점에서 끊어 두는 편이 낫습니다.

그리고 동시에 열여섯이라는 숫자는 「한 번에 열여섯 개만 만든다」가 아니라 「같은 순간에 도는 것이 열여섯을 안 넘는다」는 뜻입니다. 백 개를 예약해도 열여섯씩 차례로 돌 뿐 실패하지 않습니다. 다만 그만큼 끝나는 시각이 뒤로 밀립니다. 전문 에이전트를 나눠 쓰는 방식 자체는 서브에이전트 완전정복에서 정리해 뒀습니다.

3. 경고는 멈추지 않습니다

⚠️ 알려 주기만 하고 그대로 돕니다

예약한 에이전트가 스물다섯 개를 넘거나 예상 토큰 합이 백오십만을 넘으면 진행 줄에 경고가 붙습니다. 그런데 문서가 못 박아 뒀습니다 — 이 경고는 조언이라 실행을 멈추지도, 규모를 줄이지도 않습니다.

즉 경고를 본 시점에는 이미 돌고 있습니다. 큰 작업이라면 경고를 기다리지 말고 작은 조각으로 먼저 한 번 돌려 지출을 가늠해 보세요. 저장소 전체 대신 폴더 하나, 넓은 질문 대신 좁은 질문으로요.

경고가 뜨는 기준에도 미묘한 연결이 하나 있습니다. 크기 지침을 내가 직접 골라 두면 그 지침의 에이전트 수가 스물다섯이라는 문턱을 대신합니다. 「작게」로 두었다면 다섯 개만 넘어도 경고가 붙는다는 뜻이죠. 기본값을 그대로 두면 문턱은 스물다섯에 머뭅니다.

비용 쪽도 같이 봐 두면 좋습니다. 이 실행들은 요금제 사용량과 호출 제한에 그대로 산입됩니다. 한 번의 실행에 속한 에이전트들이 같은 식별자를 달고 나오니, 사용량 기록을 저장소별로 가르는 방법과 묶으면 「이 작업 한 번에 얼마」를 한 덩어리로 볼 수 있습니다.

4. 5초를 일부러 기다립니다

펼쳐 돌릴 때 둘째 에이전트부터는 기본 5초 뒤에 출발합니다. 느리게 만드는 장치처럼 보이지만 정반대입니다. 첫 에이전트와 앞부분을 공유하는 에이전트들이 그 앞부분을 각자 새로 처리하지 않고, 첫 에이전트가 만들어 둔 것을 읽게 하려는 것입니다.

여기에 알아 둘 성질이 하나 더 있습니다. 워크플로 에이전트의 요청은 본 대화와 다른 묶음으로 취급돼서, 아껴 둔 앞부분이 5분만 유지됩니다. 단계 사이가 길게 벌어지는 구성이라면 그사이에 식어 버린다는 뜻입니다. 중간 결과가 대화에 안 쌓이는 것도 같은 격리 구조에서 나옵니다. 도입 순서를 잡는 중이라면 AI 도입 한 바퀴를 모아 둔 글에서 이 단계의 위치를 확인해 보세요.

자주 묻는 질문 (FAQ)

Q. 동시 개수를 더 올릴 수는 없나요?

최근 판올림에서 실행당 동시 개수를 올리는 환경 변수가 생겼습니다. 추론을 기다리느라 놀고 있는 작업을 더 펼쳐 보라는 용도입니다. 다만 코어가 적으면 실제로는 그만큼 안 돌고, 같은 계정의 호출 제한을 나눠 쓰는 구조라 개수를 올린 만큼 처리량이 늘지는 않습니다. 벽시계 시간이 줄어드는 쪽에 가깝습니다.

Q. 중간에 결과를 보고 승인하게 할 수 있나요?

못 합니다. 실행을 멈출 수 있는 건 에이전트가 띄우는 권한 확인창뿐이고, 그것도 승인 절차라기보다 도구 사용 허락에 가깝습니다. 단계 사이에 사람 판단이 필요하다면 단계마다 별도 실행으로 쪼개는 것이 문서가 권하는 방법입니다. 멈춘 실행은 다시 이어 붙일 수 있고, 앞 실행의 에이전트가 아직 안 끝났으면 같은 것이 두 벌 돌지 않도록 거절됩니다.

Q. 스크립트에서 라이브러리를 쓰고 싶은데요?

안 됩니다. 스크립트 본문은 순수한 자바스크립트여야 하고, 불러오기 구문이 들어 있으면 돌기도 전에 실패합니다. 스크립트의 역할은 에이전트를 조율하는 것뿐이거든요. 라이브러리가 필요한 일은 에이전트의 작업으로 넘기면 됩니다. 에이전트는 파일을 읽고 쓰고 명령도 돌릴 수 있으니까요.

Q. 검증 단계가 「틀렸다」고 하면 믿어도 되나요?

여기가 잘 설계된 부분입니다. 검증하는 에이전트가 한도에 걸렸거나 오류가 나서 확인을 못 했을 때, 그 주장을 「반박됨」이 아니라 「확인 못 함」으로 따로 적습니다. 못 본 것과 틀린 것을 섞지 않는다는 뜻이죠. 보고서를 읽을 때 이 둘을 구분해서 보셔야 합니다.

정리하면

• 규모를 줄이려면 설정이 아니라 부탁을 좁히세요.
• 동시 열여섯은 실패가 아니라 차례를 만듭니다.
• 경고를 기다리지 말고 작은 조각으로 먼저 돌려 보세요.
• 단계 승인이 필요하면 실행을 쪼개세요.

※ 공개된 안내 문서와 판올림 기록을 읽고 정리했습니다. 설정 항목·환경 변수·함수 이름은 우리말로 풀어 적었고, 큰 규모로 직접 돌려 보지는 않았습니다.

※ 개수 제한과 기본값은 열람 시점 기준이며 판올림에 따라 달라질 수 있습니다. 동시 개수는 컴퓨터의 코어 수에 따라 더 낮아지므로 표의 숫자가 언제나 그대로 나오지는 않습니다. 큰 실행 전에 원문의 제약 표를 한 번 확인하세요.