/Alonso-pixel/claude-code-showcase

Wiki directory

Browse AI-generated documentation for any repository.

Example: The Code Review Agent

Relevant source files

The following files were used as context for generating this wiki page: - [.claude/agents/code-reviewer.md](https://github.com/Alonso-pixel/claude-code-showcase/blob/HEAD/.claude/agents/code-reviewer.md) - [README.md](https://github.com/Alonso-pixel/claude-code-showcase/blob/HEAD/README.md) - [.github/workflows/pr-claude-code-review.yml](https://github.com/Alonso-pixel/claude-code-showcase/blob/HEAD/.github/workflows/pr-claude-code-review.yml) - [.claude/commands/pr-review.md](https://github.com/Alonso-pixel/claude-code-showcase/blob/HEAD/.claude/commands/pr-review.md) - [CLAUDE.md](https://github.com/Alonso-pixel/claude-code-showcase/blob/HEAD/CLAUDE.md)

The Code Review Agent is a specialized AI assistant designed to automate deep code reviews within the project. It acts as a proactive quality gate, ensuring that all code changes adhere to the project's established conventions, patterns, and quality standards before they are merged. The agent is defined in .claude/agents/code-reviewer.md and is primarily executed through a GitHub Actions workflow.

This system is a key part of the project's MLOps strategy, offloading repetitive and detailed review tasks to an automated process. It provides consistent feedback, checks for common issues like missing error handling or improper state management, and enforces TypeScript best practices. This allows human reviewers to focus on higher-level architectural and logical concerns.

Sources: README.md:19-21, .claude/agents/code-reviewer.md

Architecture and Integration

The Code Review Agent is not a standalone service but is integrated into the development lifecycle through GitHub Actions. The primary integration point is the pr-claude-code-review.yml workflow, which triggers the agent on pull request events.

Sources: README.md:22-23, .github/workflows/pr-claude-code-review.yml

Automated PR Review Workflow

The agent is invoked automatically when a pull request is opened, synchronized, or reopened. It can also be manually triggered by adding a comment containing @claude to a pull request.

The following diagram illustrates the GitHub Action workflow:

Generating architecture diagram...

This diagram shows the events that trigger the review job, which then executes the Claude Code Action to run the agent's review process.

Sources: .github/workflows/pr-claude-code-review.yml:2-13, .claude/agents/code-reviewer.md:11-13

The core of the workflow is the anthropics/claude-code-action step, which is configured to use the code-reviewer.md agent definition.

- uses: anthropics/claude-code-action@beta
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    model: claude-opus-4-5-20251101
    prompt: |
      Review this PR using .claude/agents/code-reviewer.md standards.
      Run `git diff origin/main...HEAD` to see changes.

Sources: .github/workflows/pr-claude-code-review.yml:20-26

Agent Configuration

The agent's behavior, identity, and capabilities are defined in the .claude/agents/code-reviewer.md file using YAML frontmatter.

Field	Value	Description
`name`	`code-reviewer`	The unique identifier for the agent.
`description`	`Reviews code for quality, security, and conventions. Use after writing or modifying code.`	Explains the agent's purpose and when it should be used.
`model`	`opus`	Specifies the Anthropic model to be used for the review task.

Sources: .claude/agents/code-reviewer.md:2-5

Agent Process and Checklist

The agent follows a systematic process defined in its system prompt. The core of this process is a detailed checklist that covers multiple aspects of code quality.

Internal Review Process

The agent's internal logic is straightforward:

Analyze Changes: It first runs git diff to understand the scope of the changes in the pull request.
Apply Checklist: It systematically goes through its predefined checklist, comparing the code changes against each item.
Provide Feedback: It synthesizes its findings into a structured review, which is then posted as a comment on the pull request.

Sources: .claude/agents/code-reviewer.md:11-13

Core Review Checklist

The agent's review is guided by a comprehensive checklist. This checklist is derived from the project's overall coding standards, such as those found in CLAUDE.md.

Category	Checklist Item	Source Rule
TypeScript	No `any` type used.	`CLAUDE.md:23`
Error Handling	Error handling is present and does not swallow errors silently.	`CLAUDE.md:31-33`
UI States	Loading, error, and empty states are handled for UI components.	`CLAUDE.md:35-38`
Mutations	Asynchronous operations disable buttons and show loading indicators.	`CLAUDE.md:40-42`
Testing	Tests are included for new logic or behavior.	`CLAUDE.md:44-47`
Code Style	Adheres to project code style (e.g., early returns).	`CLAUDE.md:25`
Security	No obvious security vulnerabilities (e.g., hardcoded secrets).	`.claude/agents/code-reviewer.md:19`
Readability	Code is clear, well-commented, and easy to understand.	`.claude/agents/code-reviewer.md:20`

Sources: .claude/agents/code-reviewer.md:15-22, CLAUDE.md:21-47

Manual Invocation

Besides the automated PR workflow, developers can manually invoke a review using the /pr-review command. This command is defined in .claude/commands/pr-review.md and provides a way to trigger a review on demand.

The command's instructions are simple:

---
description: Reviews the current PR using the code-reviewer agent.
allowed-tools: Bash(git:*)
---

# PR Review

Your task is to perform a code review on the current pull request.

1.  Use the `code-reviewer` agent to perform the review.
2.  Run `git diff origin/main...HEAD` to get the changes.
3.  Provide a summary of your findings.

This provides a consistent interface for both automated and manual reviews, ensuring the same quality standards are applied in both scenarios.

Sources: .claude/commands/pr-review.md:1-10

Summary

The Code Review Agent is a powerful automation tool that enforces code quality and consistency across the project. By integrating directly into the GitHub pull request lifecycle, it provides immediate, detailed, and standardized feedback. This reduces the manual burden on developers, catches common errors early, and ensures that all code contributions align with the project's best practices as defined in documents like CLAUDE.md and various skill files.

Sources: README.md:19-21, 28-29