AI 코딩 에이전트에게 프로젝트 규칙을 기억시키는 법(AGENTS.md와 CLAUDE.md)

AI 에이전트 운영 파일 가이드 · 2026년 7월 기준

AI에게 매번 “이 프로젝트는 pnpm을 쓰고, 생성 파일은 직접 수정하지 말고, 작업이 끝나면 테스트를 실행해”라고 설명하고 있다면 문제는 모델 성능보다 프로젝트의 암묵지가 저장소에 없다는 것일 수 있다.

대화창의 지시는 세션이 바뀌면 사라지기 쉽다. 반면 AGENTS.md와 CLAUDE.md는 빌드 명령, 코드 규칙, 금지사항, 완료 기준을 프로젝트와 함께 버전 관리할 수 있게 해준다. 다만 두 파일은 이름만 다른 같은 기능이 아니다. 자동으로 읽는 도구와 탐색 방식이 다르며, 이 차이를 무시하면 “분명 파일에 적었는데 왜 안 지키지?”라는 문제가 생긴다.

먼저 보는 핵심 결론

① AGENTS.md는 여러 AI 코딩 도구가 채택하는 개방형 프로젝트 지침 포맷이며, OpenAI Codex가 기본적으로 읽는다.

② CLAUDE.md는 Claude Code가 기본적으로 읽는 지속 지침 파일이다. Claude Code는 AGENTS.md를 자동으로 읽지 않는다.

③ 여러 에이전트를 함께 쓴다면 AGENTS.md를 공용 원본으로 두고, CLAUDE.md에서 @AGENTS.md를 불러온 뒤 Claude 전용 규칙만 덧붙이는 구성이 실용적이다.

1. 공유된 Claude Cowork 사례에서 배울 점

공유 자료의 Claude Cowork 구성은 프로젝트 루트의 CLAUDE.md에 사람, 용어, 공통 작업 방식처럼 전체에 걸친 기억을 두고, investments/나 personal/ 같은 업무 폴더의 CLAUDE.md에는 그 영역의 역할과 말투를 두는 구조를 제안한다. 공통 원칙과 업무별 맥락을 계층으로 나눈다는 점이 핵심이다.

이 설계 원리는 좋은 출발점이다. 모든 규칙을 거대한 하나의 프롬프트에 넣는 대신, 루트에는 공통 규칙을 두고 가까운 폴더에는 그 작업에만 필요한 규칙을 둔다. 그러면 투자 분석을 할 때의 신중한 기준과 콘텐츠를 쓸 때의 문체를 서로 섞지 않을 수 있다.

좋은 지침 파일은 AI를 더 똑똑하게 만드는 마법의 프롬프트가 아니다. 해당 저장소에서 “무엇을 알고, 어떻게 일하고, 무엇으로 완료를 증명해야 하는지”를 적은 운영 계약이다.

단, Claude 중심의 폴더 구조를 Codex나 다른 에이전트가 그대로 읽을 것이라고 가정하면 안 된다. 공통·하위 규칙을 나눈다는 설계 원리는 공유할 수 있지만, 실제 파일명과 로딩 범위는 각 제품의 공식 동작에 맞춰야 한다.

2. AGENTS.md와 CLAUDE.md는 무엇이 다른가

AGENTS.md와 CLAUDE.md 비교

