Claude Code 실전 셋업 — 우리 팀 적용 사례

실제 운영 중인 설정 공유. 이 파일을 Claude Code에 붙여넣고 "이거 셋업해줘"라고 하면 자동 적용됨.

1. CLAUDE.md · 2. settings.json · 3. 슬래시 커맨드 · 4. 서브에이전트 · 5. Hooks · 6. MCP/플러그인

---

STEP 1. CLAUDE.md (프로젝트 규칙서)

~/.claude/CLAUDE.md 파일 생성. 매 세션 자동 로드됨.

# Claude Project Protocol

> 이 문서가 최상위 규칙. 충돌 시 이 문서 우선.

## 운영 원칙
- 비자명 작업(3단계↑/아키텍처 결정) → Plan Mode 필수
- 틀어지면 즉시 STOP → 재계획 (밀어붙이지 않음)
- 완료 전 검증 필수: 테스트 실행, 작동 증명 없이 완료 아님
- 영향 최소화, 단순함 우선, DRY 공격적 적용
- 에러 발견 시 보고 대신 자동 수리

## 서브에이전트 모델 분업
- 탐색/검색/진단 → Haiku (빠르고 저렴)
- 구현/수정/리팩터링 → Sonnet (균형)
- 설계/아키텍처/의사결정 → Opus (깊은 사고)

## 리뷰 4단계
1. 아키텍처(설계/의존성/보안)
2. 코드품질(DRY/에러핸들링/기술부채)
3. 테스트(커버리지/엣지)
4. 성능(N+1/메모리/캐싱)

## 토큰 효율
- 대형 파일: 전체 읽기 금지. offset+limit으로 필요 부분만
- 중복 읽기 금지: 이미 컨텍스트에 있으면 재읽기 안 함
- 불필요한 출력 최소화

---

STEP 2. settings.json (핵심 설정)

~/.claude/settings.json 파일 생성 또는 병합:

{
  "permissions": {
    "allow": ["Edit", "Write", "Bash", "Read", "Glob", "Grep", "WebFetch", "WebSearch"]
  },
  "model": "sonnet",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/large-file-guard.sh",
            "timeout": 3000
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/audit-log.sh",
            "timeout": 3000
          }
        ]
      }
    ]
  },
  "language": "korean"
}

---

STEP 3. Hooks (자동 트리거 스크립트)

~/.claude/hooks/ 폴더 만들고 아래 파일들 생성:

파일 1: ~/.claude/hooks/large-file-guard.sh

2000줄 이상 파일을 통째로 읽으려 하면 경고 주입

#!/bin/bash
INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
[ "$TOOL" != "Read" ] && exit 0

FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
OFFSET=$(echo "$INPUT" | jq -r '.tool_input.offset // empty' 2>/dev/null)
LIMIT=$(echo "$INPUT" | jq -r '.tool_input.limit // empty' 2>/dev/null)

[ -n "$OFFSET" ] || [ -n "$LIMIT" ] && exit 0
[ ! -f "$FILE_PATH" ] && exit 0

LINE_COUNT=$(wc -l < "$FILE_PATH" 2>/dev/null | tr -d ' ')
[ -z "$LINE_COUNT" ] && exit 0
[ "$LINE_COUNT" -lt 2000 ] && exit 0

TOKENS_EST=$((LINE_COUNT * 12))
echo "[토큰 절약] ${FILE_PATH##*/}: ${LINE_COUNT}줄 (~${TOKENS_EST} 토큰). offset+limit으로 필요 부분만 읽으세요."
exit 0

파일 2: ~/.claude/hooks/audit-log.sh

모든 Bash 명령을 타임스탬프와 함께 기록

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
[ "$TOOL" != "Bash" ] || [ -z "$COMMAND" ] && exit 0

LOG_FILE="$HOME/.claude/command-audit.log"
if [ -f "$LOG_FILE" ]; then
  SIZE=$(stat -f%z "$LOG_FILE" 2>/dev/null || echo 0)
  [ "$SIZE" -gt 10485760 ] && mv "$LOG_FILE" "${LOG_FILE}.1"
fi

SAFE_CMD=$(echo "$COMMAND" | tr '\n' ' ' | head -c 500)
echo "$(date '+%Y-%m-%d %H:%M:%S') | ${SAFE_CMD}" >> "$LOG_FILE"
exit 0

