Claude Code 서브에이전트 기능을 소개하는 공식 발표 이미지
이미지: claude.com/blog (How and when to use subagents in Claude Code)

서브에이전트에게 조사를 맡길 때 가장 귀찮은 부분은 배경 설명입니다. 새로 띄운 에이전트는 메인 세션에서 무슨 대화가 오갔는지 전혀 모르는 상태로 시작하기 때문에, 이미 충분히 설명된 내용인데도 프롬프트에 다시 적어줘야 합니다. 최근에 이 문제를 fork라는 서브에이전트 타입으로 피해간 경험을 정리합니다.

어떤 작업이었나

여러 모듈을 오가며 어떤 캐시 무효화 방식을 쓸지 한참 논의하던 중이었습니다. 메인 세션은 이미 관련 파일을 여러 개 읽었고, 후보로 떠오른 방식 두세 가지의 장단점도 어느 정도 정리된 상태였습니다. 그런데 그중 한 방식이 실제로 라이브러리 레벨에서 어떻게 동작하는지가 불확실해서, 공식 문서와 소스 코드를 뒤져볼 필요가 생겼습니다. 이 조사만 따로 떼서 서브에이전트에 맡기고 싶었는데, 지금까지 논의된 후보 목록과 판단 기준을 처음부터 다시 설명해야 한다면 차라리 메인 세션에서 직접 찾는 게 더 빠를 것 같았습니다.

AI를 어떻게 활용했나

이럴 때 쓰라고 있는 게 fork 타입이었습니다. subagent_type: "fork"로 호출하면 메인 세션의 전체 대화 맥락을 그대로 물려받아서, 지금까지 논의된 내용을 다시 설명할 필요가 없습니다.

Agent({
  description: "캐시 무효화 방식 조사",
  subagent_type: "fork",
  prompt: "방금 후보로 올라온 세 가지 캐시 무효화 방식 중 두 번째(TTL 기반) 방식이 " +
          "라이브러리 내부에서 실제로 백그라운드 재검증을 하는지, 아니면 만료 시점에 " +
          "요청이 들어와야만 갱신되는지 소스 코드와 문서에서 확인해줘. " +
          "결론과 근거 코드 위치만 짧게 보고해줘."
})

프롬프트에 "방금 후보로 올라온 세 가지" "두 번째 방식"이라고만 썼는데도, 포크된 에이전트는 어떤 후보들이었는지 다시 묻지 않고 바로 조사를 시작했습니다. 이미 메인 세션이 읽은 파일 내용과 비교 기준까지 전부 알고 있는 상태로 출발한 셈입니다. 조사 과정에서 나온 라이브러리 소스 코드 읽기, 문서 검색 같은 중간 과정은 포크 내부에서만 쓰이고, 메인 대화로는 결론과 근거 코드 위치 몇 줄만 돌아왔습니다.

처음에 헷갈렸던 부분

포크를 백그라운드로 띄운 다음, 진행 상황이 궁금해서 결과에 포함된 output_file 경로를 중간에 한번 열어보려고 했습니다. 그런데 이 방식 자체가 권장되지 않는다는 걸 뒤늦게 확인했습니다. 포크의 중간 로그를 미리 들여다보면 정작 메인 컨텍스트를 깨끗하게 유지하려고 포크를 쓴 목적이 무색해지기 때문입니다. 결과 알림이 올 때까지 기다리는 게 맞는 사용법이었고, 중간에 궁금하다고 로그 파일을 열어보는 습관은 고치는 쪽으로 정리했습니다.

또 하나는 포크와 완전히 새로 띄우는 서브에이전트의 차이가 처음엔 헷갈렸다는 점입니다. 전에 Explore 타입으로 탐색을 맡겼을 때는 매번 필요한 배경 정보를 프롬프트에 전부 적어줘야 했는데, 그건 새 에이전트가 이전 실행을 전혀 기억하지 못하기 때문이었습니다. fork는 그 전제 자체가 다릅니다 — 메인 세션을 그대로 복제해서 시작하기 때문에 "이전 턴에서 다룬 그 함수" 같은 지칭이 자연스럽게 통합니다.

결과와 얻은 팁

  • 질문이 메인 세션에서 이미 쌓인 맥락(읽은 파일, 비교 기준, 결정 이유)을 전제로 할 때는 fork가 배경 설명 없이 바로 본론으로 들어갑니다. 반대로 맥락과 무관한 독립적인 탐색이라면 fork를 쓸 이유가 없고, Explore나 일반 서브에이전트가 더 가볍습니다.
  • 포크는 메인 세션과 같은 프롬프트 캐시를 공유한다고 되어 있어서, 매번 배경 설명을 프롬프트에 다시 써넣는 것보다 캐시 적중률 면에서도 유리했습니다.
  • 백그라운드로 띄운 포크의 중간 결과를 궁금하다고 미리 열어보지 않는 게 낫습니다. 결과 알림이 올 때까지 기다리는 쪽이 애초에 컨텍스트를 분리한 이유에 맞습니다.
  • 모델을 바꿔서 조사시키고 싶어도 포크는 메인 세션과 같은 모델로 고정됩니다. 다른 모델로 검증받고 싶다면 포크가 아니라 새 서브에이전트를 띄워야 합니다.