구분	AGENTS.md	CLAUDE.md
성격	여러 코딩 에이전트를 위한 개방형 Markdown 지침 포맷	Claude Code 전용 지속 지침·프로젝트 컨텍스트
기본 인식	OpenAI Codex가 기본 지원한다. 다른 도구의 지원과 탐색 규칙은 각 문서를 확인해야 한다.	Claude Code가 기본 지원한다. Claude Code는 AGENTS.md를 직접 자동 인식하지 않는다.
대표 범위	Codex 기준 글로벌 설정, 프로젝트 루트, 현재 작업 디렉터리까지의 하위 계층	조직 정책, 사용자, 프로젝트, 개인용 로컬 파일, 하위 폴더
결합 방식	Codex는 루트에서 현재 작업 디렉터리 순으로 합치며, 가까운 지침이 뒤에 와 앞선 지침을 덮는 방식으로 취급한다.	발견한 파일을 모두 이어 붙인다. 가까운 파일이 뒤에 오지만 충돌 시 확정적 덮어쓰기를 보장하지 않으므로 모순을 없애야 한다.
하위 폴더	Codex의 시작 체인은 현재 작업 디렉터리에서 끝난다. 특정 하위 규칙은 해당 디렉터리에서 시작해 확인하는 편이 안전하다.	현재 위치 아래의 CLAUDE.md는 관련 하위 파일을 읽을 때 필요에 따라 로드된다.
모듈화	중첩 AGENTS.md, Codex의 AGENTS.override.md와 대체 파일명 설정	@path 가져오기, .claude/rules/, 경로별 규칙, CLAUDE.local.md
길이 기준	Codex는 합산 크기를 기본 32KiB까지 읽는다.	Anthropic은 파일당 200줄 미만을 목표로 권장한다.
강제성	둘 다 기본적으로 모델에 주는 지침이다. CI에서 lint·test를 실행하고 branch protection으로 통과를 강제하며, 위험 동작은 permissions·sandbox·차단 훅·승인 절차로 통제해야 한다.

AGENTS.md 공식 사이트는 이를 “에이전트를 위한 README”에 비유한다. 사람용 README를 길게 만들지 않으면서 설치 방법, 테스트 명령, 코드 스타일, 보안 주의사항처럼 에이전트가 작업할 때 필요한 정보를 예측 가능한 위치에 제공하자는 취지다. 필수 필드가 정해진 설정 파일이 아니라 일반 Markdown이므로, 프로젝트에 맞는 섹션을 직접 구성하면 된다.

3. 실제로 어떤 파일이 로드되는가

Codex: 프로젝트 루트에서 현재 작업 디렉터리까지

OpenAI 공식 AGENTS.md 가이드에 따르면 Codex는 실행 또는 세션 시작 시 지침 체인을 구성한다. 먼저 Codex 홈 디렉터리에서 AGENTS.override.md를 찾고, 없으면 AGENTS.md를 읽는다. 프로젝트에서는 보통 Git 루트부터 현재 작업 디렉터리까지 내려오며 각 디렉터리에서 하나의 지침 파일을 선택한다.

1. 글로벌 범위: AGENTS.override.md가 있으면 우선하고, 없으면 AGENTS.md를 사용한다.
2. 프로젝트 범위: 각 디렉터리에서 AGENTS.override.md, AGENTS.md, 설정된 대체 파일명 순으로 확인한다.
3. 병합 순서: 루트에서 현재 디렉터리 순으로 합치므로, 더 가까운 지침이 뒤에 놓인다.
4. 용량: 비어 있는 파일은 건너뛰고 합산 크기가 기본 32KiB에 도달하면 추가 로딩을 멈춘다.

여기서 놓치기 쉬운 점은 “저장소 어딘가에 AGENTS.md가 있으면 항상 전부 읽는다”가 아니라는 사실이다. 예를 들어 루트에서 Codex를 시작했다면 더 아래의 특정 패키지 규칙이 시작 체인에 들어오지 않을 수 있다. 중요한 하위 규칙은 --cd 등으로 그 디렉터리에서 시작해 활성 지침을 확인하는 습관이 필요하다.

Claude Code: CLAUDE.md를 읽고 하위 파일은 필요할 때 로드

Claude Code는 사용자 범위의 ~/.claude/CLAUDE.md, 프로젝트의 ./CLAUDE.md 또는 ./.claude/CLAUDE.md, 개인 프로젝트 설정인 ./CLAUDE.local.md 등을 지원한다. 현재 작업 디렉터리에서 상위로 올라가며 파일을 찾은 뒤, 파일시스템 루트에서 현재 디렉터리 순으로 컨텍스트에 이어 붙인다.

