클로드 코드 에이전트는 프로젝트 문서를 자동으로 읽지 않습니다.

Claude Code 에이전트가 프로젝트 문서를 처리하는 방식

Claude Code의 에이전트 시스템을 사용할 때, 개발자는 하위 에이전트가 프로젝트 문서에 접근하는 방식에 특정 제한이 있음을 인지해야 합니다. r/ClaudeAI의 사용자 보고서에 따르면, Claude Code가 코딩 작업을 처리하기 위해 에이전트를 파견할 때, 해당 에이전트들은 제한된 컨텍스트로 작동합니다.

출처의 주요 세부사항

이 문제는 에이전트가 문서화된 함정을 반복적으로 맞닥뜨리는 디버깅 세션 중에 발견되었습니다. 문서화된 경고를 무시한 이유를 묻자, 에이전트는 다음과 같이 답변했습니다: "콜백을 작성하기 전에 CLAUDE.md를 읽지 않았습니다. 탐색 단계에서 코드베이스 패턴을 프롬프트 컨텍스트로 가지고 있었지만, OAuth 경로를 작성하기 위해 Sonnet 에이전트를 파견했을 때, 에이전트 프롬프트는 무엇을 구축할지 설명했지, 어떤 함정을 확인해야 하는지는 설명하지 않았습니다."

에이전트는 추가로 설명했습니다: "Sonnet 하위 에이전트들은 제가 그들의 프롬프트에 넣은 내용만 볼 수 있습니다. 제가 명시적으로 지시하지 않는 한, 그들은 자동으로 CLAUDE.md, MEMORY.md 또는 어떤 프로젝트 컨텍스트도 읽지 않습니다."

실제적 영향

• Sonnet과 같은 하위 에이전트들은 특정 프롬프트에 제공된 컨텍스트로만 작동합니다
• 프로젝트 문서 파일(CLAUDE.md, MEMORY.md)은 자동으로 로드되지 않습니다
• 명시적으로 지시하지 않는 한, 에이전트들은 기존 함정 목록을 참조하지 않고 처음부터 코드를 작성합니다
• 이는 에이전트들이 피할 수 있었던 문서화된 문제를 반복하게 할 수 있습니다

이러한 동작은 개발자들이 특정 코딩 작업을 처리하기 위해 에이전트를 파견할 때 문서 참조를 포함시키는 것에 명시적이어야 함을 의미합니다. 에이전트들은 탐색 단계의 코드베이스 패턴을 유지하지만, 프로젝트별 문서 파일을 자동으로 참조하지는 않습니다.