AGENTS.md와 CLAUDE.md(에이전트 지침 파일) 뜻과 작성법

Q: 나만 쓰는 규칙은 어디에 적나요?

도구마다 개인용 위치가 따로 있습니다. 코덱스는 홈 폴더의 `~/.codex/AGENTS.md`, 클로드 코드는 `~/.claude/CLAUDE.md`, 제미나이 CLI는 `~/.gemini/GEMINI.md`를 전역 지침으로 읽습니다. 팀 저장소의 지침 파일에는 모두가 지켜야 할 규칙만 둡니다.

에이전트 지침 파일은 AI 에이전트가 작업을 시작할 때 자동으로 읽어 들이는 프로젝트 안내문이고, AGENTS.md는 여러 코딩 에이전트가 함께 읽도록 만든 공개 형식입니다. CLAUDE.md는 클로드 코드가 기본으로 읽는 같은 성격의 파일입니다.

같은 말:AGENTS.mdAGENTS.md 뜻CLAUDE.md AGENTS.md 차이GEMINI.md에이전트 지침 파일

홍승협(준이아빠)게시 2026.10.01코스 3 / 12번째 개념

새로 올라온 개념이에요. 먼저 읽어 보고 퀴즈도 풀어 보세요

#AI #바이브코딩 #자동화

🤔 도구를 바꿀 때마다 같은 규칙을 다시 적어야 할 때
🔑 에이전트 지침 파일과 AGENTS.md의 정의
🗂️ 도구별로 읽는 지침 파일
📍 폴더 여러 곳에 두었을 때 읽는 순서
✍️ 지침 파일에 적는 것
🚫 지침 파일로 막을 수 없는 것
🔗 여러 도구의 지침을 한 벌로 관리하는 방법
⚠️ 지침 파일을 쓸 때 자주 하는 실수
❓ 자주 묻는 질문
📋 3줄 요약
📚 참고 자료

🤔 도구를 바꿀 때마다 같은 규칙을 다시 적어야 할 때

한 프로젝트에서 클로드 코드와 코덱스를 번갈아 쓰기 시작하면 금방 겪는 일이 있습니다. 클로드 코드에는 CLAUDE.md에 "테스트는 npm test로 돌리고 새 라이브러리는 설치하지 않는다"라고 적어 두었는데, 코덱스는 그 파일을 읽지 않아 다른 명령으로 테스트를 돌리고 라이브러리를 하나 더 설치합니다. 코덱스용 파일을 따로 만들어 같은 규칙을 적으면 당장은 해결되지만, 몇 주 뒤에는 두 파일의 내용이 조금씩 달라져 있습니다.

이 문제를 줄이려고 나온 것이 AGENTS.md라는 공통 파일 이름입니다. 지금부터 에이전트 지침 파일이 무엇인지, 도구마다 어느 파일을 어떤 순서로 읽는지, 무엇을 적고 무엇은 다른 곳에 두어야 하는지를 도구 이름과 상관없이 통하는 원리로 정리합니다. 클로드 코드의 메모리 기능 자체는 클로드 코드 메모리와 CLAUDE.md에서 다뤘습니다.

🔑 에이전트 지침 파일과 AGENTS.md의 정의

에이전트 지침 파일은 AI 에이전트가 작업을 시작할 때 자동으로 읽어 들이는 프로젝트 안내문이고, AGENTS.md는 여러 코딩 에이전트가 함께 읽도록 만든 공개 형식입니다.

사람을 위한 설명서가 README라면, 에이전트를 위한 설명서가 지침 파일입니다. AGENTS.md 공식 사이트도 이 파일을 에이전트를 위한 README라고 소개합니다. 형식은 평범한 마크다운이고 반드시 채워야 하는 항목은 없습니다. 2026년 9월 28일 기준 공식 사이트는 6만 개가 넘는 오픈소스 프로젝트가 이 파일을 쓰고 있고, 리눅스 재단 산하 Agentic AI Foundation이 관리한다고 밝힙니다.

지침 파일이 필요한 이유는 에이전트 루프의 구조에 있습니다. 모델은 앞의 대화를 따로 기억하지 않기 때문에 세션을 새로 열면 프로젝트의 규칙을 처음부터 모릅니다. 지침 파일은 세션이 시작될 때마다 대화 앞부분에 자동으로 들어가서, 매번 설명하지 않아도 같은 규칙으로 일하게 만듭니다.

