"Claude 하네스 구축 (2/3) — CLAUDE.md, Skills, Hooks, Permissions를 어떻게 나눠 써야 하나"

-

Claude 기반 하네스를 설계할 때 가장 흔한 실수는 모든 규칙을 CLAUDE.md 한 파일에 우겨 넣는 것이다. 하지만 실제 운영에서는 역할이 다르다. CLAUDE.md는 정체성과 기본 규칙, skills는 반복 절차, hooks는 자동 검문소, permissions는 권한 경계에 가깝다. 이 네 층을 분리해야 짧고 강한 지시가 남고, 자동화도 덜 부서진다.

핵심 요약

  • CLAUDE.md는 프로젝트 정체성, hard rules, read-first 경로 같은 항상 읽혀야 하는 기본 지시층이다.
  • skills는 반복 작업을 모듈화한 절차 패키지다. 긴 업무 매뉴얼이나 단계형 실행은 여기로 빼는 편이 낫다.
  • hooks는 tool 실행 전후나 사용자 입력 시점에 개입하는 자동 강제 층이다. "지켜 줬으면 하는 규칙"보다 "어기면 막아야 하는 규칙"이 여기에 가깝다.
  • permissions와 settings는 읽기, 수정, 실행, 외부 접근을 나누는 권한 경계 층이다. 안전성과 운영 통제는 여기서 결정된다.
  • 즉 Claude 하네스의 핵심은 좋은 지시문 하나를 쓰는 것이 아니라, 무엇을 어느 층에 둘지 구분하는 일이다.

1. 왜 분리가 먼저인가

Claude Code 공식 문서를 보면 메모리 파일, settings, hooks, subagents, slash commands 같은 표면이 따로 존재한다. 이것은 기능이 많다는 뜻이기도 하지만, 더 중요한 의미가 있다.

Claude 하네스는 원래부터 단일 파일 중심이 아니라, 여러 운영 층으로 나뉘도록 설계되어 있다.

이 점을 놓치면 보통 이런 일이 생긴다.

  • CLAUDE.md가 너무 길어진다
  • 중요한 규칙이 잡음 속에 묻힌다
  • 반복 절차가 매번 프롬프트에 다시 등장한다
  • 강제해야 하는 규칙이 "권고"로만 남는다
  • 권한 문제를 지시문으로 해결하려 한다

따라서 B2의 핵심은 기능 나열이 아니다. CLAUDE.md, skills, hooks, permissions가 각각 무슨 종류의 책임을 맡아야 하는가를 분리해서 보는 것이다.

2. CLAUDE.md는 첫 표지판이지 전체 운영체제가 아니다

기존 CLAUDE.md 작성 가이드에서도 강조했듯이, CLAUDE.md는 항상 컨텍스트에 들어가는 파일이다. 그래서 길고 자세할수록 좋은 문서가 아니라, 짧고 우선순위가 분명한 문서가 좋다.

여기에 두기 좋은 것은 대체로 아래와 같다.

  • 이 프로젝트가 무엇인지
  • 무엇을 먼저 읽어야 하는지
  • 절대 하면 안 되는 것
  • 작업 규모별 기본 workflow
  • 디렉터리 책임 분리

반대로 여기서 빼야 하는 것도 명확하다.

  • 긴 단계별 작업 절차
  • 자주 바뀌는 운영 팁
  • 특정 작업 전용 상세 매뉴얼
  • 강제로 막아야 하는 안전 규칙

한 문장으로 정리하면 이렇다.

CLAUDE.md는 정체성 선언문과 안전 표지판에 가깝고, 세부 작업 설명서까지 다 넣는 장소는 아니다.

3. skills는 긴 절차를 컨텍스트 상시 비용에서 분리하는 층이다

