클로드 코드와 코덱스 같이 쓰기
CLAUDE.md와 AGENTS.md 동기화 플레이북

Claude Code에서 쌓은 문체, 업무 규칙, 스킬을 코덱스에서도 쓰고 싶은가요? 이 글은 두 제품의 성능 순위를 매기는 비교글이 아니라, 이미 만든 작업 환경을 옮기거나 번갈아 쓰기 위한 안내입니다

범위는 로컬 파일을 읽는 Codex 환경입니다 브라우저의 일반 ChatGPT 대화에 파일을 올리는 방식과는 적용 경로가 달라요

같이 쓰는 방법부터 구분하세요

“클로드 코덱스 연결”을 검색했다면 어느 쪽을 원하는지 먼저 정해보세요 같은 폴더에서 이어 쓰려는 사람에게 필요한 첫 단계는 공통 기준 문서입니다

무엇이 옮겨지고, 무엇을 다시 확인해야 하나

동기화율을 파일 수로 계산하면 이 차이가 사라져요 역할 파일을 전부 옮겼어도 위임이 한 번도 실행되지 않았다면, 확인된 것은 파일 준비까지입니다

1단계 - 기존 환경의 목록과 복구 지점을 만든다

바로 복사하기 전에 CLAUDE.md, 스킬, 훅, 외부 연결, 기억 문서를 목록으로 정리해요 각 항목에 “어디에 있는가, 누가 읽는가, 무엇을 하는가”를 붙이면 빠진 연결이 보입니다

예를 들어 “문서 수정 후 기록”이라는 훅이 있다면, 이름만 적지 말고 어떤 수정 도구를 감시하는지까지 확인합니다 같은 파일을 두 세션이 동시에 저장할 수 있는 환경에서는 작업을 넘기는 순서도 정해야 해요

2단계 - CLAUDE.md와 AGENTS.md의 공통 규칙을 한 곳에 둔다

Claude Code는 CLAUDE.md를, Codex는 AGENTS.md를 프로젝트 지침으로 사용합니다 파일명은 대소문자와 복수형까지 맞추세요 agent.md를 만들어 놓고 기본 지침으로 읽힐 것이라고 가정하면 안 됩니다

기준 문서: Claude Code 메모리와 CLAUDE.md, OpenAI AGENTS.md 안내

처음 함께 구성한다면 - AGENTS.md를 공통 기준으로

두 도구에서 똑같이 지켜야 할 규칙을 루트 AGENTS.md에 두고, 같은 폴더의 CLAUDE.md에서 이를 불러올 수 있어요 Claude Code 공식 문서도 @AGENTS.md 방식의 가져오기를 안내합니다

# 공통 작업 규칙
- 시작 전에 PROJECTS.md와 해당 프로젝트 HANDOFF.md를 읽는다
- 새 산출물을 만들기 전에 기존 자료를 찾는다
- 공개 자료에 개인 신원을 노출하지 않는다
- 마감할 때 결정, 근거, 다음 할 일을 HANDOFF.md에 적는다

@AGENTS.md

# Claude Code 전용 안내
Claude Code에서만 쓰는 명령과 설정 경로는 이 아래에 적는다

이 예시는 두 파일이 같은 폴더에 있을 때의 구조입니다 CLAUDE.md가 .claude/ 안에 있다면 가져오기 경로도 그 파일 위치를 기준으로 조정해야 해요

기존 Claude 환경이 크다면 - 원천 파일을 유지하고 Codex 사본을 생성

이미 CLAUDE.md를 여러 자동화가 읽고 있다면 기준 파일을 급하게 바꿀 필요는 없습니다 공통 규칙을 원천에서 추출해 AGENTS.md를 생성하고, Codex에 필요한 별도 안내를 더하는 방식으로 시작할 수 있어요

이때 생성된 AGENTS.md는 직접 고치지 않는다는 규칙이 필요합니다 원천을 고친 뒤 다시 생성하고, 재생성 결과와 저장된 사본이 다른지 검사하세요 양쪽을 각각 고치기 시작하면 어느 규칙이 최신인지 다시 사람이 판단해야 해요

Codex의 프로젝트 지침은 기본적으로 합산 32KiB 한도와 디렉터리별 우선순위의 영향을 받습니다 파일이 존재하는지만 보지 말고 실제 세션에 적용된 지침을 확인하세요

3단계 - 스킬과 역할은 “발견” 다음에 “실행”을 본다

스킬은 본문과 자료를 재사용하기 좋은 단위예요 Codex의 로컬 스킬 경로에는 프로젝트의 .agents/skills와 사용자의 ~/.agents/skills가 있으며, 심볼릭 링크로 연결한 스킬 폴더도 지원합니다

따라서 기존 .claude/skills의 스킬 폴더를 연결하는 방식으로 중복 사본을 줄일 수 있습니다 다만 문서 안의 Claude 전용 도구명, 다른 기기의 경로, 설치되지 않은 프로그램까지 자동으로 호환되는 것은 아니에요

기준 문서: OpenAI 로컬 스킬 경로와 심볼릭 링크

