Split View: AI 하네스란 무엇인가: Skills, Context, Hooks, Permissions로 AI를 제어하는 오케스트레이션 아키텍처

You are Claude Code, Anthropic's official CLI for Claude.
Given the user's message, you should use the tools available
to complete the task.

Your strengths:
- Searching for code across large codebases
- Analyzing multiple files to understand architecture
- Investigating complex questions
- Performing multi-step research tasks

Guidelines:
- For file searches: search broadly when you don't know
  where something lives
- NEVER create files unless absolutely necessary
- ALWAYS prefer editing existing files

# 좋은 시스템 프롬프트의 구조

## 1. 역할 선언 (Who)
당신은 시니어 백엔드 엔지니어입니다.
Java/Spring Boot 전문가이며, 10년 이상의 경험이 있습니다.

## 2. 행동 규칙 (How)
- 코드 리뷰 시 보안 취약점을 최우선으로 확인하세요
- 성능 문제가 있으면 Big-O 분석과 함께 지적하세요
- 개선 제안은 반드시 코드 예제와 함께 제시하세요

## 3. 제약사항 (Boundaries)
- 코드를 직접 수정하지 마세요, 제안만 하세요
- 외부 라이브러리 추가를 권장하지 마세요
- 기존 아키텍처 패턴을 따르세요

## 4. 출력 형식 (Format)
리뷰 결과는 다음 형식으로 작성하세요:
- [심각도]: 설명 + 제안

You are a senior code reviewer specializing in security
and performance. Review every PR with these priorities:
1. Security vulnerabilities (SQL injection, XSS, CSRF)
2. Performance bottlenecks (N+1 queries, memory leaks)
3. Code maintainability (naming, structure, SOLID)
Never approve code with critical security issues.

You are a data analyst with expertise in Python, SQL,
and statistical analysis. When analyzing data:
1. Always validate data quality first
2. Provide confidence intervals for estimates
3. Visualize results with appropriate charts
4. Explain findings in business-friendly language

{
  "name": "read_file",
  "description": "Reads a file from the local filesystem. Supports text files, images, and PDFs.",
  "input_schema": {
    "type": "object",
    "properties": {
      "file_path": {
        "type": "string",
        "description": "The absolute path to the file to read"
      },
      "offset": {
        "type": "number",
        "description": "The line number to start reading from"
      },
      "limit": {
        "type": "number",
        "description": "The number of lines to read"
      }
    },
    "required": ["file_path"]
  }
}

{
  "mcpServers": {
    "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/db"
      }
    }
  }
}

# Project Guidelines

## Build Commands

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

## Code Conventions

- TypeScript strict mode 사용
- 함수형 컴포넌트만 사용 (클래스 컴포넌트 금지)
- CSS-in-JS 대신 Tailwind CSS 사용

## Architecture

- src/components: 재사용 가능한 UI 컴포넌트
- src/hooks: 커스텀 훅
- src/lib: 유틸리티 함수
- src/app: Next.js App Router 페이지

프로젝트 구조 분석:
- package.json → 의존성, 스크립트
- tsconfig.json → TypeScript 설정
- .eslintrc → 코드 스타일 규칙
- .gitignore → 제외 파일 패턴
- 디렉토리 구조 → 아키텍처 패턴 추론

.remember/
  core-memories.md   # 프로젝트 핵심 정보
  now.md             # 현재 작업 상태
  today.md           # 오늘의 작업 기록
  recent.md          # 최근 작업 히스토리
  archive.md         # 오래된 기록 보관소

---
trigger: 'when user asks to review a PR'
description: 'Comprehensive code review workflow'
---

# Code Review Skill

## Step 1: Gather Information

- Read the PR description and diff
- Identify changed files and their purposes
- Check the PR against project conventions (CLAUDE.md)

## Step 2: Security Review

- Check for SQL injection, XSS, CSRF vulnerabilities
- Verify input validation on all user inputs
- Ensure secrets are not hardcoded

## Step 3: Performance Review

- Identify N+1 query patterns
- Check for unnecessary re-renders (React)
- Verify proper indexing for DB queries

## Step 4: Generate Review

