CLAUDE.md와 AGENTS.md: 무엇이며 무엇을 써야 하고 에이전트가 규칙을 무시하는 이유

CLAUDE.md와 AGENTS.md란 무엇인가

저장소 루트에 있는 일반 Markdown 파일로, 세션이 시작될 때 에이전트가 자동으로 context에 불러옵니다. 이 파일을 통해 에이전트가 코드만으로는 알 수 없는 것을 알려 줍니다: 환경을 어떻게 띄우는지, 어떤 명령으로 작업을 검증하는지, 어떤 프로젝트 규칙이 협상 불가능한지, 상세 문서가 어디 있는지.

CLAUDE.md는 Claude Code가 읽는 파일입니다. AGENTS.md는 같은 아이디어를 담은 개방형 형식이며, 많은 코딩 에이전트가 지원합니다. 팀에서 여러 에이전트를 쓴다면 핵심 내용은 AGENTS.md에 두고, CLAUDE.md에서는 그 파일을 참조하는 것이 편리합니다. Claude Code는 @로 다른 파일을 가져오는 것을 지원합니다:

# CLAUDE.md
@AGENTS.md

이렇게 하면 규칙이 한 곳에 있고, 두 파일이 서로 어긋나지 않습니다.

에이전트는 이 파일을 어떻게 읽는가

지침 파일의 내용은 시스템 프롬프트와 함께 모델의 context 창에 들어가 세션 내내 그대로 남습니다. 여기서 세 가지 중요한 결과가 나옵니다.

• 모든 줄이 context 공간을 차지합니다. 파일은 매번 처음부터 끝까지 읽히며, 현재 작업에 필요한 것이 그중 10분의 1뿐이어도 마찬가지입니다.
• 이것은 실행되는 규칙이 아니라 텍스트입니다. 모델은 나머지 context와 함께 이를 고려하며, 100% 준수를 보장하지 않습니다. 엄격한 금지는 검사, hooks, 접근 권한으로 뒷받침해야 합니다.
• 파일은 중첩할 수 있습니다. Claude Code는 프로젝트 루트와 ~/.claude/의 CLAUDE.md를 불러오고, 하위 디렉터리의 파일은 에이전트가 그 디렉터리의 파일로 작업할 때 불러옵니다. 그래서 모듈의 규칙을 모듈 옆에 둘 수 있습니다.

CLAUDE.md와 AGENTS.md에 무엇을 써야 하는가

좋은 지침 파일은 교과서가 아니라 지도입니다. 신입 첫날 숙련된 동료에게 물어볼 질문들에 답합니다.

1. 프로젝트를 어떻게 빌드하고 검증하는가

가장 가치 있는 부분입니다. 에이전트가 "완료"라고 말하기 전에 반드시 실행해야 하는 구체적인 명령: 테스트, linter, 타입 검사, 환경 실행. 이것이 없으면 에이전트는 "눈대중"으로 검사합니다.

2. 엄격한 제약

어떤 경우에도 어기면 안 되는 짧은 목록: 보안과 데이터의 불변 조건. 구현 지시가 아니라 불변 조건으로 쓰세요. "모든 SQL 쿼리는 매개변수화한다"처럼요. "이 파일의 이 함수를 쓰라"처럼 쓰지 마세요.

3. 프로젝트 지도

무엇이 어디 있는지: 디렉터리 구조에 대한 몇 줄과 세부 내용이 어디에 있는지. 큰 주제마다 별도 문서로 링크하세요. 에이전트는 그 주제를 다룰 때만 그 문서를 열 것입니다.

4. 작업 상태는 어디에 있는가

이전 세션이 멈춘 지점에서 이어 가려면 무엇을 봐야 하는지: 계획 파일, 진행 로그, 백로그. 이것이 에이전트의 세션 간 "건망증"을 치료합니다.

무엇을 쓰지 말아야 하는가

