AI에게 매번 프로젝트를 설명하는 것을 그만두기 — AGENTS.md로 코딩 에이전트에게 '리포지토리 탐색법'을 한 장으로 전달하는 실전 가이드

AI에게 코드를 맡길 수 있게 되면서, 확실히 개발 속도는 엄청나게 빨라졌습니다. Cursor, Codex, Claude Code, GitHub Copilot…… 어떤 것을 사용하든 "대략적으로 부탁하면, 그럴싸한 코드가 돌아온다"는 것이 당연해졌죠.

하지만 솔직히 말하면, 저는 어느 날 문득 깨달았습니다.

매번 똑같은 설명을 하고 있지 않나? 라고 말이죠.

• "이 프로젝트는 npm이 아니라 pnpm을 사용합니다" - "테스트는 vitest로, 커밋 전에 반드시 실행해 주세요" - "src/legacy/ 안은 건드리지 마세요"

세션을 열 때마다 이것을 쓰고 있습니다. AI는 똑똑하지만, 똑똑하기 때문에 "말하지 않은 것"은 아무렇지 않게 해버립니다. npm install을 실행해 락 파일(lock file)을 망가뜨리거나, 독자적인 명명 규칙(naming convention)을 무시하거나, 요청하지 않았는데 다른 디렉토리까지 "덤으로" 수정해 오기도 합니다.

그리고 세 번째쯤 같은 주의사항을 말하고 있는 자신을 발견하며, 정말 아깝다라고 생각했습니다. 왜냐하면 이것은 사람으로 치면, 새로운 멤버가 들어올 때마다 구두로 똑같은 온보딩(onboarding)을 반복하고 있는 것과 같은 상태이기 때문입니다.

이 "매번 하는 설명"을 단 하나의 파일로 정리해서 리포지토리에 놓아둘 수 있다면 어떨까요? 게다가 Cursor에서도, Codex에서도, Claude Code에서도, 어떤 도구라도 같은 파일을 읽어준다고 한다면 말이죠.

그것이 이번의 주인공인 AGENTS.md입니다.

이 기사에서는 AGENTS.md가 무엇인지, 왜 2026년에 표준으로서 단번에 확산되었는지, 무엇을 쓰고 무엇을 쓰지 않는지, 그리고 "내일부터 자신의 리포지토리에 바로 적용할 수 있는" 수준의 실제 샘플, 프롬프트, CI 체크까지, AI 개발이 아직 익숙하지 않은 분들도 헤매지 않도록 하나씩 풀어서 써 내려가겠습니다.

먼저 결론부터 말씀드릴게요. AGENTS.md는 AI 에이전트에게 "이 리포지토리의 탐색법"을 전달하는 단 한 장의 취급 설명서입니다. 그리고 완벽할 필요는 없습니다. 우선은 10줄부터 시작해도 충분합니다.

한마디로 말하자면, **AGENTS.md는 "AI용 README"**입니다.

여기서 갑자기 용어 정리를 해두겠습니다. 아는 사람에게는 당연하겠지만, 여기서 막히면 뒤 내용이 전부 흐릿해지기 때문입니다.

• README.md… 사람을 위한 설명서. 프로젝트의 개요, 사용법, 기여 가이드. GitHub 상단에 표시되는 그것입니다. - AGENTS.md… AI 코딩 에이전트를 위한 설명서. 빌드 절차, 테스트 실행 방법, 코드 작성 규칙, 건드리면 안 되는 곳…… 같은, "사람용 README에 쓰기에는 번잡하지만 AI에게는 반드시 전달하고 싶은 것"을 두는 장소.

