AGENTS.md란? AI 코딩 도구에 프로젝트 규칙 알려 주는 방법

AI에게 홈페이지를 만들어 달라고 부탁할 때 이런 말을 반복해 본 적 있나요? “기존 파일은 함부로 지우지 마.” “코드를 바꾸기 전에 어떤 부분을 고치는지 알려 줘.” “수정 후에는 테스트 결과를 보여 줘.” AI 코딩 도구를 사용할수록 프로젝트마다 지켜야 할 약속이 늘어납니다. 그런데 작업을 요청할 때마다 같은 규칙을 복사해서 붙여넣는 것은 번거롭습니다. 이럴 때 알아두면 좋은 파일 이름이 AGENTS.md입니다. AGENTS.md는 AI 코딩 에이전트에게 해당 프로젝트에서 지켜야 할 작업 기준을 설명하는 문서입니다. 예를 들어 OpenAI의 Codex는 이 파일을 찾아 읽고, 코드를 수정하거나 테스트할 때 참고할 수 있습니다. 가장 중요한 점부터 말씀드리겠습니다. AGENTS.md를 만든다고 AI에게 새로운 권한이 생기는 것은 아닙니다. 이 파일은 프로젝트의 작업 지침이지, 보안을 강제로 통제하는 프로그램이나 비밀번호 금고는 아닙니다. 이번 글에서는 AGENTS.md의 의미, 어떤 내용을 쓰는지, 예제 파일 만들기, 적용되는 폴더 범위와 보안 주의사항을 순서대로 알아보겠습니다. 2026년 10월 16일 OpenAI 공식 Codex 문서와 관련 공개 자료를 확인해 작성했습니다. 아래 예시는 교육용이며 이 글을 작성하면서 실제 컴퓨터의 Codex에 적용하거나 테스트 결과를 측정하지 않았습니다. 버전별 탐색 경로와 우선순위는 사용 중인 공식 도움말을 재확인해야 합니다.

AGENTS.md란 · 핵심 흐름AGENTS.md란의 주요 개념과 확인 순서를 네 단계로 정리한 자체 제작 도식.AGENTS.md란 · 핵심 흐름1안내 작성AGENTS.md에 프로젝트 규칙을씁니다2범위 결정상위·하위 폴더의 적용 범위를봅니다3도구 확인사용할 AI 도구의 지원을확인합니다4결과 검증작은 작업으로 반영 여부를살핍니다설명용 요약 도식입니다. 최신 기능과 이용 조건은 본문 및 공식 문서에서 확인하세요.EMFLS AI · 자체 도식
자체 제작 개념도 · EMFLS AI

1. AGENTS.md는 정확히 무엇인가요?

AGENTS.md는 AI 코딩 에이전트를 위한 프로젝트 지침 문서입니다. 이름을 두 부분으로 나누면 이해하기 쉽습니다. AGENTS는 프로젝트에서 작업할 AI 에이전트들을 의미하는 이름입니다. .md는 Markdown이라는 문서 형식의 파일 확장자입니다. 어려운 설정 프로그램을 설치하는 것이 아니라, 일반 텍스트 문서에 프로젝트 규칙을 적어 저장하는 방식이라고 이해하면 됩니다. 예를 들어 AGENTS.md에 이런 내용을 넣을 수 있습니다.


- 이 프로젝트는 개인용 연습 홈페이지입니다.
- 기존 글과 이미지는 요청 없이 삭제하지 마세요.
- 파일을 수정하기 전에 변경 계획을 알려 주세요.
- 작업 후 어떤 파일이 바뀌었는지 정리해 주세요.
- 테스트하지 않은 기능을 성공했다고 말하지 마세요.

AGENTS.md를 지원하는 코딩 도구라면 이 규칙을 작업할 때 참고하는 프로젝트 지침으로 활용할 수 있습니다. 그렇다고 모든 AI 채팅 서비스가 이 파일을 자동으로 찾아 읽는 것은 아닙니다.

2. 일반 AI 채팅에 규칙을 입력하는 것과 무엇이 다른가요?

