먼저 전제 조건 하나를 말씀드리겠습니다. Claude Code의 서브 에이전트(Sub-agent)는 메인 대화를 읽지 않습니다. 컨텍스트(Context)는 공유되지 않으며, 매번 완전히 새로운 상태로 기동됩니다. 이 점을 모른 채 사용하면 에러는 발생하지 않지만, 조용히 헛수고를 하게 됩니다.

제가 실제로 겪었던(혹은 겪을 뻔했던) NG 사례 5가지를 나쁜 예와 해결법으로 정리합니다.

• 메인에서 설명한 전제를 '알고 있다'고 가정하고 던지기
• 방침을 대화에만 적고, 파일로 만들지 않기
• 채택 여부의 판단까지 서브 에이전트에게 맡기기
• 아주 작은 태스크까지 분리하기
• fork(부모 컨텍스트 상속)를 전제로 설계하기

1. 가장 많은 헛수고 사례입니다. 메인 대화에서 아무리 정중하게 방침을 다듬어도, 서브 에이전트에게는 단 한 줄도 전달되지 않습니다.

❌ NG: 메인에서 결정한 방침을 '아까 그거'로 참조하기
아까 결정한 방침으로 이 기사를 리뷰해줘.

✅ OK: 전제를 요청문에 전부 작성하기
다음 기준에 따라 이 기사를 리뷰해줘.
- 어미가 단조롭게 반복되지 않는가
...

왜일까요? 서브 에이전트에게 '아까'라는 개념은 존재하지 않습니다. 대화가 이어지는 것처럼 보이는 UI가 함정이며, 실제로는 구두 인수인계가 전혀 없는 상태에서 신입 사원에게 일을 던지는 것과 같습니다. 엉뚱한 결과가 돌아온다면 모델을 탓하기 전에 자신의 인수인계를 먼저 의심하는 것이 지름길입니다.

매번 프롬프트에 쓰는 것은 요청이 늘어나면 한계에 부딪힙니다. 대화는 휘발됩니다.

❌ NG: 긴 방침을 매번 복사해서 요청문에 붙여넣기
(요청할 때마다 20줄의 기준을 붙여넣음)

✅ OK: 방침을 파일로 고정하고, 읽게 한 뒤 시작하기
docs/review-policy.md 에 리뷰 관점을 정리해 두었어.
먼저 그것을 읽고 나서, 이 기사를 리뷰해줘.

왜일까요? 파일은 휘발되지 않습니다. 서브 에이전트에게 전달하는 과정이 한 줄로 끝나며, 방침 자체가 대화 외부에 고정되므로 스스로 검토하기도 쉽습니다. 에이전트 정의 파일(.claude/agents/ 하위 디렉토리)에 관점을 적어두는 것도 같은 효과를 냅니다.

2. 분리한 대상에게 '수정까지 해둬'라고 시키면 조용히 어긋나기 시작합니다.

❌ NG: 조사부터 수정 실시까지 일괄적으로 맡기기
이 코드의 문제점을 찾아서 전부 수정해둬.

✅ OK: 리포트만 가져오게 하고, 채택 여부는 메인에서 결정하기
이 코드의 문제점을 중요도가 높은 순서대로 리스트로 보고해줘.
수정은 아직 하지 마.

왜일까요? 에이전트 간의 컨텍스트는 분리되어 있으므로, 서브 측은 전체적인 사정(수정하고 싶지 않은 부분, 나중에 지울 예정인 코드 등)을 알지 못합니다. 판단 재료를 가지고 있는 것은 메인 측입니다. 조사나 지적 같은 '대량으로 읽어야 하는 일'을 맡기고, 결정은 본인이 합니다. 이렇게 역할을 분담한 이후로 재작업(rework)이 눈에 띄게 줄었습니다.

3. 분리의 편리함을 알게 되면 무엇이든 분리하고 싶어집니다. 이는 역효과를 낳습니다.

❌ NG: 몇 줄 안 되는 수정을 굳이 서브 에이전트에게 시키기
이 함수의 변수명을 리네임해줘.
(기동 + 전제 전달 비용이 본체 작업보다 더 무거움)

✅ OK: 분리하는 것은 '대량으로 읽는' 작업만
・ 코드베이스 전체에서 해당 부분 찾아내기
・ 긴 로그 분석하기
...

왜일까요? 서브 에이전트는 기동할 때마다 비용이 발생하며, 전제를 전달하는 데에도 토큰을 소비합니다. 5분짜리 일을 위해 교육을 시키고 있다면 본말전도입니다. 분리 기준은 '읽는 양'입니다. 메인의 책상(컨텍스트)을 어지럽힐 정도로 읽어야 하는 일만 외부로 보냅니다.

4. 부모의 컨텍스트를 상속하는 기동 방법도 있습니다. 편리하지만, 이를 전제로 설계하는 것은 위험합니다.

❌ NG: 'fork라면 대화를 이어받으니까'라는 전제의 운용
(기동 방식에 따라 동작이 달라지며, 환경이 바뀌면 조용히 망가짐)

✅ OK: 상속 여부와 관계없이 성립하는 전달 방식 만들기
전달하고 싶은 전제는 파일이나 요청문을 통해 명시적으로 전달한다.
상속되면 덤이라는 정도의 위치로 잡아둔다.

왜일까요? fork 관련 동작은 실행 환경에 따라 달라진다는 보고가 있으며, 상속을 전제로 한 설계는 이식성이 낮아집니다. 명시적으로 전달하는 설계로 해두면 어떤 기동 방식에서도 동일하게 동작합니다. 암묵적인 공유에 의존하지 않는 것이 결국 가장 견고했습니다.

• 서브 에이전트에게 '아까'는 없다. 전제는 요청문에 적는다.
• 재사용할 방침은 파일로 고정하고, 읽게 한 뒤 시작한다.
• 서브는 보고까지만. 채택 여부는 메인에서 결정한다.
• 분리하는 것은 '대량으로 읽는' 일만. 작은 태스크는 인수인계 비용이 더 높다.
• 상속(fork)은 믿지 않는다. 명시적으로 전달하는 설계가 가장 견고하다.

분리는 결함이 아니라, 메인 컨텍스트 (Main Context)를 보호하기 위한 사양입니다. "모르는 상대에게 명시적으로 전달한다"는 원칙에 집중한 이후로는, 헛수고하는 경우가 거의 사라졌습니다. 도움이 되었다면 저장해 두었다가, 서브 에이전트 (Sub-agent)를 구성할 때 다시 확인해 보세요.

평소에는 raplsworks.com에서 WordPress 플러그인 개발이나 Claude Code 관련 글을 쓰고 있습니다.