저는 디자인 토큰(design-token) 전수 조사를 병렬 Claude Code 서브에이전트(subagents)들에게 배분: 앱의 화면과 컴포넌트 전반에 흩어져 있는 약 317개의 하드코딩된 16진수(hex) 색상들을 모두 중앙 테마 파일의 토큰으로 교체하는 작업이었습니다. 각 에이전트는 파일의 일부를 할당받았고, 작업이 완료되면 보고했습니다. 보고서는 깔끔하게 들어왔습니다. 하지만 이후 진행한 grep 결과는 달랐습니다. 일부 파일 조각들은 전혀 수정되지 않은 상태였고, 해당 작업을 담당했던 에이전트들은 아무런 말도 하지 않았습니다. 왜냐하면 그들은 더 이상 무언가를 말할 수 있는 상태로 존재하지 않았기 때문입니다.

그 전수 조사와 그 과정에서의 세션들은 서브에이전트(subagent)의 자기 보고(self-report)가 양방향 모두에서 틀릴 수 있다는 점을 가르쳐 주었습니다. 실패한 에이전트는 아무것도 보고하지 않거나 성공했다고 주장합니다. 성공한 에이전트는 치명적인 실패를 보고합니다. 만약 당신의 오케스트레이션(orchestration)이 이러한 서술을 신뢰한다면, 당신은 이미 완료된 작업을 다시 수행하거나, 완료되지 않은 작업을 배포하게 될 것이며, 때로는 같은 실행(run) 내에서 이 두 가지가 동시에 일어날 수도 있습니다.

각기 다른 거짓말을 하는 네 가지 실패 모드가 있습니다.

1. 침묵의 죽음 (The silent death)

에이전트가 작업 도중 세션 제한(또는 기타 강제 종료)에 걸려 멈춥니다. 오케스트레이터(orchestrator)에게는 아무런 오류도 전달되지 않으며, 부분 작업 보고도 없습니다. 실행은 계속 진행되며, 유일한 증거는 아무도 재확인하지 않은 파일들에서 변경 사항이 나타나지 않는다는 사실뿐입니다.

거짓말: 소식이 없는 것을 좋은 소식으로 간주하게 만듭니다. "에이전트가 불만 없이 작업을 마쳤다"를 "에이전트가 작업을 완료했다"로 취급하는 오케스트레이터는, 이러한 모든 죽음을 커버리지의 침묵하는 공백으로 물려받게 됩니다.

해결책은 기계적입니다: 에이전트가 보고를 마친 후, 각 에이전트에게 할당된 파일들에 대해 전수 조사 검색 패턴을 다시 실행하는 것입니다. 에이전트의 요약본을 점검하는 것이 아니라, 오케스트레이터가 직접 실제 범위에 대해 실제 패턴을 실행해야 합니다. 저의 전수 조사에서 이것이 바로 "모두 완료됨"을 제가 직접 수정해야 할 잔여 작업 목록으로 바꿔놓은 방법이었습니다.

2. 거짓 자백 (The false confession)

한 검증 에이전트(verifier agent)가 약 400초 동안 48번의 도구 사용(tool uses)을 수행했고, 보고서 파일을 성공적으로 작성한 뒤, API Error: Internal server error와 함께 종료되었습니다. 충돌은 결과물이 이미 디스크에 저장된 후, 중요하지 않은 후속 작업인 메모리 항목을 저장하는 과정에서 발생했습니다.

외부에서 보기에는 이것이 완전한 손실처럼 보입니다. 하지만 실제로는 정반대였습니다. 작업은 완료되었으며 실패는 외관상의 문제일 뿐이었습니다.

거짓말: 완료된 작업 위에 덧씌워진 충돌(crash) 상태입니다. 이를 믿게 되면 이미 결과물이 생성되어 있는 긴 에이전트(agent)를 다시 배정하게 되어, 전체 비용을 두 번 지불하게 됩니다. 충돌이 발생한 에이전트를 재실행하기 전에, ls 명령어로 예상되는 결과물(artifact)을 읽어보세요. 파일이 존재하고 구조적 검사(structural check)를 통과한다면, 그 결과물의 주장 중 두세 가지만 확인해 보고 그대로 사용하세요.

예방법은 프롬프트(prompt) 측면에 있습니다: 실행 시간이 긴 에이전트에게 선택적인 후속 작업을 수행하기 전에 결과물을 먼저 작성하도록 지시하세요. 그러면 나중에 충돌이 발생하더라도 비용이 들지 않습니다.

3. 작업이 없는 좀비 (The zero-work zombie)

529 Overloaded 오류는 에이전트가 아무것도 하기 전에 종료시킬 수 있습니다. 결과에는 여전히 duration_ms에 몇 분의 실행 시간이 보고되는데, 바로 이 점이 상황을 설득력 있게 만듭니다. 단서는 다른 곳에 있습니다: total_tokens: 0, tool_uses: 0입니다.

거짓말: 실행 시간(duration)이 노력을 의미한다는 점입니다. 실제 경과 시간(wall-clock)이 몇 분이라는 점을 작업 시간으로 오해하게 되며, 자연스러운 복구 방식은 "에이전트가 멈춘 지점부터 계속 진행하라"는 것이 됩니다. 하지만 진행할 곳이 없습니다. 토큰이 0개라면 계속할 컨텍스트(context)가 없으며, 충돌 메시지에 포함된 계속 진행 스타일의 복구 힌트는 막다른 길입니다. 동일한 프롬프트로 새로운 에이전트를 다시 배정했더니 첫 번째 시도에 성공했습니다.

