[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 는 기본으로 읽고, Gemini CLI 는 settings.json 의 context.fileName 설정으로 읽고, Claude Code 는 CLAUDE.md 가 없을 때 직접 읽거나 CLAUDE.md 의 @AGENTS.md import 로 읽는 구조

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 Code v2.1.277 이상 기본 설정에서, 작업 폴더나 상위 폴더에 CLAUDE.md 계열 파일이 없으면 AGENTS.md 를 읽고, 있으면 CLAUDE.md 가 @AGENTS.md 를 import 할 때만 두 파일을 함께 읽고 아니면 CLAUDE.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 를 새로 만든 날에도 다시 열어 봐야 한다.

참고