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

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

두 도구의 설치와 로그인을 마친 분을 대상으로 합니다. 처음이라면 아래 메모 파일 실습부터 해 보세요. 프로그램 개발이나 Git 브랜치를 몰라도 순서대로 작업을 넘기는 방법을 익힐 수 있습니다. 설치가 필요하면 Claude Code 맥 설치와 Codex CLI 맥 설치를 먼저 참고합니다.

같은 규칙을 원본 하나에 적습니다

주방에서 두 요리사가 같은 조리법 원본을 확인하면 한쪽만 예전 조리법을 쓰는 일을 줄일 수 있습니다. 두 도구가 함께 읽을 규칙도 AGENTS.md 하나에 적어 두면 관리하기 쉽습니다. 이 파일은 AI에게 작업 방법을 알려 주는 글이며, 파일 수정을 물리적으로 막는 잠금장치는 아닙니다.

위 화면은 과거 기록입니다. 화면에는 AGENTS.md를 직접 읽지 않는다고 나오지만 현재 설명으로 사용하면 안 됩니다. 2026년 10월 4일 공식 문서 기준으로 최근 Claude Code는 AGENTS.md를 직접 읽을 수 있습니다. 직접 지원은 v2.1.277부터 추가됐으며, 일부 연결 환경의 제한이 해제된 v2.1.281 이후 버전을 기준으로 확인하는 편이 좋습니다.

기본 설정에서는 현재 폴더와 상위 폴더에 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 없을 때 AGENTS.md를 읽습니다. 사용자 공통 파일인 ~/.claude/CLAUDE.md는 이 판단에서 제외됩니다. 기존 CLAUDE.md가 있는 프로젝트에서는 그 파일에 @AGENTS.md를 추가해 공통 규칙을 불러오는 방법을 사용할 수 있습니다. 기존 내용은 지우지 않습니다. 버전과 설정에 따른 자세한 차이는 AGENTS.md 지원 정리에 있습니다.

Codex는 기본적으로 사용자 설정 폴더의 규칙을 읽은 뒤 프로젝트 루트부터 현재 폴더까지 규칙을 모읍니다. 같은 폴더에서는 AGENTS.override.md가 AGENTS.md보다 우선하며 둘을 모두 합치지 않습니다. 프로젝트 규칙의 합계 한도는 기본 32KiB이며 설정으로 바꿀 수 있습니다. 규칙을 수정한 뒤에는 새 세션을 시작해 다시 읽게 합니다.

메모 하나를 두 도구가 순서대로 수정해 봅니다

기존 프로젝트와 구분되는 새 shared-ai-practice 폴더를 만들고 VS Code 같은 파일 편집기로 엽니다. 아래 세 파일을 그 폴더에 저장합니다. 같은 이름의 기존 파일이 있다면 덮어쓰지 말고 새 연습 폴더를 사용합니다.

먼저 AGENTS.md에는 공통 규칙을 적습니다.

이어서 같은 폴더의 CLAUDE.md에는 아래 한 줄을 적습니다. 이 실습에서는 두 도구가 공유할 파일을 분명히 지정하기 위해 불러오기를 사용합니다.

마지막으로 meeting.md에 가상 모임 메모를 적습니다.

VS Code라면 상단의 Terminal 메뉴에서 New Terminal을 선택합니다. 터미널은 명령을 입력하는 창입니다. 현재 폴더가 shared-ai-practice인지 확인합니다. macOS와 Linux에서는 pwd, Windows PowerShell에서는 Get-Location을 입력합니다. 다른 위치라면 편집기에서 연습 폴더를 다시 열고 새 터미널을 여세요.

첫 작업은 Claude Code에 맡깁니다. 터미널에 claude --permission-mode default를 입력합니다. Manual 모드에서 제안한 작업을 확인하며 진행하는 예입니다. 대화 입력칸에 다음을 입력합니다.

