.claude/ 폴더 완전 해부 — Claude Code를 제대로 길들이는 법

commands/ 폴더 — 커스텀 슬래시 명령어

• .claude/commands/에 마크다운 파일을 넣으면 그대로 슬래시 커맨드가 됨. review.md → /project:review
• ` 백틱에 ! 붙이면 셸 명령어 실행 결과를 프롬프트에 주입할 수 있음. 단순 저장 텍스트가 아니라 동적 프롬프트가 되는 거임
• $ARGUMENTS로 인자 전달도 가능 — /project:fix-issue 234 하면 이슈 234 내용을 자동으로 가져와서 프롬프트에 넣어줌
• 프로젝트 커맨드는 .claude/commands/에, 개인 커맨드는 ~/.claude/commands/에 두면 /user:command-name으로 접근 가능

skills/ 폴더 — 알아서 발동하는 워크플로우

• commands와 비슷하게 생겼지만 결정적 차이가 있음: 슬래시 커맨드 없이도 Claude가 대화 맥락 보고 알아서 발동시킴
• SKILL.md에 YAML frontmatter로 설명을 적어두면, 대화 내용이 해당 설명과 매칭될 때 자동 호출됨
• commands는 단일 파일이지만 skills는 폴더 단위 패키지 — 보조 문서 파일을 함께 번들링할 수 있음

agents/ 폴더 — 전문 서브에이전트

• .claude/agents/에 마크다운으로 서브에이전트 페르소나를 정의할 수 있음. 각 에이전트는 별도 시스템 프롬프트, 사용 가능 도구, 모델 설정을 가짐
• 예를 들어 code-reviewer.md를 만들면 코드 리뷰 요청 시 독립된 컨텍스트 윈도우에서 작업하고 결과만 돌려줌. 메인 세션이 토큰으로 더러워지지 않음
• tools 필드로 에이전트가 할 수 있는 걸 제한함 — 보안 감사용 에이전트는 Read/Grep/Glob만 허용하고 Write는 막는 식
• model 필드로 저렴한 모델 지정 가능. 읽기 전용 탐색은 Haiku로 충분하고, Sonnet/Opus는 진짜 필요한 작업에만 쓰면 됨

settings.json — 권한 관리

• .claude/settings.json에서 Claude가 뭘 할 수 있고 뭘 못 하는지 제어함
• allow 리스트: 확인 없이 바로 실행 가능한 명령어 (npm run *, git *, 파일 읽기/쓰기 등)
• deny 리스트: 무조건 차단 (rm -rf, curl, .env 접근 등)
• 둘 다 아닌 건 실행 전에 물어봄 — 이 중간 지대가 의도된 안전장치임
• settings.local.json은 개인용 권한 오버라이드. 자동 gitignore 처리됨

글로벌 ~/.claude/ 폴더

• ~/.claude/projects/에 프로젝트별 세션 기록과 자동 메모리가 저장됨. Claude가 작업하면서 발견한 명령어, 패턴, 아키텍처 인사이트를 알아서 기록함
• Claude가 "알려준 적 없는 걸 기억하는" 것처럼 보이면 여기 저장된 자동 메모리 때문임. /memory로 확인·수정 가능

• 결국 .claude/ 폴더는 "나는 누구고, 이 프로젝트는 뭐고, 어떤 규칙을 따라야 하는지"를 Claude에게 알려주는 프로토콜임. 이걸 명확하게 정의할수록 Claude를 교정하는 시간은 줄고 실제 작업 시간은 늘어남