ClaudeCode한테 어떻게 잘 시키지? 기본편

Posted on | In

AI 믿지 마라 = 예측 가능한 동작 + 사용자가 제어권


3.1 훅(Hooks) 시스템

핵심 개념

훅 = 도구 실행 전후에 사용자 스크립트를 자동 실행하는 시스템. 권한 시스템(allow/deny)이 도구 단위 ON/OFF라면, 훅은 도구의 인자까지 검사할 수 있다.

권한 시스템 vs 훅

1
2
권한 시스템: "Bash 도구 자체를 허용/거부"     → 단순 ON/OFF
훅 시스템:   "Bash에서 rm -rf만 차단"         → 인자까지 검사

3가지 타이밍

1
2
Claude가 명령어 결정 → 🪝 PreToolUse → 실제 실행 → 🪝 PostToolUse → 결과 반환
                                                                    🪝 Notification (별도)
타이밍 시점 용도
PreToolUse 실행 전 차단, 치환, 검증
PostToolUse 실행 후 결과 검증, 로깅
Notification 알림 발생 시 Slack 알림 등 외부 연동

설정 구조 (settings.json)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 my_script.py"
          }
        ]
      }
    ]
  }
}
  • matcher: 정규식 ("Bash", "Bash|Write", ".*")
  • type: "command" (외부 스크립트) 또는 "prompt" (Claude가 판단)

입력: stdin JSON

1
2
3
4
{
  "tool_name": "Bash",
  "tool_input": { "command": "rm -rf /" }
}

출력: exit code

Exit Code 의미 결과
0 통과 도구 실행 허용
2 차단 도구 실행 차단
그 외 에러 훅 에러, 도구는 실행됨

주의: exit 1은 차단이 아니다 — 명시적으로 exit 2만이 차단

고급 출력: stdout JSON

1
2
3
4
5
6
7
{
  "hookSpecificOutput": {
    "permissionDecision": "allow|deny|ask",
    "updatedInput": { "command": "안전한 명령어로 치환" }
  },
  "systemMessage": "Claude에게 전달할 메시지"
}
  • updatedInput → 도구 인자를 치환 가능 (차단 대신 안전한 명령으로 교체)
  • “ask” → Claude에게 판단을 위임

command vs prompt 타입

type 실행 주체 적합한 용도
command 외부 스크립트 명확한 규칙 (rm -rf 차단 등)
prompt Claude (LLM) 코드로 표현 어려운 검사 (보안 취약점 등)

핵심 정리

  1. 훅 = 경비원 — 기존 도구를 감시/제어 (새 도구 추가가 아님)
  2. 3가지 타이밍 — PreToolUse, PostToolUse, Notification
  3. stdin JSON → exit code — 입출력 구조
  4. exit 2만 차단 — 1은 에러일 뿐, 도구는 실행됨
  5. JSON 출력으로 치환 가능 — 차단 말고 안전한 명령으로 교체
  6. prompt 타입 — 스크립트 대신 Claude가 판단


3.2 MCP (Model Context Protocol) 서버

핵심 개념

MCP 서버 = Claude Code에 새로운 도구를 추가하는 외부 프로세스. 훅이 기존 도구를 감시하는 “경비원”이라면, MCP는 새 장비를 납품하는 것.

훅 vs MCP

1
2
훅:  기존 도구 감시/제어  → 🚦 경비원
MCP: 새로운 도구 추가     → 🧰 새 장비 납품

MCP 서버 연결하면 생기는 변화

1
2
3
4
기존:  Read, Write, Edit, Bash, Grep, Glob...
추가:  mcp__context7__query-docs, mcp__github__list-issues...
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
       MCP 서버가 제공하는 새 도구들

도구 이름 규칙

1
2
3
mcp  __  context7  __  query-docs
 ↓          ↓            ↓
MCP다    어느 서버    무슨 도구

통신 방식: stdio

1
Claude Code ←→ stdin/stdout (JSON) ←→ MCP 서버 프로세스
  • 훅과 같은 원리 (stdin/stdout JSON)
  • 차이: 훅은 이벤트마다 실행/종료, MCP는 계속 실행 중 (서버)

설정 구조 (settings.json)

1
2
3
4
5
6
7
8
9
10
11
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}
  • command + args: 서버 실행 명령
  • env: 환경변수 (API 키 등)

