AGENTS.md로 코딩 에이전트 규칙을 표준화하는 방법: 구조, 중첩, 운영 원칙

여러분, 코딩 에이전트 쓸 때 규칙 파일 관리 어떻게 하시나요? Cursor에는 rules 파일이 있고, Claude Code에는 CLAUDE.md가 있고, Gemini CLI를 비롯한 다른 도구들도 각자 규칙 파일을 가지고 있죠. 문제는 여러 에이전트를 번갈아 쓰는 순간 규칙이 도구별로 흩어진다는 겁니다. 같은 프로젝트인데 도구마다 따로 규칙을 적어 두는 일이 생깁니다.

제가 말하고 싶은 건 이 흩어진 규칙을 하나로 모으는 방법입니다. 그게 바로 AGENTS.md입니다. 프로젝트 안에 마크다운 파일로 에이전트가 알아야 할 맥락, 실행 방법, 코딩 스타일, 금지 사항, 테스트 전략을 정의해 두면, 지원하는 코딩 에이전트가 이걸 읽고 작업 기준으로 삼습니다. 핵심은 “AI에게 설명할 문서”를 매번 프롬프트에 따로 붙이는 게 아니라, 저장소 안에 버전 관리되는 규칙 파일로 남긴다는 점이죠.

이 글에서는 AGENTS.md의 목적과 효율적인 구성 방식, 중첩 규칙 파일 전략, 코드 리뷰와 온보딩에서의 활용법을 정리합니다.

핵심 요약

• AGENTS.md는 AI 코딩 에이전트에게 프로젝트 맥락과 작업 규칙을 전달하는 마크다운 기반 규칙 파일입니다.
• 여러 코딩 에이전트를 함께 쓰는 환경에서는 도구별 규칙 파일보다 표준화된 규칙 파일을 중심으로 관리하는 편이 일관성을 높입니다.
• 좋은 AGENTS.md는 모든 내용을 한 파일에 몰아넣지 않고, 루트 파일은 관제탑 역할을 하며 세부 규칙은 하위 파일로 위임합니다.
• 한 파일은 500줄 이내로 유지하는 것이 토큰 효율과 가독성 측면에서 유리합니다.
• 규칙 파일은 코드와 함께 버전 관리하고, 코드 리뷰 대상에 포함해야 합니다.
• 신규 팀원 온보딩에도 AGENTS.md는 유용합니다. 실행 방법, 테스트 방법, 금지 사항, 코드 구조가 한곳에 정리되기 때문입니다.
• 프로젝트 구조가 바뀌면 규칙 파일도 함께 업데이트해야 하며, 한 번 작성하고 방치하면 오히려 잘못된 맥락을 주입할 수 있습니다.

왜 규칙 파일 표준화가 필요한가

에이전트마다 규칙 파일이 흩어지는 문제

AI 코딩 도구가 늘어나면서 개발자는 하나의 에이전트만 쓰지 않습니다. 어떤 작업은 Codex에서 하고, 어떤 작업은 Cursor에서 하고, 또 다른 작업은 Gemini CLI나 GitHub Copilot 계열 도구를 사용할 수 있습니다. 이때 각 도구마다 별도 규칙 파일을 작성하면 같은 프로젝트의 작업 원칙이 여러 파일에 중복됩니다.

중복은 곧 드리프트를 만듭니다. 한 파일에는 “테스트는 Bun으로 실행”이라고 적혀 있는데 다른 파일에는 예전 npm 명령이 남아 있다고 해보죠. 그러면 에이전트는 도구에 따라 다른 행동을 합니다. 규칙 파일은 AI의 작업 품질에 직접 영향을 주기 때문에, 이 불일치는 단순 문서 문제가 아니라 실제 코드 변경 품질 문제로 이어집니다.

AGENTS.md는 이런 규칙을 하나의 표준화된 파일로 모으려는 접근입니다. 지원하는 에이전트가 같은 파일을 읽으면, 도구를 바꾸더라도 프로젝트의 핵심 규칙은 유지됩니다.

규칙은 프롬프트가 아니라 프로젝트 자산이다

규칙 파일을 임시 프롬프트처럼 다루면 오래가지 않습니다. 프로젝트 실행 명령, 테스트 방식, 아키텍처 제약, 보안상 금지 사항, 커밋 규칙은 코드베이스와 함께 바뀝니다. 따라서 규칙 파일도 저장소 안에서 코드와 함께 버전 관리되어야 합니다.

이 관점이 중요합니다. AGENTS.md는 에이전트에게만 읽히는 숨은 메모가 아니라, 팀이 공유하는 작업 계약입니다. 사람이 읽어도 프로젝트를 이해하는 데 도움이 되어야 하고, AI가 읽어도 같은 기준으로 작업할 수 있어야 합니다.

효율적인 AGENTS.md 구조

루트 파일은 관제탑 역할을 한다

