Claude Code 완전 가이드: 서브에이전트, 훅, Agent SDK — 에이전틱 코딩의 모든 것

# Claude Code 기본 실행
claude

# 특정 프롬프트로 실행
claude "이 프로젝트의 아키텍처를 분석해줘"

# 파이프라인 모드
cat error.log | claude "이 에러의 원인을 분석하고 수정해줘"

# Node.js 18 이상 필요
npm install -g @anthropic-ai/claude-code

# 또는 특정 디렉토리에서 npx로 실행
npx @anthropic-ai/claude-code

# 처음 실행 시 인증 프로세스 시작
claude

# Anthropic 계정 또는 API 키로 인증
# 브라우저가 열리며 인증 완료

# VS Code 확장 설치
code --install-extension anthropic.claude-code

# 설정 확인
claude config list

# 모델 설정 (기본: claude-sonnet-4-20250514)
claude config set model claude-sonnet-4-20250514

# 권한 설정
claude config set permissions.allow-edit true
claude config set permissions.allow-exec true

# 자동 승인 패턴 설정
claude config set permissions.auto-approve-commands "npm test,npm run lint"

# tmux 세션에서 Claude Code 실행 (장시간 작업에 유용)
tmux new-session -s claude
claude

# 작업 기록 저장
claude --output-dir ./claude-logs

# 비대화형 모드 (스크립트에서 사용)
claude -p "README.md를 업데이트해줘" --yes

# 프로젝트 개요

이 프로젝트는 Next.js 14 기반의 블로그 플랫폼입니다.
TypeScript를 사용하며, Tailwind CSS로 스타일링합니다.

# 기술 스택

- Framework: Next.js 14 (App Router)
- Language: TypeScript (strict mode)
- Styling: Tailwind CSS
- Database: PostgreSQL + Prisma ORM
- Testing: Jest + React Testing Library

# 코딩 컨벤션

- 컴포넌트: 함수형 컴포넌트 + 화살표 함수 사용
- 네이밍: camelCase (변수/함수), PascalCase (컴포넌트/타입)
- import 순서: 외부 라이브러리 > 내부 모듈 > 상대 경로
- 에러 핸들링: try-catch 대신 Result 타입 패턴 사용

# 테스트 규칙

- 모든 새로운 함수에 단위 테스트 필수
- 테스트 명령: npm test
- 린트 명령: npm run lint
- PR 전 반드시 npm run build 성공 확인

# 금지 패턴

- any 타입 사용 금지
- console.log 사용 금지 (logger 사용)
- 하드코딩된 문자열 금지 (상수 파일 사용)

# 디렉토리 구조

src/
app/ - Next.js App Router 페이지
components/ - 재사용 가능한 컴포넌트
lib/ - 유틸리티, 헬퍼 함수
types/ - TypeScript 타입 정의
hooks/ - 커스텀 React 훅

# 파일별 규칙

- /src/api/ 아래 파일 수정 시: 반드시 API 문서도 함께 업데이트
- /src/components/ 아래 파일 수정 시: Storybook 스토리도 업데이트
- 데이터베이스 스키마 변경 시: 마이그레이션 파일 자동 생성

# 작업 순서

1. 먼저 관련 코드를 탐색하고 이해
2. 구현 계획을 설명
3. 변경 사항 구현
4. 테스트 실행 및 확인
5. 관련 문서 업데이트

# CLAUDE.md 내용을 대화 중에 추가
claude /add-memory "API 응답은 항상 snake_case를 사용합니다"

# 현재 적용된 메모리 확인
claude /memory

# 프로젝트 초기화 시 CLAUDE.md 자동 생성
claude /init

> 이 프로젝트의 인증 시스템 구조를 분석해줘

Claude Code가 수행하는 작업:
- 프로젝트 디렉토리 구조 스캔
- auth 관련 파일 검색 (grep, glob)
- 의존성 분석 (package.json, import 추적)
- 설정 파일 확인

> JWT 토큰 갱신 로직에 리프레시 토큰 로테이션을 추가하고 싶어

Claude Code가 수행하는 작업:
- 현재 토큰 갱신 로직 분석
- 변경이 필요한 파일 목록 제시
- 구현 계획 설명
- 예상 영향 범위 분석

