| name | code-review |
| description | Reviews code changes for quality, conventions compliance, performance, and security. Triggers: review, check, validate, inspect, audit code quality. Source-code read-only — never modifies source code or test files. Outputs review report to output/reports/review/ (requires Write permission to output/reports/review/). Takes optional argument: /code-review <target-file or instruction>
|
| argument-hint | <target-file or instruction> |
| allowed-tools | Read, Glob, Grep, Bash(git *), Write(output/**), WebSearch, WebFetch, mcp__context7__resolve-library-id, mcp__context7__query-docs |
| context | fork |
Code Review
A skill that reviews project code changes.
Provides structured feedback based on CLAUDE.md conventions and the project-specific checklist in docs/development-patterns.md.
Prerequisites
| Reference File | Purpose | Fallback When Stub |
|---|
docs/architecture.md | Architecture pattern | Refer directly to project-config.md §4 |
docs/development-patterns.md | Code conventions, anti-patterns | Refer directly to project-config.md §11 |
Core Principles
- Never modify source code (read-only)
- Findings must be specific and actionable (no "just feels off")
- State severity clearly (MUST / SHOULD / CONSIDER)
- Mention good points as well (don't make it findings-only)
- Verify compliance with specification requirements (task file) as the top priority
Usage
/code-review <target-file or review instruction>
Arguments are optional. When omitted, review the scope of changes from git diff.
When a file path is specified, review changes in that file.
Examples
/code-review Review the latest commit
/code-review src/features/assignment/
/code-review output/tasks/TASK_auth.md
Output Destination
- Default: Present report in conversation
- File output:
output/reports/review/REVIEW_<target>.md (when output/ directory exists)
Integration with Other Skills
| Previous Step | This Skill | Next Step |
|---|
/implementing-features /ui-ux-design /refactoring | /code-review | (Final step) |
Review Workflow
- Understand Change Scope — Review the list of changed files and understand the impact scope
- Spec Verification — Cross-check task file acceptance criteria against the implementation
- Perspective-Based Checks — Check against the review perspectives below
- Report Output — Return structured feedback in the format below
Review Perspectives
1. Spec Compliance
- Are all acceptance criteria from the task file met?
- Are there features added that are not in the specification?
- Are data model changes as specified?
2. Code Quality & Readability
- Do names express intent (variables, functions, components)?
- Does each function have a single responsibility?
- Are there unnecessary code fragments or commented-out code?
- Are type definitions appropriate (use of
any, unnecessary assertions)?
3. Architecture Compliance
- Does it follow the project's architecture pattern (see
docs/architecture.md)?
- Is state management used correctly (see docs/development-patterns.md)?
- Are schemas and types consistent?
- Are path aliases used?
- Are there dependency direction rule violations (see
CLAUDE.md "Architecture Governance")?
4. Performance
- Is memoization used appropriately (neither excessive nor insufficient)?
- Are there anti-patterns documented in
docs/development-patterns.md related to performance?
- Are unnecessary re-renders avoided?
5. Security
- XSS: No unsafe HTML injection?
- Input sanitization/validation?
- No violations of
project-config.md section 10 security policy?
6. Dark Mode Support
- Are color specifications compatible with both light/dark?
- Are there no hardcoded color values?
7. Testing
- Do important logic paths have unit tests?
- Do tests verify specification behavior (not implementation details)?
- Do test description texts clearly state the behavior?
8. Backward Compatibility
- Is migration of existing data considered?
- Are schema changes optional or have default values?
- Are existing public interfaces preserved?
9. Documentation Sync
- Has
docs/ been updated to reflect implementation changes?
- If documentation is not updated, report as a MUST finding
10. Quantitative Measurement (Eval / Metrics)
Objectifies gate 5 (verification complete) with quantitative data. This skill is read-only, so it does not execute measurement commands — instead it aggregates existing measurement artifacts, CI logs, or data presented by the parent session.
| Metric | Source | NG Threshold |
|---|
| Coverage delta | testreport/coverage/ or CI output | Below target in project-config.md §6 |
| Static analysis error delta | Lint output / CI logs | 1+ new error introduced |
| Bundle size delta | Build output / CI logs | Exceeds threshold (when defined in project-config.md §6) |
| Performance metrics delta | /performance output / testreport/ | Regression vs baseline |
| Test failure count | CI logs | 1+ |
- If measurement data is not provided and
project-config.md §6 defines criteria → emit a CONSIDER finding ("Please attach gate 5 verification data")
- Improvements in measurement data (coverage uplift, etc.) should be called out in "Good Points"
- See
@.claude/quality-gates.md for details
Output Contract
Section Definitions
| Section | Required | Constraints |
|---|
| Overview | ✅ | Must include changed file count, impact scope, spec compliance, doc sync |
| Findings | ✅ | In MUST → SHOULD → CONSIDER order. Keep headings even when 0 items per level |
| Good Points | ✅ | Minimum 1 item. Don't make it a findings-only review |
| Overall Verdict | ✅ | Select one from enumeration values |
Severity Definitions
| Level | Criteria | Examples |
|---|
| MUST | CLAUDE.md rule violation, existing test breakage, security vulnerability, dependency direction violation, docs/ not updated | Anti-pattern usage, hardcoded color values, XSS |
| SHOULD | Readability degradation, performance concerns, insufficient tests, inappropriate naming | Missing memoization, any type usage, insufficient test coverage |
| CONSIDER | Improvement suggestions, alternative approaches, code cleanup | Function extraction suggestion, type definition cleanup |
Overall Verdict Enumeration
| Verdict | Condition |
|---|
| Approved | 0 MUST findings |
| Conditionally Approved (After MUST Fixes) | 1+ MUST findings that are fixable |
| Needs Revision | Architecture changes or design overhaul needed |
Finding Description Format
- [ ] `file-path:line-number` Finding description. **Reason**: Rationale. **Fix Suggestion**: Specific fix method.
- File path is relative from
src/
- Line number must not be omitted (for ranges use
L10-L15)
- MUST/SHOULD must include a fix suggestion. CONSIDER is optional
Vocabulary Constraints
| Term | Definition |
|---|
| Spec Compliance | All acceptance criteria from the task file are met |
| Documentation Sync | Updates to docs/ corresponding to implementation changes are complete |
| Dependency Direction Violation | Breach of rules in CLAUDE.md "Architecture Governance" |
Report Format
# Code Review: [Change Overview]
## Overview
- Changed Files: X
- Impact Scope: [Feature name]
- Spec Compliance: OK / NG
- Documentation Sync: OK / NG
## Quantitative Measurement (optional / gate 5 evidence)
| Metric | Before | After | delta | Source |
| ------ | ------ | ----- | ----- | ------ |
| Coverage | XX.X% | YY.Y% | +ΔΔ% | testreport/coverage |
| Static analysis errors | N | M | -K | npm run lint |
| Bundle size | XX KB | YY KB | +ΔΔ% | npm run build |
| Performance metrics | XX ms | YY ms | +ΔΔ% | output/reports/performance / testreport |
| Test failures | N | M | -K | CI logs / testreport |
> When no data is provided, write `_no measurement data provided_` for this section
## Findings
### MUST (Required Fixes)
- [ ] `file:line` Finding. **Reason**: Rationale. **Fix Suggestion**: Fix method.
### SHOULD (Recommended Fixes)
- [ ] `file:line` Finding. **Reason**: Rationale. **Fix Suggestion**: Fix method.
### CONSIDER (For Consideration)
- [ ] `file:line` Finding. **Reason**: Rationale.
## Good Points
- [Specific positive points]
## Overall Verdict
- **Approved** / **Conditionally Approved (After MUST Fixes)** / **Needs Revision**
Prohibited Actions
- Modifying source code (including test files)
- Requesting additions not in the specification
- Findings based on personal preference (without project convention rationale)
- Vague findings without severity
Related references (loaded on demand by Claude)
@.claude/guardrails.md
@.claude/rules/workflow-advanced.md
@.claude/pitfalls.md