현재 위치보다 아래에 있는 CLAUDE.md는 시작할 때 모두 넣지 않는다. Claude가 해당 하위 디렉터리의 파일을 읽을 때 관련 지침이 로드된다. 공유 자료에서 업무 폴더마다 역할과 말투를 분리한 구조가 Claude Code의 동작과 잘 맞는 이유다.

중요: Anthropic 공식 문서는 Claude Code가 CLAUDE.md를 읽으며 AGENTS.md는 직접 읽지 않는다고 명시한다. 두 파일을 같은 내용으로 복사해 두면 언젠가 서로 달라질 가능성이 크다.

4. 멀티에이전트라면 ‘공용 원본 + 얇은 어댑터’

Codex와 Claude Code를 같은 저장소에서 쓴다면 가장 단순한 구성은 AGENTS.md를 도구 중립적인 공용 규칙의 단일 원본으로 두는 것이다. 루트 CLAUDE.md에서는 이를 가져오고 Claude에만 필요한 내용만 추가한다.

project/
├── AGENTS.md                 # 공용 프로젝트 운영 규칙
├── CLAUDE.md                 # @AGENTS.md + Claude 전용 규칙
├── apps/
│   └── web/
│       ├── AGENTS.md         # 웹 앱 전용 공용 규칙
│       └── CLAUDE.md         # 같은 폴더의 @AGENTS.md 가져오기
└── .claude/
    └── rules/                # Claude용 경로별 세부 규칙

루트의 CLAUDE.md는 다음처럼 짧게 유지할 수 있다.

# Shared project instructions
@AGENTS.md

## Claude Code only
- src/billing/ 아래에서 3개 이상의 파일을 바꾸기 전에는
  먼저 계획과 위험 요소를 보여준다.
- 긴 반복 절차는 이 파일에 복사하지 말고 관련 skill을 사용한다.

모노레포에서는 한 단계가 더 필요하다. 루트 CLAUDE.md가 루트 AGENTS.md를 가져온다고 해서 Claude Code가 apps/web/AGENTS.md까지 자동으로 찾는 것은 아니다. Claude가 자동 발견하는 하위 파일은 CLAUDE.md이기 때문이다. 따라서 각 하위 프로젝트에 얇은 CLAUDE.md를 두고 같은 폴더의 @AGENTS.md를 가져오거나, .claude/rules/의 경로별 규칙으로 연결해야 한다.

심볼릭 링크로 CLAUDE.md를 AGENTS.md에 연결하는 방법도 있지만, Claude 전용 내용을 추가하기 어렵고 Windows에서는 관리자 권한이나 Developer Mode가 필요할 수 있다. 수정하기 쉽고 의도가 보이는 @AGENTS.md 방식이 대체로 관리하기 편하다.

5. 좋은 지침은 ‘조건 + 행동 + 검증 + 예외 보고’로 쓴다

“깔끔하게 작성한다”, “테스트를 철저히 한다”는 문장은 좋은 의도만 있을 뿐 완료 여부를 확인할 수 없다. AI가 안정적으로 따르기 쉬운 지침은 적용 조건, 구체적인 행동, 정확한 명령, 완료 기준이 함께 있다.

모호한 지침

테스트를 철저히 한다.
코드를 깔끔하게 작성한다.
보안에 주의한다.

검증 가능한 지침

웹 컴포넌트를 수정하면 지정한 lint와 test를 실행한다. 실행하지 못하면 이유와 미검증 범위를 최종 보고에 적는다.

## Web application changes

- apps/web/**/*.tsx를 수정하면 완료 전에
  pnpm --filter web lint
  pnpm --filter web test
  를 실행한다.

- generated/ 아래 파일은 직접 수정하지 않는다.
  소스를 바꾼 뒤 pnpm generate로 재생성한다.