> 변경 사항을 테스트하고 확인해줘

Claude Code가 수행하는 작업:
- npm test 실행
- 린트 체크
- 타입 체크
- 빌드 확인

# 에러 로그를 파이프로 전달
cat error.log | claude "이 에러를 분석하고 수정해줘"

# Claude Code의 작업 흐름:
# 1. 에러 메시지 분석
# 2. 관련 소스 코드 검색
# 3. 원인 파악
# 4. 수정 코드 작성
# 5. 테스트 실행으로 수정 확인

> 사용자 프로필 페이지에 활동 히스토리 타임라인을 추가해줘.
> 최근 30일간의 활동을 시간순으로 보여주고,
> 무한 스크롤로 이전 활동을 로드할 수 있게 해줘.

Claude Code의 작업:
1. 기존 프로필 페이지 코드 분석
2. 활동 데이터 API 엔드포인트 확인/생성
3. 타임라인 컴포넌트 구현
4. 무한 스크롤 로직 구현
5. 스타일링
6. 테스트 작성 및 실행

# 현재 변경사항으로 커밋 생성
claude commit

# PR 생성
claude "현재 브랜치의 변경사항으로 PR을 만들어줘"

# 코드 리뷰
claude "PR #42의 변경사항을 리뷰해줘"

# merge conflict 해결
claude "현재 merge conflict를 해결해줘"

메인 에이전트 (오케스트레이터)
├── 서브에이전트 1: API 엔드포인트 구현
├── 서브에이전트 2: 프론트엔드 컴포넌트 작성
├── 서브에이전트 3: 데이터베이스 마이그레이션
└── 서브에이전트 4: 테스트 코드 작성

> 프로젝트 전체에서 클래스 컴포넌트를 함수형 컴포넌트로 변환해줘

메인 에이전트의 작업:
1. 클래스 컴포넌트를 사용하는 모든 파일 검색
2. 파일을 그룹으로 분할
3. 각 그룹을 서브에이전트에 할당
4. 서브에이전트들이 병렬로 변환 수행
5. 결과 통합 및 테스트

> 이 프로젝트의 보안 취약점을 분석해줘

서브에이전트 1: 인증/인가 코드 분석
서브에이전트 2: SQL 인젝션 가능성 검사
서브에이전트 3: XSS 취약점 검사
서브에이전트 4: 의존성 보안 감사

> 사용자 관리 CRUD API를 만들어줘

서브에이전트 1: API 라우트 및 컨트롤러 생성
서브에이전트 2: 데이터 모델 및 마이그레이션 생성
서브에이전트 3: 통합 테스트 작성
서브에이전트 4: API 문서 생성

# 백그라운드 에이전트 시작
claude --background "테스트 커버리지를 80% 이상으로 올려줘"

# 백그라운드 에이전트 상태 확인
claude --list-backgrounds

# 결과 확인
claude --resume <session-id>

# 워크트리 생성 후 독립적인 작업 수행
claude "워크트리를 만들어서 feature-auth 브랜치에서 인증 모듈을 리팩터링해줘"

# 메인 브랜치에서는 다른 작업 계속
claude "버그 수정을 계속 진행해줘"

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit",
        "command": "cp \"$CLAUDE_FILE_PATH\" \"$CLAUDE_FILE_PATH.bak\" 2>/dev/null || true"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
      },
      {
        "matcher": "Write",
        "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\""
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "command": "terminal-notifier -message \"$CLAUDE_NOTIFICATION\" -title \"Claude Code\""
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "command": "npm test 2>&1 | tail -20"
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "if [[ \"$CLAUDE_FILE_PATH\" == *.ts ]]; then npx jest --findRelatedTests \"$CLAUDE_FILE_PATH\" --passWithNoTests; fi"
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" && npx eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "if echo \"$CLAUDE_COMMAND\" | grep -qE 'rm -rf|DROP TABLE|DELETE FROM'; then echo 'BLOCKED: 위험한 명령어가 감지되었습니다' && exit 1; fi"
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "echo \"$(date): $CLAUDE_FILE_PATH modified\" >> .claude/change.log"
      }
    ]
  }
}

