CLAUDE.md 와 AGENTS.md 의 역할과 차이

이런 상황일 때

AI 코딩 도구를 쓰다 보니 CLAUDE.md, AGENTS.md 같은 파일 이야기가 자꾸 나옵니다. 이름이 여러 개라 어느 파일에 무엇을 적어야 하는지, 하나만 만들면 되는 건지 헷갈립니다.

한 줄 결론

도구마다 읽는 파일이 다릅니다. CLAUDE.md 는 Claude Code 의 프로젝트 기억이고, AGENTS.md 는 여러 도구가 함께 읽자는 공용 규칙 파일입니다. 공통 규칙은 공용 파일에, 특정 도구 전용 지시만 그 도구의 파일에 나누어 적으세요 — 그리고 내 도구가 실제로 그 파일을 읽는지는 그 도구의 문서로 확인하세요.

핵심 개념

규칙 파일은 자동으로 실리는 문서다

프로젝트 폴더에 있으면 세션마다 자동으로 읽혀 지시의 일부가 됩니다. README 와 다른 점이 이것입니다 — README 는 사람이 여는 문서이고, 규칙 파일은 도구가 스스로 싣는 문서입니다.

CLAUDE.md — Claude Code 의 기억

Claude Code 가 읽는 파일입니다. 홈 폴더와 프로젝트 폴더에 계층으로 둘 수 있어, 모든 프로젝트 공통 취향은 홈에, 프로젝트 규칙은 프로젝트에 적습니다.

AGENTS.md — 도구를 가리지 않는 공용 규약

특정 회사 파일이 아니라 여러 AI 코딩 도구가 같이 읽자고 정한 규약입니다. Codex CLI 를 비롯해 채택한 도구가 늘고 있고, 어떤 도구가 읽는지는 규약 사이트와 각 도구 문서에 있습니다.

겹치면 중복이 아니라 분업이다

빌드·테스트 명령, 코딩 규칙, 금지 목록처럼 어느 도구든 알아야 하는 것은 공용 파일에 한 번만. 특정 도구의 기능을 켜고 끄는 지시만 그 도구 파일에. 같은 내용을 두 파일에 복사하면 한쪽만 고쳐지는 날이 옵니다.

이런 분에게 해당됩니다

• AI 코딩 도구에 프로젝트 규칙을 주고 싶은 분
• 여러 도구를 함께 쓰는 분
• 규칙 파일을 만들었는데 잘 안 지켜지는 것 같은 분

확인해야 할 항목

• 내가 쓰는 도구가 어떤 규칙 파일을 읽는지 문서에서 확인했는가
• 공통 규칙과 도구 전용 지시가 나뉘어 있는가
• 같은 내용이 두 파일에 복사돼 있지 않은가
• 규칙이 명령형 한 줄짜리로 짧게 적혀 있는가
• 낡은 규칙(지금은 틀린 것)이 남아 있지 않은가

잘못 이해하기 쉬운 부분

안전한 행동 순서

1. 쓰는 도구를 나열하고, 각 도구 문서에서 읽는 파일을 확인합니다.
2. 빌드·테스트 명령, 금지 목록 같은 공통 규칙을 공용 파일에 적습니다.
3. 특정 도구 전용 지시만 그 도구의 파일로 분리합니다.
4. 규칙마다 한 줄 명령형으로 줄입니다 — 배경 설명은 필요한 것만.
5. 한 세션 일을 시켜 보고, 안 지켜진 규칙은 더 짧고 명확하게 고칩니다.
6. 규칙이 낡으면 지웁니다. 틀린 규칙은 없는 것보다 나쁩니다.

확인 체크리스트

• 도구별 지원 파일을 문서로 확인했다
• 공통 규칙은 한 곳에만 있다
• 규칙이 명령형 한 줄로 적혀 있다
• 시험 세션으로 지켜지는지 확인했다
• 비밀 정보를 적지 않았다

관련 도구와 버전 페이지

이 글과 이어지는 사이트 기능은 아직 없습니다. 아래 공식 출처에서 직접 확인하세요.

자주 묻는 것

둘 다 만들어야 하나요?

쓰는 도구가 하나면 그 도구의 파일 하나로 충분합니다. 도구가 둘 이상이고 겹치는 규칙이 생겼을 때 공용 파일을 추가하는 것이 자연스러운 순서입니다.

규칙을 적었는데 안 지키는 것 같습니다.

너무 길거나, 서로 모순이거나, 낡았을 가능성이 큽니다. 가장 중요한 다섯 줄만 남기고 지워 보세요. 그리고 파일 위치가 도구가 읽는 위치인지 다시 확인하세요.

API 키 같은 것을 적어 둬도 되나요?

안 됩니다. 규칙 파일은 저장소에 커밋되는 평문입니다. 비밀 정보는 환경 변수나 비밀 관리 도구에 두고, 규칙 파일에는 '비밀은 어디서 읽는다' 만 적으세요.