클로드 코드 코덱스 연결: 규칙 파일과 작업 분담 정리

클로드 코드 코덱스 연결은 두 도구가 한 저장소에서 같은 규칙 파일을 읽고 서로의 수정을 덮어쓰지 않게 맞추는 작업입니다. 둘을 하나로 합치는 이야기가 아니라, 따로 도는 두 프로그램이 같은 폴더에서 부딪히지 않게 정리하는 이야기입니다.

두 도구를 다 설치해 둔 분이 많습니다. 설치 자체는 어렵지 않고, 각각에 어떻게 일을 맡기는지도 몇 번 써 보면 손에 잡힙니다.

정리가 덜 된 것은 그다음부터입니다. 두 도구가 찾아 읽는 규칙 파일은 이름이 서로 다릅니다. 같은 폴더에서 동시에 돌렸을 때 무슨 일이 생기는지도 설명이 흩어져 있습니다. 이대로 두 도구를 같이 쓰면 공들여 적어 둔 규칙이 한쪽에만 적용되거나, 두 도구가 같은 파일을 번갈아 고쳐서 방금 끝낸 작업이 사라집니다. 아래 내용은 2026년 9월 15일에 앤트로픽과 오픈AI 공식 문서, AGENTS.md 공식 사이트에서 확인했고, 명령과 옵션은 이후 바뀔 여지가 있습니다.

위 화면은 클로드 코드 공식 문서의 AGENTS.md 절입니다. 첫 문장이 "Claude Code reads CLAUDE.md, not AGENTS.md"입니다. 두 도구를 같이 쓸 때 부딪히는 첫 번째 문제가 이 한 문장에 있습니다.

두 도구가 읽는 규칙 파일 이름이 서로 다릅니다

주방 벽에 요리사마다 이름표를 붙인 조리 규칙 종이가 걸려 있고 각자 자기 이름표가 붙은 종이만 읽듯, 두 도구도 각자 정해진 파일 이름만 찾아 읽습니다.

클로드 코드가 찾는 이름은 CLAUDE.md입니다. 이 파일을 저장소 루트나 .claude/CLAUDE.md에 두면 클로드 코드가 세션을 시작할 때마다 읽습니다. 앤트로픽 공식 문서에는 클로드 코드가 AGENTS.md를 읽지 않는다고 분명히 적혀 있습니다.

코덱스가 찾는 이름은 AGENTS.md입니다. AGENTS.md는 코덱스 전용이 아니라 여러 도구가 함께 쓰기로 한 공개 형식입니다. 공식 사이트 기준으로 6만 개가 넘는 오픈소스 프로젝트가 쓰고 있고, 지금은 리눅스 재단 산하 Agentic AI Foundation이 형식을 관리합니다.

위 화면은 코덱스 공식 문서의 AGENTS.md 페이지입니다. 코덱스는 실행할 때마다 규칙을 세 단계로 모읍니다. 먼저 코덱스 홈 폴더(기본값 ~/.codex)에서 한 개를 읽고, 다음으로 프로젝트 루트에서 현재 폴더까지 내려오며 폴더마다 한 개씩 읽고, 마지막으로 루트 쪽부터 차례로 이어 붙입니다. 뒤에 붙은 파일이 앞의 내용을 덮으므로 현재 폴더에 가까운 규칙이 우선합니다.

두 도구의 파일 구성을 나란히 놓으면 이렇게 짝이 지어집니다.

공용 규칙을 덮어쓰는 파일도 양쪽에 다 있습니다. 클로드 코드는 같은 폴더의 CLAUDE.md 뒤에 CLAUDE.local.md를 이어 읽고, 코덱스는 AGENTS.override.md가 있으면 그 폴더에서 그 파일만 씁니다. 앤트로픽은 CLAUDE.local.md를 개인 설정용으로 두고 .gitignore에 넣으라고 안내합니다. 코덱스 쪽 AGENTS.override.md는 기본 파일을 지우지 않고 잠시 덮어쓰는 용도라서, 개인 설정으로 쓸지 하위 폴더 규칙으로 쓸지는 팀에서 정하면 됩니다.

