Codex와 Claude Code를 같은 폴더에서 사용하는 진입점 (AGENTS.md 및 CLAUDE.md)

CHIERO 주식회사(株式会社CHIERO)의 치에로입니다.

저희 회사에서는 같은 폴더를 Claude Code와 Codex 양쪽 모두에서 열어 업무를 시키고 있습니다.

이 글에서는 두 도구가 동일한 규칙을 동일한 순서로 읽도록 만든 진입점(entry point)을 만드는 방법을 작성합니다.

첨부하는 파일은 저희 회사 운영 방식을 다른 회사에서도 사용할 수 있도록 재구성한 'AI 직원 일체'의 실제 사례입니다.

사양 설명은 2026년 10월 12일에 공식 문서를 읽은 내용입니다.

결론: 지시는 AGENTS.md에 작성하고, CLAUDE.md는 그것을 불러오기만 하도록 한다

폴더 바로 아래의 CLAUDE.md는 다음 한 줄로 전체가 구성됩니다.

@AGENTS.md

지시 본문은 모두 AGENTS.md에 있습니다.

CLAUDE.md에 지시를 추가하지 않습니다.

두 파일에 동일한 지시를 작성하면, 한쪽만 수정해도 서로 충돌하기 때문입니다.

두 도구가 읽는 파일

Codex는 AGENTS.md를 읽는다

Codex는 작업을 시작하기 전에 AGENTS.md를 읽습니다.

공식 문서에 따르면, 검색 순서는 다음과 같습니다.

• Codex의 홈(기본값은 ~/.codex)에 있는 AGENTS.override.md. 없으면 AGENTS.md-
• 프로젝트 루트(보통 Git의 루트)부터 현재 작업 폴더까지 각 폴더를 거칩니다. 폴더마다 AGENTS.override.md, AGENTS.md 순서로 하나씩—찾은 파일을, 루트에 가까운 순서대로 연결합니다.

연결된 총합이 최대치(기본값은 32 KiB, 설정의 project_doc_max_bytes)에 도달하면 거기서 읽기를 멈춥니다.

빈 파일은 건너뜁니다.

Claude Code는 CLAUDE.md를 읽고, 조건에 따라 AGENTS.md도 읽는다

Claude Code는 작업 폴더와 그 위의 각 폴더의 CLAUDE.md를 읽습니다.

CLAUDE.md 안에 @경로라고 쓰면 해당 파일을 읽어옵니다.

상대 경로는 CLAUDE.md가 있는 폴더에서 계산합니다.

읽어온 파일 안의 @경로도 따라가며, 깊이는 4단계까지입니다.

공식 문서에는 AGENTS.md의 처리 방식도 쓰여 있습니다.

기본적으로는 작업 폴더와 그 위의 폴더에 CLAUDE.md가 하나도 없을 때만 Claude Code가 AGENTS.md를 읽습니다.

제가 읽은 시점의 공식 문서에서는 이 기본값이 Claude Code 2.1.277 이상부터입니다(Amazon Bedrock 등의 일부 연결에서는 2.1.281 이상).

그보다 오래된 버전은 CLAUDE.md만 읽기 때문에, 읽어오기 위한 한 줄이 반드시 필요합니다.

읽어오기 한 줄을 배치한 이유

표의 두 번째 행이 주의할 점입니다.

작업 폴더 위의 폴더에 CLAUDE.md가 하나라도 있으면, 기본적으로는 AGENTS.md가 읽히지 않습니다.

작업용 폴더를 중첩해서 사용할 경우, 위의 폴더에 CLAUDE.md를 놓을 때가 있습니다.

그때 아래 폴더의 AGENTS.md가 읽히지 않게 됩니다.

저희 회사에서는 회사의 폴더에 @AGENTS.md라고 쓴 CLAUDE.md를 두어, 읽기를 명시했습니다.

