AI 코딩 에이전트를 사용하면서 이런 경험을 해본 적 없으신가요?

• 테스트 실행 명령어를 매번 채팅으로 설명하고 있다
• "이 프로젝트는 이런 디렉토리 구조야"라고 말했는데, 다음 세션에서는 잊어버리고 있다
• 커밋 메시지(Commit message) 규약을 지키지 않아 매번 수정하고 있다
• "운영 환경(Production) 설정 파일은 건드리지 마"라고 전달했는데, 또 건드려서 가슴이 철렁했다

솔직히 말씀드리겠습니다. 이것은 에이전트가 똑똑하지 않아서가 아닙니다. 대부분의 경우, 원인은 "프로젝트의 전제를 매번 처음부터 설명하고 있기" 때문입니다. 인간 신입 사원도 온보딩(Onboarding) 자료가 한 장도 없다면, 매번 선배에게 똑같은 것을 물어볼 수밖에 없습니다. AI 에이전트도 완전히 마찬가지입니다.

그 "매번 설명하는 것"을 하나의 파일로 고정하여, 에이전트가 세션 시작 시 자동으로 읽도록 만드는 메커니즘이 이 기사의 테마입니다. 구체적으로는 AGENTS.md와 CLAUDE.md라는 두 가지 지시 파일입니다. 2026년, 이 두 가지는 "AI 에이전트를 사용한다면 가장 먼저 정비해야 할 것"이 되었습니다.

【경계 설정】 이전에 Claude Code의 hooks(훅)를 통해 "위험한 명령어를 구조적으로 막는" 방법에 대해 글을 쓴 적이 있습니다. 그것은

실행을 막는 메커니즘이었습니다. 이번에는 그 전 단계인, "무엇을 지켜야 하는가·어떤 전제하에 움직여야 하는가"라는 문맥(Context)을 전달하는 설계에 관한 이야기입니다. 층위가 다르기 때문에 두 가지를 모두 세트로 적용하면 효과적입니다.

그리고 가장 먼저, 가장 중요한 것을 짚고 넘어가겠습니다. 바로 역할 분담입니다.

지시 파일은 "AI에게 통째로 맡겨서 자동 생성"하는 것이 아니라, 인간이 "무엇을 지키게 하고 싶은가"를 결정하고, AI에게 언어화를 도와달라고 요청하는 것입니다. 이 점을 파악하면 이후의 이야기가 모두 연결됩니다.

한마디로 말하면, **AGENTS.md는 "AI 에이전트용 취급 설명서"**입니다.

README.md가 "인간 개발자용 설명서"라면, AGENTS.md는 "AI 에이전트용 설명서"입니다. 리포지토리(Repository)의 루트(최상위 폴더)에 두면, 대응하는 에이전트가 작업을 시작하기 전에 자동으로 읽어줍니다.

"README에 쓰면 되잖아"라고 생각할 수도 있습니다. 하지만 README는 인간을 위한 것이라 "프로젝트의 매력"이나 "사용법"이 중심이며, 에이전트가 정말로 필요로 하는 "테스트 실행 방법", "건드려서는 안 되는 곳"과 같은 실무 정보는 묻히기 쉽습니다. AGENTS.md는 그 부분을 에이전트 관점에서 분리하기 위한 장소인 셈입니다.

내용은 단순한 Markdown이며, 정해진 스키마(Schema, 형식의 제약)는 없습니다. 자주 작성되는 내용은 다음과 같습니다.

• 프로젝트 개요 및 개발 환경의 소소한 팁
• 빌드·설치·테스트 명령어
• 코드 스타일 및 명명 규약(Naming convention)
• 테스트 및 PR(Pull Request) 방식
• 보안 주의 사항, 배포 절차

이 부분은 사실 확인된 수치이므로 근거와 함께 적어둡니다.

