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

이 글에서 말하는 연결은 Claude Code와 Codex가 같은 작업 폴더와 같은 규칙 파일을 쓰도록 맞추는 것입니다. 두 계정을 합치거나 대화 기록을 옮기는 기능이 아니라, 한 도구가 고친 파일을 다른 도구가 읽고 이어서 작업하는 방식입니다.

두 도구의 설치와 로그인을 마친 분을 기준으로 씁니다. 설치가 아직이라면 Claude Code 맥 설치와 Codex CLI 맥 설치에서 먼저 설치합니다. 아래 내용은 2026년 10월 4일 공식 문서 기준입니다.

두 도구가 규칙 파일을 읽는 방식

두 도구가 함께 지킬 규칙은 AGENTS.md 한 파일에 적습니다. 이 파일은 AI에게 작업 방법을 알려 주는 글이고, 파일 수정을 막는 잠금장치는 아닙니다. 두 도구가 이 파일을 찾고 읽는 방식은 조금씩 다릅니다.

Claude Code와 Codex의 규칙 파일 읽기

항목	Claude Code	Codex
AGENTS.md 직접 읽기	v2.1.277부터 CLAUDE.md가 없을 때	제공
CLAUDE.md 읽기	제공	제공하지 않음
다른 파일 불러오기	@AGENTS.md 줄	–
같은 폴더의 우선 파일	–	AGENTS.override.md
길이 기준	파일당 200줄 권장 4MiB 넘으면 건너뜀	합계 기본 32KiB

Claude Code는 기본 설정에서 현재 폴더와 상위 폴더에 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 하나도 없을 때 AGENTS.md를 읽습니다. 사용자 공통 파일인 ~/.claude/CLAUDE.md는 이 판단에 들어가지 않습니다. AGENTS.md 직접 지원은 v2.1.277에 들어왔고, 일부 연결 환경의 제한은 v2.1.281에서 풀렸습니다. 버전과 설정별 차이는 AGENTS.md 지원 정리에 있습니다.

Codex는 사용자 설정 폴더의 규칙을 먼저 읽고, 프로젝트 루트부터 현재 폴더까지 내려오며 규칙을 모읍니다. 같은 폴더에 AGENTS.override.md와 AGENTS.md가 함께 있으면 override 파일만 읽고 둘을 합치지 않습니다. 프로젝트 규칙 합계 한도는 기본 32KiB이고 설정으로 바꿀 수 있습니다.

규칙을 읽었는지 확인하는 방법

규칙 파일을 고친 뒤에는 새 세션을 시작해야 다시 읽습니다. Claude Code에서는 /memory나 /context를 입력하면 불러온 규칙 파일 목록이 나오고, 최근 버전에서는 직접 읽은 AGENTS.md도 이 목록에 보입니다. 목록에 없으면 폴더 위치, 파일 이름, 불러오기 줄을 차례로 봅니다.

Codex에는 “현재 적용된 프로젝트 규칙과 파일 경로를 요약해 줘. 파일은 수정하지 마.”라고 요청합니다. AI가 읽었다고 답해도 실제로 규칙이 적용됐는지는 수정된 파일에서 드러납니다. 규칙을 바꿨는데 결과가 그대로라면 파일 저장 여부, 새 세션 여부, 상위 폴더의 다른 규칙 파일을 차례로 봅니다.

기존 CLAUDE.md가 있는 프로젝트에 공통 규칙 붙이기

기존 CLAUDE.md를 @AGENTS.md 한 줄로 바꿔 버리면 그 안의 규칙이 사라집니다. 기존 내용은 그대로 두고 공통 부분만 옮깁니다.

2단계에서 Claude Code에만 필요한 설명은 CLAUDE.md에 남깁니다. 두 파일의 지시가 서로 다르면 어느 쪽을 유지할지 정한 뒤 한쪽에서 지웁니다. 두 이름이 한 파일을 가리키게 하는 심볼릭 링크도 쓸 수 있지만, Windows의 권한과 Git 설정에 따라 동작이 달라져 이 글에서는 불러오기 줄을 씁니다. 설정 이전 기능은 Codex와 Claude Code 설정 이전에 따로 정리했습니다.

2026년 9월 15일 기준 두 저장소의 구성

