AGENTS.md CLAUDE.md 설계 원칙AGENTS.md and CLAUDE.md Design
📅
들어가기 전에 🔗
팀에 Codex와 Claude Code를 함께 도입하면 처음에는 아주 잘 작동하는 것처럼 보입니다.
문제는 시간이 지나며
작은 변경에도 서로 충돌하는 지침을 읽고, 에이전트는 불필요하게 긴 컨텍스트를 들고 작업하게 됩니다.
AGENTS.md, CLAUDE.md, README.md에 같은 규칙이 복사되고, 어느 에이전트가 어떤 파일을 읽는지 확신하지 못하게 되는 순간부터 시작됩니다.
👨💻
클로드야 제발 내가 원하는 파일을 읽어라~ 하며 기도를 하지는 않는지 반성할 필요가 있습니다.좋은 지침 파일은
에이전트에게 일을 설명하는 문서가 아니라, 필요한 규칙으로 빠르게 안내하는 경로표
입니다.
이 글에서는 두 파일의 역할을 나누고, 팀이 계속 유지할 수 있는 최소 구조를 만들어 보겠습니다.
공통 AGENTS.md와 Claude 전용 CLAUDE.md가 역할별로 분리된 구조
파일 역할 🔗
지침 파일은 많을수록 좋은 것이 아니라, 실제로 언제 읽히는지가 분명할수록 도움이 되는 파일입니다.
AGENTS.md 🔗
AGENTS.md에는 Codex, Claude Code, Cursor처럼 여러 에이전트가 함께 따라야 하는 저장소 공통 규칙
을 둡니다.
빌드와 테스트 명령, 변경 금지 영역, API 호환성 원칙처럼 도구가 달라도 바뀌지 않는 내용을 담기 좋습니다.Codex는 프로젝트 루트부터 현재 작업 디렉터리까지
AGENTS.md를 수집하며, 기본 지침 크기 제한 안에서 컨텍스트에 포함합니다.
OpenAI Codex agent loop↗CLAUDE.md 🔗
CLAUDE.md에는 Claude Code에서만 의미가 있는 워크플로와 설정을 둡니다.
예를 들어 Claude 전용 훅, /context 확인 방법, 특정 경로에 대한 Claude의 계획 모드 같은 규칙이 여기에 해당합니다.Claude Code는 기본 설정에서 경로에
CLAUDE.md가 있으면 AGENTS.md 대신 CLAUDE.md를 읽을 수 있습니다.
따라서 두 파일을 무심코 병렬로 만들면 공통 규칙이 누락될 수 있습니다.
Claude Code 메모리와 프로젝트 지침↗👍
Claude Code의 프로젝트 지침 로딩 설정을 바꾸지 않았다면, CLAUDE.md가 있는 경로에서 AGENTS.md의 공통 규칙이 빠질 수 있습니다. 두 파일을 함께 둘 때는 실제 로딩 결과를 반드시 확인합니다.공통 규칙 🔗
가장 먼저
AGENTS.md를 도구 공통 계약
으로 만듭니다.
프로젝트의 모든 정보를 적기보다, 에이전트가 추측하지 말아야 할 사실만 남기는 것이 중요합니다. # 공통 명령
- 패키지 설치와 실행은 npm을 사용합니다.
- 변경 후 npm run lint와 npm test를 실행합니다.
# 변경 경계
- 공개 API 응답 형식은 요청에 명시된 경우에만 바꿉니다.
- 데이터베이스 스키마 변경은 migration과 함께 검토합니다.
# 작업별 문서
- 인증 변경은 docs/auth.md를 읽습니다.
- 배포 변경은 docs/deploy.md를 읽습니다.이 파일에 폴더 구조 전체, 모든 의존성, 과거 장애 기록을 넣을 필요는 없습니다.
코드에서 다시 찾을 수 있는 정보는 지침이 아니라 검색으로 해결하게 두는 편이 낫습니다.
👨💻
지침에 넣을지 망설여진다면 이 질문을 해보시기 바랍니다. 에이전트가 이 정보를 모르면 안전하지 않거나, 같은 실수를 반복할까요. 그렇지 않다면 작업별 문서나 코드에 남기는 편이 좋습니다.Claude 규칙 🔗
Claude Code를 함께 쓴다면
CLAUDE.md에서 공통 파일을 먼저 가져오고, 그 아래에 Claude 전용 규칙만 추가합니다.
이 구조는 규칙 복사를 막고, 공통 원칙의 수정 지점을 하나로 유지합니다.@AGENTS.md
# Claude Code 규칙
- src/database/ 변경은 먼저 계획 모드에서 영향 범위를 설명합니다.
- 작업 시작 시 /context로 로드된 프로젝트 지침을 확인합니다.
- 장기 작업은 docs/agent-state/에 결정과 검증 명령을 남깁니다.@AGENTS.md를 먼저 두면 공통 규칙을 한 번만 관리하면서도 Claude 전용 규칙을 추가할 수 있습니다.
Claude Code 문서도 공통 파일을 가져온 뒤 도구별 지침을 덧붙이는 구성을 안내합니다.
Claude Code의 AGENTS.md 공유 방식↗
공통 지침을 먼저 읽고 Claude 전용 규칙을 이어 붙이는 지침 로딩 흐름
분리 기준 🔗
파일을 나누는 기준은 에이전트 이름이 아니라
적용 범위
입니다.
아래 표처럼 판단하면 중복을 줄일 수 있습니다.| 규칙 | 위치 | 이유 |
|---|---|---|
| 빌드와 테스트 명령 | AGENTS.md | 모든 에이전트가 필요합니다. |
| API 호환성·보안 경계 | AGENTS.md | 팀의 공통 계약입니다. |
| Claude 훅과 설정 | CLAUDE.md | Claude Code에서만 적용됩니다. |
| 개인 토큰과 로컬 경로 | 로컬 설정 파일 | 저장소에 커밋하면 안 됩니다. |
| 인증·배포 상세 절차 | docs/ | 해당 작업에서만 읽으면 됩니다. |
🖐️
API 키, 개인 토큰, 내부 접속 주소처럼 비밀값은 AGENTS.md와 CLAUDE.md에 적지 않습니다. 저장소 지침은 팀 전체와 자동화 도구가 읽는 공개 계약으로 취급합니다.하위 디렉터리 지침 🔗
모노레포나 큰 서비스에서는 루트 파일 하나로 모든 규칙을 설명할 수 없습니다.
이때는
apps/admin/AGENTS.md처럼 하위 경로에 가까운 지침을 두고, 해당 영역에서만 필요한 규칙을 추가합니다.루트 파일은 공통 계약이고, 하위 파일은 지역 규칙
입니다.
같은 내용을 두 파일에 반복하지 않으면 충돌과 컨텍스트 낭비를 함께 막을 수 있습니다.점검 방법 🔗
지침 파일을 만든 뒤에는 실제로 읽히는지 확인해야 합니다.
1. 새 세션에서 현재 작업 경로를 확인합니다.
2. 에이전트에게 적용 중인 프로젝트 지침을 요약하게 합니다.
3. 빌드 명령과 변경 금지 규칙을 질문합니다.
4. 하위 디렉터리 작업에서 추가 지침이 필요한지 확인합니다.
5. 실제 변경 후 lint와 test 결과를 기록합니다.Codex에서는
/status로 현재 세션의 환경과 컨텍스트 상태를 확인할 수 있습니다.
Claude Code에서는 /context 또는 /memory로 로드된 프로젝트 지침을 점검할 수 있습니다.
각 도구에서 파일이 실제로 로드되는지 확인하는 과정이 지침 설계의 마지막 단계입니다.
지침 파일을 검토하고 테스트와 컨텍스트 확인으로 검증하는 반복 흐름
팀 체크리스트 🔗
✓ 공통 규칙은
AGENTS.md 한 곳에서 관리합니다.
✓ CLAUDE.md에는 Claude 전용 규칙만 둡니다.
✓ 긴 설명은 docs/로 분리하고 적용 조건을 연결합니다.
✓ 개인 비밀값과 로컬 경로는 저장소 지침에 넣지 않습니다.
✓ 새 세션에서 실제 로드된 지침과 검증 명령을 확인합니다.결론 🔗
AGENTS.md와 CLAUDE.md의 목적은 더 많은 규칙을 쌓는 것이 아닙니다.
공통 규칙은 한 번만 유지하고, 도구별 동작은 필요한 위치에만 추가하는 것이 핵심입니다.
이 구조가 잡히면 도구를 바꾸거나 팀원이 늘어도 지침의 중복과 충돌을 줄일 수 있습니다.