• AGENTS.md는 2025년에 등장한 오픈 표준으로, 2026년 시점 공식 사이트에 따르면 6만 개 이상의 OSS 리포지토리에서 사용되고 있습니다.
• OpenAI Codex / Cursor / GitHub Copilot / Google Jules / Aider / Windsurf / Zed / Sourcegraph Amp 등 20개 이상의 도구가 대응합니다. 하나의 AGENTS.md가 여러 에이전트에 동시에 적용된다는 점이 최대의 이점입니다.
• 현재는 Linux Foundation 산하의 Agentic AI Foundation이 주도하고 있습니다.

즉, 도구마다 제각각의 독자적인 파일을 작성하지 않아도, AGENTS.md 한 장으로 "공통 언어"가 되는 방향으로 세계가 움직이고 있다는 뜻입니다. (출처는 기사 말미에 기재합니다)

한 가지 주의할 점이 있습니다.

Anthropic의 Claude Code는 이 AGENTS.md를 네이티브로 읽지 않습니다. Claude Code는 독자적인 CLAUDE.md를 사용합니다. 이 두 가지의 관계는 후반부에서 명확히 정리할 것이므로, 일단 "표준 AGENTS.md와 Claude 전용 CLAUDE.md가 있다"라고만 기억해 두세요.

이론보다 먼저, 작동하는 결과물 하나를 만들어 봅시다. 어렵게 생각하지 않아도 괜찮습니다. 우선 이것을 리포지토리 루트에 AGENTS.md라는 이름으로 두기만 하면 됩니다. 범용 샘플이므로, 자신의 프로젝트에 맞춰 내용을 교체해 주세요.

# AGENTS.md
## 프로젝트 개요
- TypeScript + React Web 앱. 패키지 관리는 pnpm.
...

이것만으로도, 대응 에이전트는 "pnpm을 사용한다", "테스트는 pnpm test를 사용한다", "production.ts는 건드리지 않는다"를 매번 설명하지 않아도 이해하게 됩니다.

포인트는, "코드를 읽으면 알 수 있는 것"은 쓰지 않는 것입니다. 예를 들어 "React를 사용하고 있습니다"는 코드를 보면 즉시 알 수 있으므로, 굳이 쓸 가치가 적습니다. 반대로 "왠지 모르겠지만 production.ts만큼은 건드리지 않았으면 좋겠다"와 같이, 코드에서는 읽어낼 수 없는 "인간의 의도"야말로 여기에 쓸 가치가 있는 것입니다.

Claude Code를 사용하는 사람은 /init이라는 명령어를 입력하면, 프로젝트를 자동으로 분석하여 CLAUDE.md의 초안을 만들어 줍니다. 처음부터 쓰는 것이 힘들다면, 우선 /init으로 초안을 뽑아낸 뒤 거기서부터 깎아 나가는 것이 빠릅니다.

자, 이제 여기가 이 기사에서 가장 중요한 부분입니다.

많은 사람이 지시 파일에서 반대 방향으로 노력하곤 합니다. "지켜주지 않는다면, 더 세밀하게, 더 많이 쓰면 된다"라고 말이죠.

하지만, 이것은 역효과를 낳습니다.

Claude Code의 공식 베스트 프랙티스(Best Practice)는 명확하게 말하고 있습니다. 지시 파일은 비대해지면 오히려 무시되기 쉬워진다라고 말입니다. 기준으로 루트 파일은 30행 정도, 길어도 파일당 200행 미만이 권장됩니다 (이는 기준일 뿐 절대적인 규칙은 아니지만, 방향성으로서 매우 올바른 수치입니다).

왜일까요? 인간도 A4 용지 한 장 분량의 온보딩(Onboarding) 자료라면 읽지만, 100페이지짜리 두꺼운 사내 규정은 아무도 읽지 않는 것과 같습니다. AI 에이전트도 방대한 지시에 파묻히면 무엇이 정말 중요한지 알 수 없게 됩니다. 따라서 "전부 적는 것"은 "아무것도 지켜지지 않는 것"에 가까워지는 길입니다.

그러므로 지시 파일을 작성할 때의 주문은 이것입니다.