실제 사용 중인 예시

이 프로젝트의 settings.local.json에서:

1
2
"mcp__context7__resolve-library-id"  → 라이브러리 ID 검색
"mcp__context7__query-docs"          → 최신 문서 조회

핵심 정리

  1. MCP = 새 도구 추가 — 훅(감시)과 역할이 다름
  2. stdio 통신 — 로컬 프로세스로 실행, JSON으로 대화
  3. 계속 실행 중 — 훅(이벤트마다 실행/종료)과 달리 서버로 상주
  4. 이름 규칙 — mcp__서버이름__도구이름
  5. 설정 — mcpServers에 command + args + env


3.4 에이전틱 코딩 패턴

핵심 개념

큰 작업을 여러 서브에이전트가 병렬로 처리. 각 서브에이전트는 별도의 Claude Code 프로세스.

서브에이전트 구조

1
2
3
4
메인 Claude Code (부모)
  ├── 서브에이전트 1 (자식 프로세스) → 작업 A
  ├── 서브에이전트 2 (자식 프로세스) → 작업 B
  └── 서브에이전트 3 (자식 프로세스) → 작업 C
  • 각각 독립적인 프로세스로 실행
  • 병렬로 동시 작업 → 속도 향상

워크트리 (Worktree)

같은 git 저장소의 복사본을 별도 폴더에 만드는 것.

1
2
3
원본:        /my-project/          ← main 브랜치
워크트리 1:  /tmp/worktree-1/      ← 복사본 (별도 브랜치)
워크트리 2:  /tmp/worktree-2/      ← 복사본 (별도 브랜치)

각 서브에이전트가 자기만의 복사본에서 작업 → 파일 충돌 방지

작업 분배 원칙

1
2
3
4
5
6
7
✅ 좋은 분배: 서로 다른 파일/영역
   에이전트 1: src/auth/    리팩토링
   에이전트 2: tests/       테스트 작성
   에이전트 3: docs/        문서화

❌ 나쁜 분배: 같은 파일을 여러 에이전트가 건드림
   → merge할 때 💥 conflict 발생

핵심 정리

  1. 서브에이전트 = 별도 Claude Code 프로세스로 병렬 작업
  2. 워크트리 = git 복사본에서 독립 작업 → 충돌 방지
  3. 주의점 = 작업 영역이 겹치면 merge conflict
  4. 원칙 = 일을 잘 나눠서 시켜야 한다


3.5 컨텍스트 관리 심화

핵심 개념

컨텍스트가 길어지면 비용 증가 + 품질 저하(환각) 두 가지 문제. 전략적으로 관리해야 한다.

/compact vs /clear

1
2
같은 작업인데 컨텍스트 길어짐 → /compact (맥락 유지하면서 압축)
다른 작업으로 전환            → /clear   (깨끗하게 시작)
전략 효과 맥락 유지
/compact 대화를 요약으로 압축 ✅ 핵심 맥락 유지
/clear 컨텍스트 초기화 ❌ 다 날아감

/compact 작동 방식

Claude가 대화 내역을 읽고 요약으로 교체. 키워드가 아니라 문맥을 유지하는 요약.

1
2
/compact 전: 수십 턴의 긴 대화
/compact 후: "auth 모듈 리팩토링 중. validate 함수 수정 완료. 현재 정상 동작."

대규모 코드베이스 전략

1
2
3
4
❌ "프로젝트 전체 읽어줘"     → 토큰 폭탄
✅ Glob으로 구조만 파악       → 파일 목록만
✅ Grep으로 필요한 부분 검색  → 핀포인트
✅ Read로 필요한 파일만       → 최소한으로
  • Explore → Plan → Act 루프 = 필요한 만큼만 점진적 탐색
  • CLAUDE.md에 프로젝트 구조 미리 작성 → 탐색 없이 바로 파악

핵심 정리

  1. 컨텍스트 길어짐 = 비용 + 환각 두 가지 문제
  2. /compact = 같은 작업, 맥락 유지하며 압축
  3. /clear = 다른 작업으로 전환 시
  4. 핀포인트 탐색 = 전체 읽기 대신 Glob/Grep/Read
  5. CLAUDE.md = 프로젝트 구조 미리 제공하여 토큰 절약