쇼피파이가 Claude Code 사용 금지를 검토하는 이유는 CLAUDE.md라는 파일 이름 자체가 문제가 되어서가 아니다. 여러 AI 코딩 도구가 같은 코드 저장소를 함께 다루는 환경에서, 도구마다 서로 다른 지침 파일을 읽으면 운영 비용과 오류 가능성이 커지기 때문이다.

쇼피파이 CEO 토비 뤼트케는 2026년 8월 25일 Anthropic이 Claude Code를 바꿔 AGENTS.md와 .agents/skills 등을 읽기 전까지 사내 사용을 금지하는 방안을 검토 중이라고 밝혔다. 그는 Claude Code가 CLAUDE.md만 고집하면 팀원들이 서로 다른 도구를 사용할 때 ‘split brain’, 즉 같은 저장소를 두고 에이전트마다 서로 다른 규칙을 인식하는 문제가 생긴다고 지적했다. 415

쇼피파이가 문제 삼은 것은 무엇인가

AGENTS.md는 AI 코딩 에이전트에게 프로젝트별 맥락을 전달하는 일반적인 마크다운 파일이다. 빌드와 테스트 방법, 코딩 규칙, 디렉터리별 제한 사항, 기여 방식 등을 적어 저장소에 함께 보관한다. 개발자가 사용하는 도구가 바뀌더라도 지침이 코드와 함께 이동한다는 점이 핵심이다. 2931

반면 Claude Code의 공식 프로젝트 설정은 CLAUDE.md, .claude/rules, 프로젝트 스킬과 훅, 설정 파일 등을 중심으로 구성된다. Claude Code는 현재 작업 디렉터리와 상위 디렉터리에서 관련 파일을 찾아 읽는 방식으로 자체적인 지침 체계를 만든다. 2

개인 개발자라면 두 형식을 관리하는 일이 큰 부담이 아닐 수 있다. 하지만 수많은 팀이 하나의 대규모 모노레포를 공유하면서 Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot 등을 병행한다면 이야기가 달라진다.

한 도구는 AGENTS.md를 읽고 다른 도구는 CLAUDE.md만 읽는다면, 같은 디렉터리에서 다음과 같은 정보가 서로 다르게 전달될 수 있다.

• 어떤 명령어로 테스트를 실행해야 하는지
• 어떤 코딩 규칙을 따라야 하는지
• 특정 디렉터리를 수정해도 되는지
• 리뷰와 커밋 과정에서 지켜야 할 제한 사항이 무엇인지

이렇게 되면 에이전트마다 같은 프로젝트를 보고도 다른 판단을 내릴 수 있다. 뤼트케가 말한 ‘분리된 두뇌’ 문제다. 47

대규모 모노레포에서 중복 문서가 비용이 되는 이유

여러 에이전트를 사용하는 기업이 선택할 수 있는 방법은 대체로 다음과 같다.

• 저장소 루트에 AGENTS.md와 CLAUDE.md를 모두 둔다.
• 필요한 하위 디렉터리에도 두 파일을 반복해 배치한다.
• 코드베이스가 바뀔 때마다 두 파일을 동기화한다.
• 지침이 서로 달라졌는지 확인하는 검사 도구를 별도로 만든다.

문제는 단순히 문서가 두 개가 된다는 데 있지 않다. 한 에이전트는 새 테스트 명령을 따르고 다른 에이전트는 폐기된 명령을 사용할 수 있다. 한 에이전트는 특정 폴더를 수정하지 말라는 규칙을 읽지만 다른 에이전트는 그 제한을 보지 못할 수도 있다.

그 결과는 일관되지 않은 코드 수정, 리뷰 품질 저하, 예상 밖의 에이전트 동작으로 이어질 수 있다. 즉, 문서 관리에 드는 반복 작업이 일종의 ‘복잡성 세금’으로 바뀐다. 47

Claude Code의 공개 기능 요청도 이 문제를 직접 지적했다. 저장소에 이미 AGENTS.md가 있어도 Claude Code가 해당 내용을 무시하기 때문에, 개발자가 별도의 CLAUDE.md를 만들고 지침을 복사해야 한다는 내용이다. 12

AGENTS.md가 상호운용성 논쟁의 중심이 된 배경

