[AI] AGENTS.md 사용법: 코딩 에이전트 지침 파일 하나로 쓰기
· IT기술 › AI
Codex 로 작업하다 Claude Code 를 열면 지침 파일부터 다시 챙겨야 한다. 도구마다 찾는 파일 이름이 달라서다. 시리즈 1편에서는 CLAUDE.md 에 결정을 쌓아 두는 법을 다뤘는데, Gemini CLI 까지 쓰면 같은 내용을 파일 세 개에 복사하게 된다. 한쪽만 고치면 지침이 어긋난다.
공용 지침 파일 AGENTS.md 는 이걸 파일 하나로 모으자는 형식이다. 설정에 손이 가는 쪽은 Claude Code 다.
1. AGENTS.md 란
코딩 에이전트용 지침을 담는 공용 형식으로, 공식 사이트는 에이전트용 README 라고 부른다. 관리는 Linux Foundation 산하 Agentic AI Foundation 이 한다.
필수 필드가 없는 일반 Markdown 이고, 저장소 루트에 둔다. 하위 폴더마다 둘 수도 있는데, 가장 가까운 파일이 우선한다. 채팅으로 준 지시는 그보다 우선한다.
권장 내용은 프로젝트 개요, 빌드·테스트 명령, 코드 스타일, 보안 주의 사항 정도다.
# 할 일 관리 예제 앱
## 빌드·테스트
- 백엔드 테스트: `./gradlew test`
- 프론트 개발 서버: `cd frontend && npm run dev`
## 코드 스타일
- Java 는 4칸 들여쓰기, Vue 는 `<script setup>` + TypeScript
## 지켜야 할 것
- `.env` 와 비밀값은 읽거나 커밋하지 않는다
- 커밋 메시지는 `feat:`, `fix:` 접두어를 붙인다
2. Codex·Gemini CLI 에서 읽게 하기

AGENTS.md 하나를 세 도구가 각자의 방식으로 읽는다.
Codex 는 설정 없이 AGENTS.md 를 읽는다. 저장소 루트부터 현재 폴더까지 폴더마다 하나씩 이어 붙인다. 가까운 폴더의 지시가 뒤에 오니 앞의 것을 덮는다. 같은 폴더에 AGENTS.override.md 가 있으면 그것을 대신 읽는다.
Gemini CLI 는 기본으로 GEMINI.md 를 읽으니, 프로젝트 루트의 .gemini/settings.json 에 파일 이름을 적어 준다.
{
"context": {
"fileName": "AGENTS.md"
}
}
기존 GEMINI.md 도 계속 쓸 거라면 ["AGENTS.md", "GEMINI.md"] 처럼 배열로 주면 된다.
3. Claude Code 는 조건부로 읽는다
Claude Code 도 v2.1.277(2026년 9월)부터 AGENTS.md 를 직접 읽지만, 항상은 아니다. 기본 설정의 규칙은 이렇다.
| 저장소에 있는 파일 | Claude Code 가 읽는 것 |
|---|---|
| AGENTS.md 만 있음 | AGENTS.md |
| AGENTS.md 와 CLAUDE.md 가 함께 있음 | CLAUDE.md 만 |
CLAUDE.md 가 @AGENTS.md 를 import 함 |
CLAUDE.md + AGENTS.md |

기본 설정에서는 CLAUDE.md 계열 파일이 하나라도 있으면 AGENTS.md 를 건너뛴다.
여기서 CLAUDE.md 계열은 작업 폴더와 상위 폴더의 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md 세 가지다. 홈 폴더의 ~/.claude/CLAUDE.md 는 판단에서 빠지고 함께 읽힌다.
가장 헷갈리는 건 개인 메모용 CLAUDE.local.md 다. 이 파일 하나만 추가해도 AGENTS.md 가 빠진다. Claude Code 2.1.326 에서 /context 로 확인해 보니 실제로 CLAUDE.local.md 만 남았고, 빈 파일은 영향이 없었다.
4. CLAUDE.md 도 함께 쓰고 싶을 때
Claude Code 전용 지시가 있다면 CLAUDE.md 첫 줄에서 AGENTS.md 를 가져온다.
@AGENTS.md
## Claude Code 에서만
- 작업을 마치면 `./gradlew test` 결과를 세 줄로 요약해 보고한다
@AGENTS.md 가 가리킨 파일을 먼저 읽고 나머지를 읽는다.
전용 내용이 없으면 심볼릭 링크(ln -s AGENTS.md CLAUDE.md)도 된다. /config 의 Project instructions 를 claude-md-and-agents-md 로 바꿔 두 파일을 모두 읽게 할 수도 있다. 그래도 여럿이 쓰는 저장소라면 import 가 낫다. 나머지 둘은 아래 주의할 점에 걸린다.
5. 주의할 점
- 심볼릭 링크 : Windows 에서 클론하면 링크가 한 줄짜리 텍스트 파일이 될 수 있다. 공식 문서도 이때는 import 를 권한다.
/config설정 : 내 컴퓨터 설정이라 저장소로 공유되지 않는다.- Claude Code 가 읽지 않는 파일 :
AGENTS.local.md,AGENTS.override.md,.agents/폴더. - 버전 : 아래 경우에는 AGENTS.md 를 읽지 못한다.
claude --version으로 2.1.281 이상인지,/config에 Project instructions 항목이 보이는지 확인하자.- v2.1.277 미만
- v2.1.276 이하에서 업데이트한 직후 첫 세션
- v2.1.281 미만에서 Bedrock·Vertex AI 를 쓰거나 텔레메트리를 끈 세션
- 확인 목록 : v2.1.280 전에는 AGENTS.md 를 읽어도
/memory·/context목록에 나오지 않는다.
여러 도구를 번갈아 쓴다면 공통 지침은 AGENTS.md 에 두고, Claude Code 전용 몇 줄만 CLAUDE.md 에서 import 하는 구성이 가장 덜 꼬인다. 설정만 하고 끝내지 말고, 대화형 세션 시작 때 나오는 AGENTS.md loaded 안내 줄이나 /memory·/context 목록에서 AGENTS.md 를 확인하자. CLAUDE.local.md 를 새로 만든 날에도 다시 열어 봐야 한다.