- Use structured format: severity + description + suggestion
- Include code examples for each suggestion
- Summarize with overall assessment

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "echo 'File modification detected'"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "/bin/sh -c 'cd PROJECT_DIR && npx eslint --fix FILE_PATH 2>/dev/null || true'"
      },
      {
        "matcher": "Bash",
        "command": "/bin/sh -c 'if echo TOOL_INPUT | grep -q \"git commit\"; then cd PROJECT_DIR && npm test; fi'"
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "command": "/bin/sh -c 'echo NOTIFICATION_CONTENT >> /tmp/ai-notifications.log'"
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "command": "/bin/sh -c 'npx prettier --write FILE_PATH'"
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "/bin/sh -c 'if echo TOOL_INPUT | grep -q \"git commit\"; then npm test || exit 1; fi'"
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "/bin/sh -c 'if echo TOOL_INPUT | grep -qE \"rm -rf|drop table|format\"; then echo \"BLOCKED: Dangerous command detected\" && exit 1; fi'"
      }
    ]
  }
}

{
  "permissions": {
    "allowedTools": [
      "Read",
      "Glob",
      "Grep",
      "Bash(git status)",
      "Bash(git diff)",
      "Bash(npm test)"
    ],
    "disallowedTools": [
      "Bash(rm *)",
      "Bash(sudo *)",
      "Bash(curl * | sh)",
      "Write(/etc/*)",
      "Write(/usr/*)"
    ]
  }
}

# core-memories.md

- 이 프로젝트는 Next.js 14 + TypeScript + Tailwind CSS를 사용합니다
- 배포는 Vercel로 합니다
- DB는 PostgreSQL (Supabase)입니다

# now.md

현재 작업: 사용자 인증 모듈 리팩토링 중
진행 상황: NextAuth.js에서 Lucia Auth로 마이그레이션 진행 중
블로커: 소셜 로그인 콜백 URL 설정 문제

# today.md

- 09:30 인증 모듈 분석 완료
- 10:15 Lucia Auth 설정 파일 생성
- 11:00 세션 관리 로직 마이그레이션
- 14:00 소셜 로그인 통합 시작

에이전트 루프 흐름:

1. User Input (사용자 요청)
      |
2. System Prompt + Context 로딩
      |
3. LLM 추론 (어떤 행동을 할지 결정)
      |
4. Tool Call 결정
      |
5. Hook (PreToolUse) 실행
      |  (검증 실패 시 → 3으로 돌아감)
      |
6. Tool 실행
      |
7. Hook (PostToolUse) 실행
      |
8. 결과 관찰 (Observation)
      |
9. 추가 행동 필요? → Yes → 3으로 돌아감
      |               No
      |
10. 최종 응답 생성

Turn 1: git diff 실행 (Bash 도구)
   → 변경된 파일 목록과 diff 획득

Turn 2: 변경된 파일 읽기 (Read 도구)
   → 전체 컨텍스트 파악

Turn 3: CLAUDE.md 읽기 (Read 도구)
   → 프로젝트 컨벤션 확인

Turn 4: 관련 테스트 파일 찾기 (Grep 도구)
   → 테스트 커버리지 확인

Turn 5: npm test 실행 (Bash 도구)
   → 테스트 통과 여부 확인

Turn 6: 리뷰 결과 생성 (최종 응답)
   → 보안, 성능, 유지보수성 관점 리뷰

메인 에이전트 (Orchestrator)
    |
    +--- 서브에이전트 A: "src/ 디렉토리 분석"
    |       (독립 컨텍스트, 파일 읽기/검색 도구)
    |
    +--- 서브에이전트 B: "tests/ 디렉토리 분석"
    |       (독립 컨텍스트, 테스트 실행 도구)
    |
    +--- 서브에이전트 C: "문서 업데이트"
            (독립 컨텍스트, 파일 쓰기 도구)

메인 에이전트: 각 서브에이전트의 결과를 통합하여 최종 응답 생성

메인 프로젝트 (main branch)
    |
    +--- .claude/worktrees/feature-auth/
    |       (독립 브랜치, 독립 작업 디렉토리)
    |
    +--- .claude/worktrees/fix-bug-123/
            (독립 브랜치, 독립 작업 디렉토리)

설정 위치 (우선순위 순):
1. 프로젝트/.claude/settings.json (최우선)
2. 홈디렉토리/.claude/settings.json (전역)
3. 기본값

{
  "permissions": {
    "allowedTools": ["Read", "Glob", "Grep"],
    "disallowedTools": ["Bash(rm *)"]
  },
  "hooks": {
    "PreToolUse": [],
    "PostToolUse": [],
    "Notification": [],
    "Stop": []
  },
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "true"
  },
  "model": "claude-sonnet-4-20250514",
  "theme": "dark"
}

