CLAUDE.md: 어디에 두고, 무엇을 쓰고, AGENTS.md와 어떻게 쓸까

CLAUDE.md란

Claude Code는 매번 지난 세션의 기억 없이 시작해요. CLAUDE.md는 새로 온 팀원에게 필요한 배경 지식을 전해 주는 방법이에요. 시작할 때 읽혀서 시스템 프롬프트 뒤에 메시지로 Claude에게 전달돼요. 그래서 강제되는 설정이 아니라 컨텍스트예요. Claude는 대체로 따르지만, 반드시 해야 하거나 절대 하면 안 되는 일은 hooks나 권한 규칙에 넣어야 해요.

• 평범한 markdown이고 필수 필드는 없어요. 제목과 짧은 글머리 기호가 가장 잘 맞아요.
• 파일은 덮어쓰지 않고 합쳐져요. 해당하는 CLAUDE.md가 모두 로드되므로, 서로 모순되는 줄이 있으면 Claude가 하나를 골라요.
• 로드된 내용은 /context all의 Memory files에서 확인할 수 있어요.

CLAUDE.md 파일의 위치와 로드 순서

Claude Code는 가장 넓은 범위부터 가장 구체적인 범위 순으로 로드하므로, 실행한 위치에 가장 가까운 파일이 마지막에 읽혀요. 작업 디렉터리에서 위로 올라가며 모든 상위 디렉터리의 CLAUDE.md도 로드해요.

제대로 동작하는 CLAUDE.md 작성법

1. /init으로 시작하기

   프로젝트에서 /init을 실행하세요. Claude Code가 코드베이스를 읽고 기본 CLAUDE.md를 써 줘요. 이미 있으면 덮어쓰지 않고 개선안을 제안해요. .cursorrules와 Copilot 지침도 가져와요.

2. Claude가 스스로 찾을 수 없는 것만 남기기

   정확한 빌드, 테스트, lint 명령어(테스트 하나만 실행하는 방법 포함), 코드가 오해를 부르는 부분, 어디에도 적혀 있지 않은 결정, 두 번 이상 바로잡았던 것을 남겨요. 파일 트리와 저장소에서 읽을 수 있는 아키텍처는 지우세요. Anthropic은 200줄 이내를 권장해요.

   # Commands
   - Install: pnpm install
   - One test file: pnpm vitest run path/to/file.test.ts
   - Typecheck: pnpm tsc --noEmit
   
   # Conventions
   - 에러는 src/lib/errors.ts의 헬퍼로 던지고, 문자열을 그대로 던지지 않는다.
   - src/legacy/는 아직 운영 중이지만 그 패턴은 따라 하지 않는다.
   
   # Gotchas
   - 통합 테스트에는 DATABASE_URL이 필요하다(.env.example 참고).

3. 구체적으로, 하지만 소리치지 않기

   "코드를 제대로 포맷하세요"가 아니라 "들여쓰기는 스페이스 2칸"처럼 쓰세요. 최신 문서에서는 IMPORTANT나 전부 대문자로 쓰는 것이 낡은 조언이라고 해요. Claude가 규칙을 과하게 적용하게 되거든요. 어떤 줄이 계속 지켜지지 않으면 파일을 줄이거나 그 규칙을 hook으로 바꾸세요.

4. 임포트와 규칙으로 나누기

   @path/to/file은 다른 파일을 임포트해요(임포트하는 파일 기준 상대 경로이고 최대 4단계). 백틱 안의 @는 그대로 문자로 남아요. 코드베이스 일부에만 해당하는 규칙은 paths glob과 함께 .claude/rules/에 두면, Claude가 일치하는 파일을 다룰 때만 로드돼요.

   ---
   paths: ["src/api/**/*.ts"]
   ---
   - 모든 핸들러는 src/api/schemas/의 스키마로 입력을 검증한다.

5. 절차는 스킬로 옮기기

   릴리스를 내는 방법처럼 여러 단계로 된 워크플로는 스킬(.claude/skills/<name>/SKILL.md)에 두세요. 스킬은 관련이 있을 때만 로드돼요. CLAUDE.md는 모든 작업에서 읽히므로 한 줄마다 주의력이 들어가요.