일반 채팅에서는 보통 새로운 대화를 시작할 때 작업 규칙을 직접 다시 설명합니다. 반면 AGENTS.md를 지원하는 코딩 에이전트는 프로젝트에 저장된 지침 파일을 찾아 작업 맥락에 포함할 수 있습니다. 예를 들어 홈페이지를 만들고 있다고 가정해 보겠습니다. 일반 채팅 방식:

“제목을 바꿔 줘. 그런데 기존 파일은 지우지 말고, 새로운 패키지도 설치하지 말고, 테스트를 했다면 근거도 남겨 줘.” AGENTS.md를 사용하는 방식: “홈페이지 제목을 바꿔 줘.” 그리고 프로젝트의 AGENTS.md에 기존 파일 보호·패키지 설치 전 승인·테스트 보고 방법을 미리 작성해 두는 것입니다. OpenAI 공식 Codex 설명은 프로젝트의 AGENTS.md 내용을 코딩 에이전트가 참고할 수 있는 지침으로 읽는다고 안내합니다. 하지만 여기에도 중요한 한계가 있습니다. 파일에 적었다고 AI가 언제나 모든 규칙을 완벽하게 지키는 것은 아닙니다. 특히 실제 파일 변경과 외부 서비스 연결에는 사용자 검수가 필요합니다.

3. AGENTS.md는 어떤 파일로 만들어야 하나요?

처음에는 컴퓨터의 텍스트 편집기만 있어도 됩니다. 파일 이름은 다음과 같이 작성합니다.

AGENTS.md

이름의 철자를 확인하세요.

AGENTS.md
AGENT.md
AGENTS.txt

위 세 이름은 서로 다릅니다. Codex 같은 도구가 AGENTS.md라는 파일명을 기준으로 지침을 찾도록 구성된 경우, 비슷한 다른 파일명을 사용하면 자동으로 인식하지 못할 수 있습니다. 처음에는 프로젝트의 최상위 폴더에 AGENTS.md를 넣는 것이 이해하기 쉽습니다. 예를 들어 다음과 같습니다.

my-homepage/
├── AGENTS.md
├── index.html
└── style.css

이 예시에서 AGENTS.md는 홈페이지를 수정할 때 지켜야 할 규칙을 설명하고, index.html·style.css는 실제 웹페이지 파일입니다.

4. 처음 만들 때 넣으면 좋은 내용

AGENTS.md를 처음 만든다면 너무 많은 규칙부터 적을 필요가 없습니다. 초보자는 프로젝트 목적, 변경 범위, 확인 방식이라는 세 가지로 시작하면 좋습니다. 다음 예시는 복사해 연습용 파일에 붙여넣을 수 있습니다.


## 프로젝트 목적
- 개인용 HTML/CSS 학습 홈페이지입니다.

## 변경 규칙
- 요청한 작업과 관련된 파일만 수정해 주세요.
- 기존 문구와 이미지는 이유 없이 삭제하지 마세요.
- 파일을 수정하기 전에 변경 계획을 간단히 설명해 주세요.

## 확인 방식
- 작업 후 변경된 파일 목록을 정리해 주세요.
- 테스트했다면 실행한 방법과 결과를 알려 주세요.
- 테스트하지 않은 부분은 '미검증'이라고 표시해 주세요.

## 주의사항
- 파일 삭제나 새 프로그램 설치는 먼저 확인해 주세요.
- 실제 인터넷 배포는 사용자 승인 전 진행하지 마세요.
- 비밀번호와 API 키를 답변에 노출하지 마세요.

이 파일은 작업 규칙을 설명하기 위한 교육용 예시입니다. 주의: ‘사용자 승인 전 배포하지 마세요’라는 규칙을 문서에 적는 것과, 프로그램의 실제 배포·인터넷 접근 권한을 제한하는 것은 서로 다릅니다. 중요한 프로젝트에서는 샌드박스·승인·접근 제어를 별도로 확인하세요.

5. README.md와 무엇이 다른가요?

개발 프로젝트를 보면 README.md라는 파일도 자주 나타납니다. 두 파일은 모두 Markdown 문서일 수 있지만 대표적인 독자가 다릅니다.

파일 주로 누구를 위한가요? 대표적인 내용
README.md 프로젝트를 살펴보는 사람 프로젝트 소개, 설치·사용 설명
AGENTS.md 해당 파일을 읽는 AI 코딩 에이전트 수정 규칙, 파일 구조, 테스트·검수 지침