가장 높음 ← 프로젝트 설정 ← 전역 설정 ← 기본값 → 가장 낮음

import anthropic
from typing import Any

# Anthropic 클라이언트 초기화
client = anthropic.Anthropic()

# 도구 정의
tools = [
    {
        "name": "read_file",
        "description": "Read the contents of a file at the given path",
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {
                    "type": "string",
                    "description": "Absolute file path to read"
                }
            },
            "required": ["path"]
        }
    },
    {
        "name": "list_directory",
        "description": "List files and directories at the given path",
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {
                    "type": "string",
                    "description": "Directory path to list"
                }
            },
            "required": ["path"]
        }
    },
    {
        "name": "search_code",
        "description": "Search for a pattern in the codebase",
        "input_schema": {
            "type": "object",
            "properties": {
                "pattern": {
                    "type": "string",
                    "description": "Regex pattern to search for"
                },
                "file_type": {
                    "type": "string",
                    "description": "File extension to filter (e.g., py, ts)"
                }
            },
            "required": ["pattern"]
        }
    }
]


def execute_tool(name: str, input_data: dict) -> str:
    """도구를 실행하고 결과를 반환합니다."""
    import os
    import subprocess

    if name == "read_file":
        try:
            with open(input_data["path"], "r") as f:
                return f.read()
        except FileNotFoundError:
            return f"Error: File not found: {input_data['path']}"

    elif name == "list_directory":
        try:
            entries = os.listdir(input_data["path"])
            return "\n".join(entries)
        except FileNotFoundError:
            return f"Error: Directory not found: {input_data['path']}"

    elif name == "search_code":
        try:
            cmd = ["grep", "-rn", input_data["pattern"], "."]
            if "file_type" in input_data:
                cmd.extend(["--include", f"*.{input_data['file_type']}"])
            result = subprocess.run(cmd, capture_output=True, text=True)
            return result.stdout or "No matches found"
        except Exception as e:
            return f"Error: {str(e)}"

    return f"Unknown tool: {name}"


def run_agent(user_message: str, max_turns: int = 10) -> str:
    """에이전트 루프를 실행합니다."""
    system_prompt = """You are an expert code reviewer.
    Analyze code for security vulnerabilities, performance issues,
    and maintainability problems. Use the provided tools to
    explore the codebase before giving your review."""

    messages = [{"role": "user", "content": user_message}]

    for turn in range(max_turns):
        # LLM 호출
        response = client.messages.create(
            model="claude-sonnet-4-20250514",
            max_tokens=4096,
            system=system_prompt,
            tools=tools,
            messages=messages,
        )

        # 응답 처리
        if response.stop_reason == "end_turn":
            # 최종 텍스트 응답 추출
            for block in response.content:
                if hasattr(block, "text"):
                    return block.text
            return "Agent completed without text response"

        # 도구 호출 처리
        if response.stop_reason == "tool_use":
            # assistant 메시지 추가
            messages.append({
                "role": "assistant",
                "content": response.content,
            })

            # 각 도구 호출 실행
            tool_results = []
            for block in response.content:
                if block.type == "tool_use":
                    result = execute_tool(block.name, block.input)
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": result,
                    })

            messages.append({
                "role": "user",
                "content": tool_results,
            })

    return "Agent reached maximum turns without completing"


# 실행
if __name__ == "__main__":
    review = run_agent("Review the authentication module in src/auth/")
    print(review)

class PermissionModel:
    """AI 에이전트의 권한을 관리합니다."""

    def __init__(self):
        self.allowed_paths = ["/project/src/", "/project/tests/"]
        self.blocked_commands = ["rm", "sudo", "chmod"]
        self.max_file_size = 1_000_000  # 1MB

    def check_file_access(self, path: str) -> bool:
        """파일 접근 권한을 확인합니다."""
        return any(path.startswith(p) for p in self.allowed_paths)

    def check_command(self, command: str) -> bool:
        """명령어 실행 권한을 확인합니다."""
        return not any(cmd in command for cmd in self.blocked_commands)

    def validate_tool_call(self, tool_name: str, input_data: dict) -> tuple:
        """도구 호출의 유효성을 검증합니다.
        Returns (is_allowed, reason)"""
        if tool_name == "read_file":
            path = input_data.get("path", "")
            if not self.check_file_access(path):
                return False, f"Access denied: {path}"

        if tool_name == "execute_command":
            cmd = input_data.get("command", "")
            if not self.check_command(cmd):
                return False, f"Blocked command: {cmd}"

        return True, "Allowed"

