Project Setup

Learn

Setting Up CLAUDE.md

The first step for any Claude Code workflow: a clear CLAUDE.md that gives the agent context. For our review project, we define build commands, code style rules, and review standards.

Create a CLAUDE.md in the project root:

# Review Workflow Project

## Build & Test
- `npm test` for tests
- `npm run lint` for linting

## Code Style
- TypeScript strict mode
- Prettier for formatting
- ESLint with recommended rules

## Review Rules
- Every PR needs at least tests
- No TODO comments in main
- Security-relevant changes need a second review
- Maximum function length: 50 lines

iWhy Review Rules in CLAUDE.md?

Claude Code reads CLAUDE.md at every start. When you define review standards here, the review agent automatically knows your team's rules -- without you having to repeat them in every prompt.

.claude/ Directory Structure

Our workflow needs a well-thought-out directory structure. Here's the complete layout:

.claude/
├── CLAUDE.md              # Local additions (git-ignored)
├── settings.json          # Hooks and permissions
├── skills/
│   └── review/
│       └── SKILL.md       # Review skill definition
├── agents/
│   └── code-reviewer.md   # Specialized review agent
└── hooks/
    └── pre-commit-check.sh

!Project-Wide vs. Local Configuration

The CLAUDE.md in the project root is committed to the repository and applies to all team members. Files under .claude/ can contain both project-wide (committed) and local (git-ignored) configurations. Sensitive data like API keys should never go into the repository.

Connecting MCP Server

For access to GitHub PRs, we connect the GitHub MCP server. Create an .mcp.json in the project root:

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

This allows Claude Code to directly access GitHub data: read PRs, analyze diffs, and write review comments.

Where is the MCP server configuration for a project stored?

Understand

Creating the Agent Definition

The core of our workflow is a specialized code review agent. Create the file .claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Reviews code changes for quality and best practices
tools: Read, Grep, Glob, Bash
model: sonnet
maxTurns: 30
---

You are an experienced code reviewer. Your task is to systematically
review code changes.

## Review Criteria

1. **Bugs** -- Logic errors, missing error handling, race conditions
2. **Security** -- SQL injection, XSS, insecure dependencies, hardcoded secrets
3. **Performance** -- Unnecessary loops, missing indexes, memory leaks
4. **Readability** -- Naming, comments, function length, DRY principle

## Output Format

Provide your feedback in this format:

### [CRITICAL/WARNING/INFO] Title

**File:** `path/to/file.ts:line`
**Problem:** Description
**Suggestion:** Solution

Note the key configuration options:

model: sonnet -- Sonnet offers the best balance of quality and cost for code reviews. For particularly critical reviews, you can switch to Opus.
maxTurns: 30 -- Limits the number of iterations to prevent infinite loops and uncontrolled costs.
tools -- The agent only gets the tools it needs for reviews: reading files, searching code, and running shell commands.

*Model Choice by Task

For standard reviews, Sonnet is more than sufficient. Reserve Opus for security-relevant changes or architectural decisions. Haiku is suitable for quick syntax checks and formatting reviews.

Apply

Now create the directory structure in your project:

mkdir -p .claude/skills/review
mkdir -p .claude/agents
mkdir -p .claude/hooks

Then create the three files: CLAUDE.md in the project root, .mcp.json for the GitHub MCP server, and .claude/agents/code-reviewer.md for the review agent. In the next section, we'll connect everything with skills and hooks.

Reflect

The setup is the foundation for everything that follows. A good CLAUDE.md means the agent knows your rules. A clear agent definition ensures consistent reviews. And the MCP connection gives the agent access to the data it needs. Take your time with this step -- a solid foundation makes everything else easier.