CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Common Commands
6 
7- **Build**: `pnpm run build` - Compiles TypeScript and packages with ncc
8- **Package**: `pnpm run package` - Alias for build command
9- **Lint**: `pnpm run lint` - ESLint with TypeScript support, must have 0 warnings
10- **Type Check**: `pnpm run type-check` - TypeScript compilation check without output
11- **Test**: `pnpm run test` - Runs Jest test suite with full coverage
12- **Manual Review**: `pnpm run review` - Runs ts-node on ai-review.ts for local testing
13 
14## Architecture Overview
15 
16This is a **GitHub Action** that provides AI-powered code review for Pull Requests using multiple LLM providers (OpenAI, Anthropic, Google Gemini).
17 
18### Core Components
19 
20- **`src/index.ts`**: GitHub Action entry point that validates inputs, generates git diffs, and delegates to ai-review.ts
21- **`src/ai-review.ts`**: Main review engine with hunk-based diff processing, LLM integration via Vercel AI SDK, and GitHub API comment posting
22- **`src/system-prompt.ts`**: Configurable system prompt builder with default code review guidelines and XML response format enforcement
23- **`types.ts`**: Type definitions for Finding objects (path, line, message, severity, suggestion, code)
24 
25### Key Architecture Patterns
26 
27- **Provider Agnostic**: Uses Vercel AI SDK (`ai` package) for unified LLM access across OpenAI, Anthropic, and Google
28- **Hunk-Based Processing**: Splits diffs into individual hunks rather than arbitrary size limits for focused reviews
29- **Structured XML Output**: Enforces consistent XML response format with severity levels (required, optional, nit, fyi)
30- **Line Resolution**: Maps XML findings to actual GitHub line numbers through diff parsing
31- **Retry Logic**: Built-in exponential backoff for LLM API failures
32- **Custom Prompts**: Supports custom review prompts while preserving XML response format
33 
34### Environment Variables
35 
36The action expects these environment variables (set automatically by GitHub Actions):
37- `GITHUB_TOKEN`: GitHub API access
38- `MODEL_PROVIDER`: "openai", "anthropic", or "gemini"  
39- `MODEL_NAME`: Specific model (e.g., "gpt-4o", "claude-3-sonnet-20240229")
40- `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`: Provider-specific keys
41- `CUSTOM_PROMPT`: Optional custom review prompt
42- `GITHUB_REPOSITORY`: Owner/repo format
43 
44### TypeScript Configuration
45 
46- Target ES2020 with CommonJS modules for Node.js 20+ compatibility
47- Strict typing enabled with declaration files
48- Uses `@vercel/ncc` for single-file bundling in `dist/index.js`