생성 후 실행 권한: chmod +x ~/.claude/hooks/*.sh

---

STEP 4. 슬래시 커맨드 (12개 중 핵심 6개)

~/.claude/commands/ 폴더 만들고 파일 생성. 이후 /파일명으로 호출 가능.

/today — 데일리 브리핑

# ~/.claude/commands/today.md
오늘 하루를 시작하기 위한 브리핑을 생성하라.
1. 현재 프로젝트 상태 (git status, 최근 커밋 5개)
2. 미완료 TODO 확인
3. 어제 변경된 파일 확인
4. 오늘 우선 처리할 작업 제안
실제 데이터를 기반으로 구체적인 수치와 내용을 포함.

/close — 하루 마감 리뷰

# ~/.claude/commands/close.md
오늘 하루의 활동을 정리하라.
1. 오늘 변경된 파일과 커밋 요약
2. 미완료 작업 목록
3. 내일을 위한 씨앗 (이어서 할 작업 제안)
4. 필요시 커밋 생성

/quality — 6단계 품질 모드

# ~/.claude/commands/quality.md
즉시 품질 모드로 전환하라. 현재 작업에 아래 6단계를 엄격히 적용:

1. UNDERSTAND — 요구사항 정확히 파악, 모호하면 질문
2. PLAN — 접근법 2-3개 비교, 최선 선택 근거 제시
3. PRE-MORTEM — "이 계획이 실패한다면 왜?" 미리 분석
4. EXECUTE — 계획대로 구현, 각 단계 완료 확인
5. VERIFY — 테스트 실행, 엣지케이스 확인
6. DELIVER — 변경 요약, 시니어 엔지니어가 승인할 수 있는 수준인지 자문

/review — 코드 리뷰

# ~/.claude/commands/review.md
현재 변경사항을 코드 리뷰하라:
1. git diff로 변경 내용 확인
2. 버그 가능성, 성능 이슈, 보안 취약점 체크
3. 각 항목별 심각도(높/중/낮) 표시
4. 개선 제안이 있으면 코드와 함께 제시

/connect — 크로스 도메인 연결 발견

# ~/.claude/commands/connect.md
프로젝트/볼트 안의 두 주제 사이에 숨겨진 연결고리를 찾아라.
1. 최근 작업한 파일들에서 공통 패턴 발견
2. 서로 다른 모듈 간 재사용 가능한 로직 식별
3. 연결 강도별(강/중/약) 분류
4. 실현 가능한 통합 제안

/system — 시스템 전체 뷰

# ~/.claude/commands/system.md
시스템의 현재 상태를 한눈에 파악하라.
1. git status + 최근 커밋
2. 실행 중인 서비스 확인
3. 디스크/메모리 사용량
4. 최근 에러 로그 확인
5. 전체 상태 요약

---

STEP 5. 서브에이전트 (모델별 분업)

~/.claude/agents/ 폴더 만들고 파일 생성.

scout.md — 빠른 탐색 (Haiku)

---
model: haiku
tools: ["Read", "Grep", "Glob", "Bash"]
---
빠른 탐색 전용 에이전트.
- 파일 구조 파악, 코드 검색, 패턴 찾기
- 상세 분석은 하지 않고 위치와 구조만 보고
- 결과는 bullet point로 간결하게

architect.md — 설계 전용 (Opus)

---
model: claude-opus-4-6
tools: ["Read", "Grep", "Glob", "Bash", "WebSearch", "WebFetch"]
---
수석 아키텍트 에이전트.
- 대규모 변경 전 영향범위 분석
- 2-3개 접근법 비교 (장단점 포함)
- 구체적 실행 계획 제시 (단계별, 파일별)
- 구현은 하지 않음 — 설계만 제시

test-runner.md — 테스트 전용 (Haiku)

---
model: haiku
tools: ["Read", "Grep", "Glob", "Bash"]
---
테스트 실행 전용 에이전트.
- 코드 변경 후 관련 테스트 실행
- 실패 시 원인 분석 (mock 이슈, 로직 에러 등)
- file:line 참조와 함께 보고
- 소스 코드 수정은 하지 않음

---

STEP 6. MCP & 플러그인

claude-mem 플러그인 (대화 간 메모리)

settings.json에 추가:

{
  "enabledPlugins": {
    "claude-mem@thedotmack": true
  }
}

→ 세션 간 메모리 저장/검색 가능. "이거 기억해줘" → 다음 세션에서 자동 참조.

---

완료 후 확인

cat ~/.claude/CLAUDE.md
cat ~/.claude/settings.json
ls ~/.claude/commands/
ls ~/.claude/agents/
ls ~/.claude/hooks/

활용 팁

• 병렬 작업: "A와 B를 병렬로 진행해줘" → 서브에이전트 동시 실행
• 워크트리: "워크트리로 진행해줘" → 별도 git 브랜치에서 격리 작업
• Plan Mode: 큰 작업 전 "계획부터 세워줘" → 토큰 낭비 방지
• 크론: /cron:create 으로 반복 작업 스케줄 가능
• 모델 지정: "이건 opus로 해줘" → 중요한 설계에 상위 모델 사용