예를 들어 README.md에는 다음처럼 쓸 수 있습니다.

“이 프로젝트는 초보자가 만든 연습용 홈페이지입니다.” AGENTS.md에는 다음처럼 쓸 수 있습니다. “이 프로젝트를 수정할 때 기존 본문은 유지하고, 변경 파일과 테스트 결과를 보고하세요.” 물론 내용이 일부 겹칠 수 있습니다. 하지만 README.md를 작성했다고 AGENTS.md를 지원하는 도구가 자동으로 동일한 프로젝트 지침으로 적용한다는 뜻은 아닙니다.

6. AGENTS.md는 모든 AI 코딩 도구에서 작동하나요?

아닙니다. 도구마다 다릅니다. OpenAI Codex는 AGENTS.md를 지원하는 대표적인 코딩 에이전트입니다. 하지만 다른 AI 도구는 다른 파일명, 다른 탐색 위치, 다른 적용 규칙을 사용할 수 있습니다. 예를 들어 Anthropic의 Claude Code는 일반적으로 CLAUDE.md라는 파일을 프로젝트 지침과 메모리 용도로 사용합니다. 따라서 다음처럼 생각하면 안 됩니다. “AGENTS.md 파일을 만들어 두면 ChatGPT·Codex·Claude Code·모든 IDE가 자동으로 같은 규칙을 읽는다.” 지원 여부는 각 도구의 공식 문서에서 확인해야 합니다. 일부 환경에서는 다른 지침 파일을 명시적으로 연결하거나 가져오는 방법이 제공될 수도 있습니다. 이 경우에도 지원 범위와 우선순위를 확인해야 합니다.

7. 폴더마다 다른 AGENTS.md를 넣을 수 있나요?

네. OpenAI Codex 공식 자료는 프로젝트의 여러 폴더에서 AGENTS.md가 사용될 수 있다고 설명합니다. 예를 들어 다음과 같이 구성할 수 있습니다.

my-site/
├── AGENTS.md
├── pages/
│   ├── AGENTS.md
│   └── home.html
└── tests/
    └── site.test.js

위 구조에는 두 개의 AGENTS.md가 있습니다. 프로젝트 루트의 AGENTS.md는 일반적으로 프로젝트 전체 작업 규칙을 설명합니다. pages 폴더의 AGENTS.md는 그 하위 파일을 수정할 때 필요한 특별한 규칙을 정할 수 있습니다. 예를 들어 루트에는 “작업 후 변경 파일을 보고하세요”라고 쓰고, pages 폴더에는 “HTML 제목 계층을 유지하세요”라고 쓸 수 있습니다. Codex의 공식 지침 구조에서는 해당 경로에 적용되는 더 깊은 폴더의 구체적인 지침이 충돌 시 우선할 수 있습니다. 다만 모든 AI 코딩 도구가 정확히 동일하게 탐색·병합하는 것은 아닙니다. 현재 사용 중인 Codex 버전과 설정에 따라 전역 지침, 프로젝트 파일, 로컬 우선 파일 등 추가 규칙이 적용될 수 있습니다.

8. 개인 규칙과 팀 규칙을 구분할 수 있나요?

실제 팀 프로젝트에서는 구성원 모두가 지켜야 할 규칙과 개인이 선호하는 방식이 다를 수 있습니다. 예를 들어 팀 규칙은 다음과 같습니다.

  • 코드 변경 전 테스트 방법 확인
  • 공통 파일 명명 규칙 준수
  • 중요한 경로를 변경할 때 근거 기록 개인 규칙은 다음과 같을 수 있습니다.
  • 설명을 한국어로 해 주세요.
  • 어려운 코드는 쉬운 말로 풀어 주세요.
  • 먼저 짧은 계획을 보여 주세요. OpenAI의 Codex AGENTS.md 안내에는 사용자 전역 설정과 프로젝트별 지침을 구분하는 방식이 설명돼 있습니다. 일부 설정에서는 AGENTS.override.md 같은 로컬 우선 지침 파일이 활용될 수도 있습니다. 다만 정확한 탐색 경로와 우선 적용 방식은 사용 중인 버전의 공식 문서에 따라 달라질 수 있습니다. 초보자라면 처음에는 프로젝트 루트의 AGENTS.md 하나부터 만들고, 실제로 잘 적용되는지 확인한 다음 구조를 확장하는 것이 좋습니다.

