AGENTS.md 사용법과 작성법, 예시 모음 사이트 추천까지

요즘 코덱스, 제미나이, 커서 같은 AI 코딩 도구를 쓰다 보면 AGENTS.md 파일을 자주 보게 된다. 처음에는 README와 비슷한 문서처럼 보이지만, 실제로는 AI 에이전트가 프로젝트를 이해하고 작업할 때 참고하는 설정 파일에 가깝다.

나는 클로드 코드 플러그인인 OMC의 deepinit 명령을 사용하다가 AGENTS.md를 처음 접했다. 자동으로 생성된 파일은 150줄 정도였고, 프로젝트 개요부터 기술 스택, 빌드 방법, 폴더 구조까지 꽤 자세하게 채워져 있었다.

다만 그대로 쓰기에는 불필요한 내용도 많았다. 그래서 처음부터 새로 작성하기보다, 자동 생성된 내용을 기준으로 필요한 항목만 남기고 정리하는 방식이 더 현실적이라고 느꼈다. 이 글에서는 AGENTS.md가 무엇인지, 어떻게 작성하면 좋은지, 참고할 만한 예시 사이트까지 함께 정리한다.

AGENTS.md가 뭐고 왜 필요한가

AGENTS.md는 AI 코딩 에이전트가 프로젝트를 이해하기 위해 읽는 안내 문서다. 사람이 읽는 README.md가 프로젝트 소개와 사용법을 설명한다면, AGENTS.md는 AI가 실제 코드를 수정하거나 테스트할 때 참고해야 하는 작업 규칙을 담는다.

예를 들면 이런 내용이 들어간다.

• 프로젝트 구조
• 빌드 명령어
• 테스트 실행 방법
• 코드 스타일
• 작업 완료 기준
• 수정하면 안 되는 파일
• 막혔을 때 따라야 할 규칙

즉, AGENTS.md는 AI에게 “이 프로젝트에서는 이렇게 작업해라”라고 알려주는 문서다. AI 코딩 도구를 자주 쓸수록 이런 파일의 필요성이 커진다.

매번 같은 설명을 반복하지 않아도 되고, 프로젝트별 규칙을 문서로 고정해 둘 수 있기 때문이다.

기존에는 AI 코딩 도구마다 설정 파일이 달랐다. 클로드 코드는 CLAUDE.md, Cursor는 .cursorrules나 자체 규칙 파일, Gemini는 GEMINI.md처럼 도구별로 읽는 파일이 달랐다.

문제는 여러 도구를 함께 쓰는 경우였다. 같은 프로젝트에서도 도구마다 규칙 파일을 따로 관리해야 했고, 내용이 조금씩 달라지면 유지보수가 번거로워졌다.

AGENTS.md는 이런 문제를 줄이기 위해 만들어진 공개 표준이다. 하나의 문서에 프로젝트 작업 규칙을 정리해 두고, 여러 AI 코딩 도구가 공통으로 참고할 수 있게 하는 것이 목적이다.

AGENTS.md 작성법, 뭐부터 넣어야 하나

AGENTS.md를 작성할 때 가장 중요한 것은 멋진 설명이 아니라 실제 작업에 필요한 정보다. AI가 코드를 수정할 때 바로 참고할 수 있는 내용이 앞에 있어야 한다.

우선순위는 다음과 같다.

1. 빌드와 테스트 명령어를 정확히 적는다.
2. 작업 완료 기준을 적는다.
3. 수정하면 안 되는 파일이나 주의할 점을 적는다.
4. 막혔을 때 어떻게 해야 하는지 적는다.
5. 작업 유형별 규칙을 나눠 적는다.

예를 들어 단순히 “테스트를 실행한다”라고 쓰는 것보다 아래처럼 쓰는 편이 좋다.

## Test

- 전체 테스트: `npm test`
- 단일 테스트: `npm test -- <파일명>`
- 배포 전에는 `npm run build`와 `npm test`를 모두 통과해야 한다.

AI 입장에서는 명령어가 구체적일수록 다시 추측할 필요가 줄어든다. 반대로 “좋은 코드를 작성한다”, “일관된 스타일을 유지한다” 같은 문장은 너무 추상적이라 실제 작업에는 큰 도움이 되지 않는다.

스타일 가이드나 색상 팔레트 같은 선호 설정은 나중에 넣어도 된다. 먼저 필요한 것은 AI가 실제로 명령어를 실행하고, 수정 범위를 판단하고, 작업을 끝냈는지 확인할 수 있는 기준이다.

참고할 만한 AGENTS.md 예시 사이트

처음부터 빈 파일을 직접 채우는 것보다, 이미 공개된 예시를 보고 프로젝트에 맞게 수정하는 편이 훨씬 쉽다.

참고할 만한 곳은 아래 두 곳이다.

• AGENTS.md 공식 GitHub 저장소
• agentsmd.net 예시 모음

공식 저장소에서는 AGENTS.md 표준과 기본 예시를 확인할 수 있다. agentsmd.net에는 Next.js, React Native, 크롬 확장 프로그램 등 프로젝트 유형별 예시가 정리돼 있어 실무에 적용하기 편하다.

