## Curation Note Automated code review has become standard in enterprise engineering workflows. Claude Opus 4.5's "thoughtful reviewer" capability stands out because it understands intent and context rather than merely flagging syntax violations. This skill distills best practices from the obra/superpowers collection and trending Reddit discussions about effective AI-assisted reviews. The key insight: structured checklists combined with contextual reasoning produces reviews that developers actually find useful. ## Review Framework ### Phase 1: Context Understanding Before reviewing code, understand the change: ``` 1. What problem does this PR solve? 2. What is the scope of changes? 3. Are there related issues or documentation? 4. What tests were added or modified? 5. What areas require domain expertise? ``` ### Phase 2: Structured Review Checklist #### Code Quality ``` □ Code is readable and self-documenting □ Functions/methods have single responsibility □ No obvious code duplication □ Variable/function names are descriptive □ Comments explain "why" not "what" □ No dead code or commented-out blocks □ Appropriate error handling □ Consistent code style ``` #### Security ``` □ No hardcoded credentials or secrets □ User input is validated and sanitized □ SQL queries use parameterization □ Authentication/authorization checks present □ Sensitive data is not logged □ HTTPS enforced for external calls □ No path traversal vulnerabilities □ Rate limiting considered for APIs ``` #### Performance ``` □ No N+1 database queries □ Expensive operations are cached appropriately □ No memory leaks (event listeners, closures) □ Pagination for large data sets □ Async operations used where beneficial □ No blocking operations in hot paths ``` #### Testing ``` □ New code has corresponding tests □ Edge cases are covered □ Tests are deterministic (no flaky tests) □ Mocks are used appropriately □ Test names describe behavior □ Integration tests for critical paths ``` #### Architecture ``` □ Changes align with existing patterns □ Dependencies are appropriate □ No circular dependencies introduced □ API contracts are maintained □ Breaking changes are documented □ Configuration is externalized ``` ### Phase 3: Providing Feedback #### Feedback Categories Use prefixes to clarify feedback importance: - **🔴 BLOCKER:** Must be fixed before merge - **🟡 SUGGESTION:** Recommended improvement - **🟢 NITPICK:** Minor style preference - **💡 QUESTION:** Seeking clarification - **👍 PRAISE:** Highlighting good practices #### Example Review Comments **Security Issue (Blocker):** ```` 🔴 BLOCKER: SQL Injection vulnerability The query concatenates user input directly: ```python query = f"SELECT * FROM users WHERE id = {user_id}" ```` Fix by using parameterized queries: ```python query = "SELECT * FROM users WHERE id = %s" cursor.execute(query, (user_id,)) ``` ``` **Performance Suggestion:** ``` 🟡 SUGGESTION: Consider caching this API response This endpoint is called frequently but the data changes rarely. Adding a 5-minute cache could significantly reduce database load. ```python @cache.memoize(timeout=300) def get_categories(): return Category.query.all() ``` ``` **Clarifying Question:** ``` 💡 QUESTION: Intentional behavior? The function returns `None` when the list is empty, but returns `[]` when results are filtered out. Is this inconsistency intentional for the caller? ``` **Positive Feedback:** ``` 👍 PRAISE: Clean separation of concerns Really like how you extracted the validation logic into its own module. This makes testing much easier and the main handler more readable. ```` ## Automated Review Workflow ### GitHub Actions Integration ```yaml name: AI Code Review on: pull_request: types: [opened, synchronize] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - name: Get changed files id: changed run: | echo "files=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | tr '\n' ' ')" >> $GITHUB_OUTPUT - name: Run AI Review env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} run: | python scripts/ai_review.py ${{ steps.changed.outputs.files }} ```` ### Review Script Pattern ```python def review_pr(files: list[str]) -> list[Comment]: comments = [] for file in files: diff = get_file_diff(file) analysis = analyze_code_changes(diff) for check in REVIEW_CHECKS: issues = check.run(analysis) comments.extend(issues) return prioritize_comments(comments) ``` ## Review Personas Adopt different perspectives during review: ### The Security Auditor Focus exclusively on security implications. Assume inputs are malicious. ### The Performance Engineer Look for bottlenecks, memory issues, and scalability concerns. ### The Maintainer Consider: "Will I understand this code in 6 months?" ### The New Team Member Is the code approachable? Are there assumptions that need documentation? ## Best Practices 1. **Review in small batches** - Large PRs get superficial reviews 2. **Start with tests** - Tests reveal intended behavior 3. **Run the code** - Static analysis misses runtime issues 4. **Be constructive** - Suggest solutions, not just problems 5. **Acknowledge good work** - Balance criticism with praise 6. **Ask questions** - Assumptions are often wrong 7. **Check the context** - Understand why before critiquing how 8. **Timebox reviews** - Deep reviews lose focus after 30-60 minutes ## Related Resources - [Google Code Review Guidelines](https://google.github.io/eng-practices/review/) - [Conventional Comments](https://conventionalcomments.org/) - [The Code Review Pyramid](https://www.morling.dev/blog/the-code-review-pyramid/)