• 에이전트가 코드에서 알 수 있는 것. 의존성 목록은 package.json이나 pyproject.toml에 있고, 클래스 구조는 코드 자체에 있습니다.
• 일반적인 조언. "깔끔한 코드를 쓰라", "주의하라"는 행동을 바꾸지 않고 자리만 차지합니다.
• 프로젝트의 역사와 일회성 메모. "3월에 MySQL 5.7에서 옮겼다"는 현재 작업에 도움이 되지 않습니다.
• 드문 작업에 대한 상세 지침. 배포나 데이터 마이그레이션 절차는 일주일에 한 번 필요합니다. 별도 문서나 skill로 옮기세요.
• 비밀 정보. 파일은 저장소에 있고 모델 전체에 전달됩니다. 토큰과 비밀번호는 환경 변수에만 두세요.

에이전트가 파일에 적힌 규칙을 무시하는 이유

흔한 이야기입니다: 에이전트가 실수하면 파일에 규칙이 추가됩니다. 또 실수하면 또 하나의 규칙이 추가됩니다. 몇 달 후 파일은 수백 줄이 되고, 중요한 보안 규칙은 마치 존재하지 않는 것처럼 어겨집니다. 보통 네 가지 원인이 있으며, 동시에 작용합니다.

부풀어 오른 파일

600줄짜리 파일은 대략 1만에서 2만 토큰입니다. context 창이 커 보여도 그 안에는 코드, 명령 출력, 대화 기록도 들어갑니다. 지침이 공간을 많이 차지할수록 각 규칙이 받는 주의는 줄고, 작업 자체에 쓸 공간도 줄어듭니다.

중간에 묻힌 규칙

언어 모델은 긴 텍스트의 가운데에 있는 정보를 처음이나 끝보다 뚜렷하게 덜 활용합니다. 600줄 중 300번째 줄의 규칙은 가장 약한 위치에 있습니다.

우선순위 없음

협상 불가능한 금지와 스타일에 대한 일시적인 메모가 목록에서 똑같이 한 줄로 쓰여 있습니다. 에이전트는 어느 것이 더 중요한지 알 방법이 없습니다. 파일에 서로 모순되는 스타일 규칙 세 개가 있다면, 실행할 때마다 동작이 무작위로 바뀝니다.

부패

규칙을 추가하는 것은 공짜지만 삭제는 무섭습니다. "혹시 다른 무엇이 여기 의존하고 있으면 어떡하지?" 그래서 파일은 계속 커지고 유용한 줄의 비율은 떨어집니다. 이를 신호 대 잡음 비율로 측정하면 유용합니다: 전형적인 작업에 실제로 필요한 줄은 몇 줄이고, 쓸모없는 줄은 몇 줄인가?

해결책: 긴 목록 대신 라우터

하나의 원인만 고쳐서는 소용이 없습니다. 파일을 줄이더라도 구조를 바꾸지 않으면 규칙들은 여전히 뒤섞여 있습니다. 효과적인 방법은 여러 조치를 함께 쓰는 것입니다.

1. 진입 파일을 라우터로 만드세요. 50에서 150줄: 검증 명령, 엄격한 규칙, 프로젝트 지도, 주제별 문서 링크.
2. 주제를 별도 파일로 옮기세요. 예: docs/agents/deploy.md, docs/agents/database.md. 에이전트는 필요할 때 이를 엽니다. Claude Code에서는 반복되는 절차에 skills가 유용합니다. 필요할 때만 로드됩니다.
3. 중요한 것을 위로 올리세요. 엄격한 규칙은 파일 맨 위에 MUST 표시가 붙은 짧은 블록으로 두세요.
4. 모순을 없애세요. 주제마다 규칙은 하나. 예외가 있다면 규칙 바로 옆에 쓰세요.
5. 규칙을 메커니즘으로 뒷받침하세요. 위반이 허용되면 텍스트만으로는 부족합니다. 위반을 잡아내는 검사가 필요합니다: linter, 테스트, pre-commit hook, 에이전트 hook, 또는 접근 권한 제한.
6. 정기적으로 점검하세요. 줄 수 상한을 정하고, 추가할 때마다 무엇을 지우거나 밖으로 옮길 수 있는지 자문하세요.

