예상 읽기 시간: 약 7분
처음에는 저도 헷갈렸습니다.
CLAUDE.md가 있고, AGENTS.md가 있고, README.md도 있고.
이거 다 다른 내용을 써야 하나?
AI마다 파일을 따로 만들어야 하나?
같은 말을 또 복붙하는 게 맞나?
이번 findings에서 가장 설명하기 좋은 실제 사례가 하나 나왔습니다.
D:\Yugyeong-Side-Income-OS\CLAUDE.md와 AGENTS.md가 바이트 단위로 동일한 파일이었습니다.
SHA256 해시까지 같았습니다.
즉 내용이 비슷한 정도가 아니라, 완전히 같은 파일이었습니다.
왜 이렇게 했을까요?
답은 단순합니다.
Claude Code는 CLAUDE.md를 읽고, Codex는 AGENTS.md를 읽기 때문입니다.
내용이 달라서가 아니라 읽는 도구가 달랐습니다
이건 디자인 회사로 비유하면 쉽습니다.
같은 프로젝트 브리프가 있습니다.
그런데 A팀은 브리프.pdf라는 이름으로 찾아보고, B팀은 작업가이드.pdf라는 이름으로 찾아봅니다.
내용은 같지만 각 팀이 기본적으로 찾는 파일명이 다른 거예요.
그래서 같은 브리프를 두 이름으로 복사해둔 셈입니다.
Claude Code에게 읽히려면 CLAUDE.md.
Codex에게 읽히려면 AGENTS.md.
이렇게 생각하면 덜 헷갈립니다.
실제로 들어 있던 규칙
findings에서 확인된 Side Income OS의 CLAUDE.md와 AGENTS.md에는 이런 규칙이 들어 있었습니다.
항상 docs 폴더의 문서를 기준으로 판단한다.
새 아이디어는 docs/01_IDEA_FILTER.md로 채점한다.
Framer 20개 일괄 양산은 하지 않고, 09 문서의 무료 1개 → 유료 1개 검증 순서를 지킨다.
이 규칙들은 특정 글 하나를 위한 요청이 아닙니다.
프로젝트 전체에서 계속 지켜야 하는 기준입니다.
그래서 Claude Code와 Codex 양쪽이 모두 읽을 수 있도록 두 파일명으로 둔 것이 자연스럽습니다.
같은 규칙을 다른 AI 도구가 읽을 수 있도록 두 파일명으로 둔 사례입니다.
같은 내용을 두 번 쓰는 게 항상 좋은 건 아닙니다
다만 여기에는 단점도 있습니다.
같은 내용을 복사해서 두 파일로 두면, 나중에 하나만 고쳤을 때 서로 달라질 수 있습니다.
이번 findings에서도 비슷한 문제가 다른 곳에서 발견됐습니다.
ChatGPT 프로젝트에 올라간 지식 파일과 로컬 원본 파일의 정책이 달랐습니다. 로컬에서는 최신 정책으로 바뀌었는데, 프로젝트에 올라간 파일은 이전 정책을 담고 있었어요.
이건 “복사본이 늘어날수록 관리할 파일도 늘어난다”는 뜻입니다.
그래서 같은 규칙을 여러 곳에 둘 때는, 어디가 원본인지 정해두는 게 좋습니다.
예를 들어:
- 로컬 프로젝트 폴더의
CLAUDE.md를 원본으로 둔다 - Codex용
AGENTS.md는 같은 내용으로 복사한다 - ChatGPT 프로젝트에 올린 파일은 정책이 바뀔 때마다 재업로드한다
이런 식의 운영 규칙이 필요합니다.
Claude Code에서는 AGENTS.md를 직접 읽지 않습니다
Claude 공식 문서 기준으로 Claude Code는 기본적으로 CLAUDE.md를 읽습니다. 이미 저장소에 AGENTS.md가 있다면 CLAUDE.md 안에서 @AGENTS.md로 불러오는 방식도 안내되어 있습니다.
즉 Claude Code에게 AGENTS.md를 읽히고 싶다면, 그냥 AGENTS.md만 만들어두는 것으로는 부족할 수 있습니다.
Claude가 읽는 입구는 CLAUDE.md입니다.
반대로 Codex 공식 문서에서는 Codex가 AGENTS.md를 읽는다고 설명합니다. 또한 빈 파일은 건너뜁니다.
이 차이를 모르면 파일을 만들어놓고도 AI가 왜 지침을 안 따르는지 헷갈릴 수 있습니다.
빈 파일은 설정이 아닙니다
findings에서 C:\Users\uesr1\.codex\AGENTS.md와 D:\Yugyeong-Notion-Rebuild\CLAUDE.md는 0바이트 빈 파일로 확인됐습니다.
이건 개인적으로 좀 웃겼습니다.
있긴 있는데 아무것도 없는 파일.
AI 설정을 열심히 해둔 것 같지만 실제로는 아무 규칙도 없는 상태입니다.
하지만 이 사례가 오히려 좋습니다.
우리가 기억해야 할 건 파일명이 아니라 내용입니다.
CLAUDE.md라는 이름을 붙였는가보다 중요한 건, 그 안에 AI가 다음 작업에서 실제로 따라야 할 규칙이 들어 있는가입니다.
저는 이렇게 정리했습니다
현재 제 기준은 이렇습니다.
README.md는 사람과 AI 모두에게 보여주는 프로젝트 안내문.
CLAUDE.md는 Claude Code가 읽는 지속 지침.
AGENTS.md는 Codex가 읽는 지속 지침.
SKILL.md는 특정 작업을 실행하기 위한 작업 매뉴얼.
여기서 중요한 건 다 md 파일이라는 점입니다.
형식은 비슷하지만 역할이 다릅니다.
디자인 파일로 비유하면 모두 이미지 파일처럼 보여도, 하나는 로고 원본이고 하나는 썸네일이고 하나는 인쇄용 시안인 것과 비슷합니다.
겉보기 확장자보다 쓰임이 중요합니다.
같은 규칙을 여러 도구에 심고 싶다면
Claude Code와 Codex를 둘 다 쓴다면 같은 규칙을 두 도구가 모두 읽게 해야 합니다.
이때 선택지는 몇 가지가 있습니다.
가장 단순한 방법은 같은 내용을 CLAUDE.md와 AGENTS.md 두 파일에 넣는 것입니다.
조금 더 관리적으로 하려면 한쪽을 원본으로 두고 다른 쪽에서 불러오게 할 수 있습니다. 다만 윈도우에서는 심볼릭 링크 같은 방식이 번거로울 수 있으니, 처음에는 복사본을 두는 편이 덜 어렵습니다.
중요한 건 복사했다는 사실을 알고 있어야 한다는 점입니다.
복사본은 언젠가 달라질 수 있습니다.
그래서 정책을 바꿨다면 반드시 묻습니다.
이 규칙을 Claude만 알아도 되는가?
Codex도 알아야 하는가?
ChatGPT 프로젝트에도 다시 올려야 하는가?
이 질문을 하는 것만으로도 AI 지침 파일이 훨씬 덜 엉킵니다.
다음 글에서는 지침 파일과 스킬 파일의 차이를 정리해보겠습니다. 특히 SKILL.md를 그냥 프로젝트에 업로드한다고 스킬처럼 실행되는 것은 아니라는 점을 다룰 예정입니다.