AGENTS.md는 OpenAI의 Codex 생태계와 함께 알려지기 시작했지만, Google, OpenAI, Sourcegraph, Factory, Cursor 등이 참여한 업계 협력을 통해 확산된 개방형 관례다. 1931

2025년 12월 9일에는 OpenAI와 Anthropic이 AGENTS.md를 비롯한 에이전트 인프라를 리눅스 재단 산하의 Agentic AI Foundation에 기부했다. 이 재단의 목표는 특정 상용 도구 업체가 통제하는 대신, 개방적이고 상호운용 가능한 에이전트 기술을 중립적으로 관리하는 것이다. 2829

리눅스 재단에 따르면 AGENTS.md는 이미 6만 개가 넘는 오픈소스 프로젝트와 에이전트 프레임워크에 채택됐다. 여기에는 Codex, Cursor, Devin, Factory, Gemini CLI, GitHub Copilot, Jules, VS Code 등이 포함된다. 31

물론 이 수치가 AGENTS.md가 법적 또는 기술적으로 의무화된 표준이라는 뜻은 아니다. 다만 여러 도구가 함께 사용하는 저장소 지침을 한곳에 두는 실질적인 이식성 계층으로 자리 잡았다는 의미는 크다.

Claude Code의 대안과 한계

현재 알려진 우회 방법 중 하나는 CLAUDE.md에서 AGENTS.md를 불러오도록 설정하는 것이다. 심볼릭 링크나 별도의 설정 브리지로 두 파일을 연결하는 방법도 거론된다. 69

이런 방법은 당장의 호환성 문제를 줄일 수 있다. 그러나 네이티브 지원과 같은 경험을 제공하지는 않는다. 저장소마다 별도 설정이 필요하고, 가져오기 순서와 우선순위, 디렉터리 범위, 업데이트 방식을 조직이 직접 결정해야 하기 때문이다.

심볼릭 링크 역시 운영체제, Git 설정, IDE, 컨테이너 환경, 기업 보안 정책에 따라 다르게 작동할 수 있다. 결국 통합 작업의 부담이 도구 업체에서 각 기업과 개발자에게 넘어간다.

Anthropic 측 인사 타리크 셰이크는 공개 답변에서 Claude Code를 더 쉽게 수정할 수 있도록 만들고 있으며, 앞으로 AGENTS.md를 사용하거나 다른 시스템 프롬프트 설정을 바꾸기 쉽게 하겠다고 밝혔다. 15 다만 공개된 자료만으로는 Anthropic이 네이티브 지원을 추가하지 않은 확정적인 기술적·상업적 이유를 확인하기 어렵다. 따라서 회사의 의도를 단정하는 해석은 추측으로 봐야 한다.

Anthropic의 ‘표준’ 행보와 제품 설정 사이의 간극

이번 논쟁이 더욱 주목받는 이유는 Anthropic이 Agentic AI Foundation의 broader ecosystem, 즉 더 넓은 생태계와 연결돼 있기 때문이다. AGENTS.md가 리눅스 재단의 중립적 관리 아래 놓인 상황에서도 Claude Code의 공식 프로젝트 지침은 여전히 Anthropic 고유의 파일 형식을 중심으로 한다. 22829

이것이 곧 Anthropic이 개방형 표준에 반대한다는 뜻은 아니다. 한 업체가 공통 기반을 지원하면서도 자사 모델이나 제품에 특화된 기능을 위해 독점 확장 기능을 유지하는 것은 가능하다.

하지만 기업 고객의 관점에서는 공통 지침을 다른 도구가 사용하기 전에 다시 작성하거나 연결해야 한다면, 개방형 기반의 장점이 제한될 수밖에 없다.

이번 대치가 AI 개발 도구 시장에 미칠 영향

반복되는 ‘설정 비용’

도구마다 고유한 지침 체계를 만들면 중복 파일, 동기화 검사, 마이그레이션 스크립트, 테스트가 계속 필요해진다. 조직이 사용하는 코딩 에이전트가 늘어날수록 지원해야 할 도구와 저장소 범위도 함께 늘어난다.

벤더 종속성에 대한 압박

저장소 지침에는 팀의 개발 방식, 보안 경계, 업무 절차, 운영 지식이 담긴다. 이 지식이 특정 업체의 파일 형식에서만 제대로 작동한다면 도구를 교체하거나 여러 제품을 병행하기가 어려워진다. 공통 형식은 전환 비용을 낮추고 기업의 구매 협상력을 높인다.

