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

# Basic Claude Code execution
claude

# Run with a specific prompt
claude "Analyze the architecture of this project"

# Pipeline mode
cat error.log | claude "Analyze this error and fix it"

# Requires Node.js 18 or higher
npm install -g @anthropic-ai/claude-code

# Or run with npx in a specific directory
npx @anthropic-ai/claude-code

# Authentication process starts on first run
claude

# Authenticate with Anthropic account or API key
# Browser opens to complete authentication

# Install the VS Code extension
code --install-extension anthropic.claude-code

# View configuration
claude config list

# Set model (default: claude-sonnet-4-20250514)
claude config set model claude-sonnet-4-20250514

# Permission settings
claude config set permissions.allow-edit true
claude config set permissions.allow-exec true

# Auto-approve patterns
claude config set permissions.auto-approve-commands "npm test,npm run lint"

# Run Claude Code in tmux session (useful for long tasks)
tmux new-session -s claude
claude

# Save work logs
claude --output-dir ./claude-logs

# Non-interactive mode (for scripts)
claude -p "Update the README.md" --yes

# Project Overview

This project is a blog platform built on Next.js 14.
Uses TypeScript with Tailwind CSS for styling.

# Tech Stack

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

# Coding Conventions

- Components: Functional components with arrow functions
- Naming: camelCase (variables/functions), PascalCase (components/types)
- Import order: External libraries > Internal modules > Relative paths
- Error handling: Use Result type pattern instead of try-catch

# Testing Rules

- Unit tests required for all new functions
- Test command: npm test
- Lint command: npm run lint
- Ensure npm run build passes before PR

# Prohibited Patterns

- No use of any type
- No console.log (use logger)
- No hardcoded strings (use constants file)

# Directory Structure

src/
app/ - Next.js App Router pages
components/ - Reusable components
lib/ - Utilities, helper functions
types/ - TypeScript type definitions
hooks/ - Custom React hooks

# File-Specific Rules

- When modifying files under /src/api/: Always update API docs as well
- When modifying files under /src/components/: Update Storybook stories
- When changing database schema: Auto-generate migration files

# Work Order

1. First explore and understand relevant code
2. Explain implementation plan
3. Implement changes
4. Run and verify tests
5. Update related documentation

# Add to CLAUDE.md during a conversation
claude /add-memory "API responses always use snake_case"

# Check currently applied memory
claude /memory

# Auto-generate CLAUDE.md during project initialization
claude /init

> Analyze the authentication system architecture of this project

What Claude Code does:
- Scans project directory structure
- Searches auth-related files (grep, glob)
- Analyzes dependencies (package.json, import tracing)
- Checks configuration files

> I want to add refresh token rotation to the JWT token renewal logic

What Claude Code does:
- Analyzes current token renewal logic
- Lists files that need changes
- Explains implementation plan
- Analyzes expected impact scope

> Test and verify the changes

What Claude Code does:
- Runs npm test
- Lint check
- Type check
- Build verification

# Pipe error log to Claude Code
cat error.log | claude "Analyze this error and fix it"

# Claude Code's workflow:
# 1. Analyze error message
# 2. Search related source code
# 3. Identify root cause
# 4. Write fix
# 5. Run tests to confirm fix

> Add an activity history timeline to the user profile page.
> Show the last 30 days of activity in chronological order,
> with infinite scroll to load older activities.

Claude Code's work:
1. Analyze existing profile page code
2. Check/create activity data API endpoint
3. Implement timeline component
4. Implement infinite scroll logic
5. Apply styling
6. Write and run tests

# Create a commit from current changes
claude commit

# Create a PR
claude "Create a PR from the changes on the current branch"

# Code review
claude "Review the changes in PR #42"

# Resolve merge conflicts
claude "Resolve the current merge conflicts"

Main Agent (Orchestrator)
├── Subagent 1: Implement API endpoints
├── Subagent 2: Write frontend components
├── Subagent 3: Database migration
└── Subagent 4: Write test code

> Convert all class components to functional components across the project

Main agent's work:
1. Search all files using class components
2. Divide files into groups
3. Assign each group to a subagent
4. Subagents perform conversion in parallel
5. Integrate results and run tests

> Analyze security vulnerabilities in this project

Subagent 1: Analyze authentication/authorization code
Subagent 2: Check SQL injection possibilities
Subagent 3: Check XSS vulnerabilities
Subagent 4: Dependency security audit

> Create a user management CRUD API

Subagent 1: Generate API routes and controllers
Subagent 2: Generate data models and migrations
Subagent 3: Write integration tests
Subagent 4: Generate API documentation

# Start background agent
claude --background "Increase test coverage to above 80%"

# Check background agent status
claude --list-backgrounds

# Review results
claude --resume <session-id>

# Create worktree and perform independent work
claude "Create a worktree and refactor the auth module on the feature-auth branch"

# Continue other work on main branch
claude "Continue with the bug fix"

{
  "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: Dangerous command detected' && exit 1; fi"
      }
    ]
  }
}

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

# View hook execution logs
claude --verbose

