---
title: "Claude Code와 Codex에서 AGENTS.md 쓰기"
description: "Codex는 기본으로 AGENTS.md를 읽어요. Claude Code 2.1.277 이상은 프로젝트에 CLAUDE.md가 없을 때 이 파일을 읽어요. 둘 다 유지하려면 CLAUDE.md에 @AGENTS.md를 넣으세요."
canonical: "https://logbrew.co/ko/guides/agents-md"
last_updated: "2026-11-10"
---

# Claude Code와 Codex에서 AGENTS.md 쓰기

Codex는 기본으로 `AGENTS.md`를 읽어요. Claude Code 2.1.277 이상은 프로젝트에 `CLAUDE.md`가 없을 때 이 파일을 읽어요. 둘 다 유지하려면 `CLAUDE.md`에 `@AGENTS.md`를 넣으세요.

Claude Code 2.1.319 및 Codex CLI 0.167.0 환경에서 2026년 11월 10일에 테스트

글 [Furkan Erday](https://github.com/furkanerday). LogBrew 창업자 Furkan Erday. 매일 Claude Code와 Codex로 LogBrew를 만들어요.

Canonical: https://logbrew.co/ko/guides/agents-md

## 각 에이전트가 `AGENTS.md`를 불러오는 경우

| 프로젝트에 있는 파일 | Claude Code | Codex |
| --- | --- | --- |
| `AGENTS.md`만 | 불러옴 | 불러옴 |
| `AGENTS.md`와 `CLAUDE.md` | 안 불러옴 | 불러옴 |
| `@AGENTS.md`를 가져오는 `CLAUDE.md` | 불러옴 | 불러옴 |
| `AGENTS.md`에 심볼릭 링크로 연결한 `CLAUDE.md` | 불러옴 | 불러옴 |
| `AGENTS.md`와 `CLAUDE.local.md` | 안 불러옴 | 불러옴 |

각 에이전트가 첫 요청에 담아 보낸 지침을 읽었어요.

## 파일 1개로 두 에이전트 설정하기

### 프로젝트 루트에 AGENTS.md 작성

빌드 명령, 테스트 명령, 코드 규칙을 파일 1개에 모으세요. 두 에이전트 모두 Git 저장소 루트부터 현재 폴더까지 내려가며 이 파일을 읽어요.

### Claude Code 업데이트

Claude Code는 2.1.277 버전부터 `AGENTS.md`를 직접 읽어요. 이전 버전에서는 다음 단계의 가져오기가 필요해요.

```bash
claude update
```

### CLAUDE.md에서 AGENTS.md 가져오기

현재 폴더나 상위 폴더에 `CLAUDE.md`, `.claude/CLAUDE.md`, `CLAUDE.local.md` 중 하나라도 있으면 Claude Code는 `AGENTS.md`를 읽지 않아요. `CLAUDE.md`에 이 줄을 추가하면 두 파일을 모두 불러와요.

```bash
@AGENTS.md
```

### 또는 CLAUDE.md를 AGENTS.md에 링크하기

`CLAUDE.md`에 가져오기 한 줄만 들어간다면 대신 심볼릭 링크로 만드세요.

```bash
ln -s AGENTS.md CLAUDE.md
```

### 또는 설정으로 둘 다 불러오기

`CLAUDE.local.md`를 유지하면서 `AGENTS.md`도 불러오려면 `~/.claude/settings.json`에 이 내용을 추가하세요. 세션에서는 `/config`의 Project instructions 옵션으로 같은 값을 설정할 수 있어요.

```bash
{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}
```

### Codex가 불러온 내용 확인

작업하는 폴더에서 실행하세요. Codex 문서가 안내하는 명령으로, Codex가 불러온 지침을 다시 알려 줘요.

```bash
codex --ask-for-approval never "Summarize the current instructions."
```

## 직접 테스트해 보니

두 에이전트를 로컬 테스트 서버에 연결하고, 각 에이전트가 첫 요청에 담아 보낸 지침을 읽었어요. 이렇게 하면 어떤 파일을 불러오는지 정확히 알 수 있어요.

프로젝트에 `CLAUDE.md`가 없을 때 Claude Code는 `AGENTS.md`를 불러왔고, 디버그 로그에 `no CLAUDE.md found; AGENTS.md loaded`가 찍혔어요. 옆에 `CLAUDE.md`가 있으면 Claude Code는 `AGENTS.md`를 불러오지 않았어요. `@AGENTS.md` 가져오기나 심볼릭 링크를 쓰면 `AGENTS.md` 내용이 정확히 한 번 나타났어요.

위의 `pluginConfigs` 설정은 프로젝트에 `CLAUDE.local.md`가 있어도 두 파일을 모두 불러왔어요.

Codex는 `~/.codex/AGENTS.md`를 먼저 불러오고, 이어서 루트의 `AGENTS.md`, 마지막으로 현재 폴더의 파일을 불러왔어요. `AGENTS.override.md`가 있으면 같은 폴더의 `AGENTS.md`를 대신했어요. `CLAUDE.md`는 `project_doc_fallback_filenames`에 추가하기 전까지 건너뛰었어요. 두 파일이 모두 있으면 Codex는 대체 파일명을 설정해도 `AGENTS.md`만 불러왔어요.

## AGENTS.md와 CLAUDE.md 비교

Codex는 각 폴더의 `AGENTS.override.md` 또는 `AGENTS.md`와 전역 `~/.codex/AGENTS.md`를 읽어요. 기본 한도는 합쳐서 32 KiB예요. `CLAUDE.md`는 `project_doc_fallback_filenames`에 넣었을 때만 읽어요.

Claude Code는 `CLAUDE.md`를 먼저 읽어요. 적용되는 프로젝트 `CLAUDE.md`가 없을 때만 `AGENTS.md`와 `.claude/AGENTS.md`를 읽어요. 개인용 `~/.claude/CLAUDE.md`는 여기에 포함되지 않아서 `AGENTS.md`와 함께 불러와요.

## GitHub 이슈에서 나온 이야기

댓글 409개가 달린 #6235는 Claude Code에 AGENTS.md 지원을 요청했어요. 2026년 8월 17일, Anthropic 엔지니어가 위의 가져오기와 심볼릭 링크 방법을 안내하며 이슈를 닫았어요. 지금은 Claude Code가 이 파일을 직접 읽어요. #31005는 `.agents/skills/` 지원도 요청하고 있고, 아직 열려 있어요.

## 자주 묻는 질문

### Claude Code는 AGENTS.md를 읽나요?

네, 2.1.277 버전부터 읽어요. 단, 현재 폴더나 상위 폴더에 `CLAUDE.md`, `.claude/CLAUDE.md`, `CLAUDE.local.md`가 없어야 해요. 2.1.319에서 확인했어요.

### AGENTS.md와 CLAUDE.md 중 무엇을 써야 하나요?

팀에 Codex나 다른 에이전트를 쓰는 사람이 있다면 `AGENTS.md`를 쓰세요. `CLAUDE.md`는 Claude Code에만 해당하는 규칙용으로만 두고, 그 안에서 `@AGENTS.md`를 가져오세요.

### CLAUDE.md를 AGENTS.md의 심볼릭 링크로 만들어도 되나요?

네. 테스트에서 Claude Code는 링크된 파일을 한 번만 불러왔어요. 가져오기와 같은 결과예요.

### Codex는 CLAUDE.md를 읽나요?

기본으로는 읽지 않아요. `~/.codex/config.toml`에 `project_doc_fallback_filenames = ["CLAUDE.md"]`를 추가하세요.

## 에이전트에게 프로덕션 오류를 보여 주세요

LogBrew MCP 서버를 연결하면 Claude Code나 Codex가 승인한 프로젝트의 오류, 로그, 트레이스를 읽어요. 넉넉한 무료 요금제로 시작하세요. 카드 등록은 필요 없어요.

[에이전트 연결하기](https://logbrew.co/ko/agents)

## 출처

- [Claude Code docs, How Claude remembers your project](https://code.claude.com/docs/en/memory#agents-md)
- [Codex docs, Custom instructions with AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md)
- [anthropics/claude-code#6235](https://github.com/anthropics/claude-code/issues/6235)
- [anthropics/claude-code#31005](https://github.com/anthropics/claude-code/issues/31005)

## AI 코딩 에이전트 가이드 더 보기

- [Claude Code와 Codex에 MCP 서버 추가하기](https://logbrew.co/ko/guides/mcp-server-claude-code-codex)
- [Claude overloaded 529 오류와 rate limit 429 오류 해결하기](https://logbrew.co/ko/guides/claude-overloaded-rate-limit-error)
- [Claude Code, Codex, 브라우저 JavaScript 오류 해결법](https://logbrew.co/ko/guides)