AGENTS.md는 AI 코딩 에이전트에게 작업 방식을 알려주기 위한 Markdown 파일이다. 쉽게 말하면, 사람을 위한 문서가 README.md라면, AGENTS.md는 AI 에이전트를 위한 안내서라고 볼 수 있다.
개발자가 새로운 프로젝트에 참여하면 먼저 README, 개발 가이드, 테스트 방법, 코드 스타일, 배포 절차 등을 읽는다. AI 코딩 에이전트도 마찬가지다. 에이전트가 저장소를 더 잘 이해하고, 프로젝트의 규칙에 맞게 코드를 수정하며, 필요한 테스트를 실행하도록 하려면 명확한 지침이 필요하다. AGENTS.md는 바로 그 역할을 한다.
즉, AI에게 다음과 같은 내용을 알려주는 파일이다.
- 이 프로젝트가 어떤 구조로 되어 있는지
- 개발 환경을 어떻게 준비해야 하는지
- 빌드, 테스트, 린트 명령어는 무엇인지
- 코드 스타일과 네이밍 규칙은 무엇인지
- PR이나 커밋 메시지는 어떤 형식을 따라야 하는지
- 수정하면 안 되는 파일이나 주의해야 할 영역은 어디인지
- 보안상 조심해야 할 점은 무엇인지
왜 필요할까?
AI 코딩 도구를 사용하다 보면 다음과 같은 문제가 자주 발생한다.
에이전트가 프로젝트 구조를 제대로 이해하지 못해 엉뚱한 파일을 수정하거나, 이미 정해진 코드 스타일을 무시하거나, 테스트를 잘못 실행하거나, 프로젝트에서 사용하지 않는 라이브러리나 패턴을 도입하는 경우가 있다.
이런 문제는 AI 모델의 지능이 낮아서만 발생하는 것이 아니다. 대부분은 “맥락 부족”에서 시작된다. 사람도 프로젝트 설명 없이 바로 코드를 고치라고 하면 실수가 생기듯이, AI 에이전트도 프로젝트별 규칙과 환경을 알아야 더 안정적으로 작업할 수 있다.
AGENTS.md는 이런 맥락을 한곳에 정리해준다. 덕분에 AI 에이전트는 매번 저장소를 추측으로 탐색하지 않고, 미리 정리해둔 기준을 바탕으로 작업할 수 있다.
README.md와 차이점
README.md는 사람을 위한 문서다. 프로젝트 소개, 설치 방법, 사용법, 기여 방법 등 사람이 쉽게 이해해야 하는 내용을 담는다.
반면 AGENTS.md는 AI 에이전트가 작업을 수행할 때 필요한 지침을 담는다. 예를 들어 README에는 “테스트를 실행하세요”라고 적을 수 있지만, AGENTS.md에는 아래처럼 구체적으로 쓸 수 있다.
## Testing instructions
- 전체 테스트는 `pnpm test`로 실행한다.
- 특정 패키지만 테스트할 때는 `pnpm turbo run test --filter <package_name>`을 사용한다.
- 코드 수정 후에는 반드시 `pnpm lint`와 `pnpm test`를 실행한다.
- 테스트가 실패하면 원인을 수정한 뒤 다시 실행한다.
README가 사람에게 프로젝트를 소개하는 문서라면, AGENTS.md는 AI 에이전트에게 “이 저장소에서 일할 때 이렇게 행동하라”고 알려주는 작업 지침서에 가깝다.
들어가면 좋은 내용
AGENTS.md는 정해진 필수 형식이 없다. Markdown 파일이므로 프로젝트 상황에 맞게 자유롭게 작성하면 된다. 다만 다음의 항목을 넣으면 도움이 된다.
1. 프로젝트 개요
에이전트가 프로젝트의 목적을 빠르게 이해할 수 있도록 간단히 설명한다.
예시:
## Project overview
이 프로젝트는 Blogger 글쓰기 화면에서 Markdown 편집을 지원하는 Chrome 확장 프로그램이다.
주요 기능은 Markdown 입력, HTML 변환, 미리보기, Blogger 편집기 삽입이다.
프로젝트의 목적이 명확하면 에이전트가 불필요한 방향으로 코드를 확장하는 일을 줄일 수 있다.
2. 디렉터리 구조
저장소의 주요 폴더가 어떤 역할을 하는지 설명한다.
예시:
## Repository structure
- `src/`: 확장 프로그램의 주요 소스 코드
- `src/content/`: Blogger 페이지에 삽입되는 content script
- `src/popup/`: 확장 프로그램 팝업 UI
- `src/shared/`: 공통 유틸리티 함수
- `public/`: 정적 파일
- `docs/`: 문서
AI 에이전트는 파일 이름만 보고 역할을 추측하는 경우가 많다. 디렉터리 구조를 명확히 적어두면 잘못된 위치에 코드를 추가하는 일을 줄일 수 있다. (뭐 이런건 Serena라는 툴로도 해결 가능하다. 이건 나중에 포스팅…)
3. 개발 환경 설정
의존성 설치, 개발 서버 실행, 빌드 방법을 적는다.
예시:
## Setup commands
- 의존성 설치: `pnpm install`
- 개발 서버 실행: `pnpm dev`
- 프로덕션 빌드: `pnpm build`
특히 monorepo나 workspace 구조에서는 어떤 패키지 매니저를 쓰는지, 어떤 명령어를 기준으로 작업해야 하는지 알려주는 것이 중요하다.
4. 테스트 및 검증 방법
에이전트가 코드 수정 후 어떤 검증을 해야 하는지 명시한다.
예시:
## Testing instructions
- 코드 수정 후 `pnpm lint`를 실행한다.
- 기능 변경이 있으면 관련 테스트를 추가하거나 수정한다.
- 전체 테스트는 `pnpm test`로 실행한다.
- 테스트를 실행할 수 없는 환경이면 그 이유를 작업 결과에 명확히 남긴다.
AI 에이전트는 결과물을 만들고 끝내는 것이 아니라, 가능한 범위에서 검증까지 수행해야 한다. AGENTS.md에 테스트 지침을 넣어두면 에이전트가 일관된 방식으로 작업을 마무리할 수 있다.
5. 코드 스타일
프로젝트에서 선호하는 코드 스타일을 적는다.
예시:
## Code style
- TypeScript strict mode를 유지한다.
- 함수형 패턴을 우선 사용한다.
- 불필요한 class 사용을 피한다.
- 문자열에는 single quote를 사용한다.
- 세미콜론은 사용하지 않는다.
코드 스타일은 사람 사이에서도 의견이 갈리는 영역이다. AGENTS.md에 명확히 적어두면 AI가 자기 방식대로 코드를 생성하는 일을 줄일 수 있다.
6. 작업 시 주의사항
수정하면 안 되는 영역, 민감한 파일, 보안상 주의할 점을 적는다.
예시:
## Safety and constraints
- `.env` 파일은 생성하거나 수정하지 않는다.
- API key, token, secret 값은 코드에 직접 작성하지 않는다.
- 기존 public API의 함수 시그니처는 변경하지 않는다.
- 마이그레이션 파일은 사용자의 명시적 요청이 있을 때만 수정한다.
AI 코딩 에이전트는 실제 파일을 수정하거나 명령어를 실행할 수 있기 때문에, 금지 사항과 주의 사항을 명확히 적어두는 것이 좋다.
7. PR 및 커밋 규칙
에이전트가 PR 설명이나 커밋 메시지를 작성해야 하는 경우를 대비해 규칙을 적는다.
예시:
## PR instructions
- PR 제목은 `[area] summary` 형식을 따른다.
- 변경 요약, 테스트 결과, 영향 범위를 포함한다.
- 테스트를 실행하지 못한 경우 그 이유를 명확히 적는다.
이런 지침은 AI가 생성한 PR을 사람이 리뷰하기 쉽게 만든다.
AGENTS.md의 위치
일반적으로 AGENTS.md는 저장소 루트에 둔다.
예시:
my-project/
├── AGENTS.md
├── README.md
├── package.json
└── src/
루트에 있는 AGENTS.md는 저장소 전체에 적용되는 기본 지침 역할을 한다. 대형 프로젝트나 monorepo에서는 하위 디렉터리마다 별도의 AGENTS.md를 둘 수도 있다.
예시:
my-monorepo/
├── AGENTS.md
├── apps/
│ └── web/
│ └── AGENTS.md
└── packages/
└── ui/
└── AGENTS.md
이 경우 루트 AGENTS.md는 전체 공통 규칙을 담고, 하위 AGENTS.md는 특정 앱이나 패키지에만 적용되는 세부 규칙을 담는다.
우선순위와 적용 범위
AGENTS.md는 보통 자신이 위치한 디렉터리와 그 하위 디렉터리에 적용된다. 예를 들어apps/web/AGENTS.md는 apps/web/ 아래의 파일을 수정할 때 적용된다.
만약 루트 AGENTS.md와 하위 AGENTS.md의 내용이 서로 충돌한다면, 더 가까운 위치에 있는 AGENTS.md가 우선한다. 예를 들어 apps/web/Button.tsx를 수정한다면 루트의 AGENTS.md보다 apps/web/AGENTS.md의 지침이 더 구체적인 지침으로 취급된다.
다만 사용자가 채팅에서 직접 지시한 내용이 있다면, 일반적으로 그 지시가 AGENTS.md보다 우선한다. 예를 들어 AGENTS.md에는 “테스트를 반드시 실행하라”고 되어 있지만 사용자가 “이번에는 코드 수정 없이 분석만 해줘”라고 했다면, 에이전트는 사용자의 현재 요청을 따라야 한다.
좋은 AGENTS.md 작성 원칙
좋은 AGENTS.md는 길고 복잡한 문서가 아니다. 오히려 짧고 명확해야 한다.
AI에게 많은 정보를 주는 것이 항상 좋은 것은 아니다. 불필요한 규칙이 많으면 에이전트가 작업을 복잡하게 만들 수 있다. 따라서 AGENTS.md에는 정말 필요한 내용만 넣는 것이 좋다.
좋은 AGENTS.md는 다음과 같은 특징을 가진다.
- 프로젝트 구조를 빠르게 이해할 수 있다.
- 자주 쓰는 명령어가 명확하다.
- 코드 스타일이 구체적이다.
- 금지 사항과 주의 사항이 분명하다.
- 테스트 방법이 실제로 실행 가능한 명령어로 적혀 있다.
- 오래된 내용이 방치되지 않는다.
- 사람도 읽기 쉽다.
반대로 나쁜 AGENTS.md는 다음과 같다.
- 너무 길고 추상적이다.
- “좋은 코드를 작성하라”처럼 당연한 말만 있다.
- 실제 명령어가 없다.
- 현재 프로젝트와 맞지 않는 오래된 내용이 있다.
- 서로 충돌하는 규칙이 있다.
- 도구별 설정 파일 내용을 무작정 복사해 중복이 많다.
AGENTS.md 예시
아래는 TypeScript 프로젝트에서 사용할 수 있는 AGENTS.md 예시다.
# AGENTS.md
## Project overview
이 프로젝트는 TypeScript 기반 웹 애플리케이션이다.
사용자 인터페이스는 React로 작성되어 있으며, 패키지 관리는 pnpm을 사용한다.
## Repository structure
- `src/`: 애플리케이션 소스 코드
- `src/components/`: 재사용 가능한 UI 컴포넌트
- `src/pages/`: 페이지 단위 컴포넌트
- `src/lib/`: 공통 유틸리티와 외부 서비스 연동 코드
- `tests/`: 테스트 코드
- `docs/`: 문서
## Setup commands
- 의존성 설치: `pnpm install`
- 개발 서버 실행: `pnpm dev`
- 빌드: `pnpm build`
## Testing instructions
- 코드 수정 후 `pnpm lint`를 실행한다.
- 기능 변경이 있으면 `pnpm test`를 실행한다.
- UI 동작이 바뀌면 관련 컴포넌트 테스트를 추가하거나 수정한다.
- 테스트를 실행할 수 없는 경우, 작업 결과에 그 이유를 남긴다.
## Code style
- TypeScript strict mode를 유지한다.
- React 컴포넌트는 함수형 컴포넌트로 작성한다.
- 불필요한 상태 관리를 추가하지 않는다.
- 기존 코드의 네이밍과 폴더 구조를 따른다.
- 중복 로직은 `src/lib/` 또는 적절한 공통 모듈로 분리한다.
## Safety and constraints
- `.env` 파일은 수정하지 않는다.
- API key, token, secret은 코드에 직접 작성하지 않는다.
- 사용자가 요청하지 않은 대규모 리팩터링은 하지 않는다.
- public API의 함수 시그니처를 변경할 때는 영향 범위를 설명한다.
## PR instructions
- 변경 요약을 짧게 작성한다.
- 실행한 테스트 명령어와 결과를 포함한다.
- 테스트를 실행하지 못한 경우 사유를 명시한다.
AGENTS.md와 다른 AI 설정 파일의 관계
AI 코딩 도구마다 자체 지침 파일을 사용하는 경우가 있다. 예를 들어 어떤 도구는 CLAUDE.md, 어떤 도구는 .cursorrules, 어떤 도구는 별도의 설정 파일을 사용한다.
이런 파일들이 많아지면 같은 내용을 여러 곳에 중복해서 관리해야 한다. 이른바 “설정 파일 난립” 문제가 생긴다. AGENTS.md는 이런 문제를 줄이기 위한 공통 지침 파일로 활용될 수 있다.
즉, 모든 도구가 완전히 동일하게 AGENTS.md를 지원하는 것은 아닐 수 있지만, 여러 AI 코딩 에이전트가 함께 사용할 수 있는 공통 문서로서 의미가 있다. 프로젝트의 기본 규칙은 AGENTS.md에 모으고, 특정 도구에서만 필요한 설정은 해당 도구의 전용 파일에 최소한으로 남기는 방식이 좋다.
실무에서의 활용 방법
AGENTS.md는 특히 다음과 같은 상황에서 유용하다.
1. AI 코딩 에이전트를 자주 사용하는 프로젝트
Codex, Claude Code, Cursor, Aider, Goose, OpenCode, Pi와 같은 도구를 함께 사용한다면 공통 지침 파일이 필요하다. AGENTS.md를 두면 어떤 도구를 쓰더라도 프로젝트의 기본 규칙을 일관되게 전달할 수 있다.
2. 여러 사람이 함께 관리하는 저장소
멤버가 많을수록 코드 스타일과 작업 방식이 흔들리기 쉽다. AGENTS.md는 사람뿐 아니라 AI 에이전트에게도 같은 기준을 제공한다.
3. monorepo 구조
monorepo는 패키지마다 빌드, 테스트, 배포 방식이 다를 수 있다. 루트 AGENTS.md와 하위 AGENTS.md를 함께 사용하면 공통 규칙과 패키지별 규칙을 분리할 수 있다.
4. 오래된 프로젝트
레거시 프로젝트는 암묵적인 규칙이 많다. “이 파일은 건드리면 안 된다”, “이 명령어는 오래 걸린다”, “이 테스트는 특정 환경에서만 통과한다” 같은 정보를 AGENTS.md에 적어두면 AI가 위험한 변경을 할 가능성을 줄일 수 있다.
작성할 때 주의할 점
AGENTS.md를 만들 때 가장 중요한 것은 “AI에게 모든 것을 설명하려고 하지 않는 것”이다.
AI에게 너무 많은 규칙을 주면 오히려 작업이 느려지거나, 중요하지 않은 규칙을 지키느라 실제 문제 해결이 어려워질 수 있다. 따라서 AGENTS.md는 완벽한 백과사전이 아니라, 에이전트가 안전하고 일관되게 작업하기 위한 최소한의 작업 지침서로 보는 것이 좋다.
따라서 아래의 원칙을 추천한다.
- 처음에는 짧게 시작한다.
- 실제로 AI가 자주 실수하는 부분을 추가한다.
- 명령어는 복사해서 실행할 수 있게 쓴다.
- 추상적인 표현보다 구체적인 규칙을 쓴다.
- 오래된 내용은 정기적으로 정리한다.
- 도구별 중복 지침은 줄인다.
- 보안, 테스트, 코드 스타일은 반드시 포함한다.
AGENTS.md는 단순한 파일 하나가 아니다. AI 에이전트와 협업하는 방식에 대한 약속이다.
이전에는 개발자가 AI에게 매번 “이 프로젝트는 pnpm을 써”, “테스트는 이 명령어로 해”, “이 폴더는 건드리지 마”, “PR 메시지는 이렇게 써”라고 반복해서 설명해야 했다. AGENTS.md를 사용하면 이런 반복 설명을 줄일 수 있다.
또한 AGENTS.md는 사람에게도 도움이 된다. 새로 조인한 개발자는 이 파일을 보고 프로젝트의 실제 작업 규칙을 파악할 수 있다. 결국 AGENTS.md는 AI만을 위한 문서라기보다, 프로젝트의 작업 방식을 명확히 정리하는 문서라고 볼 수 있다.
마무리
AGENTS.md는 AI 코딩 에이전트 시대의 새로운 프로젝트 문서 형식이다. README가 사람에게 프로젝트를 소개한다면, AGENTS.md는 AI 에이전트에게 프로젝트에서 일하는 방법을 알려준다.
좋은 AGENTS.md는 AI가 더 안전하고 일관되게 코드를 수정하도록 돕는다. 프로젝트 구조, 개발 명령어, 테스트 방법, 코드 스타일, 보안 주의사항, PR 규칙을 명확히 적어두면 에이전트의 시행착오를 줄일 수 있다.
그러나 AGENTS.md가 모든 문제를 해결해주는 것은 아니다. 너무 길거나 불필요한 규칙이 많은 AGENTS.md는 오히려 작업을 방해할 수 있다. 따라서 핵심은 “짧고 명확하게, 실제 필요한 지침만 적는 것”이다.
AI 코딩 에이전트를 함께 사용하는 환경이 늘어날수록, AGENTS.md는 프로젝트의 공통 작업 규칙을 담는 중요한 파일이 될 가능성이 크다. 특히 여러 에이전트, 여러 모델, 여러 개발자가 함께 일하는 저장소라면 AGENTS.md를 도입해볼 만하다.