Skip to content

3장. 규칙 파일 AGENTS.md — CLAUDE.md를 Codex로 옮기기 ​

필수 이 단계를 따라가려면 꼭 읽으세요.

한 줄 요약: Codex는 일을 시작하기 전에 **AGENTS.md**를 읽습니다. Claude Code의 CLAUDE.md는 Codex가 그대로 두면 읽지 않습니다. 정리도구 폴더의 규칙을 AGENTS.md로 옮기고, 새 대화에서 규칙을 말하지 않아도 지키는지 시험합니다.

이 장은 2026년 11월 1일에 확인한 Codex 공식 문서와, 이 가이드가 정리도구 폴더로 직접 해 본 결과를 바탕으로 썼습니다. 규칙 파일이 왜 필요한지는 Claude Code 6장에서 설명했습니다. 여기서는 Codex에서 달라지는 점만 다룹니다.

Codex는 CLAUDE.md를 읽지 않는다 ​

Codex의 규칙 파일 이름은 AGENTS.md입니다.[1] 다른 이름의 파일을 규칙으로 쓰려면 설정에 따로 등록해야 하고, 등록하지 않은 이름은 무시합니다.[2] 그래서 CLAUDE.md는 그대로 두면 규칙으로 읽히지 않습니다.

2장의 실행 기록에서도 확인할 수 있었습니다. Codex는 폴더에서 AGENTS.md를 찾았고, 없으니 양식(templates/)만 읽었습니다. CLAUDE.md는 열지 않았습니다.

그런데도 2장의 회의록은 (메모에 없음) 규칙을 지켰습니다. 같은 규칙이 양식 안내문(templates/README.md)에도 적혀 있었기 때문입니다. 반대로 말하면, CLAUDE.md에만 적힌 규칙은 Codex가 모릅니다.

확인 퀴즈

AGENTS.md가 없는데도 Codex가 '(메모에 없음)' 규칙을 지켰습니다. 이 가이드의 실습에서 그 이유는 무엇이었나요?

CLAUDE.md를 AGENTS.md로 옮기기 ​

옮기는 일도 Codex에게 맡깁니다. 이 장의 실행도 2장처럼 같은 Codex를 터미널에서 돌린 것입니다. 이번에는 규칙 하나를 새로 더했습니다. 나중에 이 규칙이 지켜지는지 보면, AGENTS.md를 읽었는지 꽤 믿을 만하게 짐작할 수 있습니다.

CLAUDE.md는 Claude Code가 읽는 규칙 파일이야. 같은 규칙을 Codex도 읽도록 AGENTS.md로 옮겨 줘. 규칙 내용은 바꾸지 말고, 규칙 하나만 추가해 줘: '정리한 파일 맨 아래에 「원본과 대조할 것」 절을 두고, 숫자·이름·날짜 중 다시 확인할 것을 3개 이내로 적는다.' CLAUDE.md는 그대로 둬.

Codex는 CLAUDE.md의 다섯 규칙을 그대로 옮기고, 새 규칙을 6번으로 붙였습니다. 그리고 "추가한 규칙을 제외하면 원본과 내용이 완전히 일치하는지 검증했다"고 알렸습니다.

결과: AGENTS.md

CLAUDE.md를 지우지 않은 이유가 있습니다. 같은 폴더를 Claude Code에서도 계속 쓸 수 있게 하려는 것입니다. 대신 두 파일을 함께 고쳐야 합니다. 한쪽만 고치면 두 도구가 다른 규칙으로 일하게 됩니다.

확인 퀴즈

같은 폴더를 Claude Code와 Codex에서 함께 쓰려고 AGENTS.md를 만들고 CLAUDE.md도 남겨 두었습니다. 앞으로 주의할 점은 무엇일까요?

규칙을 말하지 않고 시험하기 ​

새 대화를 열고, 규칙 이야기 없이 공부 필기 정리만 부탁합니다.

inbox/공부-2026-10-28-프롬프트-강의.txt 를 공부 노트로 정리해서 notes/ 에 저장해 줘.

