CLAUDE.md를 길게 쓸수록 AI가 더 잘할까요?

CLAUDE.md와 AGENTS.md는 길게 쓴다고 더 잘 작동하지 않습니다.

중요한 것은 얼마나 많은 내용을 넣었느냐가 아니라, 어떤 내용을 어느 범위에 두었느냐입니다.

AI에게 이번에 해야 할 일을 전달하는 방법은 AI가 발전해도 통하는 프롬프트 작성법에서 다뤘습니다. 이 글에서는 여러 작업에서 반복해서 사용할 지침을 어디에 두어야 하는지 설명합니다.

먼저 역할을 구분합니다

가장 간단하게 구분하면 다음과 같습니다.

프롬프트에 들어갈 내용을 CLAUDE.md에 복사하거나, 특정 프로젝트의 규칙을 전역 파일에 넣으면 지침이 불필요하게 길어집니다.

전역 파일과 프로젝트 파일은 역할이 다릅니다

전역 파일

모든 프로젝트에서 적용할 개인의 작업 원칙입니다.

• Claude Code: ~/.claude/CLAUDE.md
• Codex: ~/.codex/AGENTS.md

특정 언어, 프레임워크나 저장소 구조가 바뀌어도 유지할 판단 방식만 적습니다.

• 먼저 조사한 뒤 수정합니다.
• 요청을 충족하는 최소 변경을 선택합니다.
• 관련 없는 코드는 함께 수정하지 않습니다.
• 검증 결과 없이 완료했다고 말하지 않습니다.

프로젝트 파일

현재 저장소에서만 유효한 팀의 규칙과 계약입니다.

• Claude Code: ./CLAUDE.md 또는 ./.claude/CLAUDE.md
• Codex: 저장소의 ./AGENTS.md

공식 빌드·테스트 명령, 활성 API 계약, 수정 금지 영역, 데이터와 보안 경계처럼 저장소를 읽는 것만으로는 팀의 공식 판단을 알기 어려운 내용을 적습니다.

경로별 규칙

특정 디렉터리나 파일에서만 필요한 규칙은 전체 프로젝트 파일에 넣지 않습니다.

Claude Code에서는 .claude/rules/의 경로별 Rule을 사용하고, Codex에서는 해당 디렉터리에 가까운 AGENTS.md를 사용할 수 있습니다. 규칙을 실제 적용 범위에 가깝게 두면 다른 작업에 불필요한 컨텍스트가 섞이는 것을 줄일 수 있습니다.

무엇을 어디에 둘지 정하는 기준

CLAUDE.md와 AGENTS.md는 에이전트의 행동을 안내하는 컨텍스트입니다. 보안이나 실행 권한을 강제하는 설정은 아닙니다. 반드시 지켜야 하는 경계는 문서와 함께 Hook, CI, 브랜치 보호와 권한 설정으로 강제해야 합니다.

넣지 않아도 되는 내용

다음 내용은 지침 파일을 길게 만들지만 실질적인 도움이 적습니다.

• 저장소의 전체 파일 트리
• README나 API 문서의 복사본
• 코드에서 쉽게 확인할 수 있는 구조
• 이번 작업에서만 필요한 목표
• 특정 상황에서만 사용하는 긴 절차
• CI나 권한으로 강제해야 하는 보안 정책

에이전트가 저장소를 잠깐 탐색하면 확인할 수 있는 정보는 다시 복사하지 않습니다.

반대로 저장소만 읽어서는 알 수 없는 팀의 선택, 활성 계약, 수정 금지 영역과 비직관적인 제약은 기록해야 합니다.

가장 가까운 범위에 둡니다

좋은 지침 파일은 모든 정보를 모아 둔 백과사전이 아닙니다.

• 이번 일은 프롬프트에 둡니다.
• 모든 프로젝트에서 유지할 판단 방식은 전역 파일에 둡니다.
• 저장소에서만 유효한 사실은 프로젝트 파일에 둡니다.
• 특정 영역의 규칙은 해당 경로에 가깝게 둡니다.
• 반복 절차는 Skill로 분리합니다.
• 반드시 지켜야 할 제한은 시스템으로 강제합니다.

결국 CLAUDE.md와 AGENTS.md의 품질은 줄 수가 아니라 정보의 수명과 적용 범위를 정확히 나누었는가에 달려 있습니다.

이어지는 두 글에서는 전역 원칙과 프로젝트 규칙을 각각 구체적으로 설명합니다.

• 전역 CLAUDE.md와 AGENTS.md에는 무엇을 써야 할까요?
• 프로젝트 CLAUDE.md와 AGENTS.md에는 무엇을 써야 할까요?

참고한 자료

• Anthropic, How Claude remembers your project
• OpenAI, Custom instructions with AGENTS.md
• OpenAI, Customization