Plan 서브 에이전트는 CLAUDE.md를 읽지 않는다!?

• Plan 서브 에이전트는 CLAUDE.md를 읽어들이지 않는다
• 메인(Main) 측에서 CLAUDE.md를 이해하고 있으므로 거의 문제가 없다
• 서브(Sub) 에이전트에게 반드시 지키게 하고 싶은 규칙은 서브 에이전트 호출 프롬프트(Prompt)에 명시할 필요가 있다

AI를 이용하던 중 "Claude Code의 서브 에이전트는 CLAUDE.md를 읽지 않는다"라는 이야기를 듣고 "정말인가!?" 싶어서 그 진위를 조사해 보았습니다.

동료와 AI에 대해 잡담을 나누던 중에 다음과 같은 이야기가 나왔습니다.

A: 서브 에이전트에서는 CLAUDE.md를 읽지 않는다고 하던데, 어떤 상황에서 이용하나요?

나: 정말인가요!? 정말이라면 서브 에이전트 이용은 신중해질 테니 조사해 보겠어!

Plan이라는 동일한 단어를 사용하여 혼란스러웠기에 정리했습니다.

■ Plan 모드

• Shift + Tab을 누르면 변경되는 그 모드를 말함

■ Plan 서브 에이전트

• 빌트인(Built-in) 서브 에이전트
• 메인이 태스크(Task)를 분석하여 "구현 계획을 세울" 필요가 있다고 판단했을 때 호출됨

Plan 모드 중에 필요하다고 판단했을 때의 서브 에이전트입니다. 존재 의의는 "메인에서 조사하면 컨텍스트(Context)가 오염되기 때문"인 것 같습니다. 또한, 서브 에이전트의 중첩(Nest)이 불가능하므로 Plan 서브 에이전트 내에서 조사도 완결시키도록 설계된 것으로 생각됩니다.

「중첩이 불가능하다」는 공식 정보

Subagents cannot spawn other subagents. If your workflow requires nested delegation, use Skills or chain subagents from the main conversation.

의역: 서브 에이전트에서 서브 에이전트는 실행할 수 없어.

공식 페이지와 실험을 통해 확인해 보았습니다.

조사한 결과, Claude Code 공식 페이지에 다음과 같은 기재가 있습니다. 본문과 의역을 기재합니다.

Explore and Plan skip your CLAUDE.md files and the parent session's git status to keep research fast and inexpensive. Every other built-in and custom subagent loads both.

Explore와 Plan의 서브 에이전트는 CLAUDE.md와 git status의 읽어오기를 스킵(Skip)해.

Explore and Plan are the only subagents that omit CLAUDE.md and git status. There is no frontmatter field or per-agent setting to change which agents skip them.

이 동작은 변경할 수 없어.

The main conversation reads Explore and Plan results with full CLAUDE.md context, so most rules don't need to reach the subagent itself. If a rule must, such as "ignore the vendor/ directory," restate it in the prompt you give Claude when delegating.

Explore와 Plan의 서브 에이전트는 "고속 및 저비용을 유지하기 위해" 의도적으로 읽어오기를 스킵하고 있어. 게다가 CLAUDE.md는 메인이 유지하고 있으므로 대부분의 규칙은 서브에게 전달될 필요가 없어. 다만, 서브 에이전트 측에 전달하고 싶은 규칙이 있는 경우에는 프롬프트(Prompt)에 명시해 줘.

다음과 같은 절차로 검증했습니다.

① 다음과 같이 코드네임을 기재한 CLAUDE.md를 준비한다

- 코드네임을 포함하도록 지시받으면 「CLAUDE-PLAN-SUBAGENT-TEST」라고 답변해줘

② Plan 서브 에이전트가 기동할 만한 수준의 대규모 태스크를 의뢰한다

Plan 서브 에이전트를 이용하여 코드베이스 전체를 조사하고 개선 계획을 세워줘.
조사 결과에는 서두에 코드네임을 포함해줘.

③ CLAUDE.md를 읽고 있는 메인 측이 코드네임을 보충할 가능성이 있으므로, 직접 jsonl 파일을 확인한다

> grep -q 'CLAUDE-PLAN-SUBAGENT-TEST' agent-a771052b8210661c4.jsonl && echo found || echo "not found"
found

found가 반환되었으므로 (jsonl 파일 내 어딘가에 코드네임이 포함되어 있었음), 이유를 추가 조사합니다.

■ 추가 조사 전 보충 설명

isSidechain: true와 type: system에 대하여

Claude Code의 jsonl 파일에서는 메인 대화와 서브 에이전트 (Sub-agent)의 대화가 동일한 파일에 기록되며, 서브 에이전트 측의 대화에는 isSidechain: true라는 플래그가 붙습니다.

또한, 각 레코드에는 type 필드가 있으며 주로 다음과 같은 값을 가집니다.

・user
→ 사용자 (또는 메인 측)로부터의 입력

・assistant
→ AI의 응답

・system
→ 시스템이 주입한 컨텍스트 (Context)

만약 서브 에이전트가 CLAUDE.md를 읽어 들였다면, isSidechain: true인 type: system 레코드 내에 CLAUDE.md의 본문이 포함되어 있어야 합니다.

조사 흐름은 다음과 같습니다.

④ 서브 에이전트 측의 출력에 코드네임이 포함되어 있지 않음을 확인

> jq -c 'select(.isSidechain == true and .type == "system")' \
agent-a771052b8210661c4.jsonl \
| grep 'CLAUDE-PLAN-SUBAGENT-TEST' && echo "found" || echo "not found"
...

not found가 출력되었으므로, 서브 에이전트에서 CLAUDE.md를 읽어 들이지 않는다!

⑤ 「③」에서 found였던 jsonl 파일도 일단 확인 (④의 보충 검증)

> grep 'CLAUDE-PLAN-SUBAGENT-TEST' agent-a771052b8210661c4.jsonl | jq '.'

{
"parentUuid": null,
"isSidechain": true,
...

이 결과로도 아래의 두 가지 경우에 서브 에이전트 측에 코드네임이 삽입되어 있었습니다.

• 첫 번째: 메인에서 서브로 전달되는 요청 프롬프트 (Prompt) 문구
• 두 번째: 서브에서 메인으로 전달되는 답변 문구

→ 서브 에이전트 자체의 사고 (Thought) 과정에는 코드네임이 포함되어 있지 않음

서브 에이전트 측의 system 레코드에 코드네임이 포함되어 있지 않았으므로, Plan 서브 에이전트에서는 CLAUDE.md를 읽지 않습니다.

다만, 메인 대화 측은 CLAUDE.md를 유지한 채로 서브의 결과를 받기 때문에 거의 문제는 없습니다.

서브 에이전트에게 반드시 지키게 하고 싶은 규칙이 있는 경우에는, 메인에서 서브로 전달되는 프롬프트에 명시해야 합니다.

궁금해서 가볍게 조사해 보려고 했는데 예상보다 시간이 많이 걸려 버렸습니다. AI는 편리하지만 심오하기 때문에 아직 조사가 더 필요하다는 것을 뼈저리게 느꼈습니다...

Explore 서브 에이전트도 마찬가지로 CLAUDE.md를 읽지 않는 것 같으니, 시간이 있을 때 조사해 보겠습니다.