.claude/ 폴더 완전 해부: CLAUDE.md, 커스텀 명령어, 에이전트 설정까지

Who Should Read

Claude Code를 프로젝트에 도입했거나 도입을 검토 중인 개발자, 특히 팀 전체가 일관된 AI 코딩 규칙을 공유하고 싶은 테크 리드나 시니어 개발자.

Core Mechanics

• .claude/ 폴더는 Claude Code의 '제어판' 역할을 하며, 프로젝트 루트에 위치한 팀 공유용 폴더와 홈 디렉토리(~/.claude/)의 개인 설정 폴더, 두 곳에 존재한다. 팀 공유 폴더는 git에 커밋해서 모든 팀원이 동일한 규칙을 적용받도록 한다.
• CLAUDE.md는 Claude Code 세션이 시작될 때 가장 먼저 읽히는 파일로, 시스템 프롬프트에 직접 삽입된다. '항상 테스트를 먼저 작성해라', 'console.log 대신 커스텀 logger 모듈을 써라' 같은 규칙을 쓰면 Claude가 세션 내내 해당 규칙을 따른다.
• CLAUDE.md에 넣어야 할 내용은 빌드/테스트/린트 명령어, 아키텍처 핵심 결정사항, 비직관적인 주의사항, import 컨벤션, 폴더 구조 등이다. 반면 린터 설정으로 대체 가능한 내용, 긴 이론 설명, 이미 링크로 참조 가능한 문서는 넣지 않는다.
• CLAUDE.md는 200줄 이하로 유지하는 것이 중요하다. 파일이 길어질수록 Claude의 컨텍스트를 많이 차지해서 실제로 규칙 준수율이 떨어지는 문제가 생긴다. 원문에서 제시한 예시는 약 20줄 분량으로, Express API 프로젝트에서 필요한 핵심 정보만 담았다.
• CLAUDE.local.md 파일을 프로젝트 루트에 만들면 개인 설정을 팀 설정과 분리할 수 있다. 이 파일은 자동으로 .gitignore 처리되므로 개인 취향 설정이 팀 레포에 반영되지 않는다.
• rules/ 폴더를 사용하면 CLAUDE.md를 기능별 파일로 분리해서 관리할 수 있다. 팀이 커지면 단일 CLAUDE.md가 300줄을 넘어 관리가 어려워지는데, 이를 모듈화해서 해결하는 방식이다.
• ~/.claude/plans/ 디렉토리에는 Claude가 plan 모드로 실행될 때 생성한 계획 파일들이 마크다운 형식으로 저장된다. 이를 열어보거나 백업하는 용도로 활용할 수 있다는 점이 원문에서 누락된 유용한 정보다.
• Claude가 CLAUDE.md나 .claude/INSTRUCTIONS.md를 직접 수정했을 경우, Claude 자신은 해당 파일의 이전 버전을 컨텍스트에 갖고 있기 때문에 변경 내용을 자동으로 반영하지 않는다. 파일을 업데이트한 후에는 명시적으로 '이 파일을 다시 읽어라'고 지시해야 최신 내용이 적용된다.

Evidence

• 커뮤니티 전반에 걸쳐 '설정이 복잡할수록 결과가 나빠진다'는 의견이 다수였다. 'AI는 유능하지만 긴장한 어른 같아서, 많이 줄수록 더 멍청해진다'는 비유가 공감을 많이 받았고, 실제로 빈 .claude 폴더와 최소한의 설정으로 시작했을 때 더 좋은 결과를 얻었다는 경험담들이 이어졌다.
• 'CLAUDE.md에 쓴 내용을 Claude가 반드시 따른다'는 원문의 주장에 대해 회의적인 반론이 있었다. 실제로는 CLAUDE.md는 '계약'이 아니라 '제안'에 가까우며, 컨텍스트 창이 꽉 차거나 compaction(컨텍스트 압축)이 일어나면 CLAUDE.md 내용이 희석된다는 지적이 나왔다.
• MCP(Model Context Protocol, 모델에 외부 도구를 연결하는 프로토콜) 서버를 직접 만들어 에이전트에 연결하는 방식으로 높은 성과를 내고 있다는 경험이 공유됐다. AGENT.md 파일에는 '어떤 도구가 있는지 설명'만 쓰고, 복잡한 지시 없이 에이전트가 스스로 워크플로우를 구성하도록 하는 것이 효과적이라는 의견이었다.
• .claude/ 폴더를 자가 복제·자가 업데이트하는 방식으로 운영하는 고급 사용 사례가 공유됐다. 메인 에이전트가 .claude/ 파일들을 직접 작성하고, 작업 수행 후 결과를 평가해서 .claude/ 설정을 스스로 개선하는 방식으로, '코드를 짜는 게 아니라 .claude/를 짜는 것'이라는 표현이 흥미로운 패러다임을 보여줬다.
• Claude Code CLI 자체의 안정성 문제를 지적하는 목소리도 있었다. 플러그인 LSP 설정이 GitHub 이슈를 뒤져야 할 만큼 문서화가 부족하고, hooks가 오류가 없는데도 에러를 렌더링하며, permission 설정이 거의 문서화되어 있지 않다는 불만이 있었다. 2025년 초부터 열려 있는 이슈들이 아직 해결되지 않았다는 지적도 나왔다.