6. 최신 상태로 유지하기

   Claude가 같은 실수를 반복하거나 리뷰에서 걸린 것이 있으면 한 줄 추가하세요. 파일은 /memory로 편집하거나 Claude에게 업데이트를 부탁하면 돼요. 파일이 너무 길어지면 /doctor가 줄일 부분을 제안해요.

출처: Claude Code 문서, How Claude remembers your project

CLAUDE.md와 AGENTS.md 비교

AGENTS.md는 코딩 에이전트를 위한 개방형 지침 형식이고, Codex, Cursor, Gemini CLI, GitHub Copilot의 코딩 에이전트, opencode 등 많은 도구가 써요. Claude Code도 이제 읽을 수 있지만, 기본값으로는 프로젝트에 CLAUDE.md가 없을 때만 읽어요.

Claude Code와 Codex에서 파일 하나 쓰기

팀이 두 에이전트를 모두 쓴다면, 공통 지침은 AGENTS.md에 두고 CLAUDE.md가 그것을 임포트하게 한 다음, 그 아래에 Claude 전용 메모를 쓰세요. 두 번 로드되지는 않아요. 심볼릭 링크(ln -s AGENTS.md CLAUDE.md)도 되지만 Windows를 쓰는 팀원에게는 안 되고, "AGENTS.md를 읽어라"라고 글로만 적은 CLAUDE.md는 믿을 수 없어요.

• 이 웹사이트의 저장소가 바로 그렇게 해요. CLAUDE.md는 @AGENTS.md 한 줄뿐이에요.
• Codex는 저장소 루트부터 작업 디렉터리까지의 AGENTS.md 파일을 읽고, 합친 크기를 기본 32 KiB로 제한해요.

제한과 주의할 점

• 시작할 때 로드되는 CLAUDE.md는 4 MiB까지 전부 읽히고, 더 큰 파일은 건너뛰어요.
• 하위 디렉터리의 CLAUDE.md나 경로별 규칙처럼 필요할 때 로드되는 파일은 파일당 한도를 넘으면 잘려요(200K 컨텍스트 윈도우에서는 40,000자).
• 임포트는 파일을 정리해 줄 뿐 컨텍스트를 아껴 주지는 않아요. 임포트된 텍스트도 로드돼요.
• 프로젝트 밖의 임포트는 한 번 승인을 물어봐요. HTML 주석 <!-- -->은 제거되어 비용이 들지 않아요.
• 프로젝트 루트의 CLAUDE.md는 /compact 뒤에 다시 읽혀요.
• "이거 기억해"는 CLAUDE.md가 아니라 자동 메모리(~/.claude/projects/<project>/memory/)에 들어가요.

CLAUDE.md는 일하는 방법을, Crewmark는 무슨 일을 언제 할지를 알려 줘요.

좋은 CLAUDE.md가 있으면 Claude Code 세션이 모두 충분한 정보를 가지고 시작하지만, 세션은 여전히 다음 메시지를 기다려요. Crewmark는 Claude Code, Codex, DeepSeek Harness, OpenCode 세션을 직무, 목표, 근무 시간을 가진 AI 직원으로 바꾸고, 하트비트로 깨워서 보드의 다음 이슈를 가져가게 해요.

1. 세션을 직원으로 만들기

   소프트웨어 엔지니어나 SEO 전문가 같은 직무를 고르고, 목표를 숫자로 적은 다음, CLAUDE.md가 이미 있는 프로젝트에서 설정 명령어를 실행하세요.

2. 하트비트로 일을 시작하게 하기

   근무 시간 동안 직원은 15분, 30분, 60분마다 같은 대화에서 깨어나요. Claude Code를 능동적으로 만드는 방법을 참고하세요. 여러 직원이 한 저장소를 함께 쓸 수도 있어요. 여러 Claude Code 에이전트를 보세요.

3. 이슈를 배정하고 메시지에 답하기

   보드에 일을 올리면 직원이 가져가서 진행하며 댓글을 달고, 결정이 필요하면 메시지를 보내요. AI 직원이란도 읽어 보세요.

CLAUDE.md 자주 묻는 질문