처음 작성한다면 템플릿을 그대로 복사한 뒤, 자신의 프로젝트에 맞지 않는 항목을 지우는 방식이 좋다. 빈 문서에서 시작하는 것보다 훨씬 빠르다.

자동 생성된 AGENTS.md는 그대로 써도 될까

OMC의 deepinit 명령으로 생성된 AGENTS.md는 생각보다 자세했다. 프로젝트 개요, 폴더 구조, 기술 스택, 개발 규칙, 실행 방법 등이 한 번에 정리돼 있었다.

다만 자동 생성 파일은 길어질 수밖에 없다. 프로젝트를 처음 보는 사람에게 설명하듯 많은 내용을 넣기 때문에, 실제로 AI가 작업할 때는 중요하지 않은 정보도 섞인다.

나는 아래 기준으로 정리했다.

• 이미 README에 있는 일반 설명은 줄였다.
• 프로젝트와 직접 관련 없는 문장은 삭제했다.
• 빌드, 테스트, 실행 명령어는 남겼다.
• 자주 실수할 수 있는 규칙은 남겼다.
• 나중에도 참고할 가능성이 있는 구조 설명은 남겼다.

AGENTS.md는 길수록 좋은 문서가 아니다. AI가 작업할 때 바로 참고할 수 있어야 좋은 문서다. 자동 생성된 내용을 그대로 믿기보다, 실제로 내가 쓰는 도구와 프로젝트 구조에 맞게 줄이는 과정이 더 중요하다.

AGENTS.md와 CLAUDE.md는 어떻게 같이 관리할까

AGENTS.md를 쓴다고 해서 기존 도구별 설정 파일을 바로 지울 필요는 없다. 사용하는 도구에 따라 여전히 CLAUDE.md, GEMINI.md, .cursorrules 같은 파일이 필요할 수 있다.

현재 코덱스, 커서, 깃허브 코파일럿, Amp, Windsurf 같은 도구는 AGENTS.md를 직접 사용한다. 제미나이도 AGENTS.md를 지원하지만, GEMINI.md가 함께 있으면 해당 파일을 우선 사용하는 방식이다.

반면 클로드 코드는 아직 AGENTS.md를 직접 읽지는 않는다. 클로드 코드를 쓴다면 기본적으로 CLAUDE.md를 관리해야 한다.

다만 OMC 같은 플러그인을 사용하면 AGENTS.md를 생성하고, 이를 CLAUDE.md와 연결하는 방식으로 함께 활용할 수 있다.

여러 도구를 함께 쓴다면 AGENTS.md를 기준 문서로 두는 편이 깔끔하다. 공통 규칙은 AGENTS.md에 모으고, 도구별 파일에는 해당 도구에서만 필요한 예외만 남기면 된다.

예를 들면 CLAUDE.md에는 이런 식으로 적을 수 있다.

# CLAUDE.md

이 프로젝트의 공통 작업 규칙은 AGENTS.md를 기준으로 따른다.
Claude Code에서만 필요한 추가 규칙이 있으면 이 파일에 별도로 작성한다.

이렇게 하면 같은 내용을 여러 파일에 반복해서 적지 않아도 된다. 나중에 규칙을 수정할 때도 AGENTS.md만 먼저 확인하면 되기 때문에 유지보수가 편하다.

AGENTS.md는 언제 챙기면 좋을까

모든 프로젝트에 AGENTS.md가 꼭 필요한 것은 아니다. 혼자 만들고, 구조가 단순하고, AI 도구를 거의 쓰지 않는 프로젝트라면 없어도 큰 문제는 없다.

다만 아래 상황이라면 만드는 편이 좋다.

• AI 코딩 도구를 자주 사용한다.
• 프로젝트 구조가 복잡하다.
• 빌드나 테스트 명령어가 헷갈린다.
• 팀원이 여러 명이다.
• 코덱스, 커서, 제미나이 등 여러 도구를 함께 쓴다.
• AI가 매번 같은 실수를 반복한다.

특히 AI가 같은 실수를 반복한다면 AGENTS.md에 규칙을 추가해 두는 것이 좋다.

예를 들어 테스트 명령어를 자꾸 잘못 실행한다면, 정확한 명령어를 AGENTS.md에 적어 두면 된다. 수정하면 안 되는 파일을 계속 건드린다면, 그 파일을 명시해 두는 것도 방법이다.

AGENTS.md는 자동 생성보다 정리가 중요하다

AGENTS.md는 AI 코딩 도구를 위한 프로젝트 작업 가이드다. README처럼 사람에게 프로젝트를 소개하는 문서가 아니라, AI가 실제 작업할 때 필요한 규칙을 알려주는 문서에 가깝다.

처음부터 완벽하게 작성하려고 할 필요는 없다. 자동 생성 도구로 초안을 만들고, 불필요한 설명을 지운 뒤, 실제 작업에 필요한 명령어와 규칙만 남기면 된다.

핵심은 간단하다. AGENTS.md는 길게 쓰는 문서가 아니라, AI가 덜 헤매게 만드는 문서다.

FAQs