제안한 수정 대상이 meeting.md인지 보고 진행합니다. 끝났다는 답변을 받은 뒤 편집기에서 파일을 직접 열어 날짜가 2026-10-19, 장소가 미정, 준비물이 책 한 권인지 확인합니다. 장소까지 바뀌었다면 “meeting.md의 장소를 미정으로 복구하고 날짜와 준비물은 그대로 둬.”라고 요청하고 파일을 다시 확인합니다. 다른 폴더나 다른 파일을 고쳤다면 작업을 멈추고 대상 경로부터 바로잡습니다.

Claude Code 입력칸에서 /exit로 종료합니다. 같은 터미널에서 codex를 실행하고 표시된 작업 폴더와 권한 설정을 확인합니다. 연습 때문에 승인 확인을 끌 필요는 없습니다. 다음 내용을 Codex 대화 입력칸에 넣습니다.

완료 후 실제 파일에서 세 줄을 다시 확인합니다. 날짜는 2026-10-19, 장소는 도서관 2층, 준비물은 책 한 권이면 이번 인계가 끝난 것입니다. 첫 도구의 대화 전체를 복사하지 않아도 대상 파일, 확인한 변경, 다음에 바꿀 항목을 전달하면 됩니다.

혼자 다시 해 볼 때는 장소를 도서관 3층으로 바꾸게 해 보세요. 다른 두 줄이 유지됐는지 확인하면 같은 방법을 반복한 것입니다. 실습 중 실행한 AI 요청에는 사용 중인 요금제의 사용량이 적용됩니다.

규칙을 읽었는지도 따로 확인합니다

Claude Code의 /memory 또는 /context에서 불러온 규칙 파일을 확인합니다. 최근 버전에서는 직접 읽은 AGENTS.md도 목록에 표시됩니다. 목록에 없으면 폴더 위치, 파일 이름, 불러오기 줄을 먼저 확인하고 새 세션을 시작합니다.

Codex에는 “현재 적용된 프로젝트 규칙과 파일 경로를 요약해 줘. 파일은 수정하지 마.”라고 요청할 수 있습니다. 다만 AI가 규칙을 읽었다고 답한 것만으로 성공이라고 판단하지 않습니다. 실제 수정 파일에서도 날짜 형식과 수정 범위를 확인합니다. 규칙을 바꿨는데 결과가 같다면 저장 여부와 새 세션 여부, 상위 폴더의 다른 규칙을 확인합니다.

기존 프로젝트에 적용할 때

기존 CLAUDE.md 전체를 위의 한 줄로 바꾸면 그 안의 규칙이 사라집니다. 먼저 두 파일을 읽고 공통으로 적용할 내용만 AGENTS.md에 정리하세요. 기존 CLAUDE.md에 불러오기 줄이 없다면 별도 줄로 추가하고, Claude Code에만 필요한 설명은 남깁니다. 두 파일의 지시가 충돌하면 어느 규칙을 유지할지 정한 뒤 중복을 줄입니다.

심볼릭 링크로 두 이름이 같은 파일을 가리키게 하는 방법도 있습니다. 다만 Windows의 권한과 Git 설정 차이를 고려해야 하므로 이 글의 실습에서는 불러오기를 사용했습니다. 설정 이전 기능은 Codex와 Claude Code 설정 이전에서 따로 설명합니다.

당시 실제로 사용한 구성

2026년 9월 15일 당시 준이아빠블로그 운영에 쓰던 저장소 두 곳의 기록입니다. 현재 파일 크기나 구성을 뜻하지 않습니다. 당시 업무용 저장소는 불러오기를 사용했고 루트 CLAUDE.md는 326바이트였습니다. 아래가 그 앞부분입니다.

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

