Claude Code가 AGENTS.md를 무시할 때: 심볼릭 링크 해결법

작성일: 2025년 12월 25일
카테고리: AI, Developer Tools, Claude Code
키워드: CLAUDE.md, AGENTS.md, symlink, @import, Claude Code

요약

Claude Code의 공식 문서에서 @import 문법으로 AGENTS.md를 참조하라고 안내하고 있지만, 실제 개발 환경에서 Claude가 AGENTS.md를 읽지 않는 경우가 빈번하게 발생합니다. 이 글에서는 해당 문제의 원인을 분석하고, 심볼릭 링크를 활용한 현실적인 해결책을 공유합니다.

문제 상황

공식 가이드의 @import 문법

Claude 공식 블로그와 Memory Documentation에서는 @path/to/file 문법으로 다른 마크다운 파일을 import할 수 있다고 안내합니다.

# CLAUDE.md

## 프로젝트 가이드
@AGENTS.md
@docs/architecture.md

공식 문서에 따르면:

• 재귀 import 지원 (최대 5단계)
• 코드 블록 내에서는 import로 처리되지 않음
• /memory 명령어로 로드된 파일 목록 확인 가능

실제로 발생한 문제

CLAUDE.md 내용:
  @AGENTS.md

기대 동작:
  Claude가 AGENTS.md를 읽고 해당 규칙을 따름

실제 동작:
  Claude가 AGENTS.md를 무시하고 CLAUDE.md만 참조
  → 개발 가이드를 따르지 않음
  → 매번 "AGENTS.md를 읽어라"라고 명시적으로 지시해야 함

증상 확인

/memory 명령어로 확인해보면 AGENTS.md가 로드 목록에 포함되지 않는 경우가 있습니다.

$ claude /memory

Loaded files:
- ~/.claude/CLAUDE.md
- ./CLAUDE.md

Expected but missing:
- ./AGENTS.md  ← @import 했는데 없음

근본 원인 분석

1. @import 처리 타이밍 문제

Claude Code가 CLAUDE.md를 파싱할 때 @import 구문을 처리하는 시점이 일관적이지 않습니다. 특히 다음 상황에서 문제가 발생합니다:

• 세션 시작 시 초기 로드
• 컨텍스트 재구성 시
• 서브에이전트 호출 시

2. 경로 해석 불일치

# 상대 경로
@AGENTS.md           # 현재 디렉토리 기준
@./AGENTS.md         # 명시적 현재 디렉토리
@docs/AGENTS.md      # 하위 디렉토리

# 절대 경로
@~/.claude/rules.md  # 홈 디렉토리

경로 해석이 실행 컨텍스트에 따라 달라지며, Windows 환경에서는 추가적인 문제가 발생할 수 있습니다.

3. 캐싱 및 갱신 문제

CLAUDE.md 변경 후에도 이전 캐시를 참조하거나, @import된 파일의 변경사항이 즉시 반영되지 않는 경우가 있습니다.

해결책: 심볼릭 링크 사용

접근 방식

@import에 의존하지 않고, 심볼릭 링크로 하나의 파일을 두 이름으로 접근할 수 있게 합니다.

project/
├── AGENTS.md          # 실제 개발 가이드 (원본)
└── CLAUDE.md -> AGENTS.md  # 심볼릭 링크

구현 방법

Linux/macOS:

# 기존 CLAUDE.md가 있다면 백업
mv CLAUDE.md CLAUDE.md.backup

# 심볼릭 링크 생성
ln -s AGENTS.md CLAUDE.md

# 확인
ls -la CLAUDE.md
# lrwxr-xr-x  1 user  staff  10 Dec 25 12:00 CLAUDE.md -> AGENTS.md

Windows (관리자 권한 cmd에서 mklink 사용):

# cmd (관리자 권한으로 실행)
mklink CLAUDE.md AGENTS.md

Windows에서는 반드시 관리자 권한의 cmd에서 mklink 명령어를 사용해야 합니다.

Git Bash의 ln -s는 사용 금지:

# Git Bash에서 ln -s 실행 시
ln -s AGENTS.md CLAUDE.md

# 예상: 심볼릭 링크 생성
# 실제: 단순 파일 복사 발생 (심볼릭 링크 아님)

Git Bash의 ln -s는 Windows에서 심볼릭 링크를 생성하지 않고 파일을 복사합니다. 이 경우 AGENTS.md를 수정해도 CLAUDE.md에 반영되지 않아 동기화 문제가 발생합니다.

PowerShell (관리자):

# PowerShell (관리자 권한으로 실행)
New-Item -ItemType SymbolicLink -Path CLAUDE.md -Target AGENTS.md

Windows (개발자 모드 활성화 시):
Windows 10 버전 1703 이상에서 개발자 모드가 활성화되어 있으면 관리자 권한 없이 심볼릭 링크 생성이 가능합니다. 설정 > 개발자용 > 개발자 모드에서 활성화할 수 있습니다.

Git 설정

심볼릭 링크를 Git으로 관리할 때 주의사항:

# 심볼릭 링크 지원 확인
git config core.symlinks

# Windows에서 심볼릭 링크 활성화
git config --global core.symlinks true

.gitattributes에 명시적 설정:

CLAUDE.md symlink=true

결과

실제 파일 구조:
  AGENTS.md     (실제 내용 - 593줄)
  CLAUDE.md     → AGENTS.md (심볼릭 링크)

Claude Code 동작:
  CLAUDE.md 로드 → 실제로는 AGENTS.md 내용을 읽음
  → 모든 개발 가이드가 정상 적용됨

대안 비교

방법 1: @import 유지 (공식 권장, 불안정)

# CLAUDE.md
@AGENTS.md

장점:

• 공식 문서에서 권장하는 방식
• 추가 설정 불필요

단점:

• 실제 환경에서 작동하지 않는 경우 빈번
• 디버깅이 어려움

방법 2: 심볼릭 링크 (권장)

ln -s AGENTS.md CLAUDE.md

장점:

• 100% 안정적으로 작동
• 단일 파일만 관리
• OS 레벨에서 보장

단점:

• Windows에서 추가 설정 필요
• Git clone 시 심볼릭 링크 지원 확인 필요

방법 3: 파일 복사 (비권장)

cp AGENTS.md CLAUDE.md

장점:

• 모든 환경에서 작동
• 설정 불필요

단점:

• 두 파일을 동기화해야 함
• 실수로 불일치 발생 가능
• CI/CD에서 동기화 스크립트 필요

방법 4: CLAUDE.md에 직접 작성

AGENTS.md를 포기하고 CLAUDE.md에 모든 내용을 작성합니다.

장점:

• 단순함

단점:

• Codex CLI, Gemini CLI 등 다른 AI 에이전트에서 인식 불가
• 크로스 플랫폼 호환성 포기

권장 설정

단일 AI 에이전트 환경 (Claude Code만 사용)

심볼릭 링크로 단일 파일 관리:

# AGENTS.md를 원본으로 사용
mv CLAUDE.md AGENTS.md
ln -s AGENTS.md CLAUDE.md

멀티 AI 에이전트 환경 (Claude + Codex + Gemini)

project/
├── AGENTS.md              # 실제 개발 가이드 (원본)
├── CLAUDE.md -> AGENTS.md # 심볼릭 링크 (Claude Code용)
└── .gemini/
    └── settings.json      # Gemini가 AGENTS.md 인식하도록 설정

.gemini/settings.json:

{
  "contextFileName": "AGENTS.md"
}

Codex CLI는 AGENTS.md를 기본으로 인식하므로 별도 설정이 필요 없습니다.

재발 방지 방안

1. 프로젝트 초기화 스크립트

#!/bin/bash
# scripts/setup-claude.sh

# CLAUDE.md가 심볼릭 링크인지 확인
if [ ! -L "CLAUDE.md" ]; then
    echo "Creating symlink: CLAUDE.md -> AGENTS.md"
    [ -f "CLAUDE.md" ] && mv CLAUDE.md CLAUDE.md.backup
    ln -s AGENTS.md CLAUDE.md
fi

2. pre-commit 훅으로 검증

#!/bin/bash
# .git/hooks/pre-commit

# CLAUDE.md가 심볼릭 링크가 아니면 경고
if [ -f "CLAUDE.md" ] && [ ! -L "CLAUDE.md" ]; then
    echo "WARNING: CLAUDE.md should be a symlink to AGENTS.md"
    echo "Run: ln -sf AGENTS.md CLAUDE.md"
    exit 1
fi

3. CI/CD 파이프라인 검증

# .github/workflows/validate.yml
- name: Check CLAUDE.md symlink
  run: |
    if [ -f "CLAUDE.md" ] && [ ! -L "CLAUDE.md" ]; then
      echo "::error::CLAUDE.md should be a symlink to AGENTS.md"
      exit 1
    fi

교훈

1. 공식 문서와 실제 동작의 차이

공식 문서에서 지원한다고 해서 모든 환경에서 안정적으로 작동하는 것은 아닙니다. 특히 AI 도구는 빠르게 발전하면서 문서와 실제 구현 사이에 차이가 발생할 수 있습니다. 실제 개발 환경에서 충분히 테스트한 후 워크플로우에 적용하는 것이 중요합니다.

2. 심플한 해결책이 최선

@import 문법의 동작 원리를 분석하고 디버깅하는 것보다, OS 레벨에서 보장되는 심볼릭 링크를 사용하는 것이 더 효율적입니다. 복잡한 문제에 단순한 해결책을 적용하는 것이 유지보수 관점에서 유리합니다.

3. 크로스 플랫폼 고려

심볼릭 링크는 Linux/macOS에서는 기본 지원되지만, Windows에서는 추가 설정이 필요합니다. 팀 환경에서는 모든 개발자의 OS를 고려한 설정 가이드를 제공해야 합니다.

참고 자료

관련 문서

• CLAUDE.md 공식 가이드 정리 - @import 문법 공식 안내
• Claude, Gemini, Codex에서 AGENTS.md 설정하기 - 멀티 에이전트 통합 가이드
• CLAUDE.md 최적화 여정 - 가이드 작성 베스트 프랙티스

공식 문서

• Using CLAUDE.md files - Claude 공식 블로그
• Memory Documentation - Import 문법 공식 문서