각 행에 대해 "이것을 지우면 에이전트가 실수를 할까?"라고 질문하세요. 실수하지 않는다면 지웁니다.

이 질문 하나만으로 파일은 놀라울 정도로 탄탄해집니다.

Before (무시되기 쉬움) — 정보 과다이며, 자명한 내용이 대부분:

## 코딩 규약
이 프로젝트는 TypeScript로 작성되었습니다. TypeScript는 타입이 있는 언어입니다.
변수는 camelCase로 작성합니다. 함수도 camelCase입니다. 인덴트(Indent)는 스페이스 2칸입니다.
...

After (지켜지기 쉬움) — 의도만을 강조 표시와 함께 짧게:

## 코딩 규약 (중요)
- 포맷팅은 Prettier에 맡긴다 (수동으로 맞추지 말 것). 설정은 `.prettierrc`가 유일한 정답이다.
- **YOU MUST**: 외부 API를 호출하는 코드는 반드시 `src/lib/api/`를 경유해야 한다. 직접 fetch 금지.
...

Before는 "TypeScript는 타입이 있는 언어"와 같이 AI가 이미 알고 있는 것으로 행수를 낭비하고 있습니다. After는 이 프로젝트에서만 통용되는 약속에만 집중하여, YOU MUST...

우선순위를 높이고 있습니다. 공식 문서에서도 "IMPORTANT나 YOU MUST와 같은 강조는 효과가 있다"라고 언급하고 있습니다. 에이전트에게 "효과가 있는" 것은 양이 아니라 시그널의 밀도 (Signal Density) 입니다.

여기서 많은 사람들이 혼란을 느낍니다. "결국, 둘 중 무엇을 써야 하는가?"라는 문제입니다. 표로 한꺼번에 정리해 보겠습니다.

여기서 의문이 생길 것입니다. "그럼 팀에서 Cursor도 Claude Code도 사용하고 있다면, AGENTS.md와 CLAUDE.md를 둘 다 수동으로 작성해야 하나요? 그건 이중 관리 아닌가요?"라고 말이죠.

맞습니다. 두 가지를 모두 수동으로 유지 관리하면 반드시 한쪽이 오래되어 괴리가 발생합니다. 이는 피하고 싶은 상황입니다.

Claude Code의 CLAUDE.md에는 import라는 기능이 있습니다. @파일 경로라고 작성하면, 해당 파일의 내용을 읽어들일 때 그 자리에 펼쳐줍니다. 별도의 문서를 끼워 넣는 이미지입니다.

이를 사용하면, 내용의 본체는 AGENTS.md 한 장에 집약하고, CLAUDE.md에서는 그것을 가져오기만 하면 됩니다.

# CLAUDE.md
이 프로젝트의 공통 규칙은 AGENTS.md를 유일한 진실의 원천(Single Source of Truth)으로 합니다.
@AGENTS.md
...

이렇게 해두면 규칙을 업데이트할 때 건드리는 곳은 AGENTS.md뿐입니다. Cursor나 Codex는 그대로 AGENTS.md를 읽고, Claude Code는 CLAUDE.md를 통해 동일한 내용을 읽습니다. 한 곳을 수정하면 모든 도구에 반영되므로 괴리가 발생하지 않습니다. 이것이 2026년 실무에서의 정석적인 패턴입니다.

import의 세부 사양도 파악해 두세요.

• @path/to/file.md 형식을 사용합니다. 상대 경로, 절대 경로, ~ (홈 디렉토리)를 사용할 수 있습니다.
• import된 대상이 다시 다른 파일을 import하고 있어도 괜찮습니다 (재귀적 작동. 깊이는 약 4~5단계까지 가능).
• 경로를 백틱(backtick)으로 감싸면 import되지 않고, 단순한 문자열로 취급됩니다 (@README와 같이 단순히 "언급"만 하고 싶을 때 사용).
• 처음으로 외부 파일을 import할 때는 승인 다이얼로그가 나타납니다.
• 주의할 점은, import가 컨텍스트 소비량을 줄여주는 것은 아니라는 점입니다. 내용은 전부 읽어 들여집니다. 어디까지나 "정리 및 단일 소스화"를 위한 기능이라고 이해해 두시기 바랍니다.

