Claude Code 구성을 위한 .claude/ 폴더 구조 이해하기

프로젝트 및 전역 구성 폴더
.claude 디렉터리는 두 가지가 있습니다: 하나는 git에 커밋되는 팀 구성을 위한 프로젝트 루트에 있고, 다른 하나는 세션 기록과 같은 개인 선호도 및 기기 로컬 상태를 위한 홈 디렉터리(~/.claude/)에 있습니다.
CLAUDE.md: 지침 매뉴얼
CLAUDE.md는 각 세션 시작 시 Claude의 시스템 프롬프트에 로드되어 대화 내내 따릅니다. 프로젝트 루트, 전역 선호도를 위한 ~/.claude/, 또는 폴더별 규칙을 위한 하위 디렉터리에 CLAUDE.md를 둘 수 있습니다.
효과적인 CLAUDE.md 내용에는 다음이 포함됩니다:
- 빌드, 테스트, 린트 명령어(npm run test, make build 등)
- 주요 아키텍처 결정 사항
- 명확하지 않은 함정
- 가져오기 규칙, 명명 패턴, 오류 처리 스타일
- 주요 모듈의 파일 및 폴더 구조
CLAUDE.md는 200줄 이하로 유지하세요. 그보다 긴 파일은 너무 많은 컨텍스트를 소비하기 시작하여 Claude의 지침 준수도가 떨어집니다.
CLAUDE.md 구조 예시
# 프로젝트: Acme API명령어
npm run dev # 개발 서버 시작 npm run test # 테스트 실행 (Jest) npm run lint # ESLint + Prettier 검사 npm run build # 프로덕션 빌드
아키텍처
- Express REST API, Node 20
- Prisma ORM을 통한 PostgreSQL
- 모든 핸들러는 src/handlers/에 위치
- 공유 타입은 src/types/에
규칙
- 모든 핸들러에서 요청 검증에 zod 사용
- 반환 형태는 항상 { data, error }
- 클라이언트에 스택 추적을 절대 노출하지 않음
- console.log 대신 로거 모듈 사용
주의사항
- 테스트는 모의 객체가 아닌 실제 로컬 DB를 사용합니다. 먼저
npm run db:test:reset실행 - 엄격한 TypeScript: 사용하지 않는 가져오기는 절대 없음
CLAUDE.local.md를 통한 개인 재정의
전체 팀에 적용되지 않는 개인 선호도를 위해 프로젝트 루트에 CLAUDE.local.md를 생성하세요. Claude는 기본 CLAUDE.md와 함께 이를 읽으며, 개인적인 조정이 저장소에 절대 들어가지 않도록 자동으로 gitignore됩니다.
rules/ 폴더를 통한 모듈식 지침
더 큰 팀의 경우, rules/ 폴더는 단일 큰 CLAUDE.md 파일보다 확장성이 더 좋은 모듈식 지침을 제공합니다.
📖 전체 소스 읽기: HN AI Agents
👀 See Also

OpenClaw 3.22 업그레이드 체크리스트: 실패에서 배운 개발자의 실용적 단계
개발자가 OpenClaw 3.22로의 구체적인 업그레이드 단계를 공유합니다. 여기에는 더 이상 사용되지 않는 환경 변수 확인, 백업 생성, 마이그레이션 명령 실행, 플러그인 호환성 검증이 포함됩니다.

VPS vs 전용 서버: OpenClaw를 어디서 실행할까?
없음

에이전트 지향 API 디자인 패턴: Moltbook의 통찰
Moltbook의 API 설계는 직접적인 지시, 상태 전환, 인지적 도전, 교육적 속도 제한을 통합하여 능동적인 AI 에이전트 상호작용을 지원합니다.

여러 사용자를 위한 OpenClaw 인스턴스 효율적 관리
r/openclaw 커뮤니티 사용자들이 공유한 여러 OpenClaw 인스턴스 관리 전략을 살펴보세요. 커뮤니티 구성원들이 최적의 성능을 위해 자동화와 로드 밸런싱을 활용하는 방법을 배워보세요.