준이아빠블로그 운영에 쓰던 저장소 두 곳은 같은 목적을 서로 다른 방식으로 풀고 있었습니다. 업무용 저장소의 루트 CLAUDE.md는 326바이트였고 앞부분은 이렇습니다.

네 줄 아래에는 사용법을 안내하는 문단 하나가 붙어 있었고, 실제 규칙은 AGENTS.md(약 6.9KB)와 harness/CONTRACT.md(약 3.7KB)에 나눠 적었습니다. 블로그 저장소는 반대로 CLAUDE.md(212줄)에 명령과 검사 규칙을 모두 두고, AGENTS.md(13줄)에는 공통 항목과 "CLAUDE.md를 함께 읽는다"는 문장만 넣었습니다.

공통 규칙을 두는 두 가지 구성

항목	불러오기 구성업무용 저장소	안내 문장 구성블로그 저장소
규칙 원본	AGENTS.md CONTRACT.md	CLAUDE.md 212줄
Claude Code가 읽는 방법	@ 줄로 두 파일을 세션 시작 때 읽음	CLAUDE.md를 바로 읽음
Codex가 읽는 방법	AGENTS.md를 읽고 안내에 따라 CONTRACT.md	AGENTS.md의 문장을 보고 CLAUDE.md를 엶
두 도구에 같은 규칙이 반영됨	제공	Codex가 문장을 따를 때만

불러오기 구성에서는 공통 규칙을 AGENTS.md에서, 문서 작업 규칙을 CONTRACT.md에서 고치고 다음 세션에서 반영됐는지 봅니다. 안내 문장 구성은 Codex가 그 문장을 보고 파일을 열어야 규칙이 들어가므로 불러오기보다 반영이 덜 확실합니다. 새 프로젝트라면 공통 규칙의 원본을 하나로 정하고 불러오기 줄을 쓰는 편이 관리하기 쉽습니다.

한 도구가 끝낸 작업을 다른 도구에 넘기는 순서

두 도구는 대화 기록을 공유하지 않습니다. 넘겨받는 도구가 아는 것은 파일의 현재 상태와 내가 적어 준 인계 문장뿐입니다. 아래는 Claude Code가 README.md의 설치 절을 고치고, Codex가 같은 파일에 문제 해결 절을 더하는 예입니다.

1단계의 --permission-mode default는 Manual 모드로 실행하는 옵션이고, 이 모드에서 Claude Code는 파일을 고치기 전에 매번 승인을 묻습니다. 터미널을 열면 먼저 현재 폴더가 프로젝트 폴더인지 봅니다. macOS와 Linux에서는 pwd, Windows PowerShell에서는 Get-Location을 입력합니다. 2단계에서 다른 파일이나 다른 절까지 바뀌었다면 Codex로 넘어가기 전에 Claude Code에서 먼저 되돌립니다. 3단계에서 Codex를 실행하면 화면에 작업 폴더와 권한 설정이 표시되므로 같은 폴더인지 봅니다.

4단계의 인계 문장은 이런 모습입니다.

앞 도구의 대화 전체를 복사하지 않아도 대상 파일, 확인한 변경, 다음에 바꿀 항목 세 가지면 이어서 작업할 수 있습니다. 두 도구 모두 실행한 요청만큼 각자의 요금제 사용량이 줄어듭니다.

어느 도구에 무엇을 맡길지

같은 요청을 두 도구에 동시에 보내 비교하는 것보다, 이미 쓰는 도구로 작업 하나를 끝내고 결과 검토나 이어지는 작업을 다른 도구에 맡기는 편이 관리하기 쉽습니다. 저는 예전에 같은 규격서로 프로그램을 만들게 해 두 도구의 결과를 비교한 적이 있습니다.

같은 규격서로 만든 프로그램 비교(1회 기록)

항목	Codex	Claude Code
걸린 시간	65초	113초
코드 줄 수	90줄	236줄
요청에 없던 입력 처리와 예외 처리	제공하지 않음	제공

이 결과는 한 번의 기록이므로 도구를 고르는 기준으로 삼지 않습니다. 당시 조건은 Codex CLI와 Claude Code 비교에 적어 두었습니다. 일을 나눌 때는 도구 이름보다 완료 조건을 먼저 적습니다. “설치 절의 명령만 수정”, “수정 전후 차이를 검토”, “재현되는 오류의 원인 조사”처럼 대상과 결과를 나눠 적으면 넘겨받는 도구도 현재 상태를 바로 파악합니다.

