코덱스·클로드 코드 지침 공유: AGENTS.md 직접 로드와 import

코덱스와 클로드 코드를 번갈아 쓸 때 공통 규칙을 두 벌로 관리하면 수정 누락이 생기기 쉽습니다. 테스트 명령을 AGENTS.md에서만 고치고 CLAUDE.md에 남겨두면 한쪽은 새 명령을, 다른 쪽은 옛 명령을 따릅니다.

여기서 줄일 것은 파일 개수보다 같은 규칙을 두 번 고치는 일입니다. 공통 규칙의 원본을 AGENTS.md 한곳에 두고 두 도구가 읽게 만들 수 있습니다. 조건이 맞으면 클로드 코드도 이 파일을 직접 읽고, 기존 CLAUDE.md가 필요하면 그 안에서 공통 원본을 가져오는 방법도 있습니다. 파일이 두 개 남는다고 정리에 실패한 것은 아닙니다. 두 벌의 규칙과, 원본 하나에 붙은 도구별 지침은 다른 물건입니다.

CLI와 VS Code 확장의 버전을 따로 확인합니다

클로드 코드 사용방법을 설치 명령까지만 따라가면 놓치기 쉬운 부분이 있습니다. 터미널에 명령을 입력해 쓰는 CLI와 VS Code 확장 프로그램의 채팅 창은 같은 실행 파일을 쓰는 것이 아닙니다. 확장 프로그램에는 자체 CLI가 포함되어 있고, 터미널의 claude는 별도로 설치한 CLI입니다. 같은 VS Code 안에 나란히 떠 있어도 버전까지 한 몸은 아닙니다.

터미널은 claude --version으로 확인합니다. VS Code 확장 버전은 번들 Claude Code 버전에 해당하며, v2.1.280 이상에서는 확장 채팅의 /status에서도 확인할 수 있습니다. 터미널 CLI만 업데이트해도 확장에 자동으로 같은 기능이 생기는 것은 아니므로, 지침을 읽힐 그 실행 환경의 버전을 봐야 합니다.

클로드의 AGENTS.md 직접 로드 조건

클로드 코드는 v2.1.277부터 AGENTS.md를 직접 읽는 기능을 지원합니다. 코덱스는 AGENTS.md, 클로드는 무조건 CLAUDE.md이니 같은 내용을 두 파일에 적어야 한다는 설명은 이제 그대로 적용하기 어렵습니다. 프로젝트 공통 규칙을 루트의 AGENTS.md에 두고, 클로드 쪽의 직접 로드 조건까지 맞추면 같은 원본을 사용할 수 있습니다.

그런데 기본 동작은 “둘 다 있으면 사이좋게 합쳐 읽기”가 아닙니다. 현재 작업 폴더 또는 그 상위 경로에 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md 중 하나라도 있으면 AGENTS.md의 네이티브 탐색이 억제됩니다. 루트에 파일 두 개를 나란히 놓았다고 자동으로 합쳐지는 것이 아니며, 현재 폴더만 깨끗해도 상위 폴더의 지침이 걸릴 수 있습니다. 특히 개인용 메모를 남기려고 CLAUDE.local.md를 추가했다가 공통 AGENTS.md가 직접 로드되지 않는 상황은 제법 얄궂습니다. 내 취향 몇 줄 보태려다 팀 규칙을 놓치는 것입니다.

반대로 사용자 전역 지침인 ~/.claude/CLAUDE.md, 조직이 관리하는 CLAUDE.md, .claude/rules/의 규칙들은 이 억제 조건에 포함되지 않고 함께 로드됩니다. 따라서 “내 컴퓨터에 CLAUDE.md가 있으니 안 된다”까지 넓혀 생각할 필요는 없습니다. 같은 이름이어도 어디에 놓였고 어떤 범위의 지침인지가 중요합니다.

기존 파일을 유지하면서 둘 다 직접 읽게 하는 선택도 있습니다. /config의 Project instructions에서 기본값인 claude-md-or-agents-md 대신 claude-md-and-agents-md를 선택하는 방식입니다. 각 디렉터리에서 CLAUDE 계열 지침 뒤에 AGENTS 지침이 들어가며, import나 심볼릭 링크로 이미 읽은 AGENTS는 중복 로드하지 않습니다. claude-md는 CLAUDE 계열만 읽는 모드입니다. 설정 파일로 관리할 때는 사용자 설정, --settings로 지정한 파일 또는 관리 설정에서 적용되고, 프로젝트·로컬 설정 파일에 적은 값은 무시됩니다. 저장소에 설정 하나 넣어뒀다고 팀원 모두의 읽는 방식까지 통일되는 것은 아닙니다. 두 파일을 함께 읽게 했더라도 서로 모순되는 내용은 따로 정리해야 합니다.