규칙일까, 검사일까?

간결한 AGENTS.md 예시

# AGENTS.md — 결제 백엔드 (FastAPI, PostgreSQL)

## MUST — 어기지 않는다
- 금액은 정수 원 단위(int)로만, float은 쓰지 않는다
- SQL은 매개변수화된 형태만, f-string은 쓰지 않는다
- 적용된 migration은 수정하지 않고, 새 migration만 추가한다
- 비밀 정보는 환경 변수에서만 읽는다

## "완료"라고 말하기 전 검증
docker compose up -d     # 환경
make lint                # ruff + mypy
make test                # pytest
make e2e                 # 주문 흐름 시나리오
e2e 없이 unit 테스트만 초록색이면 "완료"가 아니다.

## 지도
- app/payments/   — 금액 계산, 할인, 결제사 webhook
- app/api/        — HTTP 핸들러
- tests/e2e/      — 사용자 시나리오
상세: docs/agents/architecture.md, docs/agents/database.md

## 작업 상태
- PLAN.md      — 현재 목표, 완료 기준, 다음 단계
- PROGRESS.md  — 무엇을 했고 어떻게 검증했는지, 막다른 길
- BACKLOG.md   — 작업 중 발견한 것: 여기에 적고, 지금 고치지 않는다

세션이 끝나면 PROGRESS.md와 PLAN.md의 다음 단계를 갱신한다.

여기에 없는 것도 주목하세요: 라이브러리 목록, 스타일 조언, 프로젝트의 역사. 이 모든 것은 코드에서 보이거나, 검사로 고정되어 있거나, 주제별 문서에 있습니다.

세션 사이의 건망증: 지침 파일과 계획 파일

지침 파일은 프로젝트에서 어떻게 일해야 하는지를 설명하지만, 지금 무슨 일이 일어나고 있는지는 설명하지 않습니다. 이를 위해 에이전트가 시작할 때 읽고 세션 끝에 갱신하는 별도의 상태 파일이 필요합니다. 여기에는 목표, 완료된 작업과 그것을 어떻게 검증했는지, 내린 결정과 그 이유, 기각된 대안, 그리고 다음 단계 한 줄이 들어 있어야 합니다. 품질 확인은 간단합니다: 새 세션을 열고 "계속해"라고 쓴 뒤, 에이전트가 질문 없이 유용한 작업을 시작하는지 보세요.

두 파일을 섞지 마세요. 지침은 드물게 바뀌고 모든 작업에 적용됩니다. 계획은 세션마다 바뀌고 현재 작업에만 적용됩니다. 둘을 섞으면 지침 파일이 오래된 메모로 빠르게 부풀어 오릅니다.

파일이 제대로 작동하는지 확인하기

지침 파일도 검증이 필요합니다. 몇 가지 전형적인 작업을 골라 보세요: 버그 수정, 작은 기능, 리팩터링. 힌트 없이 에이전트가 무엇을 하는지 보세요. 필요한 명령을 실행하는지, 올바른 주제 문서를 여는지, 엄격한 규칙을 지키는지. 규칙이 어겨진다면, 먼저 물어보세요: 그 규칙이 눈에 띄는가, 모순되는 것은 없는가, 자동 검사로 대체할 수 있는가? 새 줄을 추가하는 것은 마지막 수단입니다.

마무리

CLAUDE.md와 AGENTS.md는 에이전트가 프로젝트에 들어가는 입구입니다. 짧은 지도로 남아 있을 때 잘 작동합니다: 검증 명령, 위쪽의 엄격한 규칙, 세부 내용과 계획 파일로의 링크. 규칙이 무시된다면 원인은 대부분 부풀고 구조가 없는 파일이며, 정말 중요한 규칙은 검사와 hooks로 뒷받침해야 합니다. 지침과 상태의 구조를 어떻게 만들지는 실제 작업을 다루는 실습 과정에서 설명합니다.