9. AGENTS.md는 AI의 명령보다 우선하나요?

여기에서 파일에 적힌 규칙과 실제 작업 권한을 구분하는 것이 중요합니다. Codex의 공식 기본 지침에서는 AGENTS.md에 작성한 규칙이 특정 프로젝트의 작업 방식을 설명하지만, 상위 수준의 시스템·개발자·사용자 지시보다 높은 우선순위를 갖는 것은 아니다라고 설명합니다. 또한 AI가 참고했다고 해서 규칙 위반이 기술적으로 모두 차단되는 것도 아닙니다. 예를 들어 AGENTS.md에 다음과 같이 썼다고 해 보겠습니다.

외부 서버에 파일을 보내지 마세요.

이 문장은 중요한 작업 지침이지만, 네트워크 접근 권한 자체를 기술적으로 차단하는 방화벽 규칙이 아닙니다. 외부 통신을 실제로 막으려면 사용하는 프로그램의 권한·네트워크·샌드박스 설정을 함께 확인해야 합니다. 특히 중요한 데이터가 들어 있는 업무 저장소에서는 지침 파일만으로 보안이 완성됐다고 판단하면 안 됩니다.

10. API 키나 비밀번호를 AGENTS.md에 써도 되나요?

쓰지 않는 것이 원칙입니다. AGENTS.md에는 프로젝트의 작업 원칙을 적는 것이지 실제 비밀번호와 API 키를 저장하는 것이 아닙니다. 예를 들어 다음 같은 내용은 피해야 합니다.

관리자 비밀번호: (실제 비밀번호)
OpenAI API 키: (실제 비밀키)
데이터베이스 비밀번호: (실제 비밀값)

이 문구는 위험한 작성 방식의 가상 예시이며 실제 자격증명은 포함하지 않았습니다. AGENTS.md가 공개 GitHub 저장소에 올라가면 누구나 파일 내용을 볼 수 있을 수도 있습니다. 또한 코딩 에이전트가 읽는 지침은 처리 과정에서 모델에 제공될 수 있습니다. 비밀정보는 파일 위치·권한·비밀관리 기능을 따로 검토해 보관하고, AGENTS.md에는 “비밀키를 노출하지 마세요” 같은 원칙만 적는 편이 안전합니다. 이미 비밀 값이 외부에 공개됐다면 파일에서 지우는 것만으로 충분하지 않을 수 있습니다. 실제 서비스에서 해당 키를 폐기·재발급해야 할 수 있습니다.

11. AI가 AGENTS.md를 읽었는지 어떻게 확인하나요?

이제 가장 중요한 실습입니다. 프로젝트 루트에 AGENTS.md를 저장한 뒤, AGENTS.md를 지원하는 Codex 환경에서 연습용 프로젝트를 엽니다. 그다음 다음처럼 요청해 보세요.

이 프로젝트에서 적용되는 AGENTS.md 지침이
어떤 파일에 있는지 찾아보고,
작업 전에 어떤 규칙을 지켜야 하는지
간단히 정리해 줘.

아직 실제 파일을 수정하지는 마.

이 요청의 목적은 AI가 어떤 지침을 참고했다고 설명하는지 먼저 확인하는 것입니다. 그리고 정말 중요한 작업에 들어가기 전에 AI에게 다음을 물어볼 수 있습니다.

이번 수정에 영향을 주는 지침과
변경 예정 파일 목록을 보여 줘.

AGENTS.md의 해당 규칙을 설명해 줘.
코드 변경과 테스트는 내가 확인한 후 진행해.

주의할 점이 있습니다. AI가 “읽었습니다”라고 답했다고 실제로 모든 규칙을 정확하게 적용했다는 증거가 되지는 않습니다. 가능하면 실제 적용된 파일과 최종 변경 내역을 함께 확인해야 합니다.

12. AGENTS.md를 잘 써도 AI가 실수할 수 있나요?