분량 안내는 기준이 서로 다릅니다. 앤트로픽은 파일 하나를 200줄 이내로 유지하라고 권합니다. 오픈AI는 모아 읽은 파일의 합계가 project_doc_max_bytes 한도인 32KiB에 닿으면 그 뒤 파일은 더 싣지 않는다고 밝히고 있습니다. 앤트로픽 쪽은 권고이고 코덱스 쪽은 실제로 걸리는 한도라서, 코덱스를 함께 쓴다면 합계 용량을 한 번은 확인해 보는 편이 안전합니다. CLAUDE.md 분량을 줄이는 방법은 CLAUDE.md 세팅 정리 (권장 길이와 옮겨 둘 곳 바로가기)에 따로 적어 두었습니다.

규칙을 한 벌로 묶는 두 가지 방법

같은 규칙을 두 파일에 복사해 두면 한쪽만 고치는 날이 반드시 옵니다. 종이를 두 장 붙여 놓고 한 장만 고치면 요리사 둘이 서로 다른 규칙을 따르게 됩니다. 규칙 파일도 원본을 하나만 두고 나머지는 그 원본을 가리키게 만드는 편이 낫습니다.

앤트로픽 공식 문서가 안내하는 방법은 두 가지입니다.

• 불러오기: AGENTS.md에 규칙을 적고, CLAUDE.md에는 @AGENTS.md 한 줄만 적습니다. 클로드 코드가 세션을 시작할 때 그 파일 내용을 그대로 가져와 읽고, 아래에 적은 클로드 코드 전용 지시를 이어서 읽습니다.
• 심볼릭 링크: ln -s AGENTS.md CLAUDE.md로 같은 파일에 이름만 하나 더 붙여 둡니다. 두 이름이 같은 파일을 가리키므로 내용이 어긋날 일이 없습니다.

둘 중 무엇을 고를지는 아래 세 가지를 보고 정합니다.

윈도우를 함께 쓰는 팀이라면 불러오기 쪽이 무난합니다. 앤트로픽 문서도 윈도우에서는 심볼릭 링크 대신 @AGENTS.md 불러오기를 쓰라고 안내합니다.

불러오기든 심볼릭 링크든 걸어 두었다면 실제로 적용됐는지 확인해야 합니다. 클로드 코드 세션에서 /context를 치면 Memory files 항목에 그때 읽은 파일 목록이 나옵니다. 코덱스 쪽은 저장소 루트에서 codex --ask-for-approval never "Summarize the current instructions."처럼 지금 적용된 규칙을 요약해 달라고 시키면 어느 파일을 읽었는지가 답에 그대로 적힙니다.

이미 한쪽 설정을 길게 쌓아 두었다면 옮기는 명령부터 써 보는 방법도 있습니다. 두 도구 모두 /import라는 같은 이름의 명령이 있는데 넘어가는 항목은 서로 다릅니다. 무엇이 넘어가고 무엇이 남는지는 코덱스와 클로드 코드 설정 이전 (넘어가는 항목 표 바로가기)에 정리해 두었습니다.

실제로 쓰고 있는 구성

준이아빠블로그를 운영하며 쓰는 저장소 두 곳의 구성을 그대로 적어 둡니다. 업무용 저장소 쪽은 앞에서 정리한 두 가지 방법 가운데 불러오기를 그대로 씁니다. 루트 CLAUDE.md는 326바이트짜리 짧은 파일입니다. 아래가 그 앞부분입니다.

이 네 줄 아래에는 사용법을 안내하는 문단 하나가 붙어 있고, 파일은 그것으로 끝납니다. 실제 규칙은 AGENTS.md(약 6.9KB)와 harness/CONTRACT.md(약 3.7KB)에 나눠 적어 두었습니다. 코덱스는 AGENTS.md를 직접 읽고 그 안의 안내를 따라 CONTRACT.md를 엽니다. 클로드 코드는 CLAUDE.md에 적은 불러오기 두 줄 덕분에 세션을 시작하면서 같은 두 파일을 함께 읽습니다. 규칙을 고칠 때는 AGENTS.md만 고치면 두 도구에 같이 반영됩니다.

