Claude Code Review

Review a pull request for critical issues and post findings to GitHub.

Invocation

/claude-code-review <PR number or URL>

Process

dot
1digraph code_review {
2    rankdir=TB;
3    node [shape=box, style=filled, fillcolor=lightblue];
4
5    parse [label="1. PARSE INPUT\nExtract PR number\nfrom arg or URL", fillcolor="#e6f3ff"];
6    details [label="2. GET PR DETAILS\nBranch, draft status,\nchanged files", fillcolor="#e6f3ff"];
7    draft [label="Draft PR?", shape=diamond, fillcolor="#fff3e6"];
8    skip [label="Skip — inform user", fillcolor="#ffcccc"];
9    prior [label="3. CHECK PRIOR REVIEW\nFind existing claude[bot]\ncomment", fillcolor="#ccccff"];
10    checkout [label="4. CHECKOUT\nSwitch to PR branch\nfetch latest", fillcolor="#e6ffe6"];
11    diff [label="5. REVIEW DIFF\nRead changed files\nAnalyze diff vs base", fillcolor="#ccffcc"];
12    verify [label="6. VERIFY\nRun tests, lint,\ntype checks", fillcolor="#ccccff"];
13    write [label="7. WRITE REVIEW\nCritical issues only\nMarkdown format", fillcolor="#ffe6f3"];
14    post [label="8. POST COMMENT\nUpdate or create\nPR comment", fillcolor="#f3e6ff"];
15    approve [label="9. FORMAL REVIEW\nApprove or\nrequest changes", fillcolor=lightgreen];
16
17    parse -> details;
18    details -> draft;
19    draft -> skip [label="yes"];
20    draft -> prior [label="no"];
21    prior -> checkout;
22    checkout -> diff;
23    diff -> verify;
24    verify -> write;
25    write -> post;
26    post -> approve;
27}

1. Parse Input

Extract the PR number from the argument. Accept:

• Bare number: 123
• URL: https://github.com/owner/repo/pull/123

bash
1# Get owner/repo from current repo
2REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')

2. Get PR Details

bash
1PR_DATA=$(gh api repos/{owner}/{repo}/pulls/{pr_number})
2HEAD_REF=$(echo "$PR_DATA" | jq -r '.head.ref')
3IS_DRAFT=$(echo "$PR_DATA" | jq -r '.draft')
4BASE_REF=$(echo "$PR_DATA" | jq -r '.base.ref')

3. Skip Draft PRs

If IS_DRAFT is true, inform the user and stop. Do not review draft PRs.

4. Check for Prior Review

Look for an existing comment from claude[bot] on the PR:

bash
1MARKER="<!-- claude-code-review -->"
2COMMENT_ID=$(gh api repos/{owner}/{repo}/issues/{pr_number}/comments \
3  --jq '[.[] | select(.user.login == "claude[bot]" and (.body // "" | contains("<!-- claude-code-review -->")))] | first | .id // empty')

Include <!-- claude-code-review --> as a hidden marker at the top of every review comment so the lookup targets only code review comments, not other bot comments.

If found, read the prior review to understand what was previously flagged. New commits may address those findings.

5. Checkout PR Branch

bash
1git fetch origin "$HEAD_REF"
2git checkout "$HEAD_REF"

6. Review the Diff

bash
1gh pr diff {pr_number}

Read all changed files in full context. Focus the review on:

Do NOT flag:

• Style/formatting preferences (that's what linters are for)
• Minor naming suggestions
• "Consider" or "you might want to" suggestions — only flag real issues

7. Verify — Run Tests, Lint, and Type Checks

Run the project's verification commands to surface issues that static reading might miss. This strengthens the review with concrete evidence.

Backend (Python):

bash
1make test        # Unit tests
2make flake8      # Lint

Frontend (TypeScript):

bash
1cd js && pnpm test          # Unit tests
2cd js && pnpm lint          # Biome lint
3cd js && pnpm type:check    # TypeScript type checking

Run whichever commands are relevant to the files changed in the PR. Include any failures or warnings as findings in the review — these are concrete evidence of issues, not speculation.

If tests or lint fail, note the specific failures in the review findings. Do NOT attempt to fix them — just report them.

8. Write the Review

Format the review in Markdown. Write to a temp file to avoid shell escaping issues.

If this is an updated review (prior comment found):

• Prefix with ## Updated Review
• Acknowledge findings from the prior review that have been fixed
• Note any issues that remain unaddressed
• Add any new findings from new commits

Structure:

markdown
1## Code Review — PR #{pr_number}
2
3### Summary
4One-line verdict: what this PR does and overall assessment.
5
6### Findings
7
8#### [Critical/Warning] Issue Title
9**File:** `path/to/file.ts:42`
10**Issue:** Description of the problem
11**Suggestion:** How to fix it
12
13(repeat for each finding)
14
15### Verdict
16- Approved or Issues Found with sign-off emoji

Use ### for each finding heading. Use Markdown section links for cross-references. Do not reference issues/PRs with bare #123 syntax in the review body (it creates unwanted GitHub links).

bash
1cat > /tmp/review_body.md << 'REVIEW_EOF'
2<your review content here>
3REVIEW_EOF

9. Post the Review

Update existing comment or create new one:

bash
1# If prior comment exists:
2gh api repos/{owner}/{repo}/issues/comments/{comment_id} \
3  -X PATCH -f body=@/tmp/review_body.md
4
5# If no prior comment:
6gh pr comment {pr_number} --body-file /tmp/review_body.md

Submit formal GitHub review:

bash
1# No critical issues:
2gh pr review {pr_number} --approve \
3  --body "Claude Code Review: No critical issues found."
4
5# Critical issues found:
6gh pr review {pr_number} --request-changes \
7  --body "Claude Code Review: Critical issues found. See review comment for details."

Known False Positives — Do NOT Flag

• React 19 APIs: This project uses React 19.x. Do NOT flag stable React 19 APIs (e.g., useActionState, useFormStatus, use(), <Activity>) as unknown or experimental if they are used consistently in the codebase.
• Project conventions: Respect patterns established in AGENTS.md and CLAUDE.md. If the codebase consistently uses a pattern, don't flag it.

Iron Rules

• No file modifications. Do NOT modify, create, or delete any files. This is a review, not a fix. Running tests, lint, and type checks is encouraged — editing code is not.
• Critical issues only. Do not waste reviewer time with style nits or "consider" suggestions.
• Temp file for posting. Always write review body to /tmp/review_body.md and use --body-file or cat. Never inline long text in shell commands.
• Every finding must cite a file and line. No vague "somewhere in the code" findings.
• Respect AGENTS.md and CLAUDE.md. Use them for project-specific guidance on what matters.
• Sign off clearly. End with approved or issues-found verdict so the PR author knows the status at a glance.