1. 대규모 리팩토링     → "모든 class component를 function component로 변환해줘"
2. 코드베이스 탐색      → "인증 로직이 어디에 구현되어 있는지 분석해줘"
3. 버그 디버깅         → "이 에러 로그를 분석하고 원인을 찾아서 수정해줘"
4. 테스트 코드 생성     → "이 모듈의 unit test를 작성해줘"
5. Git 워크플로우       → "변경사항을 커밋하고 PR을 생성해줘"
6. 문서화              → "이 API의 JSDoc을 작성해줘"
7. CI/CD 자동화        → "GitHub Actions에서 코드 리뷰를 자동화해줘"

# macOS / Linux 네이티브 설치
curl -fsSL https://claude.ai/install.sh | bash

# npm 글로벌 설치
npm install -g @anthropic-ai/claude-code

# 설치 확인
claude --version

1. VS Code에서 Cmd+Shift+X (Mac) / Ctrl+Shift+X (Windows/Linux)
2. "Claude Code" 검색
3. Install 클릭

# 최초 실행 시 브라우저 OAuth 인증
claude

# 수동 로그인
claude auth login

# 환경 변수로 API 키 설정
export ANTHROPIC_API_KEY="sk-ant-api03-..."

# 또는 .env 파일에 저장
echo 'ANTHROPIC_API_KEY=sk-ant-api03-...' >> ~/.zshrc
source ~/.zshrc

# 모델 확인 및 변경
claude --model claude-sonnet-4-6
claude --model claude-opus-4-6
claude --model claude-haiku-3-5

# 대화 중 모델 변경
/model

# 버전 확인
claude --version

# 간단한 테스트
claude "Say hello"

# 환경 진단
claude doctor

# 대화형 모드 시작
claude

# 프로젝트 디렉토리에서 시작 (권장)
cd ~/my-project && claude

> 이 프로젝트의 구조를 분석해줘

> src/auth/login.ts 파일에서 JWT 검증 로직을 추가해줘

> package.json의 모든 의존성을 최신 버전으로 업데이트해줘

# 초기 프롬프트와 함께 시작
claude "src 디렉토리의 모든 TypeScript 파일에서 deprecated API 사용을 찾아줘"

# 특정 파일을 참조하며 질문
claude "이 파일의 성능 문제를 분석해줘" --file src/utils/parser.ts

# 비대화형 실행
claude -p "package.json의 의존성 목록을 정리해줘"

# stdin을 통한 파이프 입력
cat error.log | claude -p "이 에러 로그를 분석하고 해결 방법을 제안해줘"

# PR diff를 분석
git diff main...HEAD | claude -p "이 변경사항에서 보안 취약점을 검토해줘"

# 출력 형식 지정
claude -p "프로젝트 구조를 분석해줘" --output-format json

# CI/CD 파이프라인에서 사용
claude -p "코드 리뷰를 수행해줘" \
  --dangerously-skip-permissions \
  --output-format stream-json

# 세션 ID를 지정하여 연속 대화
claude -p "프로젝트 구조를 분석해줘" --session-id my-review

# 같은 세션에서 후속 질문
claude -p "아까 분석한 구조에서 개선할 점은?" \
  --session-id my-review --resume

/init

# 기본 압축
/compact

# 커스텀 지시와 함께 압축
/compact 인증 관련 맥락만 유지해줘

/model

/cost

/doctor

<!-- .claude/commands/review-security.md -->

다음 항목을 중점으로 보안 리뷰를 수행해줘:

1. SQL Injection 취약점
2. XSS 취약점
3. 인증/인가 우회 가능성
4. 민감 정보 노출
5. CSRF 취약점

변경된 파일만 대상으로 분석하고, 각 항목별로 심각도(High/Medium/Low)를 표시해줘.