좋은 AGENTS.md는 모든 세부사항을 루트 파일에 몰아넣지 않습니다. 루트 파일은 프로젝트 전체의 방향을 잡는 관제탑 역할을 해야 합니다. 여기에는 비즈니스 목표, 기술 스택, 절대 지켜야 할 원칙, 기본 실행 명령, 커밋과 리뷰 규칙, 하위 문서로 이어지는 컨텍스트 맵이 들어갑니다.

루트 파일이 너무 길어지면 두 가지 문제가 생깁니다. 첫째, 사람이 읽기 어렵습니다. 둘째, 에이전트가 매번 불필요한 컨텍스트를 많이 소비합니다. 거대 언어 모델 (Large Language Model, LLM)은 컨텍스트 윈도우 안에서 작업하므로, 항상 읽히는 규칙 파일이 비대해지면 실제 코드와 대화에 쓸 수 있는 공간이 줄어듭니다.

500줄 이내를 목표로 유지한다

저는 하나의 AGENTS.md 파일을 500줄 이내로 유지하는 걸 권장합니다. 이 숫자가 절대적인 규격은 아닙니다. 규칙 파일을 운영 가능한 크기로 유지하기 위한 실용적인 기준이라고 봅니다. 500줄을 넘기기 시작하면 루트 파일에 너무 많은 책임이 들어갔을 가능성이 큽니다.

규칙 파일에는 “모든 것을 자세히”보다 “반드시 지켜야 할 것을 명확히”가 더 중요합니다. 실행 명령, 금지 사항, 코드 스타일, 테스트 기준처럼 자주 참조되는 내용은 루트에 두고, 특정 도메인이나 프레임워크의 세부 규칙은 하위 파일로 분리하는 편이 좋습니다.

Golden Rules와 행동 기준

Immutable, Do’s, Don’ts로 나누기

AI 에이전트에게 규칙을 줄 때는 해야 할 일과 하지 말아야 할 일을 명확히 나누는 게 효과적입니다. Golden Rules 안에 Immutable, Do's, Don'ts 같은 구분을 두는 방식을 권합니다.

구분	목적	예시
Immutable	절대 바꾸면 안 되는 제약	배포 모드 변경 금지, 보안 키 수정 금지
Do’s	선호하는 작업 방식	기존 컴포넌트 재사용, 테스트 먼저 확인
Don’ts	피해야 할 행동	패키지 매니저 혼용 금지, 불필요한 글로벌 CSS 추가 금지

이렇게 나누면 에이전트가 규칙의 우선순위를 이해하기 쉽습니다. 특히 Immutable은 “가능하면 지켜라”가 아니라 “깨면 안 된다”는 의미로 작성해야 합니다. 보안, 배포, 데이터, 클라이언트 자산처럼 되돌리기 어렵거나 영향이 큰 항목은 이 영역에 둡니다.

코드 리뷰에서도 규칙 파일을 본다

AGENTS.md는 AI가 코드를 작성하는 방식에 영향을 주기 때문에 코드 리뷰 대상에 포함되어야 합니다. 코드가 바뀌었는데 규칙 파일이 예전 상태를 유지하면, 다음 에이전트 작업에서 잘못된 지침이 계속 사용됩니다.

예를 들어 테스트 프레임워크를 바꾸었거나 패키지 매니저를 변경했는데 AGENTS.md가 업데이트되지 않으면, 에이전트는 이전 명령을 실행하려고 할 수 있습니다. 따라서 중요한 구조 변경이 있을 때는 관련 규칙 파일도 함께 수정하고 리뷰해야 합니다.

중첩 AGENTS.md 전략

하나의 큰 파일보다 여러 개의 작은 파일

AGENTS.md의 중요한 장점 중 하나는 중첩된 경로에 여러 규칙 파일을 둘 수 있다는 점입니다. 루트 파일 하나에 모든 내용을 넣는 대신, 특정 도메인이나 기술 경계마다 별도의 규칙 파일을 둘 수 있습니다.

예를 들어 API 디렉토리에는 API 설계와 인증, 에러 처리 규칙을 담고, UI 컴포넌트 디렉토리에는 디자인 시스템과 접근성, 스타일링 규칙을 담을 수 있습니다. 이렇게 하면 에이전트가 해당 영역을 작업할 때 필요한 맥락만 더 정확하게 읽을 수 있습니다.

AGENTS.md
src/
  api/
    AGENTS.md
  components/
    AGENTS.md
  jobs/
    AGENTS.md

중첩 전략의 목적은 규칙을 많이 만드는 것이 아닙니다. 고유한 컨텍스트가 발생하는 지점에만 규칙을 두는 것입니다. 디펜던시 경계, 프레임워크 경계, 비즈니스 로직 밀도가 높은 핵심 모듈이 좋은 후보입니다.

컨텍스트 맵으로 하위 파일을 안내한다

루트 AGENTS.md에는 하위 규칙 파일로 이어지는 컨텍스트 맵을 두는 것이 좋습니다. 컨텍스트 맵은 “어떤 작업을 할 때 어떤 문서를 봐야 하는지”를 안내하는 지도 역할을 합니다.