🗂️ 도구별로 읽는 지침 파일

도구마다 기본으로 찾는 파일 이름이 다릅니다. 2026년 9월 28일 각 도구의 공식 문서 기준입니다.

도구	기본 파일	AGENTS.md를 읽는지	알아 둘 조건
코덱스(OpenAI)	AGENTS.md	읽습니다	같은 폴더에 AGENTS.override.md가 있으면 그것을 먼저 씁니다. 합친 크기가 기본 32KiB를 넘으면 그 뒤 파일은 더하지 않습니다
클로드 코드(앤트로픽)	CLAUDE.md	조건부로 읽습니다	v2.1.277부터 작업 폴더와 그 위쪽에 CLAUDE.md가 없을 때만 AGENTS.md를 대신 읽습니다
제미나이 CLI(구글)	GEMINI.md	설정하면 읽습니다	설정 파일의 `context.fileName`에 AGENTS.md를 넣으면 함께 읽습니다
깃허브 코파일럿	AGENTS.md	읽습니다	저장소 어디에 두어도 되고, 루트의 CLAUDE.md나 GEMINI.md 하나를 대신 쓸 수도 있습니다

AGENTS.md 공식 사이트에는 지원 도구로 코덱스, 커서, 제미나이 CLI, 깃허브 코파일럿 코딩 에이전트, 제드, 윈드서프를 포함해 23개 이름이 올라 있습니다. 클로드 코드는 이 목록에 없지만, 클로드 코드 문서는 v2.1.277부터 앞의 조건으로 AGENTS.md를 직접 읽는다고 설명합니다. 두 사실을 함께 알아 두어야 목록만 보고 지원하지 않는다고 오해하지 않습니다. 클로드 코드 쪽의 세부 조건과 설정값은 클로드 코드 AGENTS.md 지원 정리에 따로 있습니다.

📍 폴더 여러 곳에 두었을 때 읽는 순서

지침 파일은 저장소 루트에만 두는 것이 아닙니다. 건물 공동현관에 전체 안내문이 붙어 있고 각 사무실 문 앞에 그 팀의 안내문이 따로 붙어 있듯, 하위 폴더마다 그 폴더에만 해당하는 지침을 둘 수 있습니다. 여러 파일이 있을 때 도구가 무엇을 어떻게 합치는지는 도구마다 조금씩 다릅니다.

AGENTS.md 형식의 원칙: 에이전트는 디렉터리 트리에서 가장 가까운 파일을 읽고, 고치는 파일에 가장 가까운 AGENTS.md가 우선합니다. 대화에서 사람이 직접 준 지시는 모든 파일보다 우선합니다
코덱스: 저장소 루트부터 지금 작업 중인 폴더까지 내려오며 폴더마다 파일 하나씩을 이어 붙입니다. 가까운 폴더의 지침이 뒤에 놓이므로 앞의 지침을 덮어씁니다
클로드 코드: 작업 폴더와 그 위 폴더들의 CLAUDE.md를 모두 읽어 하나로 합칩니다. 두 규칙이 서로 어긋나면 어느 한쪽을 임의로 고를 수 있다고 공식 문서가 적고 있습니다

세 방식 모두 가까운 안내문이 더 구체적인 규칙이라는 가정 위에 있습니다. 그래서 루트에는 저장소 전체에 통하는 규칙만 두고, 폴더별 예외는 그 폴더의 파일에 적는 편이 충돌을 줄입니다. OpenAI의 대표 저장소 하나에는 AGENTS.md가 88개 있다고 공식 사이트가 소개할 만큼, 큰 저장소에서는 폴더별로 나눠 두는 방식이 흔합니다.

✍️ 지침 파일에 적는 것

AGENTS.md 공식 사이트가 권하는 항목은 다섯 가지입니다.

프로젝트 개요: 무엇을 하는 프로젝트이고 주요 폴더가 어떻게 나뉘는지
빌드와 테스트 명령: 설치, 실행, 테스트, 검사에 쓰는 정확한 명령
코드 스타일: 이름 짓는 방식, 쓰는 언어와 라이브러리 범위
테스트 지침: 무엇을 고치면 어떤 테스트를 돌려야 하는지
보안 주의점: 건드리면 안 되는 파일, 비밀 값을 다루는 방식