공식 사이트( https://agents.md/ )에서도 단도직입적으로 **"a README for agents (에이전트를 위한 README)"**라고 표현하고 있습니다.

구조는 어렵지 않으니 등장인물로 정리해 봅시다.

• 에이전트… 당신을 대신해 코드를 읽거나 쓰는 AI (Cursor 내부의 존재, Codex, Claude Code 등). - 리포지토리… 당신의 코드가 들어있는 폴더 전체. - AGENTS.md… 리포지토리 안에 두는 AI용 취급 설명서.

그리고 중요한 점은, 에이전트는 작업을 시작할 때 자동으로 AGENTS.md를 찾아 읽는다는 점입니다. 당신이 "이것 좀 읽어줘"라고 매번 붙여넣지 않아도, 파일이 그곳에 있다면 알아서 가져갑니다. 이것이 README와 결정적으로 다른 부분이며, AGENTS.md는 "두어 놓기만 해도 효과가 있다"는 것입니다.

한 가지만 더 덧붙이자면, 에이전트는 편집하려는 파일에서 보았을 때 가장 가까운(최근접한) AGENTS.md를 우선적으로 읽습니다. 영어로는 closest file wins (가장 가까운 파일이 승리한다)라고 불리는 규칙입니다.

예를 들어 큰 프로젝트에서 루트(root)에도 AGENTS.md가 있고, packages/api/ 안에도 AGENTS.md가 있다고 가정해 봅시다. packages/api/ 안의 코드를 수정할 때는 packages/api/AGENTS.md가 우선됩니다. 집 전체의 규칙과 각 방의 로컬 규칙이 있고, 그 방에 있을 때는 방의 규칙이 우선되는 것과 같은 이미지입니다 (이 모노레포(monorepo) 이야기는 나중에 제대로 다루겠습니다).

참고로, 당신이 채팅으로 직접 내리는 지시는 AGENTS.md보다 강력합니다. 따라서 파일에 적힌 내용이 오래되었더라도, 그 자리에서 "이번에는 이렇게 해줘"라고 말하면 덮어쓸 수 있습니다. 안심하세요.

여기서는 사실을 기반으로 이야기하겠습니다. AGENTS.md가 이 정도로 확산된 데에는 분명한 이유가 있습니다 (2026년 6월 기준).

채택 규모가 매우 큼… 공식 사이트에 따르면, GitHub 상에서 6만 개가 넘는 오픈 소스 프로젝트가 이미 AGENTS.md를 사용하고 있습니다.

특정 도구 전용이 아님… OpenAI Codex, Google의 Jules, Cursor, Amp, Factory와 같은 주체들의 협력으로 탄생한, 도구 비의존적 (vendor-agnostic) 오픈 표준입니다. Claude Code, GitHub Copilot, Aider, Gemini CLI 등도 지원합니다.

든든한 후원자가 있음… 현재는 **Agentic AI Foundation (Linux Foundation 산하)**이 관리 및 발전을 담당하고 있습니다. 한 기업의 변덕으로 사라질 걱정이 적습니다.

여기서 중요한 포인트는, 지금까지는 .cursorrules (Cursor용), CLAUDE.md (Claude용)와 같이 도구마다 제각각인 설정 파일을 작성해 왔다는 점입니다. 도구를 바꿀 때마다 다시 써야 했고, 팀 내에서 사용하는 도구가 다르면 전부 유지보수해야 했습니다. 이게 은근히 고된 작업이었거든요.

AGENTS.md는 이러한 난립을 **"한 장에 모아서 모두가 읽는 것"**으로 바꾸려는 움직임입니다.

README.md	AGENTS.md
읽는 대상	인간
...	...

여기서 잠시, 사고방식에 대한 이야기를 해보겠습니다. AI 시대의 엔지니어링은 지금 조용히 무게 중심이 이동하고 있습니다.

얼마 전까지만 해도 우리는 **프롬프트 엔지니어링 (Prompt Engineering, 프롬프트 설계)**에 몰두했습니다. "어떻게 요청해야 AI가 좋은 답변을 내놓을까". 이것도 중요합니다. 하지만 매번 프롬프트에 프로젝트의 전제 조건을 담는 것은 금방 한계에 부딪힙니다. 대화를 할 때마다 같은 전제를 다시 써야 하기 때문입니다.

여기서 등장하는 것이 **컨텍스트 엔지니어링 (Context Engineering, 문맥 설계)**입니다. 간단히 말해, **"AI에게 매번 설명하는 것을 그만두고, 문맥 그 자체를 설계하여 배치해 두는 것"**이라는 발상입니다. 프롬프트는 일회용 한마디이고, 문맥은 자산입니다. 이 차이가 꽤 본질적이라고 생각합니다.

AGENTS.md는 바로 이 컨텍스트 엔지니어링의 가장 가깝고, 가장 효과적인 실체입니다. 대화 속에 문맥을 흘려보내는 것이 아니라, 리포지토리에 커밋하여 모든 세션, 모든 에이전트, 모든 팀 멤버가 공유하도록 합니다. 한 번 작성해 두면 내일의 나도, 다음 주에 합류할 신규 멤버도, 모레의 AI 세션도 모두 동일한 문맥 위에서 시작할 수 있습니다.

그리고 이것은 엔지니어 역할의 변화 그 자체이기도 합니다. 구현자에서 문맥 설계자로. 코드를 한 줄씩 손으로 쓰는 사람에서, "AI가 올바르게 작동하기 위한 문맥을 설계하는 사람"으로. AGENTS.md는 그 새로운 역할의 가장 첫 번째 결과물이라고 저는 믿습니다.

"AI가 대단하다"에서 끝내지 마세요. 인간이 What(무엇을)과 Why(왜) 그리고 경계를 설계하고, How(어떻게 구현할지)를 AI에게 넘겨주는 것. 이 분담을 파일 한 장으로 표현할 수 있는 것이 바로 AGENTS.md입니다.

그렇다면 내용은 무엇을 적어야 할까요? 공식 문서나 전 세계의 뛰어난 AGENTS.md 사례를 살펴보면 대체로 다음 섹션들로 수렴됩니다.

Project overview (개요)… 어떤 프로젝트인지, 기술 스택은 무엇인지. 1~2문장이면 충분합니다.

Commands (명령어)… 설치, 실행, 빌드, 테스트를 위해 그대로 복사해서 붙여넣을 수 있는 정확한 명령어.

Testing (테스트)… 어떻게 실행하는지, 무엇을 충족해야 통과인지.

Code style (코드 규약)… 포맷, 명명 규칙, import, 설계 선호도.

Boundaries (경계)… 건드리면 안 되는 곳, 해서는 안 되는 일.

Git & PR… 커밋 메시지 형식, PR(Pull Request) 관례.

Gotchas (주의 사항)… 이 프로젝트 특유의 함정이나 주의할 점.

여기서, 이 글에서 여러분이 가장 기억해 가셨으면 하는 원칙을 말씀드리겠습니다.

AGENTS.md에는 「AI가 추론할 수 없는 것만」 적는다.

무슨 뜻일까요? AI는 똑똑하기 때문에, 코드를 보면 알 수 있는 내용은 굳이 쓰지 않아도 압니다. "TypeScript를 사용한다"는 것은 tsconfig.json을 보면 바로 알 수 있습니다. 그것을 AGENTS.md에 적는 것은 그저 노이즈일 뿐입니다.

반대로

작성 내용	어디에 둘 것인가?
언어 · 커밋 규약 · 전체 금지 사항	루트(Root)의 AGENTS.md
...	docs/agent/*.md로 분리하여 참조

이 부분이 제가 가장 중요하다고 생각하는 지점입니다.

AI는 똑똑합니다. 똑똑하기 때문에, 경계선(Boundaries)이 없으면 "좋은 의도로" 선을 넘고 들어옵니다. 요청하지 않은 리팩터링 (Refactoring), 멋대로 파일을 삭제하거나, 덤으로 운영 환경 설정을 변경하는 일 말이죠. 악의는 없습니다. 하지만 사고는 사고입니다.

그러므로, 넘지 말아야 할 곳은 미리 글로 적어둡니다. 이것이 Boundaries 섹션의 역할입니다.

특히, 되돌릴 수 없는 작업 (불가역적 작업) 은 AGENTS.md에 "실행하지 말고, 제안만 할 것"이라고 명시하여, 반드시 인간의 게이트(확인 관문)를 통과하도록 합니다.

• 운영 환경(Production)으로의 배포
• 데이터 삭제, DB의 파괴적인 마이그레이션 (Migration)
• 과금 · 결제 관련 처리
• 외부 공개 · 전송 (SNS 게시, 메일 전송 등)

여기서 역할 분담을 표로 정리해 두겠습니다. AGENTS.md는 이 표를 "파일로서 고정하는" 장치라고 생각하세요.

영역	인간이 쥐는 권한	AI에게 맡기는 권한
무엇을 만들 것인가 (What)	◎ 결정함	제안은 함
...

한 가지 주의할 점이 있습니다. 공식 사양에 따르면, AGENTS.md에 테스트 명령어를 적어두면 에이전트(Agent)가 그것을 자동으로 실행해 준다고 되어 있습니다. 이는 편리한 반면, 뒤집어 생각하면 **"AGENTS.md에 적은 명령어는 자동으로 실행될 수 있다"**는 뜻입니다. 그러니 실수로라도 파괴적인 명령어를 가볍게 적지 마세요. 적는 것은 "안전하게 몇 번이고 실행할 수 있는 명령어"뿐이어야 합니다. 이것 또한 훌륭한 경계 설계입니다.

좋은 의도로 했다가 오히려 역효과를 내는 패턴 6가지를 증상과 대책으로 나열합니다.

#	증상 (하기 쉬운 실수)	왜 안 되는가	대책
1	일단 전부 다 집어넣어 장문화함	매 세션마다 읽히며 토큰 (Token)을 낭비하고 요점이 묻힘	수십~150행 내로 압축. 상세 내용은 별도 파일로
...	커밋(Commit) = 유출. 공개 리포지토리라면 즉시 아웃
		절대 적지 말 것 (아래 참조)

6번은 격이 다르게 위험하므로 독립시키겠습니다.

⚠️

AGENTS.md는 git에 커밋되며, 공개 리포지토리라면 그대로 세상에 공개됩니다.

API 키, 토큰 (Token), 비밀번호, 사내 고유 ID, 개인정보, 미공개 URL…… 이것들을 절대로 적지 마세요.

비밀 정보는 .env (＋ .gitignore)나 시크릿 관리 서비스에 두고, AGENTS.md에는 "환경 변수는 .env.example을 기준으로 한다"와 같이 위치만 적습니다. 내용은 적지 않습니다.

이 부분은 사고가 났을 때의 피해 규모가 차원이 다르므로 몇 번이고 말씀드립니다. AGENTS.md에 적어도 되는 것은, 남에게 보여져도 곤란하지 않은 것뿐입니다.

AGENTS.md는 AI에게 만들게 하고, AI에게 점검하게 하고, AI에게 업데이트를 제안하게 하는 방식으로 순환시킬 수 있습니다. 단, 최종적으로 삭제할지 남길지를 결정하는 것은 인간입니다. AI에게는 "재료 제공"을 시키고, 판단은 인간이 쥐는 것. 이것 또한 컨텍스트 엔지니어링 (Context Engineering)의 작법입니다.

처음부터 쓰는 것은 힘드니, 먼저 리포지토리를 조사하게 하여 초안을 만들게 합니다.

당신은 이 리포지토리의 구성을 조사하여 AGENTS.md의 초안을 작성해 주세요.
절차:
1. package.json / 설정 파일 / 디렉토리 구성을 읽고,
...

이미 존재하는 AGENTS.md가 "너무 길거나, 오래되었거나, 추론 가능한 정보투성이"가 아닌지 점검하게 합니다.

이 리포지토리의 AGENTS.md를 리뷰해 주세요. 판단은 하지 말고 지적만 하세요.
관점:
- 너무 길지는 않은가 (매 세션 읽힌다는 전제하에, 줄일 수 있는 행은 무엇인가)
...

이 방법이 가장 효과적입니다. 작업이 끝난 뒤 "이번에 막혔던 부분"을 AGENTS.md에 환원시키는 것입니다.

이번 세션에서 당신이 막혔던 점, 오해했던 점, 내가 중간에 정정했던 점을 되돌아보고,
AGENTS.md에 1~3줄 추가해야 할 내용을 제안해 주세요.
조건:
...

세 가지 방법 모두 마지막에 **"판단은 인간"**이라고 적어둔 것이 포인트입니다. AI에게 전부 맡기면 AGENTS.md가 AI 생성 정형 문구로 비대해집니다 (함정 3번). 발산은 AI가, 수렴은 인간이 합니다.

함정 4번(오래되어 거짓이 되는 문제)과 1번(너무 긴 문제)은 인간의 의지만으로는 반드시 무너집니다. 그러니 기계가 감시하게 만드세요.

아래는 AGENTS.md가 "너무 길지는 않은지", "작성된 명령어가 정말로 package.json에 존재하는지"를 확인하는, 의존성(dependency)이 없는 작은 스크립트입니다. CI에 통합하면 AGENTS.md가 거짓말을 하기 시작하는 순간을 알아챌 수 있습니다.

// scripts/check-agents-md.mjs
// 사용법: node scripts/check-agents-md.mjs
import { readFileSync } from "node:fs";
...

이것을 GitHub Actions에서 호출하면, PR(Pull Request)마다 자동으로 검사해 줍니다. "인간이 열심히 지키는 것"을 "시스템이 알아서 지키는 것"으로 바꿉니다. 이것 또한 내일의 자신에게 주는 선물입니다.

이미 CLAUDE.md나 .cursorrules를 가지고 있는 분들도 많을 것입니다. 버리지 않아도 괜찮습니다. AGENTS.md를 정본(Source of Truth)으로 삼고, 기존 파일은 심볼릭 링크(Symbolic Link, 내용은 같지만 이름만 다른 바로가기)로 만들어 두면, 오래된 도구와 새로운 도구 모두 동일한 실체를 읽게 됩니다.

# 예: 기존의 CLAUDE.md를 AGENTS.md로 통합하고, 기존 이름은 링크로 남기기
mv CLAUDE.md AGENTS.md
ln -s AGENTS.md CLAUDE.md # CLAUDE.md는 AGENTS.md를 가리키게 됨
...

이렇게 하면 "도구마다 유지보수하기"에서 "한 장을 키워나가기"로 전환할 수 있습니다.

참고로, AGENTS.md는 다른 기법들과 충돌하지 않습니다. 오히려 궁합이 좋습니다. 예를 들어, 기능별 사양을 작성하는 Spec-Driven Development (사양 주도 개발)나, 출력 품질을 측정하는 평가 (Eval)와 결합하면, "리포지토리 전체의 관례는 AGENTS.md, 기능별 사양은 spec, 품질은 eval" 이라는 깔끔한 3층 구조가 됩니다. AGENTS.md는 그 토대이자, 가장 아래에 상주하는 문맥(Context)입니다.

이론은 이 정도면 충분합니다. 완벽을 목표로 하지 말고, 우선 실행해 보세요. 65점이면 충분합니다.

리포지토리 루트에 우선은 빈 파일이라도 좋습니다. AGENTS.md를 새로 생성하세요.
딱 10줄만 쓰세요. Commands (install / dev / test)와, Boundaries를 12줄(예: "src/legacy/는 건드리지 말 것") 정도만 작성합니다. 이것만으로도 효과가 있습니다.
다음 세션에서, 프롬프트 3(업데이트 제안)을 사용하세요. AI가 막혔던 포인트를 12줄씩 추가해 나갑니다.
1주일 후, 프롬프트 2(건강 진단)로 점검하세요. 너무 길지는 않은지, 진부해지지는 않았는지, 비밀 정보가 포함되지는 않았는지 체크하고 덜어냅니다.

이것만으로도, 다음 주의 당신은 "매번 설명해야 하는 번거로움"에서 해방될 것입니다.

마지막으로, 제 생각을 조금만 덧붙이겠습니다.

AGENTS.md는 기술적으로는 "AI에게 읽히는 설정 파일"이지만, 본질은 훨씬 더 다정한 것이라고 생각합니다.

README가 인간에게 쓰는 편지라면, AGENTS.md는 내일의 나, 내일의 팀, 내일의 AI 세션에게 남기는 메모입니다. 오늘 10줄만 써두면, 내일의 내가 똑같은 설명을 반복하지 않아도 됩니다. 새로 합류한 사람이 즉시 전력이 될 수 있습니다. AI가 즉시 관례에 따라 움직여 줍니다.

제가 항상 스스로에게 던지는 기준이 하나 있는데, 그것은 "이 선택을 보고 내일의 내가 '아자스(감사합니다)'라고 말해줄까?" 하는 것입니다. AGENTS.md를 10줄 쓰는 것은 바로 그것입니다. 오늘의 작은 수고가 내일의 나에게 보내는 "아자스"가 됩니다.

그리고 이것은 AI 시대 엔지니어의 역할 변화 그 자체이기도 합니다. 코드를 한 줄씩 손으로 치는 사람에서, What(무엇을)과 Why(왜) 그리고 경계를 설계하고, How(어떻게 구현할지)를 AI에게 넘겨주는 사람으로. AGENTS.md는 그 "문맥을 설계하는 능력"을 누구나 오늘부터 가질 수 있는 형태로 만들어 줍니다. 문맥은 코드와 마찬가지로 제대로 작성하면 자산이 됩니다. 키우면 키울수록 알아서 힘을 발휘해 주는 자산이 됩니다.

완벽하지 않아도 됩니다. 우선은 10줄부터. 당신의 리포지토리에 내일을 위한 메모 한 장을 놓아보지 않겠습니까?

내일의 당신이 분명 "아자스"라고 말해줄 것입니다.