AI 도구를 두 개 쓰는 회사는 지침 파일도 두 벌이었습니다

금요일에 「고객 이름은 파일에 남기지 말 것」이라는 규칙을 CLAUDE.md에 추가했다고 해 보겠습니다.
월요일에 Codex로 돌린 작업에는 이 규칙이 적용되지 않습니다.

Codex는 그 파일을 읽지 않기 때문입니다.
Codex가 읽는 규칙 파일은 AGENTS.md이고, 그쪽은 아무도 고치지 않았습니다.

9월 19일 새벽 1시 22분(한국 시간) 공개된 Claude Code 2.1.277에 이 간극을 좁히는 항목이 들어갔습니다.
이 글은 그 한 줄을 대표가 확인할 세 칸으로 옮깁니다.

AI 코딩 도구는 작업을 시작할 때 프로젝트 폴더의 규칙 파일부터 읽습니다.
문제는 도구마다 읽는 파일 이름이 달랐다는 점입니다.

Claude Code는 CLAUDE.md를, Codex는 AGENTS.md를 읽습니다.
두 도구를 같이 쓰는 팀은 같은 규칙을 두 번 적어야 했습니다.

상담에서도 도구를 섞어 쓰는 구성을 먼저 물어 오시는 경우가 있습니다.
두 명이 여러 사업을 돌리는 이커머스 대표님의 질문이었습니다.

도구를 섞는 것 자체는 문제가 아닙니다.
도구마다 규칙 파일이 따로 있으면, 규칙을 고칠 때마다 사람이 두 곳을 챙겨야 한다는 점이 문제입니다.

사람은 한 곳만 고칩니다. 그 순간부터 두 AI는 서로 다른 회사 규칙으로 일합니다.

2.1.277 변경 기록 원문은 이렇습니다.
"Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead".

프로젝트에 CLAUDE.md가 없고 AGENTS.md만 있으면, Claude Code가 그 파일을 규칙으로 읽는다는 뜻입니다.
Codex는 원래 작업 전에 AGENTS.md를 읽으니, 이제 두 도구가 같은 파일 하나를 봅니다.

공식 문서에는 제대로 읽혔는지 확인하는 방법도 적혀 있습니다.
대화 화면에 「no CLAUDE.md found; AGENTS.md loaded」로 시작하는 줄이 뜹니다.

다만 이렇게 읽힌 AGENTS.md는 /memory 목록에 나오지 않습니다.
목록에 없다고 안 읽힌 것은 아니니, 확인은 그 한 줄로 합니다.

읽는 방식은 /config의 「Project instructions」에서 바꿉니다.
기본값 외에 두 파일을 함께 읽기, CLAUDE.md만 읽기, 회사가 관리하는 규칙만 읽기 중에서 고릅니다.

이번 판이 바꾼 것은 같은 파일을 읽을 수 있게 된 것까지입니다.

여기서 대표가 정해야 할 것이 생깁니다.
폴더에 CLAUDE.md와 AGENTS.md가 둘 다 있으면, 기본 설정의 Claude Code는 CLAUDE.md만 읽습니다.

이미 두 벌을 따로 관리해 온 팀이라면 업데이트 뒤에도 달라지는 게 없습니다.
AGENTS.md에만 넣은 규칙은 여전히 Claude Code에 닿지 않습니다.

정본을 한 파일로 모으는 길은 두 가지입니다.
하나는 CLAUDE.md를 지우고 AGENTS.md만 남기는 것입니다.

다른 하나는 CLAUDE.md 맨 위에 「@AGENTS.md」 한 줄을 넣어 AGENTS.md를 불러오고, Claude에만 필요한 규칙을 그 아래에 적는 것입니다.
공식 문서가 다른 코딩 도구와 파일 하나를 나눠 쓰는 방법으로 안내하는 방식입니다.

함정도 하나 있습니다.
개인 메모용 CLAUDE.local.md를 하나 만들면 그것도 CLAUDE.md로 쳐서, 그 사람의 Claude Code는 AGENTS.md를 읽지 않게 됩니다.

상담에서 「md 파일을 어디에 두느냐」는 질문을 받으면 저희도 위치부터 답합니다.
규칙은 어디에 몇 개 있는지가 내용만큼 중요하기 때문입니다.

합치는 일의 핵심은 파일 개수가 아니라 고치는 자리를 한 곳으로 정하는 것입니다.

변경 기록 원문 끝에는 괄호가 붙어 있습니다.
"not yet on Bedrock, Vertex or Foundry".

AWS Bedrock, Google Vertex, Microsoft Foundry처럼 클라우드 회사를 거쳐 Claude를 쓰는 환경에서는 아직 AGENTS.md를 직접 읽지 않는다는 뜻입니다.
회사 보안 정책 때문에 이 경로를 쓰는 팀이 적지 않습니다.

공식 문서는 조건을 더 적어 둡니다.
원격 측정(telemetry)을 끈 경우와 설치·업데이트 직후 첫 세션도 CLAUDE.md만 읽습니다.