우리 저장소 운영 문맥에서 skills는 반복 작업을 모듈화한 문서 묶음이다. Claude 생태계 전체에서는 custom commands, subagents, 재사용 프롬프트 같은 형태로 비슷한 목적을 달성할 수도 있지만, 하네스 설계 관점의 핵심은 같다.

  • 자주 반복되는 작업인가
  • 여러 단계가 필요한가
  • 입력, 검증, 출력 형식이 비교적 안정적인가

이런 작업은 skills로 빼는 편이 낫다.

예를 들어:

  • 발행 전 검수
  • 핸드오프 작성
  • 코드 리뷰
  • 테스트 실행과 결과 요약
  • 특정 디렉터리 전용 수정 절차

이렇게 하면 생기는 이점이 있다.

  • CLAUDE.md는 짧게 유지된다
  • 긴 절차가 필요할 때만 로드된다
  • 팀이 같은 작업 방식을 공유하기 쉽다
  • 작업 종류별 출력 형식을 고정하기 쉽다

즉 skills의 핵심 가치는 "기능 추가"보다 반복 절차를 상시 컨텍스트에서 분리하는 것이다.

4. hooks는 지시가 아니라 자동 검문소다

Anthropic 공식 hooks 문서를 보면, hooks는 PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStop 같은 이벤트에 연결된다. 그리고 설정 파일에서 matcher와 command를 통해 구성된다.

이 구조를 하네스 언어로 번역하면 이렇다.

  • CLAUDE.md: 해 줬으면 하는 방향
  • skill: 이렇게 해 보라는 절차
  • hook: 이 시점에는 반드시 검사하거나 개입하는 자동 장치

예를 들어 아래 같은 규칙은 hook 후보에 가깝다.

  • 특정 파일 수정 뒤 포맷/검증 스크립트 실행
  • 민감 경로 수정 전 차단 또는 경고
  • 사용자 프롬프트 제출 시 금지 작업 검사
  • 세션 종료 시 handoff 파일 검사

이런 규칙을 CLAUDE.md에만 적어 두면 따를 때도 있고 놓칠 때도 있다. 반면 hook은 도구 실행 시점에 직접 개입하므로, 규칙을 기억 의존에서 실행 경계 의존으로 바꿀 수 있다.

그래서 hook은 "긴 문서로 더 강하게 말하기"의 대체재가 아니라, 그보다 훨씬 다른 층이다.

5. permissions는 안전 정책과 접근 범위를 맡는다

Claude Code 공식 settings 문서는 permissions.allow, ask, deny, defaultMode, disableBypassPermissionsMode, additionalDirectories 같은 설정을 제공한다. 이 표면이 중요한 이유는 안전 문제를 지시문이 아니라 구성 파일 수준에서 분리할 수 있기 때문이다.

특히 중요한 원칙은 이것이다.

  • 읽기
  • 수정
  • 실행
  • 웹 접근
  • 민감 파일 접근

이 다섯을 같은 종류의 행동으로 보면 안 된다.