import time
from dataclasses import dataclass, field
from typing import Optional


@dataclass
class AgentEvent:
    """에이전트의 행동을 기록하는 이벤트입니다."""
    event_type: str  # tool_call, tool_result, llm_response, error
    timestamp: float = field(default_factory=time.time)
    tool_name: Optional[str] = None
    input_data: Optional[dict] = None
    output_data: Optional[str] = None
    tokens_used: int = 0
    duration_ms: float = 0


class AgentMonitor:
    """에이전트의 행동을 모니터링합니다."""

    def __init__(self):
        self.events: list[AgentEvent] = []
        self.total_tokens = 0
        self.total_cost = 0.0

    def log_event(self, event: AgentEvent):
        self.events.append(event)
        self.total_tokens += event.tokens_used

    def get_summary(self) -> dict:
        return {
            "total_events": len(self.events),
            "total_tokens": self.total_tokens,
            "tool_calls": sum(
                1 for e in self.events if e.event_type == "tool_call"
            ),
            "errors": sum(
                1 for e in self.events if e.event_type == "error"
            ),
            "total_duration_ms": sum(
                e.duration_ms for e in self.events
            ),
        }

import Anthropic from '@anthropic-ai/sdk'

// 도구 정의
const tools: Anthropic.Tool[] = [
  {
    name: 'query_database',
    description: 'Execute a SQL query against the analytics database',
    input_schema: {
      type: 'object' as const,
      properties: {
        query: {
          type: 'string',
          description: 'SQL query to execute (SELECT only)',
        },
        database: {
          type: 'string',
          description: 'Database name',
          enum: ['analytics', 'users', 'products'],
        },
      },
      required: ['query', 'database'],
    },
  },
  {
    name: 'create_chart',
    description: 'Create a data visualization chart',
    input_schema: {
      type: 'object' as const,
      properties: {
        chart_type: {
          type: 'string',
          enum: ['bar', 'line', 'pie', 'scatter'],
        },
        data: {
          type: 'string',
          description: 'JSON string of chart data',
        },
        title: {
          type: 'string',
          description: 'Chart title',
        },
      },
      required: ['chart_type', 'data', 'title'],
    },
  },
]

// 권한 모델
class QueryPermissions {
  private readonly allowedOperations = ['SELECT']
  private readonly blockedPatterns = [
    /DROP\s/i,
    /DELETE\s/i,
    /UPDATE\s/i,
    /INSERT\s/i,
    /ALTER\s/i,
    /TRUNCATE\s/i,
  ]

  validateQuery(query: string): { allowed: boolean; reason: string } {
    for (const pattern of this.blockedPatterns) {
      if (pattern.test(query)) {
        return {
          allowed: false,
          reason: `Blocked: destructive operation detected`,
        }
      }
    }
    return { allowed: true, reason: 'Query is safe' }
  }
}

// 도구 실행
async function executeTool(name: string, input: Record<string, unknown>): Promise<string> {
  const permissions = new QueryPermissions()

  if (name === 'query_database') {
    const query = input.query as string
    const validation = permissions.validateQuery(query)
    if (!validation.allowed) {
      return `Permission denied: ${validation.reason}`
    }
    // 실제 DB 쿼리 실행 (여기서는 시뮬레이션)
    return JSON.stringify({
      columns: ['date', 'revenue', 'users'],
      rows: [
        ['2025-01', 150000, 12000],
        ['2025-02', 165000, 13500],
        ['2025-03', 180000, 15000],
      ],
    })
  }

  if (name === 'create_chart') {
    return `Chart created: ${input.title} (${input.chart_type})`
  }

  return `Unknown tool: ${name}`
}