Read 도구는 절대 경로를 사용하여 파일을 읽는다.
- 텍스트 파일: 줄 번호와 함께 내용 표시
- 이미지 (PNG, JPG): 멀티모달 분석
- PDF: 특정 페이지 범위 지정 가능 (pages: "1-5")
- Jupyter 노트북: 모든 셀과 출력 표시
- 대용량 파일: offset과 limit으로 부분 읽기

작업 흐름:
1. Read로 파일 내용 확인
2. old_string(기존 내용)과 new_string(새 내용) 지정
3. old_string이 파일 내에서 유일한지 확인
4. 유일하지 않으면 더 많은 주변 컨텍스트를 포함하여 재시도

# Bash 도구로 실행 가능한 작업 예시
npm install express
git status
docker compose up -d
python manage.py migrate
kubectl get pods

Glob 예시:
- **/*.ts         → 모든 TypeScript 파일
- src/**/test.*   → src 하위의 모든 테스트 파일
- *.{js,jsx,ts,tsx} → 모든 JavaScript/TypeScript 파일

Grep 예시:
- "TODO|FIXME"              → 모든 TODO/FIXME 코멘트
- "function\s+\w+"          → 함수 선언 검색
- "import.*from\s+'react'"  → React import 검색

자동 승인: Read, Glob, Grep, WebSearch, WebFetch
확인 필요: Edit, Write, Bash, NotebookEdit

자동 승인: Read, Glob, Grep, WebSearch, WebFetch
차단:      Edit, Write, Bash (모든 쓰기 작업)

# Auto-accept 모드로 실행
claude --auto-accept-edits

# CI/CD 전용 — 절대 로컬에서 사용하지 말 것
claude --dangerously-skip-permissions

{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "MultiEdit",
      "Write",
      "Glob",
      "Grep",
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Bash(wget *)",
      "WebFetch(domain:internal.company.com)"
    ]
  }
}

# 샌드박스 비활성화 (신뢰할 수 있는 환경에서만)
claude --dangerously-disable-sandbox

~/.claude/CLAUDE.md                 → 글로벌 (모든 프로젝트에 적용)
~/project/CLAUDE.md                 → 프로젝트 루트
~/project/src/CLAUDE.md             → 하위 디렉토리
~/project/src/components/CLAUDE.md  → 더 세부적인 디렉토리

> 이 프로젝트에서 테스트는 항상 vitest를 사용한다는 것을 기억해줘

✓ 기억에 저장되었습니다.

# 프로젝트 개요

Next.js 14 App Router 기반 기술 블로그. MDX 기반 콘텐츠 관리.

# 기술 스택

- Framework: Next.js 14 (App Router)
- Language: TypeScript 5.3
- Styling: Tailwind CSS v3
- DB: Prisma + PostgreSQL
- Test: Vitest + React Testing Library

# 빌드 및 실행 명령어

- `npm run dev` — 개발 서버
- `npm run build` — 프로덕션 빌드
- `npm run test` — 테스트 실행
- `npm run lint` — ESLint 실행

# 코딩 컨벤션

- 함수 컴포넌트만 사용 (class component 금지)
- named export 우선 (default export는 페이지에서만)
- 에러 처리는 반드시 try-catch로 감싸기
- 변수명은 camelCase, 타입명은 PascalCase
- import 순서: react → 외부 라이브러리 → 내부 모듈 → 스타일

# 아키텍처

- app/ — Next.js App Router 페이지
- components/ — 재사용 컴포넌트
- lib/ — 유틸리티 및 헬퍼
- prisma/ — DB 스키마 및 마이그레이션

# 주의사항

- API Route에서 인증 미들웨어를 항상 적용할 것
- DB 쿼리 시 Prisma의 select를 사용하여 필요한 필드만 가져올 것
- 환경변수는 .env.local에만 저장 (절대 커밋 금지)

# HTTP 원격 서버 추가
claude mcp add circleback --transport http https://app.circleback.ai/api/mcp

# stdio 로컬 서버 추가
claude mcp add my-tool --type stdio --command node /path/to/tool.js