예를 들어:

  • .env, secrets/**, 자격 증명 파일은 deny
  • 파괴적 bash 명령은 ask 또는 deny
  • 팀 표준 테스트/린트 명령만 좁게 allow
  • 개인 실험용 예외는 .claude/settings.local.json
  • 공용 정책은 .claude/settings.json

이렇게 해야 "AI가 할 수 있는가"와 "AI가 해도 되는가"를 분리할 수 있다.

6. 네 층은 각각 어떤 질문에 답하는가

헷갈릴 때는 기능명이 아니라 질문으로 분류하면 훨씬 선명하다.

질문 더 적합한 층
이 프로젝트는 무엇이며, 기본 태도는 무엇인가 CLAUDE.md
이 종류의 작업은 어떤 단계로 처리하나 skill
이 도구 실행 전후에 자동 검사를 붙여야 하나 hook
이 행동을 허용, 질문, 차단 중 무엇으로 둘까 permissions/settings

이 표 하나만 기억해도 CLAUDE.md 비대화 문제를 크게 줄일 수 있다.

7. 흔한 안티패턴

Claude 하네스가 약할 때는 대체로 아래 실수가 같이 나온다.

7.1 모든 규칙을 CLAUDE.md에 몰아넣는다

가장 흔한 실패다. 파일은 길어지고, adherence는 내려가고, 핵심 hard rule이 묻힌다.

7.2 반복 작업을 매번 프롬프트로 다시 설명한다

이 경우 작업 품질도 흔들리고, 세션마다 토큰을 낭비한다.

7.3 차단해야 할 규칙을 문장으로만 적는다

예: "credentials는 건드리지 마라"를 적어 두기만 하고 permissions나 hooks로 막지 않는다.

7.4 hook으로 해결할 일을 skill이나 지시문으로만 처리한다

검증 자동화, 경로 차단, 종료 시 체크 같은 것은 실행 시점 개입이 더 맞다.

7.5 권한 예외를 공용 파일에 섞어 넣는다

개인 실험성 예외는 settings.local.json 쪽이 맞고, 팀 규칙은 공유 설정에 둬야 한다.

8. 실무 분리 원칙: 짧은 규칙, 긴 절차, 자동 강제, 좁은 권한

실무에서 가장 잘 작동하는 기본 원칙은 아래 네 줄로 요약할 수 있다.

  • 짧은 규칙은 CLAUDE.md
  • 긴 절차는 skills
  • 자동 강제는 hooks
  • 좁은 권한은 permissions/settings

이 구조가 좋은 이유는 각 층의 실패 모드가 다르기 때문이다.

  • CLAUDE.md는 길어지면 묻힌다
  • skills는 오래되면 절차 드리프트가 생긴다
  • hooks는 과하면 개발 흐름을 막는다
  • permissions는 느슨하면 안전이 무너지고, 과하면 생산성이 막힌다

즉 핵심은 어느 한 층을 강화하는 것이 아니라, 각 층을 자기 역할에 맞게 얇고 선명하게 유지하는 것이다.

9. 우리 같은 저장소에서의 적용 예시

콘텐츠·스크립트 혼합 저장소라면 이런 분리가 자연스럽다.

  • CLAUDE.md: 발행 금지 규칙, config/ 금지, read-first 문서, workflow 게이트
  • skills: 블로그 초안 작성, 발행 전 검토, handoff 작성, 코드 리뷰
  • hooks: context 문서 편집 후 경로 검증, 특정 스크립트 수정 후 검사
  • permissions/settings: 비밀 파일 deny, 위험 명령 ask/deny, 공용 명령 allow

이렇게 두면 에이전트가 무엇을 해야 하는지뿐 아니라, 어디까지 해도 되는지도 구조적으로 분명해진다.

10. Claude 하네스는 좋은 문장보다 좋은 층 분리가 먼저다

Claude Code를 처음 쓰면 보통 좋은 지시문을 쓰는 데 집중하게 된다. 물론 중요하다. 하지만 운영 수준으로 가면 더 중요한 것은 문장의 질보다 책임 배치다.

  • 기본 정체성과 hard rule은 CLAUDE.md
  • 재사용 가능한 절차는 skills
  • 실행 시점 자동 개입은 hooks
  • 접근 경계와 안전 정책은 permissions/settings

이 구분이 서면 CLAUDE.md는 짧아지고, 반복 작업은 안정되고, 안전 규칙은 덜 잊히고, 팀 협업도 쉬워진다.

그래서 Claude 하네스의 질문은 "무엇을 지시할까"보다 다음에 가깝다.

이 규칙은 기억에 맡길 것인가, 절차로 빼낼 것인가, 자동으로 강제할 것인가, 아니면 권한으로 막을 것인가?

다음 B3에서는 이 관점을 OpenAI 쪽과 비교해서, 두 플랫폼이 왜 다른 운영 철학을 갖게 되는지 정리한다.

참고 자료

  • Anthropic Docs, Claude Code settings
    https://docs.anthropic.com/en/docs/claude-code/settings
  • Anthropic Docs, Hooks reference
    https://docs.anthropic.com/en/docs/claude-code/hooks
  • Anthropic Docs, Subagents
    https://docs.anthropic.com/en/docs/claude-code/sub-agents
  • Anthropic Docs, Slash commands
    https://docs.anthropic.com/en/docs/claude-code/slash-commands
  • Anthropic Docs, Security
    https://docs.anthropic.com/en/docs/claude-code/security
  • drafts/blog/260425_CLAUDEmd작성가이드_블로그.md
  • drafts/blog/260425_claude_md_authoring_guide_en.md
  • docs/blog_series_하네스엔지니어링_총괄_design.md
  • sources/260518_하네스엔지니어링_15장_블로그활용노트.md

이 글은 OpenAI·Claude 구현 시리즈의 2/3 편입니다. 후속 읽기: OpenAI vs Claude 하네스 비교.

시리즈 전체 안내: 하네스 엔지니어링 시리즈 안내

댓글

댓글 쓰기

이 블로그의 인기 게시물

"LLM 핵심 학습 (1/6) — 기본: 토큰화·임베딩·어텐션·위치 인코딩"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/6 파인튜닝 → 트랜스포머 한 블록의 데이터 흐름을 문자열 → 토큰 → 임베딩 → 어텐션 → 출력 표현 까지 손으로 풀어 본다. 이번 편이 끝나면 "왜 \(\sqrt{d_k}\)로 나누는가", "RoPE는 무엇을 회전시키는가", "한국어가 영어보다 토큰이 많은 까닭은 무엇인가"가 한 줄로 설명될 수 있다. 0. 학습 목표 이 편을 마치면 다음을 직접 할 수 있다. BPE 토크나이저 가 어휘를 어떻게 학습하고 새 문자열을 어떻게 자르는지 종이 위에서 시뮬레이션한다. 임베딩 행렬 의 모양과 초기화, weight tying의 의미를 한 줄로 설명한다. Scaled Dot-Product Attention 의 식을 차원 단위로 추적하고 PyTorch 30줄로 재현한다. Multi-Head Attention 이 한 헤드와 비교해 무엇이 다른지, 헤드 수가 늘면 어디가 비싸지는지 답한다. Sinusoidal·RoPE·ALiBi 세 위치 인코딩의 식과 외삽 성질을 구분한다. 컨텍스트 확장이 왜 \(O(N^2)\)인지, "Lost in the Middle"이 왜 발생하는지 설명한다. 1. 핵심 요약 트랜스포머의 입력은 문자열 이 아니라 정수 ID 시퀀스 다. 토크나이저가 문자열 → ID로 자른다. 임베딩은 정수 ID를 \(d\)차원 벡터로 lookup하는 학습 가능한 테이블이다. Self-Attention은 \(\text{softmax}(QK^\top / \sqrt{d_k}) V\) 한 줄이 핵심이고, 멀티헤드는 같은 연산을 여러 부분 공간에서 병렬화한 것이다. 위치 정보는 임베딩에 직접 더하거나(Sinusoidal), Q·K에 회전을 가하거나(RoPE), 어텐션 스코어에 거리 패널티를 더해서(ALiBi) 주입한다. 컨텍스트 길이 \(N\)에 대해 표준 어텐션은 \(O(N^2)\) 비용을 갖고, 긴 컨텍스트에서는 중간 위...
Read more »

"LLM 핵심 학습 (2/6) — 파인튜닝: LoRA·QLoRA·증류·Adapter"

-
이미지
← 1/6 기본 📚 시리즈 목차 3/6 디코딩과 생성 → 사전학습된 LLM을 내 데이터 에 적응시키는 방법을 비용·메모리·일반화 관점에서 정리한다. Full FT의 한계 → Adapter → LoRA → QLoRA → Distillation 순으로 같은 그림을 점점 확대해 본다. 0. 학습 목표 Full fine-tuning의 메모리 병목을 옵티마이저 상태·그래디언트·가중치·활성화 의 4분할로 설명한다. Adapter(Houlsby 2019)와 LoRA(Hu 2021)의 식 차이를 한 줄로 적는다. LoRA의 \(A, B\) 행렬이 왜 저랭크 이고, rank \(r\) 선택이 무엇을 결정하는지 답한다. QLoRA(Dettmers 2023)의 NF4·double-quant·paged optimizer를 분리해서 설명한다. Catastrophic Forgetting을 분포 시프트 관점에서 정의하고 완화 기법을 두 개 이상 든다. Hinton 2015의 Knowledge Distillation 식을 손으로 유도한다. 1. 핵심 요약 Full FT는 메모리/디스크/시간 모두 비싸다. 7B 모델 full FT는 V100 8장 + A100 1장으로도 큰 부담이다. PEFT(파라미터 효율 파인튜닝) 일가족은 극히 일부 파라미터만 학습 해 같은 효과를 얻는다. LoRA: \(\Delta W = BA\) (rank \(r \ll \min(d_{\text{in}}, d_{\text{out}})\))로 가중치 업데이트를 저랭크 분해. QLoRA: 베이스 모델을 4-bit(NF4)로 양자화한 채 LoRA만 풀-정밀(BF16)으로 학습. Catastrophic Forgetting: 새 분포에 적응하느라 이전 능력이 무너지는 현상. PEFT 자체가 부분 완화책. Distillation: 큰 교사 모델의 soft target 을 학습 신호로 써서 작은 학생 모델 을 만든다. 2. 직관: 왜 사전학습만으로는 부족한가 사전학습은 일반...
Read more »

"ML 기초 학습 (1/9) — 머신러닝과 sklearn: 학습의 좌표계"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/9 이웃 알고리즘 → 이 시리즈는 신경망과 로컬 LLM으로 가기 전에 손에 익혀 둬야 할 머신러닝 기초 9편이다. 1편은 모든 ML 코드가 공유하는 공통 문법 을 잡는 데 쓴다. sklearn은 그 문법을 가장 일관되게 보여주는 도구다. 이번 편이 끝나면 어떤 모델을 만나도 fit → predict → score → 평가 흐름이 같다는 것이 손에 잡힌다. 0. 학습 목표 이 편을 마치면 다음을 할 수 있어야 한다. 지도학습·비지도학습·강화학습을 한 문장씩 구분해 설명한다. sklearn의 estimator 인터페이스 ( fit , predict , score , transform )를 코드 한 화면 안에서 쓸 수 있다. train/validation/test 분할을 왜 하는지, 어디서 데이터 누수가 생기는지 식과 그림으로 설명한다. 분류·회귀의 핵심 평가 지표(accuracy, precision, recall, F1, MSE, R²)를 정의에서 직접 계산할 수 있다. k-fold 교차검증 을 코드 한 줄로 돌리고, 결과의 평균과 표준편차를 함께 보고할 수 있다. Pipeline 으로 전처리와 모델을 묶어 데이터 누수를 구조적으로 막는 방법을 설명한다. 1. 핵심 요약 머신러닝은 데이터에서 함수 \(f: X \to Y\)를 찾는 작업 이다. 어떤 모델이든 이 본질은 같다. sklearn은 모든 모델을 같은 인터페이스( fit , predict , score )로 통일해, 모델을 바꿀 때 한 줄만 바꾸면 되게 한다. train/val/test 세 분할이 표준이다. 검증으로 하이퍼파라미터를 고르고, 테스트는 마지막에 한 번만 본다. 데이터 누수 (test 정보가 train에 새는 현상)는 ML 입문자가 가장 자주 만드는 실수이며, Pipeline + cross_val_score 조합으로 구조적으로 막을 수 있다. 평가 지표는 문제 유형 (분류/회귀) 과 클래스 불균형...
Read more »