실제 파일은 이 정도 분량이면 시작하기에 충분합니다. 가상의 예시입니다.

# AGENTS.md

## 프로젝트
Next.js 블로그. 글은 content/, 화면 코드는 src/에 있다.

## 명령
- 설치: npm install
- 검사: npm run lint
- 빌드: npm run build (오류 0건이어야 완료)

## 규칙
- 새 라이브러리를 설치하기 전에 먼저 묻는다
- 태그는 src/lib/constants.ts의 목록에서만 고른다
- 테스트가 실패하면 테스트가 아니라 코드를 고친다

## 건드리지 않는 것
- .env 파일, public/og/ 폴더의 기존 이미지

길이는 짧을수록 잘 지켜집니다. 클로드 코드 문서는 CLAUDE.md 한 파일을 200줄 아래로 두라고 권하면서, 길어질수록 컨텍스트를 더 차지하고 지시를 따르는 비율이 떨어진다고 설명합니다. OpenAI는 2026년 2월 공개한 하네스 엔지니어링 글에서 AGENTS.md를 백과사전이 아니라 목차로 다루고 100줄 안팎으로 유지한다고 적었습니다. 자세한 설명은 별도 문서에 두고 지침 파일에는 그 문서의 경로를 적는 방식입니다.

무엇을 넣을지 고를 때는 코드를 읽어서는 알 수 없는 것을 기준으로 삼으면 편합니다. 폴더 목록이나 의존성 목록은 에이전트가 파일을 열어 보면 알 수 있지만, "태그는 이 목록에서만 고른다"는 팀의 약속은 어디에도 적혀 있지 않으면 알 방법이 없습니다.

🚫 지침 파일로 막을 수 없는 것

지침 파일은 안내문이지 잠금장치가 아닙니다. 클로드 코드 공식 문서는 CLAUDE.md를 강제 설정이 아니라 참고 자료로 다룬다고 적고, 클로드의 판단과 상관없이 어떤 동작을 막으려면 훅을 쓰라고 안내합니다. 다른 도구도 지침 파일을 모델에게 주는 글로 넣는다는 점은 같습니다.

하려는 것	두는 곳
특정 명령, 폴더, 파일 접근을 막는다	도구의 권한 설정
저장이나 커밋 직전에 검사를 반드시 돌린다	훅이나 CI 같은 자동 검사
코드 스타일과 작업 순서를 알린다	지침 파일
여러 단계로 된 긴 절차를 남긴다	스킬이나 별도 문서

어겼을 때 곤란한 정도로 나누면 판단이 쉽습니다. 한 번 어기면 되돌리기 어려운 것은 권한과 훅으로 막고, 알려 두면 대체로 지켜지는 것은 지침 파일에 둡니다.

🔗 여러 도구의 지침을 한 벌로 관리하는 방법

규칙을 도구마다 복사해 두면 반드시 어긋납니다. 원본은 한 파일에 두고 나머지는 그 파일을 가리키게 만드는 것이 원칙이고, 이 원칙을 SSOT(단일 진실 공급원)라고 부릅니다. 개념은 SSOT 정리에 있습니다.

AGENTS.md를 원본으로 둡니다: 코덱스와 코파일럿은 그대로 읽습니다
클로드 코드에는 가져오기 한 줄을 둡니다: CLAUDE.md에 @AGENTS.md를 적으면 AGENTS.md 내용을 불러와 함께 읽습니다. 클로드에게만 줄 규칙이 있으면 그 아래에 덧붙입니다
제미나이 CLI에는 설정을 바꿉니다: .gemini/settings.json의 context.fileName에 AGENTS.md를 넣습니다
심볼릭 링크는 조심해서 씁니다: CLAUDE.md를 AGENTS.md로 연결하는 방법도 있지만, 클로드 코드 문서는 프로젝트에 윈도우 사용자가 있으면 피하라고 안내합니다

⚠️ 지침 파일을 쓸 때 자주 하는 실수