버전 번호에도 덧붙일 조건이 있습니다. v2.1.277 이전에는 이 직접 읽기 기능이 없고, 내장 AGENTS 플러그인을 꺼둔 세션이나 v2.1.276 이하에서 업그레이드한 직후의 일부 첫 세션에서는 기능을 사용할 수 없습니다. v2.1.281 이전에는 Amazon Bedrock이나 텔레메트리를 끈 일부 환경에도 제약이 있었습니다. 이런 경우 /config에 Project instructions 항목 자체가 보이지 않을 수 있습니다. 그렇다고 지침 파일 하나 읽히자고 보안 설정이나 텔레메트리를 풀 일은 아닙니다. 실행 중인 버전과 새 세션을 먼저 확인하고, 직접 읽기 조건을 맞추기 어려운 환경에는 아래의 가져오기 방식이 남아 있습니다.

CLAUDE.md에서 공통 원본을 가져오는 방법

화면의 @ 참조는 현재 채팅에 파일이나 선택한 코드를 첨부하는 기능입니다. 반면 CLAUDE.md 안의 import는 지침 파일을 불러올 때 다른 파일 내용도 펼쳐 넣습니다. 다음 세션에도 프로젝트 규칙을 자동으로 읽히려는 용도에서 두 기능은 기호는 같아도 담당 업무가 다릅니다.

기존 CLAUDE.md에 클로드 전용 지침이 있거나, 팀원의 실행 환경이 제각각이라면 이 방식이 관리하기 편합니다. 프로젝트 루트의 AGENTS.md를 공통 규칙 원본으로 두고, 같은 폴더의 CLAUDE.md에 아래 한 줄을 독립된 줄로 넣습니다. 클로드 전용으로 남길 지침은 그 아래에 둡니다. 기존 파일을 통째로 덮어쓰는 작업이 아니라, 중복된 공통 내용과 도구별 내용을 나누는 작업입니다.

@AGENTS.md

실제 파일에 들어갈 것은 @AGENTS.md라는 한 줄이지, 이 글에서 예시를 감싼 코드 상자나 백틱까지가 아닙니다. 백틱이나 코드 블록 안에 넣으면 import로 해석되지 않습니다. “AGENTS.md를 읽어라”라는 일반 문장도 같은 기능은 아닙니다. 그때는 모델이 실제로 파일을 열기로 해야 내용이 전달됩니다. 상대 경로는 실행 폴더가 아니라 참조를 적은 지침 파일의 위치를 기준으로 하므로, .claude/CLAUDE.md에서 루트의 원본을 가리킬 때는 @../AGENTS.md가 됩니다. 작업 폴더 바깥의 파일을 가져오는 경우에는 외부 import 승인 조건도 따로 적용됩니다.

공통 규칙을 바꿀 때는 AGENTS.md 한곳을 고치면 됩니다. 다만 열린 대화에 실시간 반영되는 것은 아니므로 대상 작업 폴더에서 새 세션을 열어 확인합니다. 이름이 비슷한 /import는 다른 도구의 지침을 한 번 복사하는 이관 기능이며, 이후 두 파일을 계속 동기화하는 기능은 아닙니다.

심볼릭 링크로 두 이름이 같은 파일을 가리키게 하는 방법도 있습니다. 클로드 전용 내용을 따로 둘 필요가 없을 때는 선택지가 되지만, Windows에서는 링크 생성 권한이나 개발자 모드, Git의 core.symlinks 설정까지 영향을 줍니다. 다른 사람이 저장소를 받아 쓸 환경도 고려해야 하는 만큼, 이 글의 목적에는 @AGENTS.md 참조가 설명할 거리와 관리할 변수를 덜 늘리는 쪽입니다.

두 도구의 지침 탐색 경로와 우선순위

클로드 쪽 연결이 끝났다고 코덱스의 규칙도 한 가지로 단순해지는 것은 아닙니다. 코덱스는 실행을 시작할 때 지침 체인을 구성합니다. 먼저 CODEX_HOME이 가리키는 전역 위치, 기본값으로는 ~/.codex에서 AGENTS.override.md를 우선하고, 없거나 비어 있으면 AGENTS.md를 확인해 첫 번째 비어 있지 않은 파일을 사용합니다. 프로젝트 파일만 고쳤는데 다른 규칙이 계속 끼어든다면 모델 성격을 분석하기 전에 이 전역 지침부터 볼 이유가 있습니다.

