클로드 코드, CLAUDE.md 파일로 사용자 맞춤화 강화

클로드 코드 사용자 맞춤화: CLAUDE.md 파일, 스킬, 훅, 규칙, 서브에이전트 등

클로드(Claude)는 사용자의 작업 방식에 맞춰 설계되었습니다. 클로드 코드(Claude Code)에서는 이를 맞춤화할 수 있는 일곱 가지 방법이 있습니다: CLAUDE.md 파일, 규칙, 스킬, 서브에이전트, 훅, 출력 스타일, 시스템 프롬프트 추가. 각 방법은 다음을 제어합니다:

지시가 언제 컨텍스트에 로드되는지
긴 세션 동안 지속되는지 여부(압축 행동)
얼마나 많은 권위를 가지는지

아래 표는 각 방법의 주요 차이점을 간략히 요약하며, 본문에서는 각 클로드 지시가 어디에 속해야 하는지 결정하는 추가 세부 정보와 의사 결정 프레임워크를 제공합니다.

방법별 요약

CLAUDE.md (루트): 세션 시작 시 로드되며 전체 세션 동안 컨텍스트에 남아 있습니다. 메모이즈되어 세션 동안 한 번 읽고 캐시되며, 압축 후 캐시가 지워지고 다시 읽습니다. 높은 컨텍스트 비용이 들며, 명령어 빌드, 디렉토리 레이아웃, 모노레포 구조, 코딩 규칙, 팀 규범에 적합합니다.
CLAUDE.md (서브디렉토리): 해당 서브디렉토리에서 파일을 읽을 때 온디맨드로 로드됩니다. 관련 서브디렉토리가 다시 터치될 때까지 사라집니다. 낮은 컨텍스트 비용이 들며, 서브디렉토리별 규칙에 적합합니다.
규칙: 세션 시작 시(사용자 수준 규칙) 또는 매칭 파일이 터치될 때만 로드됩니다. 압축 시 재주입됩니다. 중간 컨텍스트 비용이 들며, 특정 제약이나 규칙에 적합합니다.
스킬: 세션 시작 시 이름과 설명이 로드되며, 스킬이 호출될 때 전체 본문이 로드됩니다. 호출된 스킬은 공유 예산 내에서 재주입되며, 가장 오래된 것이 먼저 제거됩니다. 낮은 컨텍스트 비용이 들며, 절차적 워크플로우에 적합합니다.
서브에이전트: 세션 시작 시 이름, 설명, 도구 목록이 로드되며, 에이전트 도구를 통해 호출될 때만 본문이 로드됩니다. 최종 메시지만 메인 세션으로 반환됩니다. 낮은 컨텍스트 비용이 들며, 병렬 작업이나 격리된 작업에 적합합니다.
훅: 라이프사이클 이벤트에 따라 작동하며, 압축을 완전히 우회합니다. 낮은 컨텍스트 비용이 들며, 결정론적 자동화에 적합합니다.
출력 스타일: 세션 시작 시 시스템 프롬프트에 주입되며, 절대 압축되지 않습니다. 높은 컨텍스트 비용이 들며, 중요한 역할 변경에 적합합니다.
시스템 프롬프트 추가: 세션 시작 시 CLI 플래그로 전달되며, 절대 압축되지 않습니다. 중간 컨텍스트 비용이 들며, 톤, 응답 길이, 포맷팅 선호도에 적합합니다.

CLAUDE.md 파일

CLAUDE.md는 프로젝트의 루트에 있는 마크다운 파일로, 세션 시작 시 컨텍스트에 로드되어 전체 세션 동안 유지됩니다. 빌드 명령어, 디렉토리 레이아웃, 모노레포 구조, 코딩 규칙, 팀 규범 등이 여기에 자연스럽게 포함됩니다. 두 가지 유형이 있으며, 로드 방식이 다릅니다:

항상 로드됨: 루트 CLAUDE.md 파일은 공유 저장소에 있거나 프로젝트에 대한 개인 선호도로 로컬에 저장됩니다. 모든 파일은 세션 시작 시 로드되며, 긴 세션 동안 손실되거나 저하되지 않습니다. 클로드 코드가 대화를 압축할 때 이 파일들을 다시 읽습니다.
온디맨드: 세션을 초기화한 폴더 아래 서브디렉토리에 있는 CLAUDE.md 파일은 해당 서브디렉토리에서 파일을 읽을 때 로드됩니다. 경로 범위 규칙의 압축 행동을 공유하며, 해당 서브디렉토리가 다시 터치될 때까지 사라집니다. 모든 서브디렉토리 CLAUDE.md 파일은 해당 디렉토리 내에서 파일을 읽을 때 로드됩니다.