동시에 일해야 할 때 작업 범위 나누기

두 도구가 같은 파일을 동시에 고치면 한쪽 변경이 다른 쪽에 덮어쓰이거나 서로 맞지 않는 결과가 남습니다. 동시에 일해야 한다면 파일을 나누거나 작업 폴더 자체를 나눕니다.

두 도구가 함께 일하는 세 가지 방법

항목	순서대로한 폴더	파일 나누기한 폴더	worktree폴더 따로
동시에 작업	제공하지 않음	제공	제공
같은 파일 수정	차례로 가능	제공하지 않음	합칠 때 충돌 확인
Git 사용 필요	제공하지 않음	제공하지 않음	제공
커밋하지 않은 변경이 따라옴	–	–	제공하지 않음

git worktree는 같은 저장소의 변경 기록을 공유하면서, 서로 다른 브랜치의 파일을 별도 폴더에서 고치게 하는 Git 기능입니다. 브랜치는 변경 이력을 나눠 관리하는 단위이고, 커밋은 그 이력에 남긴 저장 기록입니다. 새 worktree 폴더에는 원래 폴더에서 저장하지 않았거나 커밋하지 않은 변경이 복사되지 않습니다.

Claude Code는 claude --worktree 작업이름으로 worktree 세션을 시작하고, Codex는 따로 만든 worktree 폴더에서 실행합니다. 시작 전에 기준 커밋과 현재 변경 상태를 보고, 작업이 끝난 worktree 폴더는 변경을 합친 뒤에 지웁니다. 먼저 지우면 그 안의 결과도 함께 사라집니다.

worktree는 폴더를 나누는 기능이고 컴퓨터 전체의 접근을 막지는 않습니다. Claude Code는 worktree 세션에서 원래 작업 폴더를 향한 파일 수정과 명령 실행을 검사하는 기능을 따로 두고 있고, 적용 범위는 공식 worktree 문서에 있습니다. .env 같은 설정 파일은 Claude Code의 .worktreeinclude에 적으면 Git에서 제외한 파일도 새 폴더로 복사되므로, 새 작업에 그 값과 권한이 정말 필요한지 보고 넣습니다.

자주 묻는 질문

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

됩니다. 명령 이름과 기본 설정 폴더가 다르기 때문입니다. 주의할 부분은 같은 파일의 동시 수정과 도구마다 다른 권한 설정입니다.

파일이 두 개면 규칙도 중복되나요?

CLAUDE.md에서 AGENTS.md를 불러오는 구성에서는 Claude Code가 같은 AGENTS.md를 두 번 읽지 않습니다. Codex의 기본 규칙 검색에는 CLAUDE.md가 들어가지 않습니다. 같은 문장을 두 파일에 각각 복사하면 고칠 때마다 두 곳을 맞춰야 하므로 공통 원본은 하나로 둡니다.

규칙이 길어지면 어떻게 하나요?

항상 필요한 규칙만 남기고 특정 작업 절차는 별도 문서로 옮깁니다. Claude Code는 파일당 200줄을 권장하고 4MiB를 넘는 규칙 파일은 건너뜁니다. Codex의 기본 32KiB 한도와는 기준이 다릅니다. 정리 방법은 CLAUDE.md 세팅에 있습니다.

참고 자료

• Claude Code 규칙 파일
• Claude Code worktree
• Codex AGENTS.md

3줄 요약

1. Claude Code는 v2.1.277부터 프로젝트에 CLAUDE.md가 없으면 AGENTS.md를 직접 읽고, 기존 CLAUDE.md가 있으면 그 안의 @AGENTS.md 한 줄로 공통 규칙을 불러옵니다.

2. Codex는 프로젝트 루트부터 현재 폴더까지 AGENTS.md를 모으며 같은 폴더에서는 AGENTS.override.md가 우선하고 규칙 합계 한도는 기본 32KiB입니다.

3. 두 도구는 대화 기록을 공유하지 않으므로 수정 파일과 확인한 변경, 다음 할 일을 적어 넘기고 동시에 작업할 때는 파일이나 worktree 작업 폴더를 나눕니다.