프로젝트에서는 루트, 보통 Git 루트부터 현재 작업 폴더까지 내려오며 각 폴더의 AGENTS.override.md → AGENTS.md → 설정된 대체 파일명 순으로 찾고, 폴더마다 최대 하나를 읽습니다. 상위부터 이어 붙이며 현재 작업 폴더에 가까운 지침이 앞선 지침보다 우선합니다. 같은 폴더의 override와 일반 파일을 둘 다 읽어 섞는 방식은 아닙니다. 루트를 찾지 못하면 현재 폴더만 확인하고, 지침을 읽어 붙이는 크기에도 project_doc_max_bytes의 기본 32KiB 한도가 있습니다. 코덱스를 어느 폴더에서 시작했는지, 공통 파일보다 먼저 선택되는 파일이 있는지를 함께 봐야 합니다.

클로드의 네이티브 탐색은 또 다릅니다. 조건이 맞으면 현재 폴더와 상위 폴더의 AGENTS.md 및 .claude/AGENTS.md를 읽고, 하위 폴더에서는 Read 도구로 파일을 열 때 그 폴더에 앞서 말한 CLAUDE 계열 파일 세 가지가 없으면 해당 AGENTS.md를 추가로 읽습니다. 반면 AGENTS.override.md, AGENTS.local.md, .agents/ 아래의 파일은 이 자동 탐색 대상이 아닙니다. 그러니 코덱스용 override에 넣은 내용을 클로드도 알아서 읽으리라 기대할 수는 없습니다. 공통 원본을 루트의 AGENTS.md로 두자는 말은 이런 차이를 없앴다는 선언이 아니라, 두 도구가 공유할 내용을 두기 좋은 자리를 정하자는 뜻입니다.

로드 경로와 실제 작업 결과를 확인합니다

정리를 마친 뒤에는 실제 작업할 폴더에서 새 세션을 엽니다. 클로드의 CLAUDE.md 로드는 /context의 Memory files에서 확인하고, 네이티브 AGENTS는 시작할 때 나타나는 AGENTS.md loaded 메시지와 파일 경로를 살핍니다. v2.1.280 이상에서는 /memory에서도 AGENTS 경로를 확인할 수 있습니다. 그 이전 버전의 /memory나 /context에 네이티브 AGENTS가 나타나지 않았다는 이유만으로 로드 실패라고 단정해서는 안 됩니다. 반대로 목록에 경로가 보인다고 실제 작업까지 지침대로 끝났다는 뜻도 아닙니다.

코덱스에 활성 지침과 출처를 설명하게 한 뒤 실제 파일 내용과 전역·프로젝트 경로를 대조합니다. 로그를 남기는 환경에서는 codex-tui.log나 활성화된 세션 로깅의 session-*.jsonl에서 로드 기록도 확인할 수 있습니다. 지침을 바꿨다면 대상 폴더에서 다시 시작합니다. AI의 답만으로 확인을 끝내는 것은 작성자가 자기 검수란에도 도장을 찍는 셈입니다.

마지막 확인은 작게 합니다. 예를 들어 공통 지침에 검증 결과를 구분해 보고하도록 적어뒀다면, 작은 수정 하나를 맡겨 수행한 검증과 하지 못한 검증을 실제로 나눠 보고하는지 확인할 수 있습니다. 파일이 읽혔는지와 지침이 지켜졌는지는 별개이고, 작은 작업 한 번의 성공도 이후 모든 작업의 보증서는 아닙니다. 특히 지침 파일은 모델에게 주는 맥락이지 권한·보안 설정을 대신하는 장치가 아니므로, 변경 승인과 결과 검토는 그대로 남겨둡니다.

총평: 공통 규칙의 원본을 한곳에서 관리합니다

코덱스와 클로드 코드 때문에 같은 프로젝트 규칙을 두 번 수정할 필요는 없습니다. 직접 로드 조건이 맞는 환경에는 공통 AGENTS.md를 사용하고, 기존 클로드 지침이나 호환성을 챙겨야 하는 환경에는 CLAUDE.md의 @AGENTS.md 참조를 두면 됩니다. 둘 다 직접 읽는 모드를 선택할 때도 각자의 설정과 충돌 여부까지 확인합니다. 어느 쪽이든 목표는 공통 내용은 한 번만 고치고, 도구별 차이는 필요한 만큼만 남기는 것입니다.

고쳐야 할 공통 원본이 하나이고 두 도구가 실제로 읽는 것까지 확인했다면 관리 목적은 달성한 것입니다. 파일이 두 개 남아 있다는 이유만으로 기존 지침을 지울 필요는 없습니다. 줄이려는 것은 파일 탐색기의 줄 수보다 사람이 반복해서 고치는 일입니다.