// 에이전트 루프
async function runDataAnalysisAgent(question: string): Promise<string> {
  const client = new Anthropic()

  const systemPrompt = `You are a data analyst agent.
    Analyze data by querying databases and creating visualizations.
    Always validate data before making conclusions.
    Provide insights in clear, business-friendly language.`

  const messages: Anthropic.MessageParam[] = [{ role: 'user', content: question }]

  const maxTurns = 10

  for (let turn = 0; turn < maxTurns; turn++) {
    const response = await client.messages.create({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 4096,
      system: systemPrompt,
      tools,
      messages,
    })

    if (response.stop_reason === 'end_turn') {
      for (const block of response.content) {
        if (block.type === 'text') {
          return block.text
        }
      }
      return 'Agent completed'
    }

    if (response.stop_reason === 'tool_use') {
      messages.push({
        role: 'assistant',
        content: response.content,
      })

      const toolResults: Anthropic.ToolResultBlockParam[] = []
      for (const block of response.content) {
        if (block.type === 'tool_use') {
          const result = await executeTool(block.name, block.input as Record<string, unknown>)
          toolResults.push({
            type: 'tool_result',
            tool_use_id: block.id,
            content: result,
          })
        }
      }

      messages.push({
        role: 'user',
        content: toolResults,
      })
    }
  }

  return 'Agent reached maximum turns'
}

// 실행
async function main() {
  const result = await runDataAnalysisAgent('What was the revenue trend in Q1 2025?')
  console.log(result)
}

main().catch(console.error)

from langgraph.graph import StateGraph, END
from typing import TypedDict


class ReviewState(TypedDict):
    code_diff: str
    security_issues: list
    performance_issues: list
    review_summary: str


def analyze_security(state: ReviewState) -> ReviewState:
    """보안 취약점을 분석합니다."""
    # LLM 호출로 보안 분석
    state["security_issues"] = ["SQL injection in login.py:42"]
    return state


def analyze_performance(state: ReviewState) -> ReviewState:
    """성능 이슈를 분석합니다."""
    # LLM 호출로 성능 분석
    state["performance_issues"] = ["N+1 query in users.py:87"]
    return state


def generate_review(state: ReviewState) -> ReviewState:
    """최종 리뷰를 생성합니다."""
    issues = state["security_issues"] + state["performance_issues"]
    state["review_summary"] = f"Found {len(issues)} issues"
    return state


# 그래프 구성
workflow = StateGraph(ReviewState)
workflow.add_node("security", analyze_security)
workflow.add_node("performance", analyze_performance)
workflow.add_node("review", generate_review)

workflow.set_entry_point("security")
workflow.add_edge("security", "performance")
workflow.add_edge("performance", "review")
workflow.add_edge("review", END)

app = workflow.compile()

from crewai import Agent, Task, Crew

security_reviewer = Agent(
    role="Security Reviewer",
    goal="Find all security vulnerabilities in the code",
    backstory="You are a senior security engineer with 15 years "
              "of experience in application security.",
    tools=[],  # 도구 목록
)

performance_reviewer = Agent(
    role="Performance Reviewer",
    goal="Identify performance bottlenecks and optimization opportunities",
    backstory="You are a performance engineering specialist "
              "who has optimized systems serving millions of users.",
    tools=[],
)

review_task = Task(
    description="Review the authentication module for security issues",
    agent=security_reviewer,
    expected_output="List of security vulnerabilities with severity ratings",
)

crew = Crew(
    agents=[security_reviewer, performance_reviewer],
    tasks=[review_task],
)

result = crew.kickoff()

사용자 입력
    |
    v
[Router Agent] → "코드 리뷰 요청" → Code Review Agent
               → "데이터 분석 요청" → Data Analysis Agent
               → "문서 작성 요청" → Documentation Agent
               → "일반 질문"       → General Assistant

[Orchestrator]
    |
    +--- "파일 A 리뷰해줘" → [Worker 1] → 결과 A
    |
    +--- "파일 B 리뷰해줘" → [Worker 2] → 결과 B
    |
    +--- "파일 C 리뷰해줘" → [Worker 3] → 결과 C
    |
    v
[Orchestrator] → 결과 A + B + C 통합 → 최종 리뷰

[분석 Agent] → 코드 분석 결과
    |
    v
[계획 Agent] → 리팩토링 계획
    |
    v
[실행 Agent] → 코드 수정
    |
    v
[검증 Agent] → 테스트 실행 + 결과 확인

[Generator Agent] → 초안 생성
    |
    v
[Evaluator Agent] → 품질 평가 (1-10점)
    |
    +--- 점수 >= 8 → 완료
    |
    +--- 점수 < 8 → 피드백과 함께 Generator에게 재요청
                         |
                         v
                    [Generator Agent] → 수정본 생성
                         |
                         v
                    [Evaluator Agent] → 재평가
                         ...