블로그 저장소는 아직 옛 구성입니다. CLAUDE.md가 212줄이고 명령과 검사 규칙이 전부 그 안에 있으며, AGENTS.md는 13줄뿐이고, 두 도구가 공통으로 지킬 항목과 "CLAUDE.md를 함께 읽는다"는 한 줄만 들어 있습니다. 코덱스가 그 문장을 보고 파일을 여는 식이라, 규칙이 불러오기만큼 확실하게 반영되지는 않습니다. 새로 만드는 저장소라면 처음부터 AGENTS.md를 본체로 두고 CLAUDE.md에 불러오기 한 줄만 적는 쪽을 권합니다.

클로드 코드와 코덱스에 어떤 일을 나눠 맡기면 좋을까요?

규칙을 묶고 나면 남는 질문은 분담입니다. 같은 일을 두 번 시킬 이유는 없으니, 결과가 눈에 띄게 달라지는 작업을 기준으로 나눠 두면 고민이 줄어듭니다.

아래 표는 준이아빠블로그에서 두 도구를 함께 쓰며 정리한 기준이고, 공식 성능 지표가 아니라 사용 기록에 바탕을 둔 판단입니다.

표의 첫 두 항목은 직접 재 본 결과입니다. 같은 규격서를 둘에 주고 같은 프로그램을 만들게 했더니 코덱스는 65초에 90줄로, 클로드 코드는 113초에 236줄로 끝냈습니다. 클로드 코드 쪽은 규격서에 없던 입력 형태와 예외 처리까지 스스로 넣었습니다. 다만 그때 두 도구가 쓴 모델의 급이 달랐으므로 속도만으로 우열을 가리기는 어렵습니다. 측정 조건과 전체 결과는 코덱스 CLI와 클로드 코드 비교 (같은 규격서로 잰 결과 바로가기)에 있습니다.

표의 마지막 두 항목이 두 도구를 같이 쓰는 현실적인 이유라고 봅니다. 구독 하나만 쓰면 남은 한도가 한 곳에서만 줄지만, 두 회사로 나누면 한쪽이 막혀도 작업이 멈추지 않습니다. 여러 도구를 한 화면에 띄워 같은 지시를 동시에 보내는 방법은 Orca 사용법 총정리 (여러 코딩 AI를 동시에 돌리는 방법 바로가기)에 따로 적어 두었습니다.

같은 폴더에서 부딪히지 않게 쓰는 세 가지 방법

분담을 정해도 두 도구의 작업 폴더가 같으면 문제가 남습니다. 도마 하나에 두 사람이 붙어 동시에 썰면 앞사람이 손질해 둔 재료를 뒷사람이 쓸어 내듯, 한 폴더에서 두 도구가 동시에 파일을 고치면 나중에 저장한 쪽이 앞의 수정을 지웁니다. 막는 방법은 세 가지이고 뒤로 갈수록 확실합니다.

첫째, 순서대로 돌립니다. 하나가 끝난 뒤에 다른 하나를 켭니다. 가장 단순하고 설정할 것이 없어서, 하루에 몇 번 쓰지 않는다면 이 방법으로 충분합니다.

둘째, 파일 경계를 규칙 파일에 적어 둡니다. 어느 폴더를 누가 고치는지 AGENTS.md에 한 줄로 적어 두면 두 도구가 같은 문장을 읽습니다. 다만 규칙 파일은 지시이지 잠금장치가 아니라서, 앤트로픽 문서도 반드시 막아야 하는 동작은 훅(정해진 시점에 자동으로 실행되는 짧은 명령)으로 처리하라고 안내합니다.