작은 프로젝트라면 루트(root)에 한 장만 있어도 충분합니다. 하지만 monorepo (하나의 리포지토리 안에 여러 앱이나 패키지가 공존하는 구성)라면 이야기가 달라집니다.

프론트엔드와 백엔드는 테스트 명령어도, 코드 규약도 다릅니다. 그것을 전부 루트의 파일 한 장에 적으면 순식간에 비대해져서 다시 "무시되는 파일"로 돌아가게 됩니다.

이때 사용하는 것이 nested (중첩) 배치입니다. AGENTS.md와 CLAUDE.md 모두 서브 디렉토리마다 배치할 수 있으며, 에이전트는 작업 중인 위치에서 가장 가까운 파일을 우선하여 읽습니다.

my-monorepo/
├── AGENTS.md # 전체 공통 규칙 (최소한으로)
├── apps/
...

이렇게 하면 에이전트가 apps/api/ 안에서 작업할 때는 루트의 공통 규칙 + apps/api/AGENTS.md의 고유 규칙이 적용됩니다. 가까운 쪽이 우선순위를 가지므로, "백엔드는 pytest를 사용한다"와 같은 고유한 사정을 프론트엔드에 흘리지 않고 전달할 수 있습니다. 게다가 하위 파일은 해당 디렉토리에서 작업할 때 필요에 따라 읽히기 때문에, 항상 전부를 읽게 하여 컨텍스트를 압박하는 일도 없습니다.

리포지토리가 커질수록, "공통 사항은 얇게, 고유 사항은 가까이" 원칙이 효과를 발휘합니다.

지시 파일 자체를 AI에게 도움받도록 합시다. 그대로 사용할 수 있는 프롬프트 예시 3가지를 소개합니다. 역할 분담 측면에서 '언어화와 재고 조사(Inventory)' 부분을 AI에게 맡기는 이미지입니다.

당신은 이 리포지토리의 온보딩 담당자입니다.
다음 정보를 바탕으로 AI 코딩 에이전트용 AGENTS.md 초안을 작성해 주세요.
# 제약 사항
...

다음은 현재의 CLAUDE.md입니다. 내용이 비대해져서 에이전트가 지시 사항을 지키지 않습니다.
다음 기준에 따라 '삭제 후보', '유지', '링크로 대체'의 3가지로 분류하고, 이유를 한 문장씩 덧붙여 주세요.
- 삭제 후보: 언어 표준, 코드에서 자명한 내용, 오래되기 쉬운 정보
...

이 프로젝트에는 '외부 API는 src/lib/api/를 경유한다'라는 규약이 있는데,
에이전트가 직접 fetch 하는 코드를 작성합니다.
원인을 다음 관점에서 분류해 주세요.
...

프롬프트 3과 같은 '지켜지지 않는 원인 진단'은 특히 유용하며, 대부분의 원인은 '쓰여 있지 않거나', '묻혀 있거나', '모순되는' 세 가지로 집약됩니다. 사람이 이 관점을 가지고 있으면 무턱대고 행 수를 늘리는 일을 방지할 수 있습니다.

일관된 점은, '결정·승인'은 사람, '언어화·체크·초안 작성'은 AI라는 선긋기입니다. 지시 파일은 '팀의 약속'이므로, 마지막에 책임지고 commit 하는 것은 사람이라는 원칙은 지키는 것이 좋습니다.

좋은 점만 쓰는 것은 공정하지 않으므로, 이 방법이 효과가 없거나 오히려 해가 되는 조건을 솔직하게 나열하겠습니다. 하나라도 해당된다면 잠시 멈춰주세요.