결과 맨 아래에 새 규칙의 절이 생겼습니다.

## 원본과 대조할 것

- 강의 날짜: 10/28(수). 원본에는 10/28로 적혀 있으며, 연도는 파일명의 2026년을 기준으로 했다.
- 강의 분량: 1시간.
- 강사가 소개한 프롬프트 작성 방법: 5가지.

결과: 규칙만으로 쓴 공부 노트

언제 만든 파일「원본과 대조할 것」 절
AGENTS.md 전(2장 회의록)없음
AGENTS.md 후(이 공부 노트)있음

출처: 이 가이드의 실습 결과(2026-11-01, 각 1회)

새 규칙은 AGENTS.md에만 있었으므로, Codex가 그 파일을 읽고 따랐다고 볼 수 있습니다. 매번 지킨다는 보장은 아니니, 결과를 볼 때마다 확인하세요.

이 실험의 한계 (눌러서 펼치기)
  • 한 번씩 해 본 결과입니다.
  • 전과 후의 메모 종류(회의록·공부 노트)가 다릅니다.
  • 양식 점검표에도 "원본 메모와 한 번 대조했다"는 비슷한 항목이 있습니다.

더 확실히 하려면 같은 메모를 AGENTS.md 없이 한 번, 있이 한 번 돌려 비교해 보세요.

확인 퀴즈

AGENTS.md가 정말 읽히는지 확인하려고 합니다. 이 가이드가 쓴 방법은 무엇일까요?

AGENTS.md를 읽는 순서 ​

AGENTS.md는 두 곳에 둘 수 있습니다.[3]

위치적용 범위예
~/.codex/AGENTS.md내 모든 폴더"답은 한국어로"
프로젝트 폴더의 AGENTS.md그 폴더만정리도구 규칙

출처: Codex 공식 문서(일부만 옮김)[3:1]

둘 다 있으면 이어 붙여서 하나처럼 읽습니다. 이때 지금 폴더에 가까운 파일이 뒤에 붙고, 뒤에 온 지침이 앞의 지침보다 우선합니다.[4]

예를 들어 ~/.codex/AGENTS.md에 "답은 한국어로", 정리도구 폴더의 AGENTS.md에 "답은 영어로"가 있다고 해 보세요. 정리도구 폴더 파일이 뒤에 붙으므로, 이 폴더에서는 "영어로"가 이깁니다.

붙일 수 있는 양에는 한도가 있습니다. 합친 크기가 기본 32KiB(키비바이트, 파일 크기 단위)에 닿으면 그 뒤는 붙이지 않습니다.[5] 한국어로 대략 1만 자 남짓입니다. 규칙은 짧게 유지하세요.

규칙을 고쳤는데 반영이 안 된 것 같으면 새 대화를 시작하거나 Codex를 다시 시작하세요. Codex는 실행을 시작할 때마다 규칙을 새로 읽습니다.[6]

AGENTS.md가 아직 없는 폴더라면 앱 입력창에 /init을 쳐서 뼈대를 만들 수도 있습니다.[7]

확인 퀴즈

~/.codex/AGENTS.md와 정리도구 폴더의 AGENTS.md가 서로 다른 말을 합니다. 어느 쪽이 우선할까요?

가져오기(Import)와 메모리 ​

이 장에서 손으로 한 일을 한 번에 해 주는 기능도 있습니다. 가져오기는 다른 에이전트의 설정을 한 번에 옮겨 주는 기능입니다. 앱에서는 Claude Code·Claude Cowork·Cursor에서 가져올 수 있습니다.[8] 앱 설정의 Import 메뉴에서 시작합니다.[9]

ChatGPT 앱의 Settings → Import 화면: 「Import from another AI app」 아래에 Claude Code·Claude Cowork·Cursor가 있고 각각 Import 버튼이 있다