# 환경 변수와 함께 추가
claude mcp add github-mcp \
  --type stdio \
  --command npx \
  --args "-y @modelcontextprotocol/server-github" \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx

# 서버 목록 확인
claude mcp list

# 서버 제거
claude mcp remove my-tool

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/docs"]
    }
  }
}

# Claude Code를 MCP 서버로 실행
claude mcp serve

# MCP 디버그 모드로 문제 진단
claude --mcp-debug

> 다음 3개 모듈의 테스트 코드를 병렬로 작성해줘:
  1. src/auth/login.ts
  2. src/api/users.ts
  3. src/utils/validator.ts

## <!-- .claude/agents/security-reviewer.md -->

name: Security Reviewer
description: 보안 취약점을 전문적으로 검토하는 에이전트
tools:

- Read
- Grep
- Glob
- WebSearch

---

당신은 보안 전문가입니다. 코드를 검토할 때 다음 관점에서 분석하세요:

1. OWASP Top 10 취약점
2. 인증/인가 결함
3. 데이터 유출 위험
4. 안전하지 않은 의존성

각 발견에 대해 심각도(Critical/High/Medium/Low)와 수정 제안을 포함하세요.

사용자 요청
    ↓
메인 Claude (오케스트레이터)
    ↓
┌─────────────┬─────────────┬─────────────┐
│ Task 1      │ Task 2      │ Task 3      │
│ Security    │ Performance │ Test        │
│ Reviewer    │ Analyzer    │ Generator   │
└─────────────┴─────────────┴─────────────┘
    ↓                ↓             ↓
결과 수집 및 종합
    ↓
최종 응답

적합한 시나리오:
- 여러 파일의 테스트 코드 생성
- 여러 모듈의 코드 리뷰
- 여러 API 엔드포인트의 문서화
- 다국어 번역

적합한 시나리오:
- 분석 → 설계 → 구현 → 테스트 파이프라인
- DB 스키마 변경 → 마이그레이션 → API 수정 → 테스트

# Worktree를 생성하여 격리된 환경에서 작업
claude --worktree feature-auth

1. VS Code 마켓플레이스에서 "Claude Code" 설치
2. 터미널에 Claude Code CLI가 이미 설치되어 있어야 함
3. 설치 후 사이드바에 Claude 아이콘이 표시됨
4. 클릭하여 채팅 패널 열기

Cmd+Shift+P (Mac) / Ctrl+Shift+P (Windows)
  → "Claude Code" 입력하여 사용 가능한 명령 확인

주요 단축키:
- Claude Code 패널 열기/닫기
- 선택 영역을 Claude에게 보내기
- 현재 파일 컨텍스트로 Claude 시작

1. JetBrains Marketplace에서 "Claude Code [Beta]" 검색
2. Install 클릭
3. IDE 재시작

/hooks
→ 이벤트 선택 (예: PostToolUse)
→ 매처 패턴 (예: Edit|Write)
→ 명령어 (예: npx prettier --write $FILE)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx prettier --write $(echo $TOOL_INPUT | jq -r '.file_path')"
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "echo $TOOL_INPUT | jq -r '.command' | grep -q 'rm -rf /' && exit 1 || exit 0"
      }
    ]
  }
}

stdin:     이벤트별 JSON 데이터 (파일 경로, 도구 입력 등)
stdout:    Claude에게 전달할 메시지
stderr:    로깅 (Claude에게 전달되지 않음)
exit code: 0 = 성공/계속, 1 = 차단/중단, 2 = 에러

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "FILE=$(echo $TOOL_INPUT | jq -r '.file_path') && npx prettier --write \"$FILE\" 2>/dev/null || true"
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "CMD=$(echo $TOOL_INPUT | jq -r '.command') && echo \"$CMD\" | grep -qE '(rm -rf /|DROP TABLE|format c:)' && echo 'BLOCKED: Dangerous command detected' && exit 1 || exit 0"
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "FILE=$(echo $TOOL_INPUT | jq -r '.file_path') && [[ \"$FILE\" =~ \\.(ts|tsx|js|jsx)$ ]] && npx eslint --fix \"$FILE\" 2>/dev/null || true"
      }
    ]
  }
}

