에이전트 사용법

# 에이전트 실행 기본 패턴

# 단일 에이전트 실행
claude task run explore "프로젝트의 인증 시스템 구조 분석"

# 병렬 에이전트 실행
claude task run \
  explore "API 엔드포인트 찾기" \
  plan "새로운 결제 기능 구현 계획" \
  --parallel

# 백그라운드 실행
claude task run security "보안 취약점 전체 스캔" --background

# 에이전트 체이닝
claude task run explore "사용자 모델 분석" | \
  claude task run plan "사용자 프로필 기능 추가"

# 주요 에이전트 유형

1. Explore 에이전트
   - 코드베이스 탐색 및 분석
   - 파일, 클래스, 함수 찾기
   - 아키텍처 이해

2. Plan 에이전트
   - 구현 계획 수립
   - 작업 분해 및 우선순위
   - 기술적 의사결정

3. Code Review 에이전트
   - 코드 품질 검토
   - 베스트 프랙티스 검증
   - 개선 제안

4. Security 에이전트
   - 보안 취약점 스캔
   - 의존성 검사
   - 보안 베스트 프랙티스

5. Performance 에이전트
   - 성능 병목 분석
   - 최적화 기회 발견
   - 리소스 사용 검토

6. Custom 에이전트
   - 사용자 정의 에이전트
   - 특정 도메인 전문화
   - 팀별 워크플로우

# 에이전트 상태 확인 및 관리

# 실행 중인 에이전트 목록
claude task list

# 특정 에이전트 상태
claude task status <task-id>

# 에이전트 로그 확인
claude task logs <task-id> --tail 50

# 에이전트 중지
claude task stop <task-id>

# 결과 조회
claude task output <task-id>

# Explore 에이전트 기본 사용

# 빠른 탐색 (quick)
claude task run explore \
  "인증 관련 코드 찾기" \
  --depth quick

# 중간 탐색 (medium) - 기본값
claude task run explore \
  "결제 시스템 구조 파악"

# 상세 탐색 (thorough)
claude task run explore \
  "데이터베이스 연결 및 쿼리 전체 분석" \
  --depth thorough

# 특정 디렉토리 범위 지정
claude task run explore \
  "API 라우팅 구조 분석" \
  --path "src/api"

# 실제 사용 예제

# 1. 새 프로젝트 온보딩
claude task run explore \
  "프로젝트 전체 구조와 주요 컴포넌트 파악" \
  --depth thorough

# 2. 특정 기능 찾기
claude task run explore \
  "사용자 프로필 편집 기능이 어디에 구현되어 있는지 찾기"

# 3. 버그 원인 조사
claude task run explore \
  "로그인 실패 관련 코드와 에러 처리 로직 찾기"

# 4. 리팩토링 대상 파악
claude task run explore \
  "중복된 유효성 검증 로직 찾기"

# 5. 의존성 추적
claude task run explore \
  "UserService를 사용하는 모든 컴포넌트 찾기"

# Explore 결과 예시

📊 탐색 결과 보고서

## 프로젝트 구조
src/
├── auth/          # 인증 시스템
│   ├── login.ts   # 로그인 로직
│   └── session.ts # 세션 관리
├── api/           # API 라우트
└── components/    # UI 컴포넌트

## 주요 발견사항

### 인증 시스템
- 위치: src/auth/
- 주요 파일:
  * login.ts (142 lines)
  * session.ts (89 lines)
  * middleware.ts (56 lines)
- 사용 기술: JWT, bcrypt
- 의존성: jsonwebtoken@9.0.0

### 관련 컴포넌트
1. LoginForm (src/components/LoginForm.tsx)
2. ProtectedRoute (src/components/ProtectedRoute.tsx)
3. AuthContext (src/contexts/AuthContext.tsx)

## 권장사항
- session.ts의 토큰 갱신 로직 개선 권장
- 에러 처리 일관성 부족

# Plan 에이전트 기본 사용

# 새 기능 계획
claude task run plan \
  "사용자 프로필 편집 기능 추가"

# 리팩토링 계획
claude task run plan \
  "인증 시스템을 JWT에서 OAuth2로 마이그레이션"