이 가이드의 화면(2026-11-01)에서는 설정 왼쪽 목록에 Import가 있었고, 이 컴퓨터에서 찾은 Claude Code·Claude Cowork·Cursor가 각각 Import 버튼과 함께 보였습니다. 이 가이드는 버튼을 누르지 않았습니다.

이 가이드는 가져오기를 실행하지 않았습니다. 가져오기는 폴더 하나가 아니라 내 컴퓨터의 개인 설정까지 함께 살펴봅니다.[10] 그리고 규칙 파일, 스킬, 슬래시 명령, 설정 파일을 Codex 쪽 짝으로 바꿔 한꺼번에 옮깁니다. 예를 들어 CLAUDE.md는 AGENTS.md가 됩니다.[11] 한 번에 많이 옮겨지므로, 무엇이 옮겨지는지 하나씩 직접 보고 싶다면 이 장처럼 손으로 옮기는 편이 낫습니다.

가져오기가 옮기는 것과 검토할 것 (눌러서 펼치기)
Claude Code 쪽Codex로 오면
규칙 파일(CLAUDE.md 등)AGENTS.md
스킬스킬
슬래시 명령(/이름)스킬($이름)
settings.jsonconfig.toml

출처: Codex 공식 문서(일부만 옮김)[11:1]

settings.json과 config.toml은 각 도구의 설정을 적어 두는 파일입니다. 이름만 다를 뿐 같은 역할입니다.

가져와도 원래 설정은 바뀌거나 지워지지 않습니다.[12] 다만 가져온 뒤에는 이런 것을 꼭 검토하라고 합니다.[13]

  • 스킬이 쓸 수 있는 도구나 권한을 제한해 둔 부분
  • 훅(정해진 때 자동으로 도는 스크립트)
  • 빈칸에 값을 넣어 쓰는 명령(인자를 쓰는 명령)

설정에 Import 메뉴가 없으면 General에서 Import other agent setup을 찾습니다.[9:1]

메모리(Memories)는 예전 작업의 맥락을 다음 작업에 가져가는 기능입니다.[14] 내 컴퓨터의 Codex 메모리는 기본으로 꺼져 있습니다.[15] 공식 문서는 메모리를 "떠올리기 보조"로만 보고, 꼭 지킬 규칙은 메모리에 맡기지 말라고 합니다.[16] 꼭 지킬 규칙은 AGENTS.md에 적으라고 합니다.[17]

확인 퀴즈

꼭 지켜야 하는 정리 규칙을 어디에 두라고 공식 문서가 권할까요?

직접 해 보기 ​

  1. 위의 요청으로 CLAUDE.md를 AGENTS.md로 옮기게 한다. 새 규칙 하나를 함께 더한다.
  2. AGENTS.md를 열어 원래 규칙이 그대로인지, 새 규칙이 붙었는지 본다.
  3. 새 대화를 열고 규칙 이야기 없이 공부 필기를 정리시킨다.
  4. 결과에 새 규칙이 지켜졌는지 확인한다.

이어지는 과제: 4장에서는 Codex가 무엇을 스스로 하고 무엇을 물어보는지 정하는 권한 메뉴와, 바뀐 내용을 되돌리는 법을 배웁니다.

정리 ​

  • Codex는 AGENTS.md를 읽고, CLAUDE.md는 그대로 두면 읽지 않는다.
  • 두 도구를 함께 쓰면 두 파일을 함께 고친다.
  • 새 규칙을 넣고 말하지 않은 채 시험해 보면, 규칙 파일이 읽히는지 알 수 있다(이번 실습: 전 0 → 후 1).
  • 개인 규칙은 ~/.codex/AGENTS.md, 폴더 규칙은 폴더의 AGENTS.md. 가까운 쪽이 우선한다.
  • 가져오기는 설정을 한 번에 옮기지만 개인 설정까지 보인다. 꼭 지킬 규칙은 메모리가 아니라 AGENTS.md에.

용어 정리 ​

용어읽는 법한 줄 뜻
Import임포트다른 에이전트의 설정을 Codex로 옮기는 기능
Memories메모리즈예전 작업 맥락을 다음에 떠올리는 기능
/init이닛AGENTS.md 뼈대를 만드는 명령

