Claude Code 커스터마이징 완벽 가이드

Rules는 `.claude/rules/` 디렉토리에 위치하며, 특정 파일 경로에 따라 지침을 로드하는 경로 기반 규칙(Path-Scoped Rules)을 지원합니다. 이는 토큰 낭비(Token Waste)를 줄이고 관련 없는 컨텍스트 로딩을 방지하는 데 효과적입니다. 예를 들어, `src/api/` 경로에만 적용되는 규칙은 API 관련 작업 시에만 로드되어 효율성을 높입니다. 반면, Unscoped Rules는 CLAUDE.md와 같이 항상 로드되어 세션 시작 시 컨텍스트에 포함됩니다. 교차 관심사(Cross-cutting Concern)**나 여러 코드베이스 영역에 걸쳐 적용되는 지침은 경로 기반 규칙으로 관리하는 것이 좋습니다.

Skills는 `.claude/skills/`에 위치하며, 코드 리뷰(/code-review)와 같이 절차적 워크플로우(Procedural Workflow)를 자동화하는 데 사용됩니다. 이름과 설명만 세션 시작 시 로드되고, 전체 본문은 스킬이 호출될 때 로드됩니다. Subagents는 `.claude/agents/`에 정의되며, 독립적인 조수(Isolated Assistant) 역할을 수행합니다. 이름, 설명, 도구 접근 권한만 세션 시작 시 로드되고, 본문은 별도의 컨텍스트 창에서 실행되어 메인 대화의 복잡성을 줄입니다. 딥 서치(Deep Search)나 로그 분석(Log Analysis)과 같이 메인 대화에서 분리해야 하는 작업에는 Subagents를, 사용자가 각 단계를 보고 제어해야 하는 절차에는 Skills를 사용하는 것이 권장됩니다.

Hooks는 Claude Code 세션의 특정 이벤트(파일 수정, 도구 호출 등) 발생 시 사용자 정의 명령, HTTP 엔드포인트, LLM 프롬프트 등을 실행하여 Claude의 동작을 결정론적으로 제어(Deterministic Control)합니다. `settings.json` 또는 스킬/에이전트 프론트매터에 등록되며, 낮은 컨텍스트 비용으로 작동합니다. 예를 들어, 파일 수정 후 린터(Linter)를 실행하거나, 작업 완료 시 Slack에 알림을 보내는 등의 자동화에 활용될 수 있습니다. 특히, `PreToolUse` 훅은 도구 호출을 검사하고 특정 조건에서 이를 차단하는 데 사용될 수 있어, 안전 가드레일(Safety Guardrail) 역할을 수행합니다.

Output Styles는 `.claude/output-styles/`에 위치하며 시스템 프롬프트에 지침을 주입하여 Claude의 응답 스타일을 제어합니다. 이 방식은 가장 높은 지침 준수율(Highest Instruction-Following Weight)을 가지지만, 기본 설정을 크게 변경할 수 있어 신중한 사용이 필요합니다. 반면, `append-system-prompt` 플래그는 기존 시스템 프롬프트에 지침을 추가(Additive)하는 방식으로, Claude의 역할을 변경하지 않고 특정 지침만 더합니다. 이 방식은 일회성 호출에 적용되며, 컨텍스트 비용(Context Cost)이 상대적으로 높을 수 있습니다. 특정 코딩 표준이나 도메인 지식을 일시적으로 추가할 때는 `append-system-prompt`가 유용하며, Output Styles는 보다 근본적인 행동 변화를 유도할 때 사용됩니다.

CLAUDE.md 파일에 복잡한 절차나 절대 금지 사항을 명시하는 것은 권장되지 않습니다. 반복적인 작업(Repetitive Tasks)은 Hooks를 사용하여 자동화하고, 절대 금지해야 하는 동작(Strictly Forbidden Actions)은 Hooks나 관리 설정을 통해 강제하는 것이 더 안정적입니다. 또한, 30줄 이상의 긴 절차는 Skills로 분리하고, 특정 API에만 적용되는 규칙은 `paths` 필드를 사용하여 경로별로 스코핑하는 것이 토큰 효율성을 높입니다. 개인적인 선호 사항은 사용자 레벨 설정 파일에, 팀 전체의 프로젝트별 규칙은 프로젝트 레벨 CLAUDE.md 파일에 저장하는 것이 관리 효율성을 높입니다.