# 성능 개선 계획
claude task run plan \
  "API 응답 시간을 50% 개선하기 위한 최적화"

# 특정 제약사항 포함
claude task run plan \
  "결제 시스템 구현 (PCI-DSS 준수 필요)" \
  --constraints "보안 감사 통과, 기존 API 호환성 유지"

# Plan 결과 예시

📋 구현 계획: 사용자 프로필 편집 기능

## 1. 분석 결과

### 기존 아키텍처
- 프론트엔드: React + TypeScript
- 백엔드: Express.js + PostgreSQL
- 인증: JWT (src/auth/)
- 상태관리: Redux Toolkit

### 주요 파일
- src/models/User.ts (사용자 모델)
- src/api/users.ts (사용자 API)
- src/components/UserProfile.tsx (프로필 UI)

## 2. 구현 단계

### Phase 1: 백엔드 (우선순위: 높음)
- [ ] User 모델에 updateProfile 메서드 추가
- [ ] PUT /api/users/:id/profile 엔드포인트 생성
- [ ] 입력 검증 미들웨어 구현
- [ ] 프로필 이미지 업로드 처리 (multer)

### Phase 2: 프론트엔드 (우선순위: 높음)
- [ ] ProfileEditForm 컴포넌트 생성
- [ ] Redux slice: profileSlice 추가
- [ ] API 클라이언트 함수 구현
- [ ] 이미지 크롭/리사이즈 UI

### Phase 3: 테스트 & 문서 (우선순위: 중간)
- [ ] 단위 테스트 (Jest)
- [ ] E2E 테스트 (Playwright)
- [ ] API 문서 업데이트

## 3. 기술적 의사결정

### 이미지 업로드
- 옵션 A: AWS S3 (권장)
  - 장점: 확장성, CDN 통합
  - 단점: 비용
- 옵션 B: 로컬 스토리지
  - 장점: 단순, 무료
  - 단점: 확장성 제한

### 결정: AWS S3 사용
이유: 기존 프로젝트에서 이미 S3 사용 중

## 4. 예상 리스크

⚠️ 대용량 이미지 업로드 처리
→ 해결: 클라이언트 측 리사이징

⚠️ 동시 편집 충돌
→ 해결: Optimistic locking 구현

## 5. 권장 명령어

bash
# Bash 권한 필요 (이미지 처리 라이브러리 설치)
claude permission request bash "install dependencies"

# 계획 승인 및 실행

# 계획 검토
claude task output <plan-task-id>

# 계획 승인
claude plan approve <plan-task-id>

# 계획대로 구현 시작
claude implement from-plan <plan-task-id>

# 특정 단계만 실행
claude implement from-plan <plan-task-id> \
  --step "Phase 1"

# Code Review 에이전트 사용

# 특정 파일 리뷰
claude task run review src/components/UserForm.tsx

# 여러 파일 동시 리뷰
claude task run review "src/api/**/*.ts"

# Pull Request 전체 리뷰
claude task run review --pr 123

# 최근 커밋 리뷰
claude task run review --commits HEAD~5..HEAD

# 전체 프로젝트 리뷰 (백그라운드 권장)
claude task run review . --background

# 리뷰 옵션 커스터마이징

# 특정 측면만 리뷰
claude task run review src/auth/ \
  --focus security,performance

# 심각도 필터
claude task run review . \
  --severity critical,high

# 자동 수정 가능 항목 적용
claude task run review src/ \
  --auto-fix

# 팀 코딩 스타일 적용
claude task run review . \
  --style-guide .claude/style-guide.md

# 리뷰 리포트 생성
claude task run review . \
  --output review-report.md \
  --format markdown

# Review 결과 예시

📝 코드 리뷰 리포트

## 요약
- 총 파일: 12개
- Critical 이슈: 2개
- High 이슈: 5개
- Medium 이슈: 8개
- Low 이슈: 12개

## Critical Issues

### 1. SQL Injection 취약점
**파일:** src/api/users.ts:45
**심각도:** Critical

```typescript
// 문제 코드
db.query(`SELECT * FROM users WHERE id = ${userId}`)

// 수정 제안
db.query('SELECT * FROM users WHERE id = ?', [userId])
```