이 장을 다 읽었나요?

기록은 이 브라우저에만 저장됩니다. 진행 현황은 전체 목차에서 볼 수 있어요.

다음 장: 4장. 권한과 되돌리기

참고 자료 (17개)
  1. Codex 공식 문서, 「Custom instructions with AGENTS.md」. "Codex reads AGENTS.md files before doing any work." learn.chatgpt.com (확인일 2026-11-01) ↩︎

  2. Codex 공식 문서, 「Custom instructions with AGENTS.md」. "Filenames not on this list are ignored for instruction discovery." learn.chatgpt.com (확인일 2026-11-01) ↩︎

  3. Codex 공식 문서, 「Custom instructions with AGENTS.md」. "In your Codex home directory (defaults to ~/.codex, unless you set CODEX_HOME), Codex reads AGENTS.override.md if it exists." / "Starting at the project root (typically the Git root), Codex walks down to your current working directory." learn.chatgpt.com (확인일 2026-11-01) ↩︎

  4. Codex 공식 문서, 「Custom instructions with AGENTS.md」. "Files closer to your current directory override earlier guidance because they appear later in the combined prompt." learn.chatgpt.com (확인일 2026-11-01) ↩︎

  5. Codex 공식 문서, 「Custom instructions with AGENTS.md」. "Codex skips empty files and stops adding files once the combined size reaches the limit defined by project_doc_max_bytes (32 KiB by default)." learn.chatgpt.com (확인일 2026-11-01) ↩︎

  6. Codex 공식 문서, 「Custom instructions with AGENTS.md」. "If instructions look stale, restart Codex in the target directory." learn.chatgpt.com (확인일 2026-11-01) ↩︎

  7. Codex 공식 문서, 「Slash commands」. "Generate an AGENTS.md scaffold for the current project." learn.chatgpt.com (확인일 2026-11-01) ↩︎

  8. Codex 공식 문서, 「Import from another agent」. "The desktop app can import from Claude Code, Claude Cowork, or Cursor." learn.chatgpt.com (확인일 2026-11-01) ↩︎

  9. Codex 공식 문서, 「Import from another agent」. "If Import isn't available as a settings section yet, open General and find Import other agent setup." learn.chatgpt.com (확인일 2026-11-01) ↩︎

  10. Codex 공식 문서, 「Import from another agent」. "The import flow checks both your user-level setup and your existing projects." learn.chatgpt.com (확인일 2026-11-01) ↩︎

  11. Codex 공식 문서, 「Import from another agent」. 표 「What ChatGPT can import」의 Instruction files·settings.json·Skills·Slash commands 행. learn.chatgpt.com (확인일 2026-11-01) ↩︎

  12. Codex 공식 문서, 「Import from another agent」. "Importing doesn't change or delete your existing agent setup." learn.chatgpt.com (확인일 2026-11-01) ↩︎

  13. Codex 공식 문서, 「Import from another agent」. "Tool restrictions or permissions in imported skills and agents." / "Hooks whose behavior may differ after import." / "Prompt templates or command-style prompts that depend on arguments, shell interpolation, or file-path placeholders." learn.chatgpt.com (확인일 2026-11-01) ↩︎

  14. Codex 공식 문서, 「Memories」. "Memories let ChatGPT and Codex carry useful context from earlier work into future work." learn.chatgpt.com (확인일 2026-11-01) ↩︎

  15. Codex 공식 문서, 「Memories」. "Local Codex memories are off by default." learn.chatgpt.com (확인일 2026-11-01) ↩︎

  16. Codex 공식 문서, 「Memories」. "Treat memories as a helpful recall layer, not as the only source for rules that must always apply." learn.chatgpt.com (확인일 2026-11-01) ↩︎

  17. Codex 공식 문서, 「Memories」. "Keep required team guidance in AGENTS.md or checked-in documentation." learn.chatgpt.com (확인일 2026-11-01) ↩︎