사용자 입력
    |
    v
[Input Guardrail] → 유해 콘텐츠 필터링
    |                 프롬프트 인젝션 탐지
    |                 입력 정규화
    v
[AI Agent] → 작업 수행
    |
    v
[Output Guardrail] → PII 마스킹
    |                  환각 탐지
    |                  형식 검증
    v
최종 응답

class InputGuardrail:
    """입력을 검증하고 정제합니다."""

    def validate(self, user_input: str) -> tuple:
        # 프롬프트 인젝션 탐지
        injection_patterns = [
            "ignore previous instructions",
            "system prompt",
            "you are now",
            "disregard all",
        ]
        for pattern in injection_patterns:
            if pattern.lower() in user_input.lower():
                return False, "Potential prompt injection detected"

        # 입력 길이 제한
        if len(user_input) > 10000:
            return False, "Input too long"

        return True, "Valid input"


class OutputGuardrail:
    """출력을 검증하고 정제합니다."""

    def validate(self, output: str) -> str:
        # PII 마스킹
        import re
        # 이메일 마스킹
        output = re.sub(
            r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}",
            "[EMAIL_REDACTED]",
            output,
        )
        # 전화번호 마스킹
        output = re.sub(
            r"\b\d{3}[-.]?\d{4}[-.]?\d{4}\b",
            "[PHONE_REDACTED]",
            output,
        )
        return output

code-review-harness/
  src/
    agent.py          # 에이전트 루프
    tools.py           # 도구 정의 및 실행
    permissions.py     # 권한 모델
    guardrails.py      # 입출력 검증
    memory.py          # 기억 관리
    monitor.py         # 모니터링
  skills/
    code-review.md     # 코드 리뷰 스킬
    security-audit.md  # 보안 감사 스킬
  config/
    settings.json      # 설정 파일
  tests/
    test_agent.py      # 에이전트 테스트
  README.md
  requirements.txt

You are an expert code reviewer specializing in Python
and TypeScript applications.

## Your Responsibilities
1. Security: Find vulnerabilities (injection, XSS, auth issues)
2. Performance: Identify bottlenecks (N+1 queries, memory leaks)
3. Maintainability: Check code quality (naming, structure, SOLID)
4. Testing: Verify test coverage and quality

## Rules
- NEVER modify code directly. Only suggest changes.
- Always explain WHY something is an issue, not just WHAT.
- Provide code examples for every suggestion.
- Rate issues by severity: Critical, High, Medium, Low.

## Output Format
For each issue found:
[SEVERITY] file:line - Description
Suggestion: How to fix it
Example: Code snippet showing the fix

# tools.py
import subprocess
import os


def git_diff(base_branch: str = "main") -> str:
    """현재 브랜치와 base 브랜치의 diff를 가져옵니다."""
    result = subprocess.run(
        ["git", "diff", f"{base_branch}...HEAD"],
        capture_output=True,
        text=True,
    )
    return result.stdout


def read_file(path: str) -> str:
    """파일 내용을 읽습니다."""
    try:
        with open(path, "r") as f:
            lines = f.readlines()
        # 줄 번호 추가
        numbered = [f"{i+1}: {line}" for i, line in enumerate(lines)]
        return "".join(numbered)
    except FileNotFoundError:
        return f"File not found: {path}"


def search_pattern(pattern: str, directory: str = ".") -> str:
    """코드베이스에서 패턴을 검색합니다."""
    result = subprocess.run(
        ["grep", "-rn", pattern, directory,
         "--include=*.py", "--include=*.ts",
         "--include=*.tsx", "--include=*.js"],
        capture_output=True,
        text=True,
    )
    return result.stdout or "No matches found"


def run_tests(test_path: str = "") -> str:
    """테스트를 실행합니다."""
    cmd = ["python", "-m", "pytest", "-v"]
    if test_path:
        cmd.append(test_path)
    result = subprocess.run(cmd, capture_output=True, text=True)
    return f"STDOUT:\n{result.stdout}\nSTDERR:\n{result.stderr}"


def get_file_history(path: str, count: int = 5) -> str:
    """파일의 git 히스토리를 가져옵니다."""
    result = subprocess.run(
        ["git", "log", f"-{count}", "--oneline", "--", path],
        capture_output=True,
        text=True,
    )
    return result.stdout

# skills/code-review.md

