Claude Code와 AGENTS.md 표준: 상호운용성 갈등

갈등의 핵심: CLAUDE.md vs. AGENTS.md

Claude Code는 AI에게 프로젝트별 컨텍스트와 메모리를 제공하기 위해 독점적인 CLAUDE.md 파일을 사용합니다. 그러나 이미 20,000개 이상의 오픈 소스 프로젝트에서 채택되었고 Cursor 및 Codex와 같은 도구에서 지원되는 AGENTS.md라는 성장하는 오픈 표준은, 모든 코딩 AI를 위한 통합되고 에이전트 중립적인 지침 파일을 제공하는 것을 목표로 합니다.

개발자들은 Claude Code가 이중 파일 접근 방식을 채택할 것을 요청하고 있습니다. 즉, Claude 전용 최적화(예: MCP 서버 구성 또는 서브 에이전트 정의)를 위해 CLAUDE.md를 우선시하되, 일반적인 프로젝트 가이드라인, 빌드 명령 및 스타일 규칙을 위해 AGENTS.md를 보조 수단으로 사용하는 방식입니다. 이를 통해 Claude Code는 지침을 수동으로 복제할 필요 없이 수천 개의 기존 저장소에서 즉시 효과적으로 작동할 수 있습니다.

현재 상태 및 커뮤니티의 반발

높은 지지율(GitHub 이슈에서 4,600개 이상의 반응)에도 불구하고, 해당 기능 요청은 핵심 제품에 네이티브 구현 없이 "completed" 상태로 종료되었습니다. 이는 개발자 커뮤니티로부터 상당한 비판을 불러일으켰으며, 사용자들은 투명성 부족, 미흡한 홍보(PR), 그리고 "폐쇄형 생태계(walled garden)"로의 이동에 대한 우려를 제기하고 있습니다.

비판론자들은 CLAUDE.md 파일을 요구하는 것이 Anthropic을 위한 일종의 "무료 광고" 역할을 하며, 지침이 오픈 표준과 동일하더라도 모든 저장소에 Claude 전용 파일을 표시하도록 강제한다고 주장합니다. 일부 사용자들은 변경 로그나 문서 없이 이슈를 조용히 종료한 것은 전문 개발자를 대상으로 하는 도구로서 용납할 수 없는 일이라고 말하며 극심한한 좌절감을 표현했습니다.

상호운용성을 위한 기술적 우회 방법

AGENTS.md에 대한 네이티브 지원이 불가능한 상황에서, 커뮤니티는 서로 다른 AI 도구 간에 단일 진실 공급원(single source of truth)을 유지하기 위해 몇 가지 우회 방법을 개발했습니다.

1. 가져오기(Import) 방식

Claude Code의 CLAUDE.md는 다른 파일을 가져오는 기능을 지원합니다. 개발자들은 다음과 같은 한 줄의 코드를 포함하는 CLAUDE.md 파일을 만들어 일반 표준을 불러올 수 있습니다.

@AGENTS.md

2. 심볼릭 링크(Symbolic Linking)

macOS 및 Linux 사용자들은 Claude Code가 AGENTS.md 파일을 마치 CLAUDE.md인 것처럼 읽을 수 있도록 심볼릭 링크를 생성할 수 있습니다.

ln -s AGENTS.md CLAUDE.md

3. 세션 훅(Session Hooks)을 통한 자동화

중첩된 디렉터리 전반에서 더 원활한 경험을 위해, 개발자들은 .claude/settings.json 훅을 사용하여 저장소 내의 모든 AGENTS.md 파일을 시작 시 세션 컨텍스트에 자동으로 주입할 수 있습니다.

설정 구성:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/append_agentsmd_context.sh"
          }
        ]
      }
    ]
  }
}

셸 스크립트 (append_agentsmd_context.sh):

#!/bin/bash
echo "=== AGENTS.md Files Found ==="
find "$CLAUDE_PROJECT_DIR" -name "AGENTS.md" -type f | while read -r file; do
    echo "--- File: $file ---"
    cat "$file"
    echo ""
done

개발자 관점의 종합

AGENTS.md에 대한 논쟁은 도구 전용 최적화와 생태계 상호운용성 사이의 근본적인 긴장 관계를 보여줍니다.

"명백한 이유는 그들이 모든 저장소에 CLAUDE.md 파일을 두는 것을 선호하기 때문일 것입니다... 이는 우리 시대의 'Sent from my iPhone'과 같습니다."

일부에서는 도구 전용 파일이 모델의 특정 특성에 맞게 지침을 더 잘 조정할 수 있게 해준다고 주장하지만, 파워 유저들 사이의 지배적인 의견은 대규모 조직이나 많은 오픈 소스 프로젝트에서 거의 동일한 파일을 여러 개 유지 관리해야 하는 오버헤드가 AI 코딩 에이전트 도입을 저해하는 상당한 마찰 지점이라는 것입니다.

Sources

관련