AI 코딩 도구를 쓰다 보면 답변 품질보다 먼저 반복 설명에 지칩니다. “이 프로젝트는 pnpm을 쓴다”, “이 폴더는 건드리지 않는다”, “끝나면 이 검사를 돌린다” 같은 말입니다.
이 설명을 매번 프롬프트에 붙이는 대신 프로젝트 안에 규칙 파일로 남길 수 있습니다. 대표적인 이름이 AGENTS.md와 CLAUDE.md입니다.
이 파일은 AI에게 마법처럼 정확성을 부여하는 설정이 아닙니다. 프로젝트 맥락을 반복해서 전달하는 문서이자, 팀이 AI에게 기대하는 작업 절차를 적어 둔 운영 계약에 가깝습니다.
먼저 “어떤 파일을 읽는가”와 “무엇을 강제하는가”를 나눠야 합니다. OpenAI의 AGENTS.md 안내는 Codex가 작업 디렉터리의 지침 파일을 계층적으로 읽는 방식을 설명하지만, 다른 클라이언트가 같은 파일을 읽는다는 뜻은 아닙니다. Anthropic의 Claude Code 메모리 문서는 CLAUDE.md를 프로젝트 맥락으로 읽고 다른 파일을 불러오는 방법을 별도로 설명합니다. 반면 명령 차단·시크릿 보호·배포 승인은 설정이나 CI처럼 자연어 밖의 장치가 맡아야 합니다.
- 구조진입점과 주요 폴더, 생성 파일 위치를 알려 줍니다.
- 명령설치·테스트·빌드처럼 실제 실행할 명령을 적습니다.
- 경계수정 금지 영역과 사람 승인이 필요한 행동을 나눕니다.
- 완료 조건diff와 테스트 등 작업이 끝났음을 증명할 기준을 둡니다.
AGENTS.md와 CLAUDE.md는 무엇이 다른가
| 구분 | 역할 | 설명 | 예시 |
|---|---|---|---|
| AGENTS.md | 여러 도구에 공유할 프로젝트 지침 | 공통 규칙으로 쓰려면 사용하는 도구가 실제로 이 파일을 읽는지 확인해야 합니다. | 적용 위치와 지원 여부 |
| CLAUDE.md | Claude Code의 프로젝트 맥락 | Claude Code가 읽는 위치와 하위 디렉터리 적용 범위, import 규칙을 확인합니다. | 프로젝트·사용자·하위 디렉터리 범위 |
| 도구 설정 파일 | 권한과 실행 동작을 제어 | 모델, 명령 실행, 권한 승인처럼 제품별 동작을 자연어 규칙과 분리해 적습니다. | 권한·모델·명령 실행 설정 |
파일 이름이 같다고 모든 도구가 같은 방식으로 읽는 것은 아닙니다. Anthropic의 Claude Code 기능 개요는 CLAUDE.md를 세션마다 불러오는 지속적 맥락으로 설명합니다. OpenCode 공식 문서도 규칙 파일을 별도 구성 항목으로 안내합니다. 실제로 어떤 도구가 어느 위치의 파일을 읽는지와 권한·모델·명령 실행 설정은 OpenCode 설정 문서처럼 사용 중인 도구의 현재 문서에서 확인해야 합니다.
도구별로 먼저 확인할 질문
| 구분 | 역할 | 설명 | 예시 |
|---|---|---|---|
| 탐색 경로 | 루트 파일을 자동으로 읽는가 | 저장소에 있어도 클라이언트가 지원하지 않으면 규칙은 적용되지 않습니다. | 파일 이름·탐색 위치 |
| 상속 범위 | 하위 폴더 파일을 추가로 읽는가 | 폴더별 예외를 둘 수 있는지와 충돌 가능성을 판단합니다. | 하위 디렉터리 규칙 |
| 우선순위 | 상·하위 규칙이 충돌하면 무엇이 우선인가 | 같은 작업에 서로 다른 명령이 제시되는 상황을 예방합니다. | 가장 가까운 규칙·명시적 예외 |
| 강제 장치 | 설정·훅·CI로 차단할 수 있는가 | 자연어 규칙을 우회해도 막아야 하는 위험을 별도 통제로 분리합니다. | 권한·승인·자동 검사 |
이 네 가지 답을 문서에 적어 두면 “파일을 만들었는데 왜 안 지키지?”라는 문제를 재현하기 쉽습니다. 문서에 없는 동작을 관행처럼 가정하지 말고, 작은 작업으로 적용 여부를 확인하세요.
좋은 규칙 파일은 짧고 실행 가능하다
처음부터 프로젝트의 모든 역사와 취향을 넣으면 AI가 중요한 규칙을 놓치기 쉽습니다. 다음 네 종류만 먼저 적어도 효과가 큽니다.
- 프로젝트 구조: 앱의 진입점, 주요 폴더, 생성 파일 위치
- 실행 명령: 설치, 개발 서버, 린트, 테스트, 빌드 명령
- 변경 원칙: 수정 전 계획, diff 확인, 호환성 유지, 금지된 폴더
- 완료 조건: 반드시 실행할 검증과 결과 보고 방식
예를 들어 저장소 루트에 두는 AGENTS.md는 모든 작업에 공통인 기준만 짧고 구체적으로 담을 수 있습니다. 아래는 특정 도구의 실행 결과가 아니라, 웹 프로젝트에 맞춰 바꿔 쓸 수 있는 문서 기반 예시입니다.
# AGENTS.md
## 프로젝트 기준
- 패키지 매니저는 pnpm을 사용한다.
- 앱 코드는 `src/`, 콘텐츠는 `content/articles/`에 둔다.
- 기존 구조와 디자인 토큰을 먼저 확인하고 최소 diff로 수정한다.
## 작업 순서
1. 관련 파일과 검증 명령을 읽고 변경 범위를 먼저 요약한다.
2. 필요한 파일만 수정하고, 무관한 포맷 변경과 리팩터링을 섞지 않는다.
3. 가능한 검증을 실행하고 성공·실패·미실행 항목을 나눠 기록한다.
## 경계
- 비밀키와 고객 데이터를 파일·로그·프롬프트에 포함하지 않는다.
- 인증·결제·삭제·배포 변경은 계획과 영향을 먼저 보고하고 승인 후 실행한다.
- 자연어 규칙을 권한 차단이나 CI 검증의 대체물로 간주하지 않는다.
## 완료 조건
- 변경 파일과 핵심 diff를 요약한다.
- 실행한 명령과 결과, 실행하지 못한 검증을 함께 기록한다.
- 남은 가정과 위험, 되돌릴 방법을 명시한다.
이 예시의 경로와 패키지 매니저, 검증 명령은 실제 프로젝트에 맞게 바꿔야 합니다. 존재하지 않는 명령을 적거나, “항상 완벽하게 작성한다” 같은 추상적인 문장을 늘어놓으면 규칙 파일은 장식이 됩니다. 반대로 수정 범위·금지 경계·완료 증거처럼 확인할 수 있는 문장을 남기면 다음 작업에서도 기준을 재사용하기 쉽습니다.
Claude Code에서도 같은 기준을 사용하려면 AGENTS.md를 통째로 복사해 두기보다 프로젝트 루트의 CLAUDE.md에서 @AGENTS.md를 불러오는 방법을 고려할 수 있습니다. Claude Code는 AGENTS.md를 자동으로 읽지 않으므로, Claude 전용 규칙이 필요할 때만 import 아래에 별도 항목을 덧붙이는 편이 두 파일의 불일치를 줄입니다.
범위를 나눠야 규칙이 충돌하지 않는다
규칙의 효과는 파일 이름보다 도구가 실제로 읽는 범위에서 결정됩니다. 다음은 특정 저장소의 실구조가 아니라 충돌을 설명하기 위한 작은 예시입니다.
sample-repo/
├─ AGENTS.md # pnpm 사용, 전체 quick 검사
├─ CLAUDE.md # @AGENTS.md를 불러오고 Claude Code 전용 설명 추가
├─ src/
│ ├─ AGENTS.md # UI 변경이면 접근성 검사 추가
│ └─ checkout.ts
└─ docs/
└─ guide.md
Codex가 src/checkout.ts를 다룰 때는 OpenAI의 AGENTS.md 문서에 설명된 탐색 규칙에 따라 루트 지침과 더 가까운 src/AGENTS.md를 함께 확인합니다. 따라서 공통 quick 검사에 UI 접근성 검사가 더해집니다. Claude Code 쪽은 같은 동작이라고 가정하지 않습니다. Anthropic의 메모리 문서에 나온 CLAUDE.md와 import 규칙으로 @AGENTS.md를 명시해서 공통 내용을 가져오고, Claude Code에만 필요한 내용은 별도로 둡니다.
개인 지침에 “테스트를 생략하라”가 있고 저장소 규칙에 “quick 검사를 통과하라”가 있다면 파일명만 보고 승자를 정하지 않습니다. 도구별 공식 우선순위와 현재 세션에 실제로 로드된 지침을 확인하고, 저장소의 강제 검사 결과를 완료 조건으로 삼습니다. 같은 문장을 여러 파일에 복사하면 어느 사본이 최신인지 알기 어려우므로 공통 규칙은 한곳에 두고 도구가 지원하는 import나 짧은 연결 문장으로 이어야 합니다.
규칙 파일에 넣으면 안 되는 것
- API 키, 비밀번호, 개인 액세스 토큰
- 고객 원문 데이터와 운영 환경의 비밀 값
- 법적·보안상 공개하면 안 되는 내부 정보
- 도구가 실제로 실행할 수 없는 추상적인 약속
- 서로 모순되는 오래된 규칙
규칙 파일은 AI가 읽을 수 있는 문서이므로 저장소의 일반 문서와 같은 방식으로 관리해야 합니다. 특히 공개 저장소에 들어갈 수 있는 파일이라면 비밀정보가 없는지 검토해야 합니다.
규칙 파일이 팀의 작업 표준이 되는 순간
AI 코딩 도구가 바뀔 때마다 프롬프트를 다시 연구하는 방식은 오래가기 어렵습니다. 반면 “변경 전에 계획을 보여 준다”, “테스트 실패를 숨기지 않는다”, “민감한 로직은 승인받는다” 같은 원칙은 도구가 바뀌어도 유지할 수 있습니다.
그래서 AGENTS.md와 CLAUDE.md를 작성할 때는 AI에게 잘 보이게 쓰는 것보다 팀이 실제로 지킬 수 있게 쓰는 것이 먼저입니다. 규칙이 너무 많아 지켜지지 않으면 중요한 규칙도 묻힙니다. Anthropic은 Claude Code 메모리 문서에서 프로젝트 지침을 짧게 유지하는 방향을 안내하고 있으며, 이 원칙은 다른 도구에도 실무적으로 적용할 만합니다.
프로젝트 규칙을 남기는 일과 긴 대화의 작업 상태를 정리하는 일도 구분해야 합니다. 규칙 파일은 유지하면서 세션을 언제 이어가거나 나눌지 판단하는 방법은 Claude Code 컨텍스트 관리에서 이어집니다.
자연어 규칙과 강제 장치를 분리하기
규칙 파일은 의도와 맥락을 전달하는 데 강하고, 설정·권한·CI는 위반을 차단하는 데 강합니다. 둘을 한 문장에 섞으면 “적어 두었으니 막혔다”는 잘못된 기대가 생깁니다.
| 구분 | 역할 | 설명 | 예시 |
|---|---|---|---|
| 규칙 파일 | 무엇을 왜 지켜야 하는가 | 폴더 구조, 작업 순서, 검증 기준처럼 사람이 읽고 수정할 맥락을 전달합니다. | AGENTS.md·CLAUDE.md |
| 제품 설정 | 어떤 행동을 승인할 것인가 | 명령 실행, 네트워크, 모델, 승인 흐름처럼 클라이언트가 제공하는 통제 범위를 정합니다. | 권한·샌드박스·승인 |
| 자동 검증 | 결과가 기준을 통과했는가 | 린트·테스트·CI·정책 검사로 자연어 지침이 실제 결과에 반영됐는지 판정합니다. | CI·훅·정적 분석 |
예를 들어 “운영 데이터베이스를 수정하지 않는다”는 의도는 규칙 파일에 적을 수 있지만, 실제 차단은 읽기 전용 계정·네트워크 정책·CI 승인 단계가 담당해야 합니다. Anthropic도 CLAUDE.md를 행동 맥락으로 설명할 뿐, 이 파일이 권한 경계를 대신한다고 설명하지 않습니다.
앞으로 AI가 더 많은 작업을 맡게 되더라도 프로젝트의 품질은 자연어 지침만으로 보장되지 않습니다. 규칙 파일은 테스트, 린트, CI, 권한 설정과 함께 있어야 합니다. 자연어는 의도를 전달하고, 자동화된 검증은 실제 준수 여부를 확인하는 역할을 나누는 것이 좋습니다.
프로젝트 전체에 적용할 규칙과 특정 업무의 반복 절차를 나누고 싶다면 Agent Skill과 SKILL.md 작성법을 함께 참고하세요. 공통 규칙 파일을 모든 작업의 상세 매뉴얼로 늘리는 일을 줄일 수 있습니다.
팀에서 운영하는 방법
- 한 프로젝트에서 가장 자주 반복하는 설명 다섯 개를 고릅니다.
- 루트 규칙 파일에 짧게 기록합니다.
- AI가 자주 틀리는 부분만 한 항목씩 보완합니다.
- 규칙이 실제로 적용되는지 diff와 명령 로그로 확인합니다.
- 프로젝트 구조가 바뀔 때 규칙 파일도 함께 리뷰합니다.
규칙 파일을 한 번 만들고 잊어버리면 오히려 잘못된 작업을 유도할 수 있습니다. 코드와 마찬가지로 변경 이유를 남기고, 오래된 명령과 폴더 설명을 정리해야 합니다.
작은 변경으로 적용 여부와 충돌을 함께 확인합니다
긴 작업을 바로 맡기기보다 위 파일 트리에서 src/checkout.ts의 버튼 이름 하나를 바꾸는 작은 변경을 요청합니다. 보고에는 읽은 규칙 파일, 선택한 검사 명령, 실제 diff, 검사 결과를 포함하게 합니다. 이 예시는 문서에 적힌 탐색 방식을 확인하는 절차이지 특정 실행 결과를 주장하는 테스트 기록이 아닙니다.
- 발견도구가 루트와 대상 경로에서 어떤 규칙 파일을 읽었는지 확인합니다.
- 충돌개인·루트·하위 지침이 다르면 도구별 공식 우선순위와 현재 로드 상태를 확인합니다.
- 실행규칙에 적힌 명령이 현재 package script와 CI에 존재하는지 대조합니다.
- 강제자연어 지침으로 끝내지 않고 lint·test·권한·승인 장치가 실제 실패를 막는지 봅니다.
파일을 못 찾으면 위치와 이름을, 충돌하면 적용 범위와 우선순위를, 오래된 명령을 실행하면 저장소 스크립트와 CI를 먼저 확인합니다. 실수가 반복되면 규칙을 더 길게 쓰기 전에 모호한 문장을 예시·검사·승인 경계로 바꿉니다. 규칙 파일은 실행 권한이나 보안 통제가 아니므로 비밀값 접근, 네트워크 전송, 배포 같은 행동은 별도의 기술적 제한과 사람 승인이 막아야 합니다.
작성 전 체크리스트
- [ ] 사용하는 AI 도구가 이 파일을 읽는지 확인했는가
- [ ] 규칙의 적용 범위를 구분했는가
- [ ] 실제로 실행 가능한 명령만 적었는가
- [ ] 금지 대상과 사람 승인이 필요한 작업을 구체화했는가
- [ ] 비밀정보와 고객 데이터가 없는가
- [ ] 완료 조건에 테스트·린트·diff 확인을 포함했는가
- [ ] 팀원이 읽고 수정할 수 있는 길이인가
- [ ] 코드 구조 변경 시 함께 업데이트할 책임자가 있는가
자주 묻는 질문
AGENTS.md 하나만 쓰면 Claude Code에서도 작동하나요?
도구와 설정에 따라 다릅니다. Claude Code는 CLAUDE.md를 중심으로 프로젝트 지침을 읽으며, 다른 파일을 import하는 방식도 문서화되어 있습니다. AGENTS.md를 공통 파일로 쓰고 싶다면 현재 버전의 지원 방식과 적용 여부를 먼저 확인하세요.
규칙을 많이 적을수록 AI가 더 정확해지나요?
반드시 그렇지는 않습니다. 서로 충돌하거나 오래된 규칙이 많으면 중요한 지침이 묻힐 수 있습니다. 반복되는 실수와 실제 검증 명령부터 적는 편이 낫습니다.
규칙 파일로 보안을 완전히 막을 수 있나요?
아닙니다. 규칙은 의도를 전달하는 장치이고, 권한 차단·시크릿 관리·CI 검증을 대신하지 못합니다. 위험한 명령은 도구의 권한 설정과 시스템 정책으로도 제한해야 합니다.
VIEW—