비대해지면 무시됩니다. 반복해서 말씀드리지만, 이것이 가장 큰 함정입니다. '지켜지지 않으니까 늘린다'는 악순환입니다. 지켜지지 않을 때는 먼저 깎아내는 것을 먼저 시도하세요. -
코드에서 자명한 내용은 쓰는 것이 오히려 역효과입니다. 신호가 희석되어 정말 중요한 지시가 묻히게 됩니다. -
자주 바뀌는 정보는 싣지 마세요. 버전 번호나 이번 스프린트에서만 적용되는 일시적인 사정을 적으면 금방 진부해져서 '거짓말을 하는 파일'이 됩니다. 상세 내용은 링크로 참조하게 하는 것이 안전합니다. -
이중 관리는 괴리를 낳습니다. AGENTS.md와 CLAUDE.md를 모두 수동으로 작성하면 반드시 한쪽이 오래됩니다. 앞서 언급한 import를 통한 단일 소스화로 회피하세요. -
비밀 정보를 절대 적지 마세요. API 키, 토큰, 내부 URL, 개인 정보, 사내 채널 ID 등을 지시 파일에 적으면 git에 올라가 유출됩니다. 지시 파일은 팀과 공유되고 버전 관리된다는 전제가 있습니다. 비밀 정보는 환경 변수나 시크릿 관리 도구로 보내세요. 개인적인 메모는 .gitignore에 추가한 CLAUDE.local.md에 작성하세요. -
채팅에서의 명시적 지시가 우선됩니다. 지시 파일은 '기본 전제'일 뿐, 절대적인 강제력은 아닙니다. 그 자리의 채팅에서

사용하여 내용을 교체한다. Claude Code를 사용한다면 /init 명령어로 초안을 생성한 뒤 다듬는다. -
30행으로 줄인다. 각 행에 대해 "이걸 지우면 실수가 발생할까?"라고 자문하고, 그렇지 않다면 지운다. 자명한 내용이나 금방 쓸모없어질 내용은 과감히 덜어낸다. -
단일 소스(Single Source)로 만든다. Claude Code도 사용한다면, CLAUDE.md에 @AGENTS.md를 작성하여 본체는 AGENTS.md 한 장으로 집약한다. -
git에 commit 하여 팀 표준으로 만든다. 리뷰를 거쳐 반영한다. 이후 규약이 바뀌면 AGENTS.md를 수정한다. 이렇게 하면 "매번 설명해야 하는 번거로움"에서 해방됩니다.

지시 파일은 참 수수한 영역입니다. 화려한 기능도 아니고, 작성한다고 해서 세상이 순식간에 바뀌는 것도 아닙니다. 하지만 이것은 쓰면 쓸수록 자산이 복리로 늘어나는 타입의 투자라고 생각합니다. 오늘 30행을 써두면, 내일의 나도, 다음 달의 팀원도 그만큼 "같은 설명"으로부터 자유로워집니다.

미래의 자신과 팀을 향해, "매번 해야 할 설명"을 한 장에 접어두는 것. 이것이야말로 내일의 내가 "고마워요"라고 말하게 만드는 준비 과정이 아닐까 싶습니다. 작게라도 한 장, 만들어 두시기 바랍니다.

• AGENTS.md 공식 사이트: https://agents.md/
• Claude Code 베스트 프랙티스 (CLAUDE.md 작성법 · 30행 기준 · /init): https://code.claude.com/docs/en/best-practices
• Claude Code 메모리 / import 구문 (@path · monorepo · 계층): https://code.claude.com/docs/en/memory
• AGENTS.md 표준화 배경 (InfoQ): https://www.infoq.com/news/2025/08/agents-md/

※ 본문의 명령어 및 파일 예시는 범용 샘플입니다. 도구의 버전에 따라 동작이 달라질 수 있으므로, 도입 시에는 각 공식 문서에서 최신 사양을 확인하시기 바랍니다. 행 수의 기준(30행/200행)은 공식에서 제시하는 권장 값이며, 절대적인 제약은 아닙니다.

생성형 AI 활용 엔지니어 & 세 아이의 아빠. AI × 개발의 실천적 지식을 매일 발신하고 있습니다 → X: https://x.com/akira_papa_AI