네. 예를 들어 AGENTS.md에 “기존 파일을 삭제하지 마세요”라고 써 두더라도 AI가 잘못된 변경을 시도할 수 있습니다. 또는 오래된 지침을 읽고 이미 바뀐 프로젝트 구조를 잘못 이해할 수도 있습니다. 따라서 중요한 수정 작업에서는 다음 절차가 도움이 됩니다. 첫째. 원본 파일과 프로젝트 상태를 백업합니다. 둘째. 작업 범위를 가능한 한 작게 정합니다. 셋째. AI가 변경하려는 파일을 먼저 확인합니다. 넷째. 수정 후 파일 차이(diff)를 점검합니다. 다섯째. 필요한 테스트를 실제로 수행합니다. 여섯째. 인터넷 배포나 외부 서비스 변경은 별도 승인합니다. 이 순서에서 AGENTS.md는 반복할 규칙을 문서화하는 도구입니다. 실제 안전성은 설정·작업 방식·검수가 함께 뒷받침해야 합니다.

13. 팀 프로젝트에서 AGENTS.md가 특히 유용한 이유

여러 사람이 같은 저장소를 수정한다고 가정해 보겠습니다. 사람마다 말하는 방식이 조금씩 다르면 AI에게 전달되는 지시도 서로 다를 수 있습니다. 예를 들어 어떤 사람은 “기존 기능 유지”, 다른 사람은 “가능하면 새 코드 작성”이라고 요구할 수 있습니다. 이럴 때 프로젝트의 공통 규칙을 AGENTS.md에 정리해 두면 팀이 기대하는 기본적인 작업 방식을 설명하는 데 도움이 됩니다. 권장되는 주제는 다음과 같습니다.

  • 프로젝트의 목적과 중요한 파일 위치
  • 코드 스타일과 파일 이름 규칙
  • 수정하지 않아야 할 민감한 영역
  • 테스트 명령과 검수 방법
  • 변경 사항을 보고하는 형식
  • 승인 없이 하면 안 되는 외부 작업 다만 팀 규칙을 너무 길고 복잡하게 만들면 AI가 필요한 내용을 구분하기 어려울 수 있습니다. 실제 작업에 중요한 규칙만 간단하고 구체적으로 적는 것이 좋습니다.

14. 자주 발생하는 문제 6가지

문제 1. 파일을 만들었는데 AI가 규칙을 모릅니다

사용하는 AI 도구가 AGENTS.md를 지원하는지 먼저 확인하세요. 또한 파일 이름, 저장 위치, 현재 작업 폴더가 맞는지 확인해야 합니다.

문제 2. 하위 폴더의 규칙이 적용되지 않습니다

AGENTS.md를 어디에 두었는지 확인합니다. 규칙이 영향을 미치는 폴더와 실제 수정하려는 파일의 위치가 맞아야 합니다.

문제 3. 팀 규칙과 개인 규칙이 충돌합니다

실제로 적용되는 지침 파일이 여러 개라면 어떤 파일이 해당 경로에 적용되는지 확인합니다. 도구의 공식 우선순위 규칙을 확인하고 중복·상충하는 지침을 정리하세요.

문제 4. AGENTS.md만으로 파일 삭제를 막으려고 합니다

파일의 지침 문구는 보안 설정을 대신하지 않습니다. 위험한 명령은 도구의 권한 승인·샌드박스 설정에서도 통제하세요.

문제 5. 같은 파일을 Claude Code에서도 자동으로 읽을 거라 생각합니다

Claude Code는 공식적으로 CLAUDE.md를 주요 지침 파일로 설명합니다. 도구별 지원 범위와 가져오기 설정을 확인해야 합니다.

문제 6. 프로젝트 구조가 바뀌었는데 옛 규칙이 남아 있습니다

AGENTS.md도 프로젝트와 함께 유지·검수해야 합니다. 파일 위치나 테스트 명령이 바뀌었다면 지침도 최신 상태로 고치세요.

자주 묻는 질문

Q. AGENTS.md는 무료로 만들 수 있나요?

네. 텍스트 파일이므로 특별한 유료 작성 도구가 필요하지 않습니다. 다만 AGENTS.md를 읽어 작업하는 AI 서비스나 모델은 사용 조건·요금이 별도로 있을 수 있습니다.