**이유:** 사용자 입력을 직접 쿼리에 삽입하면 SQL Injection 공격에 취약합니다.

### 2. 민감한 정보 로깅
**파일:** src/auth/login.ts:78
**심각도:** Critical

```typescript
// 문제 코드
console.log('User logged in:', { email, password })

// 수정 제안
logger.info('User logged in:', { email })
```

**이유:** 비밀번호를 로그에 남기면 보안 위험이 있습니다.

## High Issues

### 3. 에러 처리 누락
**파일:** src/utils/fetchData.ts:23
**심각도:** High

비동기 함수에 try-catch가 없어 예외 발생 시 앱이 크래시할 수 있습니다.

### 4. 메모리 누수 가능성
**파일:** src/components/Chart.tsx:56
**심각도:** High

useEffect cleanup 함수가 없어 이벤트 리스너가 제거되지 않습니다.

## 개선 제안

### 코드 품질
- [ ] 중복 코드 3곳 발견 → 공통 유틸 함수로 추출 권장
- [ ] 함수 복잡도가 높은 2개 함수 → 분리 권장

### 테스트
- [ ] 커버리지: 현재 68% → 80% 목표
- [ ] 에지 케이스 테스트 부족

### 성능
- [ ] 불필요한 re-render 3곳
- [ ] 효율적이지 않은 반복문 2곳

# Security 에이전트 기본 사용

# 전체 프로젝트 보안 스캔
claude task run security "전체 프로젝트 보안 감사" \
  --background

# 특정 디렉토리 스캔
claude task run security src/auth/ \
  --severity critical,high

# 의존성 취약점 검사
claude task run security \
  --check dependencies

# 민감 정보 노출 검사
claude task run security \
  --check secrets,credentials

# 웹 보안 취약점 검사 (XSS, CSRF, etc.)
claude task run security src/ \
  --check web-vulnerabilities

# 보안 스캔 결과 예시

🔒 보안 감사 리포트

## 요약
- Critical: 3개 🔴
- High: 7개 🟠
- Medium: 12개 🟡
- Low: 5개 ⚪

## Critical Vulnerabilities

### 1. SQL Injection (CWE-89)
**위치:** src/api/users.ts:67
**심각도:** Critical
**CVSS 점수:** 9.8

```typescript
// 취약한 코드
const query = `SELECT * FROM users WHERE email = '${email}'`;
db.query(query);

// 안전한 수정
const query = 'SELECT * FROM users WHERE email = ?';
db.query(query, [email]);
```

**영향:** 공격자가 임의의 SQL 명령을 실행할 수 있습니다.
**권장 조치:** Parameterized queries 사용

### 2. 하드코딩된 인증 정보
**위치:** src/config/database.ts:12
**심각도:** Critical

```typescript
// 취약한 코드
const DB_PASSWORD = "super_secret_123";

// 안전한 수정
const DB_PASSWORD = process.env.DB_PASSWORD;
```

**영향:** 소스코드 노출 시 데이터베이스 접근 권한 획득
**권장 조치:** 환경 변수로 이동

### 3. 취약한 JWT 서명
**위치:** src/auth/jwt.ts:23
**심각도:** Critical

JWT를 'none' 알고리즘으로 서명 시도 가능.
HS256 이상의 알고리즘 사용 필요.

## High Vulnerabilities

### 4. XSS (Cross-Site Scripting)
**위치:** src/components/UserComment.tsx:45

사용자 입력을 sanitize 없이 dangerouslySetInnerHTML 사용

### 5. CSRF 보호 누락
**위치:** src/api/middleware.ts

State-changing 엔드포인트에 CSRF 토큰 검증 없음

## 의존성 취약점

📦 package.json 취약점 (6개)

- express@4.16.0 → 4.18.2 (DoS 취약점)
- jsonwebtoken@8.5.0 → 9.0.0 (보안 개선)
- axios@0.21.1 → 1.6.0 (SSRF 취약점)

## 권장 조치

### 즉시 조치 (Critical)
1. ✅ SQL Injection 수정
2. ✅ 하드코딩 비밀번호 제거
3. ✅ JWT 알고리즘 강화

### 단기 조치 (High)
1. ⬜ XSS 방어 추가
2. ⬜ CSRF 보호 구현
3. ⬜ 의존성 업데이트