- 검사를 실행할 수 없으면 성공했다고 표현하지 않는다.
  이유와 미검증 범위를 최종 보고에 적는다.

- 새 운영 의존성을 추가하기 전에는
  기존 패키지로 해결할 수 없는 이유와 대안을 먼저 제시한다.

지침 파일에 넣기 좋은 내용은 다음과 같다.

• 정확한 빌드·테스트 명령: 패키지 관리자, 워크스페이스 필터, 필요한 환경 조건
• 아키텍처 경계: 직접 수정하면 안 되는 생성 파일, 계층 간 의존 규칙, 소스 오브 트루스
• 코드 규칙: 추상적인 “클린 코드”가 아니라 이 저장소만의 구체적 관례
• 검증 기준: 무엇을 실행하고 어떤 결과를 보고해야 완료인지
• 안전 규칙: 삭제, 배포, 외부 메시지, 운영 데이터 변경 전에 확인이 필요한 조건

6. 지침 파일에 넣지 말아야 할 것

정보 유형별 권장 위치

정보	권장 위치	이유
항상 적용할 빌드·코드·검증 규칙	AGENTS.md 또는 CLAUDE.md	매 작업에 필요한 지속 컨텍스트다.
특정 상황의 긴 다단계 절차	Skill, runbook, 별도 문서	항상 로드하면 컨텍스트만 차지하고 핵심 지침의 준수도가 떨어진다.
반드시 막아야 하는 명령·경로	Permissions, hooks, sandbox	Markdown 지침은 행동을 유도하지만 기술적으로 차단하지는 않는다.
반드시 통과해야 하는 품질 기준	CI, lint, test, branch protection	실행 결과로 강제하고 기록할 수 있다.
API 키, 비밀번호, 개인 정보	Secret manager, 환경 변수	지침 파일은 저장소에 커밋될 수 있으므로 비밀 저장소가 아니다.

코드에서 바로 알 수 있는 전체 디렉터리 목록이나 패키지 설명을 길게 복사하는 것도 피하는 편이 좋다. Anthropic은 CLAUDE.md를 파일당 200줄 미만으로 유지하도록 권장한다. Codex도 프로젝트 지침의 합산 크기에 기본 제한이 있다. 길이가 품질을 보장하는 것이 아니라, 자주 필요한데 코드만 보고는 알기 어려운 규칙을 얼마나 선명하게 남겼는지가 중요하다.

7. 이 티스토리 프로젝트에 적용한 방식

실제로 이 블로그 프로젝트도 루트 AGENTS.md에는 모든 글에 공통으로 적용되는 원칙만 두고, 주제별 규칙은 하위 폴더에 나눠 두고 있다.

• posts/coding-test/AGENTS.md에는 기본 풀이 언어, 글의 고정 순서, 요청하지 않은 언어를 추가하지 않는 금지사항, 발행 전 검색 항목이 있다.
• posts/buying-guide/AGENTS.md에는 가격 기준일, 공식 근거와 작성자 판단의 분리, 과장 표현 금지, 표·외부 링크·출처 검수 기준이 있다.

이렇게 나누면 구매 가이드의 가격·재고 검증 규칙이 코딩테스트 풀이에 끼어들지 않고, 코딩테스트의 Python 전용 규칙이 일반 AI 글에 적용되지 않는다. 동시에 반복되는 출력 구조와 금지사항을 매 프롬프트마다 다시 설명할 필요가 줄어든다. 이번 글 역시 “공통 규칙은 루트, 주제 규칙은 하위 폴더”라는 구조를 실제 사례로 삼아 작성했다.

8. 만들고 끝내지 말고 실제 로딩을 검증한다

지침 파일의 가장 흔한 실패는 내용이 나쁜 것이 아니라 아예 로드되지 않은 경우다. 파일을 추가하거나 위치를 바꾼 뒤에는 도구가 무엇을 읽었는지 확인해야 한다.