관련된 함정: Write 작업 직후에 발생하는 최상위 529 오류가 Write 작업의 실패를 의미하지는 않습니다. 무엇인가를 다시 하기 전에 파일을 확인하세요.

4. 인라인 우회 (The inline bypass)

가장 이상한 사례입니다: 에이전트가 채팅 텍스트로서 결과물을 완전히 생성하지만, Write를 호출하지 않는 경우입니다. 도구(tool)는 목록에 있습니다. 프롬프트에는 출력 경로가 명시되었습니다. 내용은 마지막 메시지에 그대로 들어있지만, 파일은 존재하지 않으므로 해당 경로를 읽는 모든 다운스트림(downstream) 단계는 아무것도 받지 못하게 됩니다.

거짓말: 작업은 눈에 보이게 존재하지만, 단지 파이프라인(pipeline)이 필요로 하는 위치에 없을 뿐입니다. 채팅 텍스트를 받아들이고 에이전트(agent)를 대신해 직접 파일을 작성하고 싶은 유혹이 들 것입니다. 그러지 마세요. 오케스트레이터(orchestrator)가 에이전트를 위해 전사(transcribing)를 시작하는 순간, 당신은 자동화된 파이프라인에 수동 단계를 구축하게 되며, 어떤 에이전트가 실제로 준수(comply)하고 있는지에 대한 신호(signal)를 잃게 됩니다.

제가 이 문제를 해결한 방법은 모든 에이전트 프롬프트(prompt)에 '쓰기 또는 차단(write-or-block)' 계약을 넣는 것이었습니다. 즉, 제공된 경로에 대한 필수적인 Write 호출, 채팅창에 결과물을 출력하는 것에 대한 명시적 금지, 그리고 "<path>를 작성함"으로 제한된 최종 메시지입니다. 이로써 준수 여부를 한 줄로 확인할 수 있게 되었습니다.

네 가지 실패를 모두 잡아내는 게이트(Gate)

전수 조사 이후, 모든 디스패치(dispatch)는 다운스트림(downstream) 단계가 시작되기 전 오케스트레이터가 실행하는 동일하고 저렴한 Bash 게이트(gate)로 끝납니다.

[ -f blocker.md ] && echo BLOCKER
[ -s report.md ] && echo OK || echo MISSING/EMPTY
grep -c "^## Findings" report.md

존재 여부, 비어 있지 않음, 구조적 형태를 아티팩트(artifact)를 컨텍스트(context)에 로드하지 않고 단 한 번의 호출로 모두 확인합니다. 이 게이트는 529 에러로 죽어버린 실행기(executer)와 인라인 우회(inline-bypass)를 시도한 리뷰어(reviewer)를 모호함 없이 모두 잡아냈습니다. 게이트는 MISSING/EMPTY를 출력했고 해석의 여지를 남기지 않았습니다. 실패 모드 1에서 언급한 할당된 범위에 대한 grep 체크와 결합하면, 아무것도 했다고 주장하지 않는 죽은 에이전트와 너무 많은 것을 했다고 주장하는 살아있는 전사(transcript) 모두를 양방향에서 커버할 수 있습니다.

핵심 요약(Takeaway)

이전에 저는 도구가 사라졌을 때 침묵 속에서 즉흥적으로 대처하는 오케스트레이터에 대해 쓴 적이 있는데, 여기서의 결론도 동일하며 더 확장된 형태입니다. 서술(narration)은 증거가 아닙니다. 에이전트의 최종 메시지, 충돌(crash) 상태, 심지어 실행 시간(runtime duration)조차도 모두 작업에 대한 신호(signal)일 뿐이며, 그중 어느 것도 틀릴 수 있습니다. 디스크 상의 아티팩트(artifact)가 곧 작업입니다. 그것에 게이트를 설치하고, 범위를 grep으로 확인하며, 에이전트가 자신에 대해 말하는 모든 것을 단 한 번의 Bash 호출 비용으로 검증해야 할 가설(hypothesis)로 취급하십시오.

파일 시스템(filesystem)을 믿으세요. 파일 시스템은 단 한 번도 저에게 거짓말을 한 적이 없습니다.

실제 Claude Code 멀티 에이전트 실행 과정에서 수집된 실패 모드(Failure modes)입니다. 여기에는 약 317개의 하드코딩된 16진수 색상(hex colors)을 중앙 디자인 토큰(design tokens)으로 교체하기 위해 병렬 서브에이전트(subagents)로 분할하여 수행한 스윕(sweep) 작업이 포함됩니다. 쓰기 또는 차단 계약(write-or-block contract)과 아티팩트 게이트(artifact gates)는 현재 제가 실제 Expo/Supabase 리포지토리(repos)를 대상으로 매일 사용하는 오케스트레이터(orchestrator)인 Suhail에 탑재되어 있습니다. 에러 페이로드(API Error: Internal server error, 529 Overloaded, total_tokens: 0)는 2026년 7월의 실제 세션 결과에서 가져온 것입니다.