표의 세 번째 행 형태이므로, 위의 폴더에 CLAUDE.md가 늘어나도 설정을 변경하지 않아도 AGENTS.md가 읽힙니다.

AGENTS.md 전체 내용

AGENTS.md는 13줄입니다.

# AI 직원 일체: 이 폴더의 진입점
이 폴더는 AI 직원 18명의 회사 운영 일체입니다.
요청을 받으면 다음 순서로 진행합니다.
...

작성 방식(書き方)으로 결정하는 것은 세 가지입니다.

AGENTS.md에는 진행 과정과 읽어야 할 곳만 작성합니다.

규정된 본문은 rules/ 폴더의 각 파일에, 담당별 규정은 team/ 아래 담당 폴더에 작성합니다.

AGENTS.md는 업무를 할 때마다 읽힙니다.

길어지면 AI가 한 번에 읽을 수 있는 양 중 업무에 사용할 분량이 줄어듭니다.

Codex는 총 32 KiB의 제한이 있으며, Claude Code 공식 문서도 CLAUDE.md는 200줄 이내를 권장하고 있습니다.

실행하지 말아야 할 규정은 입구에 작성합니다.

3번째 줄부터 5번째 줄까지는 외부로 나가는 작업, 근거로 삼아도 되는 사실, 외부에서 받은 문서를 처리하는 내용입니다.

담당 파일을 읽기 전에, 어떤 담당에도 해당되는 '해서는 안 될 것'이 먼저 들어갑니다.

전체를 읽게 하지 않습니다.

1번째 줄과 2번째 줄처럼, 분류표로 담당을 하나 선택하고 그 담당의 파일만 읽게 합니다.

18개 담당 파일을 모두 읽은 후에 시작하는 구조는 아닙니다.

스킬도 같은 형태로 양쪽에 배치합니다

절차를 요약한 스킬은 두 도구 모두 SKILL.md을 놓는 폴더에 있습니다.

놓는 위치가 다릅니다.

Codex 공식 문서는 개인용 위치를 ~/.agents/skills로 하고 있습니다.

제 환경(codex-cli 0.158.0)에서는, ~/.codex/skills에 놓은 스킬도 읽혔습니다 (2026년 10월 12일에 Codex에게 사용 가능한 스킬 목록을 답변하게 하여 확인했습니다).

# Claude Code
mkdir -p ~/.claude/skills
cp -R preflight-reviewer ~/.claude/skills/preflight-reviewer
...

SKILL.md의 맨 앞에는 이름과 언제 사용하는지에 대한 설명을 작성합니다.

description은 예를 들어 다음과 같이 작성합니다 (실물은 좀 더 길고 영어 설명도 첨부되어 있습니다).

---
name: preflight-reviewer
description:

## 공개된 항목

- **preflight-reviewer** (무료・MIT): 생성한 세션과 별도의 세션에서 결과물을 검토하는 스킬입니다. `~/.claude/skills/`에도, `~/.codex/skills/`에도 둘 수 있습니다.

https://github.com/kounkt/preflight-reviewer -
**ai-setup-guide** (무료): Mac에 제작 도구가 갖춰져 있는지 목록화하는 환경 점검과 설치 절차입니다.

https://github.com/kounkt/ai-setup-guide -
**AI 직원 일체** (9,800엔・note): 이 글의 시작 부분에 있는 2개 파일을 포함하여, 18명의 담당자가 사용하는 회사 운영 일체로 총 104개의 파일이 있습니다. `AGENTS.md`와 `CLAUDE.md`, 전사 규정 6가지, 담당별 역할 파일, 절차 36개가 포함되어 있습니다. Claude Code와 Codex 모두 설치 방법이 제공됩니다.

https://note.com/kounkt/n/nf6640ae56f4e -
담당별 목록 및 결과물 샘플: https://chiero.jp/skills/

### 토론
![](https://static.zenn.studio/images/drawing/discussion.png)