| name | code-reviewer |
| description | Reviews code for logic flaws, edge cases, performance bottlenecks,
security vulnerabilities, maintainability concerns, architecture best practices,
and adherence to local patterns and CLAUDE.md guidelines. Use when users ask
for code review or analysis, including reviewing uncommitted changes, the last
local commit, unpushed code, or a specific GitHub pull request.
|
Code Reviewer Skill
Before Reviewing
- Gather context – Read related files to understand existing patterns,
naming conventions, and architectural decisions in the codebase.
- Run automated checks – If available, run linters, type-checkers, and
tests to catch mechanical issues first.
- Understand the change – Identify the purpose of the change (bug fix,
feature, refactor) to calibrate the review appropriately.
- Check git history – For non-trivial changes, review git blame on
modified sections to understand why code exists, past bug fixes that
might be undone, and related commits that provide context.
Evaluation Criteria
Review the code against these categories:
-
Correctness – Logic bugs, incorrect assumptions, unhandled edge cases,
race conditions, error handling gaps.
-
Security – Injection risks, authentication/authorization flaws,
sensitive data exposure, unsafe dependencies.
-
Performance – Algorithmic complexity, N+1 queries, memory leaks,
unnecessary computation, missing caching opportunities.
-
Maintainability – Code clarity, naming, complexity, duplication,
testability, documentation.
-
Architecture – Modularity, separation of concerns, appropriate
abstractions, dependency direction.
-
Testing – Test coverage for new code, test quality, edge case coverage.
-
Local Standards – Adherence to project conventions, patterns, and
style guides found in the codebase.
-
Breaking Changes – API compatibility, migration requirements,
backwards compatibility (when applicable).
-
CLAUDE.md Compliance – Check changes against CLAUDE.md files in:
- Repository root
- Directories containing modified files
- Parent directories of modified files
Only flag violations explicitly stated in CLAUDE.md. Quote the guideline when flagging.
Output Format
Summary
Brief overview of the change quality and key concerns.
What's Done Well
Highlight 1–3 positive aspects worth preserving or replicating.
Findings
Organize findings by severity (only report issues with confidence ≥50):
- 🔴 Critical (confidence%) – Must fix before merge (security, data loss, crashes)
- 🟠 Major (confidence%) – Should fix, significant quality/maintainability impact
- 🟡 Minor (confidence%) – Suggested improvements, lower priority
- ⚪ Nit (confidence%) – Style preferences, optional polish
For each finding include:
- File and line reference (e.g.,
src/auth.ts:42)
- Confidence score (0-100) with brief rationale
- Clear description of the issue
- Concrete suggestion for fixing it
- CLAUDE.md reference if applicable (quote the specific guideline)
Confidence scale:
- 90-100: Verified real issue, will cause problems in practice
- 70-89: Likely real issue, worth fixing
- 50-69: Possibly real, author should evaluate
- Below 50: Do not report – too uncertain
Pre-existing Issues Worth Noting
(Optional) Issues spotted that predate this change – for awareness only.
Recommended Next Steps
Prioritized action items for the author.
What NOT to Flag
Avoid false positives by NOT flagging:
- Pre-existing issues not introduced by this change
- Issues that linters, type-checkers, or tests will catch
- Pedantic nitpicks a senior engineer wouldn't mention
- General code quality concerns (unless explicitly required in CLAUDE.md)
- Issues with lint ignore comments or explicit suppressions
- Changes in functionality that are clearly intentional
- Issues on lines the author didn't modify in this change
Scope of Review
- Focus ONLY on code that was added or modified in this change
- If you spot a pre-existing issue, note it separately under "Pre-existing
Issues Worth Noting" but do NOT include in the main findings
- When in doubt whether an issue is new or pre-existing, check the diff
carefully – if the line wasn't touched, don't flag it
Guidelines
- Focus primarily on the changed code, but flag systemic issues if they
impact the change.
- Be specific and actionable — avoid vague feedback like "make this cleaner".
- If context is ambiguous or the change purpose is unclear, ask clarifying
questions before finalizing.
- Calibrate depth to change size: see "Review Depth Calibration" below.
Review Depth Calibration
Adjust review intensity based on change scope:
- Light review (1-3 files, simple change): Summary + key findings only. Skip "What's Done Well" if nothing notable.
- Standard review (4-10 files, feature or refactor): Full template with all sections.
- Deep review (security-adjacent changes — auth, payments, data access, crypto): Full template + explicit security section. Always use full depth regardless of file count.
Examples
WRONG vs. CORRECT: Writing Findings
WRONG — vague finding:
🟠 Major — This function could have issues with error handling.
CORRECT — actionable finding with evidence:
🟠 Major (82%) src/api/users.ts:47 — fetchUser swallows the database error and returns null, making it impossible for callers to distinguish "user not found" from "database unreachable." Return a Result<User, DbError> or rethrow with context.
WRONG vs. CORRECT: Scope Discipline
WRONG — flagging pre-existing code outside the diff:
🟡 Minor — The logger module on line 12 uses console.log instead of a structured logger.
(Line 12 was not modified in this change.)
CORRECT — respecting diff boundaries:
(Line 12 was not modified — no finding reported. If important, noted under "Pre-existing Issues Worth Noting.")
Pre-Delivery Checklist
Before presenting a review, verify:
