code-review
Code review methodology and best practices
When & Why to Use This Skill
This Claude skill provides a comprehensive methodology and structured framework for conducting high-quality code reviews. It features detailed checklists covering correctness, design, maintainability, performance, and security, alongside professional feedback guidelines and comment templates designed to improve software quality and foster a constructive engineering culture.
Use Cases
- Standardizing Team Workflows: Implement a consistent review process across development teams using the structured checklist to ensure no critical edge cases or security vulnerabilities are missed.
- Mentoring and Professional Growth: Use the constructive feedback guidelines and 'Question' templates to provide educational critiques that help junior developers improve without discouraging them.
- Prioritizing Fixes: Apply the defined severity levels (Critical to Low) to clearly communicate which issues must block a merge and which are merely optional suggestions.
- Streamlining Pull Requests: Utilize the step-by-step review workflow to efficiently move from understanding high-level architecture to detailed line-by-line analysis, reducing the time spent on manual reviews.
| name | code-review |
|---|---|
| description | Code review methodology and best practices |
Code Review Methodology
Objective
Conduct thorough, constructive code reviews that improve code quality while respecting developer time and effort.
Review Checklist
Correctness
- Logic is correct and handles edge cases
- Error handling is appropriate
- Boundary conditions are handled
- Concurrent access is safe (if applicable)
Design
- Code follows existing patterns
- Abstractions are appropriate
- Dependencies are justified
- Interface is intuitive
Maintainability
- Code is readable and self-documenting
- Names are clear and consistent
- Complexity is manageable
- Comments explain "why" not "what"
Performance
- No obvious inefficiencies
- Resource usage is reasonable
- Scaling considerations addressed
Security
- Input is validated
- Output is properly encoded
- Sensitive data is protected
- Authentication/authorization is correct
Testing
- Tests cover new functionality
- Edge cases are tested
- Tests are maintainable
- Test names are descriptive
Feedback Guidelines
Constructive Feedback
DO:
- Explain the "why" behind suggestions
- Provide examples or alternatives
- Acknowledge good practices
- Use questions to prompt thinking
DON'T:
- Make personal comments
- Use dismissive language
- Demand changes without explanation
- Focus on minor style issues
Severity Levels
| Level | Description | Action Required |
|---|---|---|
| Critical | Security vulnerability, data loss risk | Block merge |
| High | Significant bug, major design flaw | Request changes |
| Medium | Code smell, minor issue | Suggest fix |
| Low | Nitpick, optional improvement | Comment only |
Comment Templates
Bug Found:
🐛 Bug: [description]
This could cause [impact] when [condition].
Suggested fix:
[code example]
Design Suggestion:
💡 Suggestion: [brief description]
Consider [alternative approach] because [reasoning].
This would [benefit].
Question:
❓ Question: [question]
I'm trying to understand [context]. Could you explain [specific aspect]?
Review Workflow
Understand Context
- Read PR description
- Understand the goal
- Check related issues/docs
High-Level Review
- Architecture and design
- Overall approach
- Major concerns
Detailed Review
- Line-by-line analysis
- Edge cases
- Error handling
Final Assessment
- Summarize findings
- Provide verdict
- Suggest next steps