CLAUDE.md는 Claude가 프로젝트를 이해하는 방식을 결정하는 하나의 파일입니다. 잘 작성된 파일은 수정을 줄이고, 코드 품질을 높이며, 에이전트가 작업 대상을 정확히 파악하게 합니다.
이 가이드는 기술 스택 선언부터 에이전트별 힌트까지 CLAUDE.md 파일의 모든 섹션을 설명합니다. 단계별로 따라 하며 직접 작성해 보세요.
CLAUDE.md는 프로젝트 루트에 배치하는 마크다운 파일입니다. Claude Code가 세션을 시작하면 이 파일을 가장 먼저 읽습니다. 기술 스택, 파일 구조, 팀의 컨벤션, 모든 에이전트가 따라야 할 지시사항 등 파일 안의 모든 내용이 Claude의 컨텍스트가 됩니다.
브리핑 문서라고 생각하면 됩니다. 이것이 없으면 Claude는 프로젝트 구성을 추측해야 합니다. 잘 작성된 CLAUDE.md가 있으면 Claude는 이미 파일 위치, 따라야 할 패턴, 피해야 할 것을 알고 있습니다. 출력 품질의 차이는 상당합니다.
“CLAUDE.md에 10분을 투자하면 프로젝트 패턴에 맞지 않는 AI 생성 코드를 수정하는 데 걸리는 수 시간을 절약할 수 있습니다.”
수백 개의 Claude Code 프로젝트에서 관찰된 결과
CLAUDE.md의 구조와 구체성이 Claude의 코드베이스 성능에 직접적으로 영향을 미칩니다.
잘 구성된 CLAUDE.md는 이 여섯 가지 영역을 다룹니다. 각각이 Claude에게 즉시 활용할 수 있는 구체적인 정보를 제공합니다.
프레임워크, 라이브러리, 버전을 명시적으로 나열합니다. 패키지 매니저, Node 버전, 런타임 요구 사항도 포함합니다. Claude는 이를 사용하여 추측 없이 호환되는 코드를 생성합니다.
주요 디렉토리와 각 디렉토리의 내용을 설명합니다. 컴포넌트, 스토어, 서비스, API 라우트, 타입. 폴더별로 한 줄 설명이 있는 짧은 트리 다이어그램이 효과적입니다.
네이밍 패턴(파일은 camelCase, 컴포넌트는 PascalCase), 에러 처리 방식, import 순서, 프로젝트 고유 규칙을 문서화합니다. Claude의 출력이 기존 코드와 일관성을 유지하도록 합니다.
dev, build, test, lint 명령어를 포함합니다. Claude가 동작을 확인하거나 스크립트를 제안할 때 프로젝트에서 기대하는 정확한 명령어를 사용합니다.
여러 에이전트(QA, 프론트엔드, 백엔드, DevOps)를 사용하는 경우 각 역할이 무엇에 집중해야 하는지 설명하는 섹션을 추가합니다. AgentsRoom의 멀티 에이전트 설정에서 특히 유용합니다.
Claude에게 하지 말아야 할 것을 알려줍니다. 설정 파일을 수정하지 마세요, 인증 시스템을 변경하지 마세요, 데이터베이스 레이어를 리팩토링하지 마세요. 명시적인 경계가 에이전트의 의도치 않은 변경을 방지합니다.
한 번에 모든 것을 작성할 필요는 없습니다. 기본부터 시작하고, Claude가 알아야 할 내용을 발견할 때마다 확장하세요.
package.json을 열고 프로젝트에서 사용하는 모든 프레임워크, 라이브러리, 도구를 나열합니다. 버전을 기록하고 런타임 요구 사항(Node 버전, Python 버전, 데이터베이스)을 확인합니다. 이것이 기술 스택 섹션이 됩니다.
package.json + 런타임 버전 + 데이터베이스
src 디렉토리의 트리를 간단히 출력합니다. 최상위 폴더를 식별하고 각각에 한 줄 설명을 작성합니다. 컴포넌트, 스토어, 서비스, 타입, API 라우트의 위치에 집중합니다.
용도 주석이 달린 src/ 트리
기존 코드를 살펴보고 패턴을 기록합니다. 파일 이름 짓는 방법, 에러 처리 방법, import 구성 방법, 기본 내보내기와 네임드 내보내기 중 어떤 것을 사용하는지. 짧은 규칙으로 작성합니다.
네이밍, import, 에러 처리, 내보내기
전문 에이전트와 작업하는 경우 각 역할의 집중 영역을 추가합니다. 프론트엔드 에이전트에게는 컴포넌트 라이브러리를, DevOps 에이전트에게는 배포 파이프라인을, QA 에이전트에게는 테스트 프레임워크를 알려줍니다.
역할별 집중 영역 + 금지 영역
AgentsRoom은 CLAUDE.md를 부가 기능이 아닌 핵심 개념으로 구축되었습니다.
AgentsRoom 내에서 구문 강조와 실시간 저장 기능으로 CLAUDE.md를 직접 편집할 수 있습니다. 텍스트 편집기나 IDE로 전환할 필요가 없습니다.
각 에이전트가 CLAUDE.md를 어떻게 해석하는지 실시간으로 확인할 수 있습니다. 터미널 출력을 보며 에이전트가 컨벤션을 따르고 금지 영역을 준수하는지 확인하세요.
AgentsRoom의 각 프로젝트에는 고유한 CLAUDE.md가 있습니다. 프로젝트를 전환하면 각 에이전트가 해당 코드베이스의 올바른 컨텍스트 파일을 자동으로 로드합니다.
AgentsRoom의 14가지 에이전트 역할은 CLAUDE.md 섹션과 직접 연동됩니다. 역할별로 집중 영역과 금지 영역을 정의하면 각 에이전트가 자신에게 해당하는 지시만 가져갑니다.
CLAUDE.md is prepended to every Claude turn. A bloated CLAUDE.md silently inflates Claude Code token usage on every message. AgentsRoom puts a per-session token meter on each agent so you can see exactly how much your CLAUDE.md is costing you, with a live cache hit rate to confirm it stays cached.
See the Claude Code token usage trackerAgentsRoom을 다운로드하고 내장 CLAUDE.md 편집기로 에이전트에게 필요한 컨텍스트를 제공하세요. 좋은 지시가 좋은 코드로 이어집니다.
컴패니언 앱: 이동 중에도 에이전트를 모니터링
Claude, Codex, Gemini CLI 또는 다른 AI 공급자를 사용하세요.
버그와 요청을 공개 백로그로 바로 보내세요.