셋째, 작업 폴더를 아예 나눕니다. git worktree는 같은 저장소 기록을 공유하면서 파일과 브랜치만 따로 두는 폴더입니다. 도마를 하나 더 꺼내 놓는 것과 같아서, 한쪽이 무엇을 고치든 다른 쪽 파일에는 닿지 않습니다.

클로드 코드에는 이 폴더를 만들어 주는 옵션이 있습니다. --worktree나 -w에 이름을 붙이면 저장소 루트의 .claude/worktrees/이름/에 폴더가 생기고 worktree-이름 브랜치에서 세션이 시작됩니다. 격리된 동안에는 원래 폴더의 파일을 고치거나 그 안에서 명령을 실행하는 일이 막힙니다.

작업이 끝나면 두 브랜치를 차례로 병합합니다. 먼저 끝난 쪽을 먼저 병합해야 하는 것은 아닙니다. 다른 쪽이 맞춰 와야 할 변경이 많은 브랜치를 먼저 넣고, 나머지를 그 위에 다시 맞추는 편이 수월합니다. 새로 만든 폴더에는 .env 같은 파일이 따라오지 않으므로, 클로드 코드 쪽은 저장소 루트에 .worktreeinclude를 두어 복사할 파일을 적어 둡니다. 여기에 적더라도 실제로 복사되는 것은 .gitignore에 걸린 파일뿐입니다.

자주 묻는 질문

두 도구를 같은 컴퓨터에 설치해도 되나요?

됩니다. 명령 이름이 claude와 codex로 달라 서로 부딪히지 않고, 설정 폴더도 ~/.claude와 ~/.codex로 나뉘어 있습니다. 조심할 것은 설치가 아니라 같은 폴더에서 동시에 돌리는 경우입니다. 설치 순서는 클로드 코드 맥 설치 (설치 순서 바로가기)와 코덱스 CLI 맥 설치 (설치 순서 바로가기)에 각각 적어 두었습니다.

CLAUDE.md와 AGENTS.md를 둘 다 만들면 규칙이 두 번 실리나요?

불러오기로 묶으면 그렇지 않습니다. 기본 설정에서 코덱스는 폴더마다 AGENTS.override.md와 AGENTS.md만 찾고 CLAUDE.md는 아예 보지 않으므로, CLAUDE.md에 @AGENTS.md 한 줄만 두면 코덱스 쪽에는 원본 하나만 올라갑니다. 클로드 코드 쪽에서도 같은 파일을 한 번만 읽습니다. 규칙 본문을 두 파일에 복사해 둔 경우에만 중복이 생깁니다.

규칙 파일이 길어지면 어떻게 되나요?

앤트로픽은 파일 하나를 200줄 이내로 두라고 권하고, 클로드 코드는 4MiB를 넘는 파일을 건너뜁니다. 코덱스는 모아 읽은 파일의 합계가 32KiB에 닿으면 그 뒤 파일은 더 싣지 않습니다. 길어졌다면 클로드 코드는 .claude/rules/에 주제별로 나눠 두고 paths로 적용 범위를 좁히고, 코덱스는 규칙을 해당 하위 폴더의 AGENTS.md로 내려 두면 됩니다. 2026년 9월 15일 기준 한도이며 이후 바뀔 여지가 있습니다.

3줄 요약

1. 클로드 코드는 CLAUDE.md를 읽고 코덱스는 AGENTS.md를 읽습니다. 클로드 코드는 AGENTS.md를 직접 읽지 않습니다.
2. 규칙을 원본 하나로 두려면 CLAUDE.md 첫 줄에 @AGENTS.md를 적거나 심볼릭 링크를 겁니다. 제대로 적용됐는지는 /context의 Memory files에서 확인합니다.
3. 같은 폴더에서 동시에 돌리면 같은 파일을 서로 덮어씁니다. 순서대로 돌리거나 git worktree로 작업 폴더를 나눕니다.

Sources

• Claude Code 메모리와 CLAUDE.md 문서
• Claude Code 워크트리 병렬 세션 문서
• Codex AGENTS.md 문서
• Codex 개발자 명령과 전역 옵션 문서
• AGENTS.md 공식 사이트