공통 기반과 독점 확장의 결합

현실적인 타협점은 하나의 형식이 모든 독점 규칙을 대체하는 방식이 아닐 수 있다. AGENTS.md에는 여러 도구가 함께 사용할 수 있는 프로젝트 기본 지침을 담고, CLAUDE.md 같은 업체별 파일에는 특정 제품에만 필요한 선택적 확장 기능을 담는 ‘2단 구조’가 가능하다.

이 방식이라면 제품별 차별화는 유지하면서도 기본적인 프로젝트 맥락은 도구 간에 이동시킬 수 있다.

기업 고객이 표준을 결정할 가능성

뤼트케의 발언은 사소해 보이는 호환성 요청이 대기업의 제품 도입 조건으로 바뀔 수 있음을 보여준다. 쇼피파이 같은 고객이 여러 도구에서 동일한 지침을 읽을 수 있는지를 배포 요건으로 삼는다면, 업체들은 상호운용성을 단순한 커뮤니티 요구가 아니라 기업용 제품의 기본 조건으로 받아들여야 할 수 있다.

결론

쇼피파이가 Claude Code 금지를 거론한 이유는 CLAUDE.md가 본질적으로 AGENTS.md보다 열등해서가 아니다. 문제는 여러 개발자가 여러 AI 에이전트를 같은 코드베이스에서 사용할 때, 업체별 기본 형식이 중복 관리와 규칙 불일치를 만들어낸다는 점이다.

6만 개가 넘는 프로젝트의 채택, 리눅스 재단 산하의 관리, 주요 코딩 도구 전반의 지원은 AGENTS.md를 신뢰할 만한 공통 계층으로 만들고 있다. 2931 Claude Code의 가져오기 기능과 심볼릭 링크는 임시 해결책이 될 수 있지만, 통합 비용을 각 조직에 남긴다.

결국 이번 논쟁의 본질은 파일 확장자나 이름이 아니다. AI 코딩 에이전트가 서로 호환되는 개발 인프라로 발전할 것인지, 아니면 프로젝트 지식을 도구마다 다시 맞춰야 하는 폐쇄형 플랫폼으로 남을 것인지에 관한 문제다.

쇼피파이가 Claude Code 사용 금지를 검토하는 이유는 CLAUDE.md라는 파일 이름 자체가 문제가 되어서가 아니다. 여러 AI 코딩 도구가 같은 코드 저장소를 함께 다루는 환경에서, 도구마다 서로 다른 지침 파일을 읽으면 운영 비용과 오류 가능성이 커지기 때문이다.

쇼피파이 CEO 토비 뤼트케는 2026년 8월 25일 Anthropic이 Claude Code를 바꿔 AGENTS.md와 .agents/skills 등을 읽기 전까지 사내 사용을 금지하는 방안을 검토 중이라고 밝혔다. 그는 Claude Code가 CLAUDE.md만 고집하면 팀원들이 서로 다른 도구를 사용할 때 ‘split brain’, 즉 같은 저장소를 두고 에이전트마다 서로 다른 규칙을 인식하는 문제가 생긴다고 지적했다. 415

쇼피파이가 문제 삼은 것은 무엇인가

AGENTS.md는 AI 코딩 에이전트에게 프로젝트별 맥락을 전달하는 일반적인 마크다운 파일이다. 빌드와 테스트 방법, 코딩 규칙, 디렉터리별 제한 사항, 기여 방식 등을 적어 저장소에 함께 보관한다. 개발자가 사용하는 도구가 바뀌더라도 지침이 코드와 함께 이동한다는 점이 핵심이다. 2931

반면 Claude Code의 공식 프로젝트 설정은 CLAUDE.md, .claude/rules, 프로젝트 스킬과 훅, 설정 파일 등을 중심으로 구성된다. Claude Code는 현재 작업 디렉터리와 상위 디렉터리에서 관련 파일을 찾아 읽는 방식으로 자체적인 지침 체계를 만든다. 2

개인 개발자라면 두 형식을 관리하는 일이 큰 부담이 아닐 수 있다. 하지만 수많은 팀이 하나의 대규모 모노레포를 공유하면서 Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot 등을 병행한다면 이야기가 달라진다.

한 도구는 AGENTS.md를 읽고 다른 도구는 CLAUDE.md만 읽는다면, 같은 디렉터리에서 다음과 같은 정보가 서로 다르게 전달될 수 있다.