# 훅 실행 로그 확인
claude --verbose

# 특정 훅 비활성화
claude config set hooks.PostToolUse.enabled false

# 훅 건너뛰기 (일시적)
claude --no-hooks

import { AgentSDK } from '@anthropic-ai/claude-code-sdk'

const agent = new AgentSDK({
  model: 'claude-sonnet-4-20250514',
  permissions: {
    fileRead: true,
    fileWrite: true,
    commandExec: ['npm test', 'npm run lint'],
  },
})

import { AgentSDK } from '@anthropic-ai/claude-code-sdk'

async function createCodeReviewAgent() {
  const agent = new AgentSDK({
    model: 'claude-sonnet-4-20250514',
    systemPrompt: `당신은 시니어 코드 리뷰어입니다.
    다음 관점에서 코드를 검토합니다:
    1. 보안 취약점
    2. 성능 이슈
    3. 코딩 컨벤션 준수
    4. 테스트 커버리지`,
    permissions: {
      fileRead: true,
      fileWrite: false,
      commandExec: ['git diff'],
    },
  })

  const session = await agent.createSession()
  const result = await session.send('현재 PR의 변경사항을 리뷰해주세요')

  console.log(result.response)
  console.log('발견된 이슈:', result.issues)
}

async function createDocAgent() {
  const agent = new AgentSDK({
    model: 'claude-sonnet-4-20250514',
    systemPrompt: `함수와 모듈의 JSDoc/TSDoc 문서를 자동으로 생성합니다.
    기존 문서가 있으면 업데이트하고, 없으면 새로 생성합니다.`,
    permissions: {
      fileRead: true,
      fileWrite: true,
      commandExec: ['npm run build'],
    },
  })

  const session = await agent.createSession()
  await session.send('src/lib/ 디렉토리의 모든 export 함수에 문서를 추가해주세요')
}

async function createMigrationAgent() {
  const agent = new AgentSDK({
    model: 'claude-sonnet-4-20250514',
    systemPrompt: `Prisma 마이그레이션을 관리하는 전문 에이전트입니다.
    스키마 변경을 분석하고, 안전한 마이그레이션을 생성합니다.`,
    permissions: {
      fileRead: true,
      fileWrite: true,
      commandExec: ['npx prisma migrate dev', 'npx prisma generate', 'npx prisma db push'],
    },
  })

  const session = await agent.createSession()
  await session.send('User 모델에 profileImage 필드를 추가하는 마이그레이션을 만들어주세요')
}

const session = await agent.createSession()

session.on('toolUse', (event) => {
  console.log(`도구 사용: ${event.tool} - ${event.description}`)
})

session.on('fileChange', (event) => {
  console.log(`파일 변경: ${event.path} - ${event.type}`)
})

session.on('commandExec', (event) => {
  console.log(`명령어 실행: ${event.command}`)
  console.log(`결과: ${event.output}`)
})

session.on('error', (event) => {
  console.error(`에러 발생: ${event.message}`)
})

const agent = new AgentSDK({
  permissions: {
    // 파일 접근 제어
    fileRead: true,
    fileWrite: true,
    fileGlob: ['src/**/*.ts', 'tests/**/*.ts'], // 허용 패턴
    fileExclude: ['*.env', 'secrets/**'], // 차단 패턴

    // 명령어 실행 제어
    commandExec: ['npm test', 'npm run lint', 'npx prisma migrate dev'],

    // 네트워크 접근 제어
    networkAccess: false,

    // MCP 서버 접근
    mcpServers: ['filesystem', 'database'],
  },
})

Claude Code <--MCP--> 데이터베이스 서버
Claude Code <--MCP--> GitHub API
Claude Code <--MCP--> Slack API
Claude Code <--MCP--> 파일 시스템
Claude Code <--MCP--> 커스텀 API

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_TOKEN": "xoxb-xxxxxxxxxxxx"
      }
    }
  }
}

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'

const server = new McpServer({
  name: 'my-internal-api',
  version: '1.0.0',
})