# Disable a specific hook
claude config set hooks.PostToolUse.enabled false

# Skip hooks (temporarily)
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: `You are a senior code reviewer.
    Review code from these perspectives:
    1. Security vulnerabilities
    2. Performance issues
    3. Coding convention compliance
    4. Test coverage`,
    permissions: {
      fileRead: true,
      fileWrite: false,
      commandExec: ['git diff'],
    },
  })

  const session = await agent.createSession()
  const result = await session.send('Review the changes in the current PR')

  console.log(result.response)
  console.log('Issues found:', result.issues)
}

async function createDocAgent() {
  const agent = new AgentSDK({
    model: 'claude-sonnet-4-20250514',
    systemPrompt: `Automatically generate JSDoc/TSDoc documentation for functions and modules.
    Update existing docs or create new ones where missing.`,
    permissions: {
      fileRead: true,
      fileWrite: true,
      commandExec: ['npm run build'],
    },
  })

  const session = await agent.createSession()
  await session.send('Add documentation to all exported functions in the src/lib/ directory')
}

async function createMigrationAgent() {
  const agent = new AgentSDK({
    model: 'claude-sonnet-4-20250514',
    systemPrompt: `A specialized agent for managing Prisma migrations.
    Analyzes schema changes and generates safe migrations.`,
    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('Create a migration to add a profileImage field to the User model')
}

const session = await agent.createSession()

session.on('toolUse', (event) => {
  console.log(`Tool used: ${event.tool} - ${event.description}`)
})

session.on('fileChange', (event) => {
  console.log(`File changed: ${event.path} - ${event.type}`)
})

session.on('commandExec', (event) => {
  console.log(`Command executed: ${event.command}`)
  console.log(`Result: ${event.output}`)
})

session.on('error', (event) => {
  console.error(`Error occurred: ${event.message}`)
})

const agent = new AgentSDK({
  permissions: {
    // File access control
    fileRead: true,
    fileWrite: true,
    fileGlob: ['src/**/*.ts', 'tests/**/*.ts'], // Allowed patterns
    fileExclude: ['*.env', 'secrets/**'], // Blocked patterns

    // Command execution control
    commandExec: ['npm test', 'npm run lint', 'npx prisma migrate dev'],

    // Network access control
    networkAccess: false,

    // MCP server access
    mcpServers: ['filesystem', 'database'],
  },
})

Claude Code <--MCP--> Database Server
Claude Code <--MCP--> GitHub API
Claude Code <--MCP--> Slack API
Claude Code <--MCP--> File System
Claude Code <--MCP--> Custom 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',
})

// Define tools
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}`,
        },
      ],
    }
  }
)

// Start server
const transport = new StdioServerTransport()
await server.connect(transport)

> Check the users table schema and create a new API endpoint

Claude Code's work:
1. Query schema via MCP postgres server
2. Analyze existing API patterns
3. Generate new endpoint code
4. Generate migration file
5. Write tests

> Check recently opened issues with the bug label,
> and fix the highest priority one

Claude Code's work:
1. Query issue list via MCP github server
2. Analyze priorities
3. Explore and fix related code
4. Create PR

# In a monorepo environment
claude "Analyze the impact of changes to the packages/shared library on
packages/web and packages/api, and perform all necessary updates"

# Develop multiple features simultaneously
claude "Create worktrees and perform these tasks in parallel:
1. feature/auth - Refactor authentication module
2. feature/dashboard - Optimize dashboard performance
3. fix/memory-leak - Fix memory leak"

# Generate daily code quality report
claude schedule --cron "0 9 * * *" "Generate a code quality report and share it on Slack"

# Check dependency updates every Monday
claude schedule --cron "0 10 * * 1" "Check npm outdated and apply safe updates"

# GitHub Actions example
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 \
            "Review the changes in this PR and leave comments" \
            --yes --output-format json
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

# .claudeignore example
node_modules/
dist/
.next/
coverage/
*.lock
*.log

/help          # Help
/clear         # Clear conversation
/compact       # Compress conversation
/memory        # Check memory (CLAUDE.md)
/add-memory    # Add rule to memory
/model         # Change model
/cost          # Check current session cost
/diff          # View current changes
/undo          # Undo last change
/review        # Request code review
/init          # Initialize project
/bug           # Bug report
/config        # Change settings

# Add memory during conversation
/add-memory "API responses in this project always use camelCase"
/add-memory "Test files are located in __tests__ directories"
/add-memory "Always run npx prisma generate after Prisma migrations"

Make a login feature

Add Google OAuth login using NextAuth.js.
- Configure in /app/api/auth/[...nextauth]/route.ts
- Use Google Provider
- Include user ID in session
- Create login/logout button component
- Integrate into existing Navbar component

# Verbose logging mode
claude --verbose

# Tool usage logging
claude --debug-tools

# Export session history
claude --export-session ./session-log.json

# Switch to a specific model for comparison
claude --model claude-opus-4-20250514

# Check current session cost
/cost

# Economy mode (use Haiku)
claude --model claude-haiku

# Set automatic cost alerts
claude config set cost.alert-threshold 5.00