• Codex: 대상 디렉터리에서 새 세션을 시작하고 활성 지침의 출처와 내용을 요약하게 한다. 하위 프로젝트는 그 디렉터리에서 별도로 확인한다.
• Claude Code: /memory로 현재 로드된 CLAUDE.md, CLAUDE.local.md, rules 파일을 확인한다.
• 충돌 검사: 루트와 하위 파일이 같은 항목에 반대되는 지시를 하지 않는지 검색한다.
• 실행 검사: 단순히 “규칙을 이해했니?”라고 묻는 데서 끝내지 말고 작은 수정 후 실제 lint·test·보고 형식을 확인한다.
• 세션 갱신: Codex 지침을 수정했다면 새 실행에서 체인이 다시 구성되는지 확인한다.

9. 시작할 때 필요한 최소 템플릿

처음부터 완벽한 운영 매뉴얼을 만들 필요는 없다. 매번 반복하는 지시 세 개, AI가 두 번 이상 틀린 관례, 작업 완료 전에 꼭 확인해야 할 명령부터 적으면 된다.

# Project instructions

## Scope
- 이 파일은 저장소 전체에 적용한다.
- 더 가까운 폴더의 지침이 있으면 그 영역의 세부 규칙을 함께 따른다.

## Before editing
- 변경 대상과 관련된 기존 구현, 테스트, 문서를 먼저 확인한다.
- 새 운영 의존성을 추가하기 전에는 대안과 영향 범위를 설명한다.

## Implementation
- generated/ 아래 파일은 직접 수정하지 않는다.
- 기존 공개 API를 바꾸면 마이그레이션 영향을 함께 기록한다.

## Verification
- 코드 변경 후 프로젝트의 lint와 test 명령을 실행한다.
- 실행하지 못한 검사는 이유와 미검증 범위를 최종 보고에 적는다.

## Safety
- 삭제, 배포, 운영 데이터 변경은 실행 전에 확인을 받는다.
- 비밀값을 코드, 로그, 지침 파일에 기록하지 않는다.

이 템플릿을 그대로 오래 유지하기보다 실제 실패를 관찰하며 다듬는 것이 중요하다. 에이전트가 같은 실수를 반복하면 더 구체적인 조건과 명령으로 바꾸고, 더 이상 필요 없는 규칙은 삭제한다. 지침 파일도 코드처럼 리뷰하고 버전 관리해야 한다.

10. 최종 정리

AGENTS.md와 CLAUDE.md 중 하나가 무조건 더 좋은 것은 아니다. 핵심은 사용하는 도구가 실제로 읽는 파일을 선택하고, 공통 규칙과 도구 전용 규칙의 경계를 명확히 하는 것이다.

• 여러 에이전트가 공유할 규칙은 AGENTS.md에 둔다.
• Claude Code에서는 CLAUDE.md가 @AGENTS.md를 가져오게 하고 Claude 전용 내용만 추가한다.
• 하위 프로젝트에는 그 범위에 필요한 지침만 두고, 각 도구의 실제 탐색 방식을 확인한다.
• 지침은 짧고 구체적이며 검증 가능하게 쓴다.
• 품질 기준은 CI와 branch protection으로, 위험 동작은 permissions·sandbox·차단 훅·승인 절차로 강제한다.

대화창에서 반복하는 지시가 세 개를 넘었다면, 더 긴 프롬프트를 쓰기 전에 저장소에 에이전트용 운영설명서를 만들 때다.

참고 자료

• My Full Claude Cowork Setup: How to Build Your Personal AI System From Scratch
• OpenAI Codex: Custom instructions with AGENTS.md
• Anthropic Claude Code: How Claude remembers your project
• AGENTS.md: An open format for guiding coding agents
• OpenAI: The Agentic AI Foundation

이 글은 2026년 7월 15일 기준 공식 문서를 바탕으로 정리했습니다. AI 도구의 지침 탐색 방식과 지원 파일은 버전에 따라 바뀔 수 있으므로 실제 적용 전 최신 공식 문서를 다시 확인하세요.