공유 저장소에서 CLAUDE.md는 소유되지 않은 구성 파일처럼 성장합니다. 각 팀은 자체 지시를 추가하고 아무것도 삭제되지 않습니다. 이는 규모에 따라 비용이 증가합니다. 모든 엔지니어가 작업하는 저장소의 모든 세션에 모든 줄이 로드되며, 이는 관련 여부와 상관없이 토큰을 소모하고 실제로 중요한 지시의 준수를 희석시킵니다. 파일이 커지면 팀별 규칙을 경로 범위 규칙으로, 절차를 스킬로 푸시하여 관련 있을 때만 로드되도록 합니다.

규칙

규칙은 .claude/rules/에 있는 마크다운 파일로, 클로드에게 특정 제약이나 규칙을 제공합니다. 범위가 지정되지 않은 규칙은 CLAUDE.md처럼 세션 시작 시 항상 로드되며, 압축 시 재주입됩니다. 이는 작업과 관련이 없을 때도 컨텍스트를 로드하여 토큰을 낭비할 수 있습니다. 경로 범위 규칙은 관련 있을 때만 규칙 지시를 로드할 수 있도록 paths 필드를 추가하여 로드 시기를 제어합니다.

스킬

스킬은 .claude/skills/에 있는 지시, 스크립트, 리소스 폴더로, 클로드가 동적으로 로드합니다. 각 스킬에는 이름, 설명, 본문이 있는 SKILL.md 파일이 있습니다. 이름과 설명만 세션 시작 시 로드되며, 스킬이 호출될 때 전체 본문이 로드됩니다. 스킬은 시스템 프롬프트를 통해 트리거됩니다. 예를 들어, /code-review는 현재 차이를 검토하고 파일을 편집하지 않고 결과를 보고하는 내장 스킬입니다. 스킬은 매번 동일한 구조적 접근 방식을 따르도록 정의됩니다.

서브에이전트

서브에이전트는 .claude/agents/에 있는 마크다운 파일로, 특정 부가 작업을 위한 격리된 도우미를 정의합니다. 각 파일은 YAML 전면부(이름, 설명, 모델 및 도구 접근을 위한 선택적 필드)와 그 서브에이전트의 시스템 프롬프트가 되는 본문으로 구성됩니다. 서브에이전트는 스킬과 유사하게 이름, 설명, 도구 목록이 세션 시작 시 로드되지만, 에이전트의 본문 내의 더 큰 컨텍스트는 자동 호출되지 않습니다. 클로드는 에이전트 도구를 통해 이를 호출하며, 프롬프트 문자열을 전달합니다.

훅

훅은 사용자 정의 명령어, HTTP 엔드포인트, 또는 LLM 프롬프트로, 파일 편집, 도구 호출, 세션 시작과 같은 클로드의 라이프사이클의 특정 이벤트에서 작동하여 클로드의 행동을 더 결정론적으로 제어합니다. 설정.json, 관리 정책 설정, 또는 스킬/에이전트 전면부에 훅을 등록합니다. 여러 유형의 훅이 있으며, 모든 훅은 결정론적으로 트리거됩니다.

출력 스타일

출력 스타일은 .claude/output-styles/에 있는 파일로, 시스템 프롬프트에 지시를 주입합니다. 절대 압축되지 않으며, 세션 시작 시 로드되고, 세션 내 첫 요청 후 캐시됩니다. 이는 중간 컨텍스트 비용을 의미합니다. 시스템 프롬프트에 위치하기 때문에, 출력 스타일은 지금까지 다룬 방법 중 가장 높은 지시 따르기 가중치를 가지며 신중하게 사용해야 합니다.

시스템 프롬프트 추가

출력 스타일을 수정하는 대안으로, 시스템 프롬프트 추가 플래그가 있습니다. 출력 스타일 파일을 수정하는 것이 클로드의 행동에 큰, 의도치 않은 변화를 줄 수 있는 반면, 추가 플래그는 원래 시스템 프롬프트에 추가적일 뿐입니다. 이는 클로드의 역할을 수정하지 않고, 기본 역할에 지시를 추가합니다. 이는 호출 시점에 전달되며, 세션 간 파일로 지속되지 않습니다. 시스템 프롬프트 추가는 지시 전달의 다른 방법에 비해 높은 컨텍스트 비용을 가질 수 있습니다. 이는 입력 토큰을 증가시키지만, 프롬프트 캐싱이 세션의 첫 요청 후 이 비용을 줄입니다. 클로드에게 더 장황하거나 긴 스타일을 사용하도록 지시하면 출력 토큰도 증가합니다.

파이랩 정리