• 어떤 명령어로 테스트를 실행해야 하는지
• 어떤 코딩 규칙을 따라야 하는지
• 특정 디렉터리를 수정해도 되는지
• 리뷰와 커밋 과정에서 지켜야 할 제한 사항이 무엇인지

이렇게 되면 에이전트마다 같은 프로젝트를 보고도 다른 판단을 내릴 수 있다. 뤼트케가 말한 ‘분리된 두뇌’ 문제다. 47

대규모 모노레포에서 중복 문서가 비용이 되는 이유

여러 에이전트를 사용하는 기업이 선택할 수 있는 방법은 대체로 다음과 같다.

• 저장소 루트에 AGENTS.md와 CLAUDE.md를 모두 둔다.
• 필요한 하위 디렉터리에도 두 파일을 반복해 배치한다.
• 코드베이스가 바뀔 때마다 두 파일을 동기화한다.
• 지침이 서로 달라졌는지 확인하는 검사 도구를 별도로 만든다.

문제는 단순히 문서가 두 개가 된다는 데 있지 않다. 한 에이전트는 새 테스트 명령을 따르고 다른 에이전트는 폐기된 명령을 사용할 수 있다. 한 에이전트는 특정 폴더를 수정하지 말라는 규칙을 읽지만 다른 에이전트는 그 제한을 보지 못할 수도 있다.

그 결과는 일관되지 않은 코드 수정, 리뷰 품질 저하, 예상 밖의 에이전트 동작으로 이어질 수 있다. 즉, 문서 관리에 드는 반복 작업이 일종의 ‘복잡성 세금’으로 바뀐다. 47

Claude Code의 공개 기능 요청도 이 문제를 직접 지적했다. 저장소에 이미 AGENTS.md가 있어도 Claude Code가 해당 내용을 무시하기 때문에, 개발자가 별도의 CLAUDE.md를 만들고 지침을 복사해야 한다는 내용이다. 12

AGENTS.md가 상호운용성 논쟁의 중심이 된 배경

AGENTS.md는 OpenAI의 Codex 생태계와 함께 알려지기 시작했지만, Google, OpenAI, Sourcegraph, Factory, Cursor 등이 참여한 업계 협력을 통해 확산된 개방형 관례다. 1931

2025년 12월 9일에는 OpenAI와 Anthropic이 AGENTS.md를 비롯한 에이전트 인프라를 리눅스 재단 산하의 Agentic AI Foundation에 기부했다. 이 재단의 목표는 특정 상용 도구 업체가 통제하는 대신, 개방적이고 상호운용 가능한 에이전트 기술을 중립적으로 관리하는 것이다. 2829

리눅스 재단에 따르면 AGENTS.md는 이미 6만 개가 넘는 오픈소스 프로젝트와 에이전트 프레임워크에 채택됐다. 여기에는 Codex, Cursor, Devin, Factory, Gemini CLI, GitHub Copilot, Jules, VS Code 등이 포함된다. 31

물론 이 수치가 AGENTS.md가 법적 또는 기술적으로 의무화된 표준이라는 뜻은 아니다. 다만 여러 도구가 함께 사용하는 저장소 지침을 한곳에 두는 실질적인 이식성 계층으로 자리 잡았다는 의미는 크다.

Claude Code의 대안과 한계

현재 알려진 우회 방법 중 하나는 CLAUDE.md에서 AGENTS.md를 불러오도록 설정하는 것이다. 심볼릭 링크나 별도의 설정 브리지로 두 파일을 연결하는 방법도 거론된다. 69

이런 방법은 당장의 호환성 문제를 줄일 수 있다. 그러나 네이티브 지원과 같은 경험을 제공하지는 않는다. 저장소마다 별도 설정이 필요하고, 가져오기 순서와 우선순위, 디렉터리 범위, 업데이트 방식을 조직이 직접 결정해야 하기 때문이다.

심볼릭 링크 역시 운영체제, Git 설정, IDE, 컨테이너 환경, 기업 보안 정책에 따라 다르게 작동할 수 있다. 결국 통합 작업의 부담이 도구 업체에서 각 기업과 개발자에게 넘어간다.