### 장기 개선
- Content Security Policy 추가
- 보안 헤더 설정 (Helmet.js)
- Rate limiting 구현
- 정기 보안 감사 자동화

# CI/CD 보안 체크 통합

# .github/workflows/security.yml
name: Security Scan

on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Claude Security Scan
        run: |
          claude task run security . \
            --severity critical,high \
            --format json \
            --output security-report.json

      - name: Check for Critical Issues
        run: |
          if grep -q '"severity": "critical"' security-report.json; then
            echo "Critical security issues found!"
            exit 1
          fi

# 커스텀 에이전트 생성

# 1. 에이전트 디렉토리 생성
mkdir -p .claude/agents

# 2. 에이전트 정의 파일 생성
touch .claude/agents/database-optimizer.yaml

# 3. 에이전트 등록
claude agent register .claude/agents/database-optimizer.yaml

# 4. 에이전트 실행
claude task run database-optimizer \
  "모든 N+1 쿼리 문제 찾고 해결 방안 제시"

# 커스텀 에이전트 정의 예제
# .claude/agents/database-optimizer.yaml

name: database-optimizer
version: 1.0.0
description: "데이터베이스 쿼리 최적화 전문 에이전트"

# 에이전트의 역할과 전문성
system_prompt: |
  당신은 데이터베이스 최적화 전문가입니다.

  전문 분야:
  - N+1 쿼리 문제 식별 및 해결
  - 인덱스 최적화 제안
  - 쿼리 성능 분석
  - ORM 사용 패턴 개선

  작업 방식:
  1. 코드베이스에서 데이터베이스 쿼리 식별
  2. 성능 문제가 있는 패턴 찾기
  3. 구체적인 최적화 방안 제시
  4. 인덱스 추가 권장사항 제공

# 에이전트가 사용할 수 있는 도구
tools:
  - Glob
  - Grep
  - Read
  - Write  # 최적화 제안을 파일로 저장

# 특정 파일 패턴에만 집중
file_patterns:
  include:
    - "**/*model*.{ts,js,py}"
    - "**/*repository*.{ts,js,py}"
    - "**/*query*.{ts,js,py}"
  exclude:
    - "**/*.test.*"
    - "**/node_modules/**"

# 실행 제약
constraints:
  max_files: 100
  timeout: 600  # 10분

# 출력 형식
output:
  format: markdown
  sections:
    - summary
    - issues
    - recommendations
    - code_examples

# 고급 커스텀 에이전트 예제
# .claude/agents/api-documentation.yaml

name: api-documentation
version: 1.0.0
description: "API 문서 자동 생성 에이전트"

system_prompt: |
  당신은 API 문서 작성 전문가입니다.
  OpenAPI 3.0 스펙에 따라 문서를 생성합니다.

# 단계별 실행 프로세스
workflow:
  - step: discover
    description: "API 엔드포인트 찾기"
    prompt: "모든 API 라우트와 컨트롤러 찾기"

  - step: analyze
    description: "엔드포인트 분석"
    prompt: "각 엔드포인트의 메서드, 파라미터, 응답 분석"

  - step: generate
    description: "문서 생성"
    prompt: "OpenAPI 3.0 스펙 문서 생성"
    output_file: "docs/api-spec.yaml"

# 에이전트 실행 후 자동 실행할 명령
post_execution:
  - command: "npx swagger-ui-watcher docs/api-spec.yaml"
    description: "Swagger UI로 문서 미리보기"

# 환경 변수
env:
  - name: API_VERSION
    default: "1.0.0"
  - name: API_BASE_URL
    required: true

# 커스텀 에이전트 활용 예제

# 1. 데이터베이스 최적화 에이전트
claude task run database-optimizer \
  "모든 Prisma 쿼리 최적화"

# 2. API 문서 생성 에이전트
claude task run api-documentation \
  --env API_BASE_URL=https://api.example.com

# 3. 마이그레이션 검증 에이전트
claude task run migration-validator \
  "최근 마이그레이션 파일 검증"

# 4. 테스트 커버리지 개선 에이전트
claude task run test-coverage-improver \
  "커버리지 80% 미만인 파일에 테스트 추가"