> 현재 변경사항을 커밋해줘

> auth/ 디렉토리의 변경사항만 커밋해줘
> 테스트 파일은 제외하고 커밋해줘
> 보안 관련 변경만 별도 커밋으로 분리해줘

> 현재 변경사항으로 PR을 생성해줘

## Summary

- 인증 모듈에 JWT 리프레시 토큰 로직을 추가
- 토큰 만료 시 자동 갱신 처리 구현

## Test plan

- [ ] 리프레시 토큰 발급 테스트
- [ ] 만료된 토큰 갱신 테스트
- [ ] 잘못된 리프레시 토큰 거부 테스트

> 현재 변경사항을 리뷰해줘
> 이 PR의 보안 관점 리뷰를 수행해줘

# .github/workflows/claude-review.yml
name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]
  issue_comment:
    types: [created]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          # PR 코멘트에서 @claude 멘션 시 자동 응답
          trigger_phrase: '@claude'

# Claude Code 내에서 GitHub App 자동 설치
/install-github-app

Step 1: 분석
> 이 프로젝트에서 class component를 사용하는 모든 파일을 찾아줘

Step 2: 계획
> 이 컴포넌트들을 function component로 변환하는 계획을 세워줘.
  변환 순서, 의존성, 위험 요소를 포함해서.

Step 3: 실행 (Auto-accept 모드 권장)
> 계획대로 src/components/Header.tsx부터 변환을 시작해줘

Step 4: 검증
> 변환된 파일들의 테스트를 실행하고 결과를 알려줘

> 다음 3개 모듈을 병렬로 리팩토링해줘:
  1. src/auth/ — class → function component
  2. src/api/ — callback → async/await
  3. src/utils/ — CommonJS → ES Module
  각각의 테스트도 함께 수정해줘.

> src/utils/validator.ts의 모든 함수에 대한 unit test를 작성해줘.
  edge case와 에러 케이스도 포함해줘.

> src/api/users.ts의 통합 테스트를 작성해줘.
  - Vitest + Supertest 사용
  - 테스트 DB는 SQLite in-memory
  - 각 테스트 전후로 DB 초기화
  - 인증/비인증 경우 모두 테스트
  - 에러 응답 형식도 검증

> npm run test -- --coverage 결과를 분석하고,
  커버리지가 80% 미만인 파일들의 테스트를 보강해줘.

# 에러 로그를 직접 파이프
npm run build 2>&1 | claude -p "이 빌드 에러를 분석하고 수정해줘"

# 스택 트레이스 분석
cat crash.log | claude -p "이 크래시의 근본 원인을 찾아줘"

> TypeError: Cannot read properties of undefined (reading 'map')
  이 에러가 src/components/UserList.tsx에서 발생해.
  원인을 찾고 수정해줘.

> 이 API 엔드포인트의 응답 시간이 3초 이상이야.
  코드를 분석하고 성능 개선 방안을 제안해줘.
  특히 N+1 쿼리, 불필요한 반복, 캐싱 가능 지점을 중심으로.

> src/lib/ 디렉토리의 모든 public 함수에 JSDoc을 작성해줘.
  파라미터 타입, 반환값, 예시를 포함해줘.

> src/api/ 디렉토리의 모든 REST 엔드포인트를
  OpenAPI 3.0 스펙으로 문서화해줘.

> 최근 10개 커밋을 분석하여 CHANGELOG 항목을 작성해줘.
  Keep a Changelog 형식을 사용해줘.

일상 코딩:        Cursor (인라인 완성) + Claude Code (복잡한 작업)
코드 리뷰:        Claude Code (GitHub Actions 자동 리뷰)
리팩토링:         Claude Code (터미널에서 대규모 작업)
빠른 프로토타입:   Cursor (GUI로 빠른 반복)
CI/CD 자동화:     Claude Code (헤드리스 모드)