당시 블로그 저장소는 이전 구성이었습니다. CLAUDE.md가 212줄이고 명령과 검사 규칙이 전부 그 안에 있었으며, AGENTS.md는 13줄뿐이고, 두 도구가 공통으로 지킬 항목과 "CLAUDE.md를 함께 읽는다"는 한 줄만 들어 있었습니다. 코덱스가 그 문장을 보고 파일을 여는 식이라, 규칙이 불러오기만큼 확실하게 반영되지는 않습니다. 새 프로젝트에서는 이 글의 실습처럼 공통 규칙의 원본을 하나로 정하고 불러온 결과를 확인하면 됩니다.

어느 도구에 무엇을 맡길지 정합니다

처음부터 같은 요청을 양쪽에 보내 비교할 필요는 없습니다. 이미 쓰는 도구로 작은 작업 하나를 완료하고, 결과 확인이나 이어지는 작업이 필요할 때 다른 도구를 사용해도 됩니다. 서로 다른 구독을 이용한다면 사용량도 각각 확인해야 합니다.

저는 과거 같은 규격서로 프로그램을 만들게 했을 때 Codex에서 65초와 90줄, Claude Code에서 113초와 236줄이라는 결과를 얻었습니다. Claude Code 결과에는 요청에 없던 입력 처리와 예외 처리도 들어갔습니다. 하지만 사용 모델과 조건이 달랐던 한 번의 기록이므로, 어느 도구가 항상 빠르거나 꼼꼼하다는 근거로 삼지는 않습니다. 당시 조건은 Codex CLI와 Claude Code 비교에 남겨 두었습니다.

일을 나눌 때는 도구 이름보다 완료 조건을 먼저 적는 편이 좋습니다. “메모에서 날짜만 수정”, “수정 전후 차이를 확인”, “아직 확인하지 못한 오류를 조사”처럼 대상과 결과를 구분하면 다음 도구도 현재 상태를 이해하기 쉽습니다.

동시에 일해야 한다면 작업 범위를 나눕니다

같은 폴더에서 실행했다는 이유만으로 반드시 수정이 사라지는 것은 아닙니다. 다만 같은 파일을 동시에 고치면 한쪽 변경을 덮어쓰거나 서로 맞지 않는 결과가 생길 수 있습니다. 처음에는 위 실습처럼 한 작업을 마친 뒤 다음 작업을 시작하세요.

동시 작업이 필요하면 서로 다른 파일을 맡기고 공통 파일은 한 도구만 수정하게 합니다. 규칙에 적는 것은 작업 약속이므로 실제 변경 목록도 확인해야 합니다.

Git 사용에 익숙해졌다면 git worktree로 작업 폴더를 나눌 수 있습니다. 같은 저장소의 변경 기록을 공유하되 서로 다른 브랜치의 파일을 별도 폴더에서 수정하는 기능입니다. 브랜치는 변경 이력을 나누어 관리하는 단위이고, 커밋은 그 이력에 남긴 저장 기록입니다. 새 작업 공간에는 원래 폴더의 저장하지 않은 내용이나 커밋하지 않은 변경이 자동으로 복사되지 않습니다.

Claude Code에는 claude --worktree 작업이름 옵션이 있고, Codex는 별도로 만든 작업 폴더에서 실행할 수 있습니다. 이 단계에서는 Git 저장소와 기준 커밋, 현재 변경 상태를 먼저 확인해야 합니다. 작업 종료 시 폴더를 지우면 그 안의 결과도 잃을 수 있으므로 변경을 확인하기 전에는 제거하지 않습니다.

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는 조건에 따라 AGENTS.md를 직접 읽으며, 기존 CLAUDE.md가 있다면 @AGENTS.md로 공통 규칙을 불러올 수 있습니다.

2. 공통 규칙을 원본 하나에 적고 새 세션에서 적용 여부와 실제 수정 파일을 함께 확인합니다.

3. 처음에는 두 도구를 순서대로 사용하고, 동시에 작업해야 할 때 수정 파일이나 작업 폴더를 나눕니다.