Claude 에이전트의 서브 에이전트 컨텍스트 단절 문제와 해결 방법

실용적 조언

에이전트에게 작업을 시킬 때 'claude.md의 규칙을 준수하여 서브 에이전트를 실행하라'고 명시적으로 지시하십시오.
중요한 프로젝트 패턴이나 주의사항은 서브 에이전트 파견 프롬프트에 직접 포함되도록 유도하십시오.

섹션별 상세

사용자는 Claude 에이전트가 claude.md에 정의된 프로젝트 규칙을 무시하고 코드를 작성하는 현상을 발견했다. 에이전트는 기존 코드 패턴은 모방했으나 OAuth 구현 시 필수적인 주의사항들을 누락하여 디버깅 과정에서 큰 혼란을 야기했다.

에이전트와의 대화를 통해 확인한 결과, 메인 에이전트가 작업을 수행하기 위해 생성하는 서브 에이전트(Sonnet)는 프로젝트의 컨텍스트 파일을 자동으로 읽지 않는다. 메인 에이전트가 서브 에이전트에게 전달하는 프롬프트에 해당 내용이 포함되지 않으면 서브 에이전트는 백지 상태에서 작업을 시작한다.

이러한 작동 방식은 에이전트가 작업을 분할하여 처리할 때 발생하는 컨텍스트 단절 문제로 정의된다. 메인 에이전트는 무엇을 할지에 집중하여 프롬프트를 구성하며, claude.md나 memory.md 같은 참조 파일을 서브 에이전트에게 명시적으로 전달하지 않는 한 정보가 유실된다.

실무적으로 이 문제를 해결하려면 사용자가 메인 에이전트에게 작업을 지시할 때 서브 에이전트가 특정 컨텍스트 파일을 반드시 참조하도록 명시적인 지침을 주어야 한다. 이는 에이전트 기반 개발 도구를 사용할 때 자동화된 컨텍스트 상속을 맹신해서는 안 됨을 시사한다.

용어 해설

Claude 프로젝트 규칙 파일(claude.md): — Claude Code 도구에서 프로젝트의 코딩 스타일, 아키텍처 규칙, 주의사항을 저장하는 마크다운 파일이다. 에이전트가 작업을 시작할 때 이 파일을 읽어 프로젝트의 맥락을 파악하도록 설계되었으나 서브 에이전트에게는 자동으로 상속되지 않는 한계가 있다.
서브 에이전트(Sub-agent): — 메인 AI 에이전트가 복잡한 작업을 분할하여 실행하기 위해 생성하는 하위 인스턴스이다. 독립적인 프롬프트 환경을 가지며 메인 에이전트가 명시적으로 전달한 정보 외에는 상위 컨텍스트를 자동으로 공유하지 않는다.
컨텍스트 전파(Context Propagation): — 상위 작업의 맥락이나 설정 정보가 하위 작업이나 서브 에이전트로 올바르게 전달되는 과정이다. 에이전트 시스템에서 이 과정이 누락되면 하위 모델이 프로젝트의 고유 규칙을 무시하고 일반적인 답변을 내놓는 문제가 발생한다.

언급된 도구

Claude Code중립

에이전트 기반 코딩 보조 도구