Santiago.

🔒 A lock for vibe coding: a PR reviewer with Claude

October 3, 2026 · 7 min read

I'm working on a project and something happened that I really liked: Claude, running inside GitHub Actions, reviewed and fixed my pull requests (PRs). It felt great and very efficient, so much so that I wanted to understand how it works and share it here. To me it's like a lock 🔒 for vibe coding: it lets you move fast, but makes sure nothing slips through.

🧠 The problem: the agent loses context

When you code with AI, what is already known as vibe coding (telling the AI what you want and letting it write the code, often accepting it without reading it closely), the agent you're programming with sometimes gets lost in the small stuff. However much you try to always give it context, as the session grows longer it loses it, and some things slip through: a business rule, an edge case, a file that also depended on what changed.

The reviewer works differently. It starts every time with a clear head and a single mission: review that pull request. It doesn't carry hours of conversation, which is why, in my experience, it is much more efficient at finding what the coding agent let slip.

🤖 What is it?

Claude Code GitHub Actions is a GitHub Action (anthropics/claude-code-action) that runs Claude Code inside your repository's workflows. It works in two ways:

  • Interactive: you mention @claude in a PR or issue comment and it replies right there.
  • Automatic: you give it a prompt and it runs on its own when something happens in the repository, for example every time a pull request is opened.

For a reviewer, the second one is what we want.

One difference to keep in mind: the reviewer we set up below comments, it does not modify code. If you also want Claude to make the fix, you mention it with @claude, and for it to push changes the workflow needs write permissions (contents: write and pull-requests: write).

⚙️ How to set it up

⚡ The quick way. Open claude inside your repository and run /install-github-app. It installs the GitHub app, saves the authentication secret and leaves a pull request ready with the workflows. You need to be a repository admin, have the GitHub CLI authenticated (gh auth login), and the repository must be on github.com.

🛠️ The manual way. Three steps:

  1. Install the Claude app on your repository.
  2. Save a secret: ANTHROPIC_API_KEY (API key) or CLAUDE_CODE_OAUTH_TOKEN (if you use a subscription).
  3. Create a workflow in .github/workflows/.

This workflow reviews every pull request when it is opened or updated, using the official review plugin:

name: Code Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
          plugins: "code-review@claude-code-plugins"
          prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

What matters in each part:

  • on: pull_request: it triggers when a PR is opened, updated, reopened or marked as ready.
  • plugins and prompt: they install the code-review plugin and run its review on that PR.
  • --comment: Claude posts the review on the PR itself, with an inline comment for each problem, or a summary comment if it finds nothing. Without this option you would only see the result in the run log.
  • claude_args: keep this line, because it is what enables inline comments.
  • Claude skips draft PRs, closed ones, trivial ones and those that already have a comment from it.

🎯 What matters most: the reviewer's prompt

This is the difference between a reviewer that only makes noise and one that really helps you. The quality of the reviewer depends largely on the prompt you give it. The official plugin already comes with its own, but if you want a reviewer that knows your business and your architecture, you write yours (or a skill). From my experience, these are the things you need to give it:

  • 💼 Business context. What the product does and for whom, the critical flows and the rules that cannot be broken: how amounts are calculated, who can view or change what, which states are valid. Without this the reviewer only sees code; with it, it can see whether the code does what the business needs.
  • 🏗️ Architecture context. The layers and their responsibilities, the conventions, the patterns to respect and what is forbidden, for example putting business logic in controllers. If you have architecture documents or recorded decisions, point it to them.
  • 📋 What to review and in what order. First what costs the most: logic errors and edge cases, security, data integrity, the risk of breaking other parts, and missing tests.
  • 🚫 What to ignore. Formatting and style that the linter already checks, and personal preferences. Otherwise it fills your PR with noise.
  • 🔍 Look beyond the diff. Ask it to check who uses what changed, not just the modified lines. Many bugs are in what the diff doesn't show.
  • 💬 How to answer. Have it classify each finding (blocking, important or suggestion) and give the file and line, the impact and the proposed fix. Have it say so when it has a doubt instead of making things up, and, if everything is fine, say it in a single sentence.

A template to start with:

You are the senior reviewer of this repository. Review the current pull request.

Business context:
- What the product does and for whom.
- Critical rules: how amounts are calculated, who can view or modify
  what, valid states of each process.

Architecture context:
- Layers and responsibilities (API, services, data access).
- Conventions and patterns that must be respected.
- What is forbidden (for example, business logic in controllers).

What to review, in this order:
1. Logic errors and edge cases.
2. Security and handling of sensitive data.
3. Data integrity and transactions.
4. Risk of breaking other parts: check who uses what changed,
   not just the diff.
5. Missing tests.

What to ignore: formatting and style already checked by the linter, and
personal preferences.

How to answer:
- Classify each finding as blocking, important or suggestion.
- Give the file and line, explain the impact and propose the fix.
- If you are not sure, say it as a doubt; do not make things up.
- If everything is fine, say so in a single sentence.

Where to put it, depending on how you work:

  • In the workflow's prompt. With your own text, Claude has no access to the shell or the GitHub API until you grant the tools it needs with --allowedTools in claude_args. Also tell it which PR to review: the number comes in ${{ github.event.pull_request.number }}.
  • In a skill in the repository. You keep it in .claude/skills/, run the checkout first and pass /skill-name as the prompt. That way the prompt is versioned and reviewed like any other code.
  • In CLAUDE.md. This is the place for code style, review criteria and project rules. Claude reads it on every run. Keep it short, because it is read every time.

And don't expect it to be perfect the first time. See which false positives it gives you, what slips past it, and adjust the prompt. It is iterative work, like tuning any other tool.

🛡️ Things not to forget

  • 🔑 Secrets: never commit keys to the repository; store them as GitHub secrets.
  • 🔐 Minimal permissions: give the workflow only what it needs. In the example, read-only access to code, PRs and issues, plus id-token: write, which the Action needs to authenticate. If you want Claude to push fixes, it will need write access: grant it only to the workflow that requires it.
  • 💰 Costs: every run uses GitHub Actions minutes and API tokens (or your subscription, if you authenticate with an OAuth token). --max-turns, timeouts and concurrency controls help limit it.
  • 🌐 Public repositories: GitHub does not hand secrets to runs triggered by PRs from forks.
  • 🧑‍💻 You decide: the reviewer does not replace human judgment. Check its comments and Claude's changes before merging.

If you don't want to maintain a workflow, there is also Code Review, the Claude product that reviews every pull request automatically without you writing one.

💡 My takeaway

🔒 Vibe coding is powerful, but it needs its lock. To me, AI does not remove responsibility: it shares it better. I write with AI's help, a reviewer with a clear head and good context reviews, and I decide. That combination is what lets me move fast with peace of mind.

✍️ By Santiago Perea Restrepo

← Back