예를 들어 다음처럼 작성할 수 있습니다.

## Context Map

- API 작업: `src/api/AGENTS.md`
- UI 컴포넌트 작업: `src/components/AGENTS.md`
- 배치 작업: `src/jobs/AGENTS.md`

이 구조는 루트 파일이 관제탑 역할을 하도록 돕습니다. 에이전트는 먼저 전체 규칙을 파악하고, 필요한 세부 영역으로 이동해 더 구체적인 지침을 확인할 수 있습니다.

자동 생성 프롬프트를 사용할 때의 기준

프로젝트 구조를 먼저 분석하게 한다

프로젝트 전체를 검토해 루트 AGENTS.md와 하위 규칙 파일을 자동 생성하는 마스터 프롬프트를 쓸 수도 있습니다. 이런 프롬프트를 쓸 때 중요한 건 바로 파일을 만들게 하는 게 아니라, 먼저 프로젝트 구조와 경계를 분석하게 하는 겁니다.

분석 단계에서는 기술 스택, 실행 명령, 테스트 명령, 주요 디렉토리, 도메인 경계, 배포 방식, 보안상 주의할 점을 확인해야 합니다. 코드베이스를 보면 알 수 있는 내용은 사용자에게 묻지 않고 직접 확인하는 편이 좋습니다.

이모지와 장식보다 정확성이 중요하다

AI가 문서를 생성할 때 불필요한 이모지나 장식적인 표현을 넣는 경우가 많습니다. 하지만 규칙 파일은 예쁘게 보이는 문서가 아니라 에이전트와 사람이 함께 쓰는 작업 계약입니다. 따라서 문장은 짧고 명확해야 하며, 실행 가능한 규칙 중심으로 작성해야 합니다.

좋은 규칙은 “깔끔하게 작성하세요”가 아니라 “새 UI 컴포넌트는 src/components/의 기존 패턴을 우선 재사용하세요”처럼 구체적입니다. 에이전트가 바로 행동으로 옮길 수 있어야 합니다.

온보딩과 팀 운영에서의 활용

신규 팀원이 빠르게 맥락을 잡는다

잘 작성된 AGENTS.md는 AI 에이전트뿐 아니라 신규 팀원에게도 유용합니다. 프로젝트 실행 방법, 테스트 방법, 코딩 스타일, 금지 사항, 코드베이스 구조가 한곳에 정리되어 있기 때문입니다.

특히 문서가 여러 곳에 흩어진 프로젝트에서는 AGENTS.md가 출발점 역할을 할 수 있습니다. 신규 팀원은 루트 파일을 읽고 전체 구조를 이해한 뒤, 필요한 하위 규칙 파일을 따라가며 세부 맥락을 파악할 수 있습니다.

반복적으로 개선해야 한다

규칙 파일은 한 번 만들고 끝나는 문서가 아닙니다. 에이전트가 자주 실수하는 부분, 팀원이 반복해서 지적하는 부분, 프로젝트 구조 변경으로 달라진 부분을 계속 반영해야 합니다. 규칙이 오래되면 에이전트에게 잘못된 컨텍스트를 주입하는 위험이 생깁니다.

운영 관점에서는 다음 상황에서 AGENTS.md 업데이트를 검토하는 것이 좋습니다.

• 패키지 매니저, 테스트 도구, 빌드 도구가 바뀐 경우
• 주요 디렉토리 구조나 도메인 경계가 바뀐 경우
• 보안상 금지해야 할 작업이 새로 생긴 경우
• 에이전트가 반복적으로 같은 실수를 하는 경우
• 신규 팀원 온보딩 과정에서 빠진 맥락이 발견된 경우

마무리

AGENTS.md는 AI 코딩 에이전트 시대의 프로젝트 운영 문서에 가깝습니다. 에이전트에게 그냥 “잘 해줘”라고 말하는 대신, 프로젝트가 어떤 방식으로 개발되어야 하는지 저장소 안에 명확히 남기는 방식이죠.

제가 가장 중요하게 보는 원칙은 작고 정확하게 유지하는 겁니다. 루트 파일은 관제탑 역할을 하고, 세부 규칙은 중첩된 파일로 분리하고, 변경된 코드와 함께 규칙 파일도 계속 업데이트하는 거죠. 이렇게 해야 여러 코딩 에이전트를 써도 프로젝트의 작업 기준이 흔들리지 않습니다.

결론부터 말하면, AGENTS.md는 에이전트 성능을 높이는 프롬프트 조각이 아니라 팀의 개발 방식과 AI 작업 방식을 연결하는 표준 계약이라고 봅니다. 아직 규칙 파일이 없다면 루트 파일부터 작게 시작하고, 프로젝트가 커질수록 도메인별 하위 파일로 확장하는 방식이 가장 현실적입니다. 한번 만들어 보면 좋겠습니다.

---

관련 영상

이 글과 연결된 영상은 개발동생 유튜브 채널에서 보기에서 확인할 수 있습니다.