Anthropic 측 인사 타리크 셰이크는 공개 답변에서 Claude Code를 더 쉽게 수정할 수 있도록 만들고 있으며, 앞으로 AGENTS.md를 사용하거나 다른 시스템 프롬프트 설정을 바꾸기 쉽게 하겠다고 밝혔다. 15 다만 공개된 자료만으로는 Anthropic이 네이티브 지원을 추가하지 않은 확정적인 기술적·상업적 이유를 확인하기 어렵다. 따라서 회사의 의도를 단정하는 해석은 추측으로 봐야 한다.

Anthropic의 ‘표준’ 행보와 제품 설정 사이의 간극

이번 논쟁이 더욱 주목받는 이유는 Anthropic이 Agentic AI Foundation의 broader ecosystem, 즉 더 넓은 생태계와 연결돼 있기 때문이다. AGENTS.md가 리눅스 재단의 중립적 관리 아래 놓인 상황에서도 Claude Code의 공식 프로젝트 지침은 여전히 Anthropic 고유의 파일 형식을 중심으로 한다. 22829

이것이 곧 Anthropic이 개방형 표준에 반대한다는 뜻은 아니다. 한 업체가 공통 기반을 지원하면서도 자사 모델이나 제품에 특화된 기능을 위해 독점 확장 기능을 유지하는 것은 가능하다.

하지만 기업 고객의 관점에서는 공통 지침을 다른 도구가 사용하기 전에 다시 작성하거나 연결해야 한다면, 개방형 기반의 장점이 제한될 수밖에 없다.

이번 대치가 AI 개발 도구 시장에 미칠 영향

반복되는 ‘설정 비용’

도구마다 고유한 지침 체계를 만들면 중복 파일, 동기화 검사, 마이그레이션 스크립트, 테스트가 계속 필요해진다. 조직이 사용하는 코딩 에이전트가 늘어날수록 지원해야 할 도구와 저장소 범위도 함께 늘어난다.

벤더 종속성에 대한 압박

저장소 지침에는 팀의 개발 방식, 보안 경계, 업무 절차, 운영 지식이 담긴다. 이 지식이 특정 업체의 파일 형식에서만 제대로 작동한다면 도구를 교체하거나 여러 제품을 병행하기가 어려워진다. 공통 형식은 전환 비용을 낮추고 기업의 구매 협상력을 높인다.

공통 기반과 독점 확장의 결합

현실적인 타협점은 하나의 형식이 모든 독점 규칙을 대체하는 방식이 아닐 수 있다. AGENTS.md에는 여러 도구가 함께 사용할 수 있는 프로젝트 기본 지침을 담고, CLAUDE.md 같은 업체별 파일에는 특정 제품에만 필요한 선택적 확장 기능을 담는 ‘2단 구조’가 가능하다.

이 방식이라면 제품별 차별화는 유지하면서도 기본적인 프로젝트 맥락은 도구 간에 이동시킬 수 있다.

기업 고객이 표준을 결정할 가능성

뤼트케의 발언은 사소해 보이는 호환성 요청이 대기업의 제품 도입 조건으로 바뀔 수 있음을 보여준다. 쇼피파이 같은 고객이 여러 도구에서 동일한 지침을 읽을 수 있는지를 배포 요건으로 삼는다면, 업체들은 상호운용성을 단순한 커뮤니티 요구가 아니라 기업용 제품의 기본 조건으로 받아들여야 할 수 있다.

결론

쇼피파이가 Claude Code 금지를 거론한 이유는 CLAUDE.md가 본질적으로 AGENTS.md보다 열등해서가 아니다. 문제는 여러 개발자가 여러 AI 에이전트를 같은 코드베이스에서 사용할 때, 업체별 기본 형식이 중복 관리와 규칙 불일치를 만들어낸다는 점이다.

6만 개가 넘는 프로젝트의 채택, 리눅스 재단 산하의 관리, 주요 코딩 도구 전반의 지원은 AGENTS.md를 신뢰할 만한 공통 계층으로 만들고 있다. 2931 Claude Code의 가져오기 기능과 심볼릭 링크는 임시 해결책이 될 수 있지만, 통합 비용을 각 조직에 남긴다.

결국 이번 논쟁의 본질은 파일 확장자나 이름이 아니다. AI 코딩 에이전트가 서로 호환되는 개발 인프라로 발전할 것인지, 아니면 프로젝트 지식을 도구마다 다시 맞춰야 하는 폐쇄형 플랫폼으로 남을 것인지에 관한 문제다.