서로 어긋나는 규칙을 남겨 둡니다: 루트와 하위 폴더, 개인 파일과 프로젝트 파일에 반대되는 규칙이 있으면 에이전트가 어느 쪽을 따를지 보장되지 않습니다
코드에서 알 수 있는 내용으로 채웁니다: 폴더 구조를 길게 옮겨 적으면 정작 지켜야 할 규칙이 눈에 덜 띄어 덜 지켜집니다
비밀 값을 적습니다: 지침 파일은 저장소에 함께 올라가는 경우가 많아 API 키나 비밀번호를 적으면 그대로 공개됩니다
한 번 쓰고 고치지 않습니다: 앤트로픽 AI 네이티브 개발 플레이북은 클로드가 같은 실수를 두 번 하면 그 교정을 CLAUDE.md에 적으라고 권합니다. 지침 파일은 실수가 나올 때마다 한 줄씩 자라는 문서입니다

❓ 자주 묻는 질문

AGENTS.md와 README.md는 무엇이 다른가요?

README는 사람이 프로젝트를 이해하도록 쓰는 문서이고, AGENTS.md는 에이전트가 작업할 때 필요한 명령과 규칙을 모아 두는 문서입니다. 사람에게는 길고 친절한 설명이 필요하지만 에이전트에게는 정확한 명령과 금지 사항이 더 쓸모가 있어서 둘을 나눠 둡니다. 겹치는 설명은 README에 두고 AGENTS.md에서 경로만 알려 줘도 됩니다.

클로드 코드에서 CLAUDE.md를 지우고 AGENTS.md만 두면 되나요?

v2.1.277 이상이고 작업 폴더와 그 위쪽 어디에도 CLAUDE.md가 없으면 AGENTS.md를 읽습니다. 상위 폴더에 CLAUDE.md가 하나라도 남아 있거나 개인용 CLAUDE.local.md가 있으면 AGENTS.md는 읽지 않으므로, 두 파일을 함께 두려면 CLAUDE.md에 @AGENTS.md를 적는 방법이 가장 확실합니다.

지침 파일은 얼마나 길게 써도 되나요?

파일이 잘리지 않더라도 길수록 덜 지켜집니다. 클로드 코드 문서는 파일 하나를 200줄 아래로 권하고, 코덱스는 합친 크기가 기본 32KiB를 넘으면 그 뒤 파일을 더하지 않습니다. 긴 절차나 참고 자료는 별도 문서로 빼고 지침 파일에는 그 경로만 남기는 편이 낫습니다.

나만 쓰는 규칙은 어디에 적나요?

도구마다 개인용 위치가 따로 있습니다. 코덱스는 홈 폴더의 ~/.codex/AGENTS.md, 클로드 코드는 ~/.claude/CLAUDE.md, 제미나이 CLI는 ~/.gemini/GEMINI.md를 전역 지침으로 읽습니다. 팀 저장소의 지침 파일에는 모두가 지켜야 할 규칙만 둡니다.

📋 3줄 요약

AGENTS.md는 여러 코딩 에이전트가 작업을 시작할 때 함께 읽도록 만든 공개 지침 파일 형식이고 2026년 9월 기준 6만 개가 넘는 오픈소스 프로젝트가 쓰고 있습니다.
코덱스와 깃허브 코파일럿은 AGENTS.md를 바로 읽지만 클로드 코드는 v2.1.277부터 작업 폴더와 그 위쪽에 CLAUDE.md가 없을 때만 AGENTS.md를 대신 읽습니다.
지침 파일은 에이전트가 참고하는 안내일 뿐 강제 설정이 아니어서 반드시 막아야 할 동작은 권한 설정이나 훅으로 따로 막아야 합니다.

📚 참고 자료

AGENTS.md 공식 사이트: https://agents.md/
클로드 코드 문서, How Claude remembers your project: https://code.claude.com/docs/en/memory
OpenAI 코덱스 문서, AGENTS.md: https://developers.openai.com/codex/guides/agents-md
제미나이 CLI 문서, GEMINI.md: https://geminicli.com/docs/cli/gemini-md/
깃허브 문서, Adding repository custom instructions: https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions

제대로 이해했는지 한 문제로 확인해 볼까요?

답을 고르면 바로 풀이가 나와요.

저장소 루트의 AGENTS.md에는 "테스트는 npm test"라고, 하위 폴더 packages/web의 AGENTS.md에는 "테스트는 pnpm test:web"이라고 적혀 있습니다. packages/web의 파일을 고치는 에이전트가 따라야 할 규칙은 어느 쪽일까요?

4개념 / 클래스intent.md 뜻과 작성법: 왜 하는지를 적는 파일