이런 환경에서는 AGENTS.md를 정본으로 두고, CLAUDE.md에 「@AGENTS.md」 한 줄만 넣어 불러오게 하면 됩니다.
어느 환경에서 열어도 같은 규칙이 읽힙니다.

같은 판에는 보조 변화도 두 가지 있습니다.
프롬프트 속 보이지 않는 유니코드 문자를 지우고 보여 준 뒤 보내며, 하위 에이전트 결과는 별도 머리말을 붙여 세션의 지시로 오인되지 않게 합니다.

회사의 AI 접속 경로에 따라 같은 파일이 읽히기도, 안 읽히기도 합니다.

버전만 올린다고 규칙이 하나로 합쳐지지 않습니다.
이번 판을 우리 회사 말로 옮기면 물어볼 칸이 세 개 남습니다.

한 칸은 개수입니다. 우리 회사 AI 업무 규칙이 CLAUDE.md, AGENTS.md, 개인 메모 파일까지 몇 벌로 흩어져 있는지 셉니다.

다음 칸은 정본입니다. 둘 다 있으면 CLAUDE.md가 우선이니, 어느 파일을 고치는 자리로 둘지 정하고 나머지는 지우거나 불러오게 바꿉니다.

마지막 칸은 환경입니다. Bedrock, Vertex, Foundry를 거쳐 쓰는 팀이 있는지 확인하고, 있으면 불러오기 한 줄을 남겨 둡니다.

세 칸이 채워지면 규칙을 고칠 때 한 파일만 고치면 두 AI가 같이 바뀝니다.

정리

경고 신호

• 같은 규칙을 CLAUDE.md와 AGENTS.md에 손으로 복사해 둔다

• 두 파일이 다 있는데 어느 쪽이 우선인지 아무도 모른다

• 클라우드 경유 환경에서도 AGENTS.md가 읽힐 거라고 짐작한다

좋은 신호

• 회사 AI 업무 규칙을 고치는 파일이 하나로 정해져 있다

• CLAUDE.md는 비었거나 「@AGENTS.md」 한 줄로 정본을 불러온다

• 대화창의 「AGENTS.md loaded」 줄로 실제로 읽혔는지 확인한다

AI 도구 규칙을 하나로 합치기 전에 확인할 네 가지

1. 우리 폴더에 규칙 파일이 몇 개 있습니까?
   CLAUDE.md, AGENTS.md, CLAUDE.local.md를 모두 셉니다.

2. 둘 다 있다면 어느 쪽이 정본입니까?
   기본 설정에서는 CLAUDE.md가 있으면 AGENTS.md를 읽지 않습니다.

3. Claude Code는 2.1.277 이상입니까?
   그 전 버전은 AGENTS.md를 직접 읽지 않습니다.

4. 클라우드 경유로 쓰는 팀이 있습니까?
   Bedrock, Vertex, Foundry에서는 아직 지원되지 않아 불러오기 한 줄이 필요합니다.

함께 읽기

• 회사 규칙을 AI가 매번 지키게 만드는 방법: https://agenticworkflows.club/blog/claude-skills-company-rules

• ChatGPT와 Claude, 회사에서 어떻게 나눠 쓰나: https://agenticworkflows.club/blog/chatgpt-vs-claude

자주 묻는 질문

Q. Claude Code와 Codex가 같은 업무 지침을 읽게 하려면 어떻게 합니까?

Claude Code 2.1.277부터 CLAUDE.md가 없는 프로젝트에서는 AGENTS.md를 대신 읽습니다. Codex도 AGENTS.md를 읽으므로 규칙을 AGENTS.md 한 파일에 두면 두 도구가 같은 규칙으로 일합니다.

Q. CLAUDE.md와 AGENTS.md가 둘 다 있으면 어느 쪽을 읽습니까?

기본 설정에서는 CLAUDE.md만 읽습니다. AGENTS.md도 읽게 하려면 CLAUDE.md에 @AGENTS.md 한 줄을 넣거나, /config의 Project instructions를 두 파일 함께 읽기로 바꿉니다.

Q. AGENTS.md가 제대로 읽혔는지 어떻게 확인합니까?

대화 화면에 no CLAUDE.md found; AGENTS.md loaded로 시작하는 줄이 뜹니다. 이렇게 읽힌 AGENTS.md는 /memory 목록에는 나오지 않으니 그 줄이나 Claude에게 현재 프로젝트 규칙을 물어 확인합니다.

Q. Bedrock이나 Vertex를 거쳐 쓰는 회사도 바로 됩니까?

아직 안 됩니다. 변경 기록에 Bedrock, Vertex, Foundry는 아직 지원하지 않는다고 적혀 있습니다. 이 환경에서는 CLAUDE.md에 @AGENTS.md 한 줄을 넣어 같은 파일을 불러오게 합니다.

Q. 개인 메모용 CLAUDE.local.md를 만들어도 괜찮습니까?

만들면 기본 설정에서는 그 사람의 Claude Code가 AGENTS.md를 읽지 않습니다. 개인 메모를 유지하려면 Project instructions를 두 파일 함께 읽기로 바꿉니다.