단순 작업 (파일 검색, 간단한 수정):  Haiku  → 비용 75% 절약
일반 작업 (코딩, 디버깅):            Sonnet → 기본값
복잡한 작업 (아키텍처, 리팩토링):    Opus   → 필요할 때만

# 세션 비용 확인
/cost

# 대화 압축
/compact

# 압축 후 비용 확인 — 보통 40-60% 토큰 절약
/cost

❌ "이 코드를 개선해줘"
✅ "src/api/users.ts의 getUserById 함수에서 N+1 쿼리를 Prisma include로 최적화해줘"

월 50M 토큰 미만:     Pro ($20) 또는 API pay-as-you-go
월 50-200M 토큰:      Max 5x ($100) — 가장 효율적
월 200M 토큰 이상:    Max 20x ($200) 또는 Enterprise

# PATH 확인
which claude

# npm 글로벌 경로 확인
npm list -g --depth=0

# 재설치
npm install -g @anthropic-ai/claude-code

# 네이티브 재설치
curl -fsSL https://claude.ai/install.sh | bash

# 셸 재시작
exec zsh  # 또는 exec bash

# 로그아웃 후 재인증
claude auth logout
claude auth login

# API 키 사용 시 환경변수 확인
echo $ANTHROPIC_API_KEY

# API 키 유효성 테스트
claude "Hello" --verbose

# Node.js 버전 확인
node --version

# v18 미만이면 업데이트
nvm install 18
nvm use 18

# 또는 네이티브 설치로 전환 (Node.js 의존성 없음)
curl -fsSL https://claude.ai/install.sh | bash

# MCP 디버그 모드로 진단
claude --mcp-debug

# MCP 서버 목록 확인
claude mcp list

# 특정 서버 로그 확인
claude mcp logs my-server

# 서버 재시작
claude mcp remove my-server
claude mcp add my-server --type stdio --command node /path/to/server.js

# 증상: 응답 품질 저하, 이전 맥락 망각

# 해결 1: 대화 압축
/compact

# 해결 2: 새 세션 시작
/clear

# 해결 3: Task tool로 작업 분할 (각 Task는 독립 컨텍스트)
> 이 작업을 3개의 하위 작업으로 분할해서 처리해줘

# 모델 변경 (Opus → Sonnet → Haiku)
/model

# 불필요한 MCP 서버 제거
claude mcp list
claude mcp remove unused-server

# 캐시 초기화
claude cache clear

# 1. 설치 상태 확인
claude --version

# 2. 환경 자동 진단
claude doctor

# 3. 상세 로그 출력
claude --verbose "테스트"

# 4. MCP 서버 진단
claude --mcp-debug

# 5. 설정 파일 확인
cat ~/.claude/settings.json

# 6. 네트워크 확인
curl -I https://api.anthropic.com

npm install @anthropic-ai/claude-agent-sdk

import { query } from '@anthropic-ai/claude-agent-sdk'

// 기본 쿼리
const response = await query({
  prompt: 'src/auth 디렉토리의 보안 취약점을 분석해줘',
  model: 'claude-sonnet-4-6',
  maxTokens: 4096,
})

for await (const message of response) {
  console.log(message)
}

import { query } from '@anthropic-ai/claude-agent-sdk'

async function reviewPR(diff: string): Promise<string> {
  const response = await query({
    prompt: `다음 PR diff를 리뷰해줘:\n${diff}`,
    model: 'claude-sonnet-4-6',
    systemPrompt:
      '당신은 시니어 소프트웨어 엔지니어입니다. 보안, 성능, 코드 품질 관점에서 리뷰하세요.',
    permissions: { allowRead: true, allowWrite: false, allowBash: false },
  })

  let result = ''
  for await (const message of response) {
    result += message.content
  }
  return result
}