---

trigger: "when user asks to review code or a PR"
description: "Comprehensive code review workflow"

---

## Code Review Workflow

### Step 1: Gather Context

1. Run git diff to see all changes
2. Read the changed files completely
3. Check project conventions (CLAUDE.md, .eslintrc)
4. Identify the purpose of the changes

### Step 2: Security Analysis

Check for these common vulnerabilities:

- SQL injection (raw queries, string interpolation)
- XSS (unescaped user input in HTML)
- Authentication issues (weak tokens, missing checks)
- Authorization issues (missing role checks)
- Sensitive data exposure (API keys, passwords in code)

### Step 3: Performance Analysis

Check for these common issues:

- N+1 database queries
- Missing database indexes
- Unnecessary re-renders (React)
- Memory leaks (unclosed resources)
- Blocking operations in async code

### Step 4: Code Quality Analysis

Check for these issues:

- Unclear naming conventions
- Functions exceeding 50 lines
- Missing error handling
- Duplicated code
- SOLID principle violations

### Step 5: Generate Review Report

Format each issue as:
[SEVERITY] file:line - Description
Use severity levels: Critical, High, Medium, Low, Info

# permissions.py

class ReviewPermissions:
    """코드 리뷰 에이전트의 권한을 정의합니다."""

    # 읽기만 허용 - 코드 수정 불가
    ALLOWED_TOOLS = [
        "git_diff",
        "read_file",
        "search_pattern",
        "run_tests",
        "get_file_history",
    ]

    BLOCKED_TOOLS = [
        "write_file",
        "delete_file",
        "execute_command",
        "deploy",
    ]

    # 접근 가능한 디렉토리
    ALLOWED_PATHS = [
        "src/",
        "tests/",
        "lib/",
        "config/",
    ]

    # 접근 불가 디렉토리
    BLOCKED_PATHS = [
        ".env",
        "secrets/",
        "credentials/",
        ".git/",
    ]

    def is_tool_allowed(self, tool_name: str) -> bool:
        if tool_name in self.BLOCKED_TOOLS:
            return False
        return tool_name in self.ALLOWED_TOOLS

    def is_path_allowed(self, path: str) -> bool:
        # 차단 경로 확인
        for blocked in self.BLOCKED_PATHS:
            if blocked in path:
                return False
        # 허용 경로 확인
        return any(path.startswith(p) for p in self.ALLOWED_PATHS)

def evaluate_review_quality(
    original_code: str,
    review_output: str,
    evaluator_model: str = "claude-sonnet-4-20250514"
) -> dict:
    """LLM을 사용하여 코드 리뷰 품질을 평가합니다."""
    evaluation_prompt = f"""
    Evaluate this code review on a scale of 1-10 for each criterion:

    1. Accuracy: Are the identified issues real problems?
    2. Completeness: Were important issues missed?
    3. Actionability: Are suggestions specific and implementable?
    4. Communication: Is the review clear and constructive?

    Original Code:
    {original_code}

    Review Output:
    {review_output}

    Respond in JSON format:
    accuracy, completeness, actionability, communication, overall, feedback
    """

    # LLM 호출하여 평가 수행
    # ... (실제 API 호출 코드)
    return evaluation_result

class CostTracker:
    """에이전트의 API 호출 비용을 추적합니다."""

    # 모델별 토큰당 가격 (USD)
    PRICING = {
        "claude-sonnet-4-20250514": {
            "input": 0.003 / 1000,
            "output": 0.015 / 1000,
        },
        "claude-opus-4-20250514": {
            "input": 0.015 / 1000,
            "output": 0.075 / 1000,
        },
    }

    def __init__(self):
        self.total_input_tokens = 0
        self.total_output_tokens = 0
        self.model = "claude-sonnet-4-20250514"

    def add_usage(self, input_tokens: int, output_tokens: int):
        self.total_input_tokens += input_tokens
        self.total_output_tokens += output_tokens

    def get_total_cost(self) -> float:
        pricing = self.PRICING[self.model]
        return (
            self.total_input_tokens * pricing["input"]
            + self.total_output_tokens * pricing["output"]
        )

    def get_report(self) -> str:
        cost = self.get_total_cost()
        return (
            f"Input tokens: {self.total_input_tokens:,}\n"
            f"Output tokens: {self.total_output_tokens:,}\n"
            f"Total cost: ${cost:.4f}"
        )