// 도구 정의
server.tool(
  'getDeployStatus',
  'Get deployment status',
  {
    environment: { type: 'string', enum: ['staging', 'production'] },
  },
  async (params) => {
    const status = await fetchDeployStatus(params.environment)
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(status, null, 2),
        },
      ],
    }
  }
)

server.tool(
  'triggerDeploy',
  'Trigger a deployment',
  {
    environment: { type: 'string' },
    version: { type: 'string' },
  },
  async (params) => {
    const result = await triggerDeploy(params.environment, params.version)
    return {
      content: [
        {
          type: 'text',
          text: `Deployment triggered: ${result.id}`,
        },
      ],
    }
  }
)

// 서버 시작
const transport = new StdioServerTransport()
await server.connect(transport)

> users 테이블의 스키마를 확인하고, 새로운 API 엔드포인트를 만들어줘

Claude Code의 작업:
1. MCP postgres 서버로 스키마 조회
2. 기존 API 패턴 분석
3. 새 엔드포인트 코드 생성
4. 마이그레이션 파일 생성
5. 테스트 작성

> 최근 열린 이슈 중 bug 라벨이 있는 것을 확인하고,
> 가장 우선순위가 높은 것을 수정해줘

Claude Code의 작업:
1. MCP github 서버로 이슈 목록 조회
2. 우선순위 분석
3. 관련 코드 탐색 및 수정
4. PR 생성

# 모노레포 환경에서
claude "packages/shared 라이브러리의 변경이 packages/web과 packages/api에
미치는 영향을 분석하고, 필요한 업데이트를 모두 수행해줘"

# 여러 기능을 동시에 개발
claude "워크트리를 만들어서 다음 작업들을 병렬로 수행해줘:
1. feature/auth - 인증 모듈 리팩터링
2. feature/dashboard - 대시보드 성능 최적화
3. fix/memory-leak - 메모리 누수 수정"

# 매일 아침 코드 품질 리포트 생성
claude schedule --cron "0 9 * * *" "코드 품질 리포트를 생성하고 Slack에 공유해줘"

# 매주 월요일 의존성 업데이트 확인
claude schedule --cron "0 10 * * 1" "npm outdated를 확인하고 안전한 업데이트를 적용해줘"

# GitHub Actions 예시
name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Claude Code Review
        run: |
          npx @anthropic-ai/claude-code -p \
            "이 PR의 변경사항을 리뷰하고 코멘트를 남겨줘" \
            --yes --output-format json
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

# .claudeignore 예시
node_modules/
dist/
.next/
coverage/
*.lock
*.log

/help          # 도움말
/clear         # 대화 초기화
/compact       # 대화 내용 압축
/memory        # 메모리(CLAUDE.md) 확인
/add-memory    # 메모리에 규칙 추가
/model         # 모델 변경
/cost          # 현재 세션 비용 확인
/diff          # 현재 변경사항 확인
/undo          # 마지막 변경 되돌리기
/review        # 코드 리뷰 요청
/init          # 프로젝트 초기화
/bug           # 버그 리포트
/config        # 설정 변경

# 대화 중 메모리 추가
/add-memory "이 프로젝트에서 API 응답은 항상 camelCase를 사용합니다"
/add-memory "테스트 파일은 __tests__ 디렉토리에 위치합니다"
/add-memory "Prisma 마이그레이션 후 항상 npx prisma generate를 실행합니다"

로그인 기능 만들어줘

NextAuth.js를 사용하여 Google OAuth 로그인 기능을 추가해줘.
- /app/api/auth/[...nextauth]/route.ts 에 설정
- Google Provider 사용
- 세션에 사용자 ID 포함
- 로그인/로그아웃 버튼 컴포넌트 생성
- 기존 Navbar 컴포넌트에 통합

# 상세 로그 모드
claude --verbose

# 도구 사용 로그
claude --debug-tools

# 세션 기록 내보내기
claude --export-session ./session-log.json

# 특정 모델로 전환하여 비교
claude --model claude-opus-4-20250514

# 현재 세션 비용 확인
/cost

# 경제적 모드 (Haiku 사용)
claude --model claude-haiku

# 자동 비용 알림 설정
claude config set cost.alert-threshold 5.00