code-review
Reviews code changes for architectural fitness, extensibility, and alignment with design principles. Use when reviewing code, checking PRs, or validating implementations.
When & Why to Use This Skill
This Claude skill provides automated, high-level code reviews focused on architectural fitness, extensibility, and strict adherence to design principles. It helps developers maintain clean codebases by identifying 'hacks,' ensuring proper error handling, and validating that new implementations align with established system abstractions, particularly in complex C++ environments.
Use Cases
- Pull Request (PR) Validation: Automatically check incoming code changes for architectural consistency and the use of proper abstractions before merging into the main branch.
- Architectural Debt Detection: Identify and flag 'patch-like' solutions or feature-specific workarounds that could hinder future scalability and system maintainability.
- Compliance with Design Guidelines: Ensure all code follows project-specific principles such as 'Parameterize, Don't Specialize' and 'Unify Before Multiplying' to prevent code duplication.
- Error Handling Audits: Verify that the correct exception types (e.g., DiagnosticException vs. InternalError) are used according to the project's technical documentation and source location requirements.
- Low-Level System Review: Evaluate changes to Intermediate Representation (LIR) or compiler backends to ensure they follow the correct mental model for variable access and register-based operations.
| name | code-review |
|---|---|
| description | Reviews code changes for architectural fitness, extensibility, and alignment with design principles. Use when reviewing code, checking PRs, or validating implementations. |
Code Review
Early-stage C++ compiler project. Primary goal: keep architecture clean and extensible.
Review Checklist
1. Architecture and Extensibility
- Does the change fit the intended structure and boundaries?
- If it doesn't fit existing abstractions, should we generalize the design?
- Will this scale as we add more features?
2. No Hacks or Special Cases
- Avoid patch-like solutions with feature-specific workarounds
- No scattered conditional logic ("just for this feature")
- If forcing something in, consider a better abstraction
3. Use Existing Utilities
- Don't reinvent what standard library or codebase already provides
- Use modern C++ when it improves clarity (not for fancy)
4. Error Handling
Check docs/error-handling.md for correct error type usage:
DiagnosticExceptiononly in AST→MIR (with source location)InternalErrorfor compiler bugs (MIR→LIR, codegen, unreachable code)std::runtime_errorfor interpreter/SDK runtime failures- Never use
std::unreachable()orDiagnosticException({})
5. Design Principles Alignment
Read docs/design-principles.md and check:
- No Workarounds
- Parameterize, Don't Specialize
- Capture Behavior at the Source
- Unify Before Multiplying
- Follow Established Patterns
- Use Domain Vocabulary
- Comments Explain Why, Not What
6. LIR Design (if touching LIR)
Check that LIR changes follow the correct mental model (see docs/architecture.md):
- Variable access: uses slang's flat symbol model (symbol = unique address, no instance traversal)
- Operations: RISC-V assembly style (register-based, explicit data flow)
- Method calls on complex types: RISC-V function call style (object pointer as
this)
Output Format
- Summary: One sentence on what the change does
- Architecture: Impact on system structure, potential issues
- Concerns: Hacky patterns, violations of design principles
- Suggestions: Better abstractions if needed