Q. AGENTS.md가 없으면 Codex를 사용할 수 없나요?

그렇지는 않습니다. AGENTS.md는 프로젝트에 필요한 추가 지침을 제공하는 선택적 문서입니다. 없다고 모든 코딩 기능이 작동하지 않는 것은 아닙니다.

Q. AGENTS.md는 어느 폴더에 넣어야 하나요?

일반적으로 프로젝트 루트에 두면 이해하기 쉽습니다. 필요하면 특정 하위 폴더에 별도의 지침을 둘 수 있습니다. 실제 탐색 경로는 사용 중인 도구 공식 문서를 확인하세요.

Q. AGENTS.md와 README.md는 같은 파일인가요?

아닙니다. README.md는 주로 사람에게 프로젝트를 소개하는 문서이고, AGENTS.md는 이를 지원하는 코딩 에이전트의 작업 지침을 적는 문서입니다.

Q. AGENTS.md와 CLAUDE.md는 이름만 다른 같은 파일인가요?

아닙니다. 제품별로 기본 탐색 이름과 기능이 다릅니다. AGENTS.md는 Codex 등에서 활용되고, Claude Code는 CLAUDE.md를 주로 사용합니다. 하나를 작성했다고 모든 도구가 자동으로 같은 내용과 범위로 적용하지는 않습니다.

Q. AGENTS.md를 만들면 AI가 코드를 마음대로 수정하지 못하나요?

AGENTS.md 자체는 실제 권한 차단 기능이 아닙니다. 파일 수정·명령 실행·외부 통신을 제한하려면 프로그램의 별도 승인과 샌드박스 설정이 중요합니다.

Q. AGENTS.md 안에 테스트 명령을 적어도 되나요?

프로젝트에서 필요한 테스트 방법을 설명할 수 있습니다. 하지만 AI가 임의로 위험한 명령을 실행하지 않도록 명령의 내용과 실행 권한을 함께 검토해야 합니다.

Q. AGENTS.md를 공개 GitHub에 올려도 되나요?

공통 작업 지침처럼 공개해도 되는 내용이라면 프로젝트에 포함할 수 있습니다. 하지만 비밀번호, API 키, 개인정보, 비공개 보안 설정값은 넣지 마세요.

Q. AGENTS.md를 넣으면 AI가 파일을 읽었다는 사실을 어떻게 확인하나요?

사용 중인 코딩 에이전트에서 적용한 지침의 출처를 설명해 달라고 요청하고, 실제 변경 결과를 검토하세요. AI가 읽었다고 답하는 것만으로 모든 규칙의 완벽한 준수가 입증되지는 않습니다.

Q. AGENTS.md는 AI의 기억 기능인가요?

AGENTS.md는 파일로 저장된 작업 규칙입니다. 대화 기록 전체를 저장하는 기억 기능과는 다릅니다. 문서가 남아 있어도 지원 도구·폴더·실행 환경에 따라 읽기 여부가 달라질 수 있습니다.

마무리: AI에게 중요한 약속을 반복하지 않기 위한 문서

AGENTS.md는 코딩 에이전트에 프로젝트의 목적과 작업 규칙을 알려 주는 문서입니다. 처음에는 거창한 파일을 만들 필요가 없습니다. “기존 글 삭제 금지”, “변경 파일 먼저 설명”, “테스트하지 않은 결과는 미검증이라고 보고” 같은 규칙만 적어도 출발점이 됩니다. 그리고 두 가지를 구별하세요. AGENTS.md는 지침 문서입니다. 실제 파일·인터넷 접근 권한을 강제로 제한하는 보안 기능은 아닙니다. 중요한 프로젝트에서는 지침을 작성한 다음에도 백업, 최소 권한, 변경 내역 검수, 실제 테스트를 함께 진행해야 합니다. 이런 원칙을 지키면 AI 코딩 도구를 보다 예측 가능하게 활용하는 데 도움이 됩니다.

공식 자료

제품의 동작과 제한은 바뀔 수 있으므로 게시 시점에도 공식 문서에서 다시 확인하세요.

함께 읽으면 좋은 글