서브에이전트도 같은 기준으로 봅니다 Codex에도 서브에이전트 기능이 있으므로 “Claude의 역할을 Codex에서는 쓸 수 없다”고 단정하면 틀려요 다만 역할 지침 재사용과 실제 위임 기능의 개통은 별도로 확인해야 합니다

기준 문서: OpenAI 서브에이전트 안내

• 발견 확인 - 의도한 스킬이나 역할이 현재 환경에 표시되는가
• 참조 확인 - 연결된 지침과 자료를 열 수 있는가
• 실행 확인 - 예시 작업을 실제로 수행하고 결과를 돌려주는가
• 제약 확인 - 현재 세션에서 위임이나 특정 도구 사용이 허용되어 있는가

4단계 - 훅은 파일을 복사한 뒤 입력과 결과를 검증한다

훅은 에이전트의 특정 시점에 자동으로 실행되는 점검이나 기록 장치예요 Codex도 훅을 지원하며, 프로젝트의 .codex/hooks.json이나 설정 파일 안에서 구성할 수 있습니다 일반 훅은 정의를 검토하고 신뢰한 상태여야 실행됩니다

기준 문서: OpenAI Hooks, 발견 경로와 신뢰 검토

옮길 때 가장 놓치기 쉬운 부분은 도구 호출이 훅에 전달되는 모양입니다 문서를 바꾸는 행동이라도 파일 편집, 패치, 셸 명령, 외부 앱 호출은 입력이 다를 수 있어요 기존 훅이 특정 도구명만 보고 있다면 다른 경로의 변경을 기록하지 못합니다

훅을 시험할 때는 운영 파일이나 실제 수신자를 대상으로 위험한 행동을 재현하지 마세요 격리된 임시 폴더와 테스트 입력을 먼저 쓰고, 외부 쓰기 시험은 그 작업이 허용된 테스트 공간에서 진행합니다

5단계 - 외부 앱과 기억 문서는 별도로 이어준다

MCP 서버 주소를 알고 있는 것, 도구가 목록에 있는 것, 실제 자료를 읽을 수 있는 것은 서로 다른 상태예요 Codex의 MCP 설정과 연결 상태를 확인한 뒤, 현재 연결된 계정으로 필요한 자료가 열리는지 읽기 작업부터 확인합니다

기준 문서: OpenAI MCP 설정과 인증

이번 이전에서도 기존 Claude 연결을 복사한 것으로 끝나지 않았습니다 Codex에서 쓸 계정을 확정하고 외부 앱 인증을 별도로 연결했어요 설치 완료를 인증 완료로 기록하면, 다음 작업에서 도구는 보이는데 데이터를 못 읽는 상황이 생길 수 있습니다

대화 맥락은 필요한 결정을 문서로 남겨 넘기세요 저장소를 공유한다고 이전 대화 전체가 자동으로 이어지는 것으로 기대하지 않는 편이 좋습니다 HANDOFF.md에 목표, 확정한 결정과 이유, 미결, 다음 행동을 적고 새 세션이 먼저 읽도록 공통 지침에 넣어둬요

동기화 완료 점검표

“환경을 동일하게 맞췄다” 대신 아래 항목별로 확인 결과를 남기세요 새 세션에서 읽기 작업 하나와 임시 문서 작성 하나를 이어 수행하면, 문서 대조만으로는 드러나지 않던 차이를 찾을 수 있습니다

• 공통 운영 규칙이 누락 없이 반영되고 도구 전용 지시와 충돌하지 않는가
• 공통 규칙을 한 곳에서 고치면 다른 쪽에도 반영되거나 차이가 검출되는가
• 스킬이 발견되고 필요한 참조 파일과 실행 도구를 사용할 수 있는가
• 훅이 신뢰된 상태이며 성공, 실패, 읽기 상황을 구분하는가
• 외부 연결이 올바른 계정으로 필요한 자료를 읽을 수 있는가
• 위임을 쓸 예정이라면 역할 하나의 실제 실행과 결과 회수를 확인했는가
• 새 세션이 HANDOFF.md를 읽고 같은 다음 행동을 이해하는가
• 아직 시험하지 않은 항목을 완료 항목과 분리해 적었는가

같은 운영 기준을 유지하면서 실행환경의 차이는 드러내는 것이 현실적인 목표예요 모델의 답변과 내부 실행 방식까지 같게 만드는 것을 동기화의 완료 조건으로 삼으면 끝이 나지 않습니다

자주 묻는 질문

지침 작성이 처음이라면 3편 CLAUDE.md부터 읽어보세요 자동 실행을 이해하려면 6편 Hooks, 운영 환경 전체를 정리하려면 12편 하네스 엔지니어링, 권한과 기록 기준은 18편 에이전트 거버넌스로 이어집니다

검증 기준일: 2026-09-12 KST 공식 문서로 확인한 기능과 한 로컬 환경의 이전 관찰을 구분해 작성했으며, 제품 업데이트에 따라 설정과 제공 범위는 달라질 수 있습니다