How to Apply

• 새 프로젝트에 Claude Code를 도입하는 경우, CLAUDE.md를 20~30줄 수준으로 최소화해서 시작하라. 빌드/테스트 명령어, 핵심 아키텍처 결정(예: ORM, 폴더 구조), 진짜 비직관적인 주의사항만 담고, 나머지는 Claude가 코드베이스를 직접 읽어서 파악하도록 맡기면 오히려 더 정확하게 동작한다.
• 팀 프로젝트라면 .claude/ 폴더를 git에 커밋해서 팀 규칙을 공유하고, 각 팀원은 CLAUDE.local.md에 개인 설정을 별도로 관리하라. 이렇게 하면 개인 취향 차이로 인한 설정 충돌 없이 팀 공통 규칙을 유지할 수 있다.
• Claude가 CLAUDE.md를 직접 편집하도록 시켰다면, 편집 후 반드시 '이 파일을 다시 읽어라(re-read this file)'고 명시적으로 지시해야 한다. Claude는 파일을 수정했더라도 컨텍스트에 이전 버전을 갖고 있어서 변경 사항을 자동으로 인식하지 못한다.
• ~/.claude/plans/ 디렉토리를 주기적으로 확인하면 Claude가 plan 모드에서 생성한 계획 파일들을 마크다운 형식으로 열람하거나 백업할 수 있다. 복잡한 작업의 계획을 재사용하거나 팀과 공유할 때 유용하다.

Code Example

# Project: Acme API

## Commands
npm run dev    # Start dev server
npm run test   # Run tests (Jest)
npm run lint   # ESLint + Prettier check
npm run build  # Production build

## Architecture
- Express REST API, Node 20
- PostgreSQL via Prisma ORM
- All handlers live in src/handlers/
- Shared types in src/types/

## Conventions
- Use zod for request validation in every handler
- Return shape is always { data, error }
- Never expose stack traces to the client
- Use the logger module, not console.log

## Watch out for
- Tests use a real local DB, not mocks. Run `npm run db:test:reset` first
- Strict TypeScript: no unused imports, ever

Terminology

관련 논문

• OpenKnowledge – Obsidian/Notion의 오픈소스 AI-first 대안

  Git 기반 동기화와 Claude/Codex/Cursor 연동을 내장한 로컬 우선 마크다운 에디터로, AI 에이전트의 두 번째 뇌(LLM Wiki)로 활용할 수 있는 오픈소스 도구다.

• Unfireable Safety Kernel: AI 에이전트를 위한 Execution-Time AI Alignment

  AI 에이전트가 자신의 안전장치를 우회할 수 없도록, 에이전트 프로세스 바깥에 수학적으로 증명된 강제 통제 게이트를 배치하는 아키텍처

• RubyLLM: 주요 AI 프로바이더를 모두 지원하는 Ruby 프레임워크

  OpenAI, Claude, Gemini 등 주요 AI 프로바이더를 단일 인터페이스로 통합한 Ruby 프레임워크로, Rails 통합과 에이전트 기능까지 지원해 Ruby 개발자가 AI 기능을 빠르게 붙일 수 있다.

• Qwen-AgentWorld: 범용 에이전트를 위한 Language World Model

  Alibaba Qwen 팀이 AI 에이전트가 행동 결과를 미리 시뮬레이션할 수 있는 'Language World Model'을 공개했다. 에이전트 훈련과 실행 경로 검증에 새로운 패러다임을 제시하는 연구다.

• SHERLOC: Code Repair Agent를 위한 구조화된 Diagnostic Localization 프레임워크

  버그 위치만 알려주는 게 아니라 '왜, 어떻게 고쳐야 하는지'까지 진단 리포트를 생성해서 코드 수정 에이전트의 성능을 높이는 training-free 프레임워크

• peerd – 브라우저에서 완전히 실행되는 AI Agent Harness

  백엔드 서버 없이 Chrome/Firefox 확장 프로그램으로만 동작하는 AI 에이전트 실행 환경으로, 브라우저 탭을 직접 조작하고 WASM Linux VM까지 구동할 수 있어 프라이버시와 보안을 동시에 챙길 수 있다.

Related Resources

• Anatomy of the .claude/ folder (원문)
• Claude Fast - CLAUDE.md Mastery 가이드
• claude-code-types (npm 패키지, ~/.claude/projects 파싱용)