Claude Agent SDK로 코드 리뷰 에이전트 만들기: PR 분석부터 코멘트까지

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

// 가장 단순한 에이전트: 프롬프트를 주고 결과를 받는다
for await (const message of query({
  prompt: "이 프로젝트의 구조를 분석해줘",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
    permissionMode: "acceptEdits"
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

mkdir pr-review-agent && cd pr-review-agent
npm init -y
npm install @anthropic-ai/claude-agent-sdk zod
npm install -D typescript @types/node tsx
npx tsc --init --target ES2022 --module NodeNext --moduleResolution NodeNext

export ANTHROPIC_API_KEY="sk-ant-..."
export GITHUB_TOKEN="ghp_..."

pr-review-agent/
├── src/
│   ├── index.ts          # 진입점
│   ├── tools.ts          # 커스텀 도구 정의
│   ├── server.ts         # MCP 서버 설정
│   └── prompts.ts        # 시스템 프롬프트
├── package.json
└── tsconfig.json

// src/tools.ts
import { tool } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const GITHUB_TOKEN = process.env.GITHUB_TOKEN!;

async function githubApi(endpoint: string) {
  const response = await fetch(`https://api.github.com${endpoint}`, {
    headers: {
      Authorization: `Bearer ${GITHUB_TOKEN}`,
      Accept: "application/vnd.github.v3+json",
    },
  });
  if (!response.ok) {
    throw new Error(`GitHub API error: ${response.status} ${response.statusText}`);
  }
  return response.json();
}

export const getPullRequest = tool(
  "get_pull_request",
  "GitHub PR의 기본 정보를 가져온다 (제목, 설명, 작성자, 브랜치 등)",
  z.object({
    owner: z.string().describe("리포지토리 소유자"),
    repo: z.string().describe("리포지토리 이름"),
    pullNumber: z.number().describe("PR 번호"),
  }),
  async (args) => {
    const pr = await githubApi(
      `/repos/${args.owner}/${args.repo}/pulls/${args.pullNumber}`
    );
    return {
      content: [{
        type: "text" as const,
        text: JSON.stringify({
          title: pr.title,
          body: pr.body,
          user: pr.user.login,
          base: pr.base.ref,
          head: pr.head.ref,
          changedFiles: pr.changed_files,
          additions: pr.additions,
          deletions: pr.deletions,
        }, null, 2),
      }],
    };
  }
);

// src/tools.ts (계속)
export const getPullRequestDiff = tool(
  "get_pull_request_diff",
  "PR의 변경된 파일 목록과 diff를 가져온다",
  z.object({
    owner: z.string().describe("리포지토리 소유자"),
    repo: z.string().describe("리포지토리 이름"),
    pullNumber: z.number().describe("PR 번호"),
  }),
  async (args) => {
    const files = await githubApi(
      `/repos/${args.owner}/${args.repo}/pulls/${args.pullNumber}/files`
    );

    const diffs = files.map((file: any) => ({
      filename: file.filename,
      status: file.status,
      additions: file.additions,
      deletions: file.deletions,
      patch: file.patch || "(binary file)",
    }));

    return {
      content: [{
        type: "text" as const,
        text: JSON.stringify(diffs, null, 2),
      }],
    };
  }
);

// src/tools.ts (계속)
export const createReviewComment = tool(
  "create_review_comment",
  "PR에 리뷰 코멘트를 게시한다. 전체 리뷰 또는 파일별 인라인 코멘트를 남길 수 있다.",
  z.object({
    owner: z.string().describe("리포지토리 소유자"),
    repo: z.string().describe("리포지토리 이름"),
    pullNumber: z.number().describe("PR 번호"),
    body: z.string().describe("리뷰 본문"),
    event: z.enum(["COMMENT", "APPROVE", "REQUEST_CHANGES"])
      .describe("리뷰 액션"),
    comments: z.array(z.object({
      path: z.string().describe("파일 경로"),
      line: z.number().describe("코멘트를 달 라인 번호"),
      body: z.string().describe("인라인 코멘트 내용"),
    })).optional().describe("인라인 코멘트 목록"),
  }),
  async (args) => {
    const reviewBody: any = {
      body: args.body,
      event: args.event,
    };

    if (args.comments && args.comments.length > 0) {
      reviewBody.comments = args.comments.map((c) => ({
        path: c.path,
        line: c.line,
        body: c.body,
      }));
    }

    const result = await fetch(
      `https://api.github.com/repos/${args.owner}/${args.repo}/pulls/${args.pullNumber}/reviews`,
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${GITHUB_TOKEN}`,
          Accept: "application/vnd.github.v3+json",
          "Content-Type": "application/json",
        },
        body: JSON.stringify(reviewBody),
      }
    );

    if (!result.ok) {
      const error = await result.text();
      throw new Error(`리뷰 생성 실패: ${result.status} ${error}`);
    }

    const review = await result.json();
    return {
      content: [{
        type: "text" as const,
        text: `리뷰가 성공적으로 게시되었다. Review ID: ${review.id}`,
      }],
    };
  }
);

// src/server.ts
import { createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import {
  getPullRequest,
  getPullRequestDiff,
  createReviewComment,
} from "./tools.js";

export const githubReviewServer = createSdkMcpServer({
  name: "github-review",
  version: "1.0.0",
  tools: [getPullRequest, getPullRequestDiff, createReviewComment],
});

// src/prompts.ts
export const REVIEW_SYSTEM_PROMPT = `
당신은 시니어 개발자 수준의 코드 리뷰어입니다. PR의 변경 사항을 분석하고, 구체적이고 실행 가능한 피드백을 제공합니다.

## 리뷰 절차

1. PR 정보를 가져와서 변경의 맥락을 파악합니다.
2. Diff를 가져와서 모든 변경된 파일을 분석합니다.
3. 파일별로 다음 관점에서 리뷰합니다:
   - **버그**: 런타임 에러, 논리 오류, 엣지 케이스 누락
   - **보안**: 인젝션, 인증 누락, 민감 정보 노출
   - **성능**: 불필요한 연산, N+1 쿼리, 메모리 누수 가능성
   - **가독성**: 네이밍, 복잡한 로직, 누락된 에러 처리
4. 발견한 이슈를 인라인 코멘트로 남깁니다.
5. 전체 요약 리뷰를 작성합니다.

## 코멘트 작성 규칙

- 문제가 **왜** 문제인지 설명합니다.
- 가능하면 수정 코드를 제안합니다.
- 사소한 스타일 이슈는 무시합니다 (린터가 처리).
- 심각도를 표시합니다: 🔴 Critical, 🟡 Warning, 🔵 Suggestion
- 좋은 코드에는 칭찬 코멘트도 남깁니다 👍

## 판단 기준

- 변경 사항이 없는 파일은 리뷰하지 않습니다.
- 테스트 파일은 테스트 커버리지 관점에서만 확인합니다.
- 설정 파일(package.json, tsconfig.json 등)은 의존성 변경만 확인합니다.
- .env, credentials 등 민감 파일이 포함되었다면 반드시 경고합니다.
`.trim();

// src/index.ts
import { query } from "@anthropic-ai/claude-agent-sdk";
import { githubReviewServer } from "./server.js";
import { REVIEW_SYSTEM_PROMPT } from "./prompts.js";

async function reviewPR(owner: string, repo: string, pullNumber: number) {
  console.log(`\nPR #${pullNumber} 리뷰를 시작합니다...\n`);

  for await (const message of query({
    prompt: `${owner}/${repo} 리포지토리의 PR #${pullNumber}을 리뷰해주세요.`,
    options: {
      systemPrompt: REVIEW_SYSTEM_PROMPT,
      mcpServers: {
        "github-review": githubReviewServer,
      },
      allowedTools: ["mcp__github-review__*"],
      maxTurns: 10,
    },
  })) {
    // 에이전트의 추론 과정을 실시간으로 출력
    if (message.type === "assistant" && message.message?.content) {
      for (const block of message.message.content) {
        if ("text" in block) {
          console.log(block.text);
        } else if ("name" in block) {
          console.log(`\n🔧 도구 호출: ${block.name}`);
        }
      }
    } else if (message.type === "result") {
      console.log(`\n✅ 리뷰 완료: ${message.subtype}`);
    }
  }
}

// CLI에서 실행
const [owner, repo, prNumber] = process.argv.slice(2);
if (!owner || !repo || !prNumber) {
  console.error("사용법: npx tsx src/index.ts <owner> <repo> <pr-number>");
  process.exit(1);
}

reviewPR(owner, repo, Number(prNumber));

npx tsx src/index.ts facebook react 28000

// src/index.ts — 스트리밍 버전
async function reviewPRStreaming(owner: string, repo: string, pullNumber: number) {
  console.log(`\nPR #${pullNumber} 리뷰를 시작합니다...\n`);

  let inTool = false;

  for await (const message of query({
    prompt: `${owner}/${repo} 리포지토리의 PR #${pullNumber}을 리뷰해주세요.`,
    options: {
      systemPrompt: REVIEW_SYSTEM_PROMPT,
      mcpServers: {
        "github-review": githubReviewServer,
      },
      allowedTools: ["mcp__github-review__*"],
      maxTurns: 10,
      includePartialMessages: true,
    },
  })) {
    if (message.type === "stream_event") {
      const event = message.event;

      if (event.type === "content_block_start") {
        if (event.content_block.type === "tool_use") {
          process.stdout.write(`\n🔧 [${event.content_block.name}]`);
          inTool = true;
        }
      } else if (event.type === "content_block_delta") {
        if (event.delta.type === "text_delta" && !inTool) {
          process.stdout.write(event.delta.text);
        }
      } else if (event.type === "content_block_stop") {
        if (inTool) {
          process.stdout.write(" ✓\n");
          inTool = false;
        }
      }
    } else if (message.type === "result") {
      console.log(`\n\n✅ 리뷰 완료: ${message.subtype}`);
    }
  }
}

PR #28000 리뷰를 시작합니다...

PR 정보를 확인하겠습니다.
🔧 [get_pull_request] ✓

변경된 파일 3개의 diff를 분석합니다.
🔧 [get_pull_request_diff] ✓

src/hooks/useCallback.ts에서 메모이제이션 관련 이슈를 발견했습니다...
🔧 [create_review_comment] ✓

✅ 리뷰 완료: success

// src/guardrails.ts
const SENSITIVE_PATTERNS = [
  /\.env(\..+)?$/,
  /credentials/i,
  /secret/i,
  /\.pem$/,
  /\.key$/,
  /password/i,
];

export function checkSensitiveFiles(files: string[]): string[] {
  return files.filter((file) =>
    SENSITIVE_PATTERNS.some((pattern) => pattern.test(file))
  );
}

// src/index.ts에 추가
if (message.type === "result") {
  const usage = message.usage;
  if (usage) {
    const inputTokens = usage.input_tokens;
    const outputTokens = usage.output_tokens;
    console.log(`📊 토큰 사용량: 입력 ${inputTokens}, 출력 ${outputTokens}`);

    // 토큰 제한 경고
    if (inputTokens + outputTokens > 100_000) {
      console.warn("⚠️ 토큰 사용량이 100K를 초과했습니다.");
    }
  }
}

// src/prompts.ts에 추가
export const SELF_REVIEW_PROMPT = `
리뷰를 게시하기 전에, 다음을 스스로 점검하세요:

1. 오탐(false positive)은 없는가? 실제로 문제가 맞는지 다시 확인한다.
2. 코멘트가 구체적인가? "이 부분이 이상하다" 대신 "이 조건에서 null 참조가 발생할 수 있다"로 쓴다.
3. 수정 제안이 포함되었는가? 문제만 지적하지 말고 해결책을 제시한다.
4. 심각도가 적절한가? 스타일 이슈에 🔴 Critical을 달지 않았는지 확인한다.

이 점검을 통과한 코멘트만 게시한다.
`;

// 외부 GitHub MCP 서버 사용 예시
for await (const message of query({
  prompt: "PR #42의 변경 사항을 리뷰해줘",
  options: {
    mcpServers: {
      github: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: {
          GITHUB_TOKEN: process.env.GITHUB_TOKEN!,
        },
      },
    },
    allowedTools: ["mcp__github__*"],
    maxTurns: 10,
  },
})) {
  // 메시지 처리
}

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

async function* interactiveReview() {
  // 첫 번째 메시지: 리뷰 요청
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "facebook/react 리포지토리의 PR #28000을 리뷰해줘",
    },
  };

  // 리뷰 결과를 받은 후 후속 질문
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "useCallback 관련 변경 사항을 더 자세히 분석해줘. 성능 영향이 있는지 확인해줘.",
    },
  };
}

for await (const message of query({
  prompt: interactiveReview(),
  options: {
    systemPrompt: REVIEW_SYSTEM_PROMPT,
    mcpServers: {
      "github-review": githubReviewServer,
    },
    allowedTools: ["mcp__github-review__*"],
    maxTurns: 15,
  },
})) {
  // 메시지 처리
}

# .github/workflows/ai-review.yml
name: AI Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: npm ci

      - name: Run AI Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          npx tsx src/index.ts \
            ${{ github.repository_owner }} \
            ${{ github.event.repository.name }} \
            ${{ github.event.pull_request.number }}