Review Skill
Systematic code review against project conventions, architecture rules, and best practices.
Philosophy: A good review doesn't just find bugs – it ensures that code
follows the project's conventions and remains maintainable long-term.
What This Skill Does
- Captures changes – Staged/unstaged changes, branch diff, or user-specified files
- Checks against rules – BCE architecture, lessons-learned, security, code quality, configuration, tests
- Creates report – Structured output with findings (Critical / Warning / Note) and positive feedback
- Offers fixes – After confirmation, findings can be corrected directly
How to Use
Check the code I changed
Review the changes on the current branch
Do a code review for src/main/java/com/example/
Instructions
Before every review:
- Read
.claude/lessons-learned.md
- Use references/review-checklist.md as the review catalog
Dynamic Context (automatically preloaded)
The following Git information is automatically injected on invocation:
- Staged changes: !
git diff --cached --name-only 2>/dev/null
- Unstaged changes: !
git diff --name-only 2>/dev/null
- Untracked files: !
git ls-files --others --exclude-standard 2>/dev/null
- Current branch: !
git branch --show-current 2>/dev/null
Step 1 – Capture Changes
If $ARGUMENTS was provided (e.g. /review src/main/java/), review those files/directories.
Otherwise, evaluate the dynamic context above – in this order:
| Priority |
Source |
| 1 |
$ARGUMENTS (explicitly provided files/directories) |
| 2 |
Staged changes (from dynamic context) |
| 3 |
Unstaged changes (from dynamic context) |
| 4 |
Branch diff against main: git diff main...HEAD --name-only |
Rules:
- If staged or unstaged changes exist → review those
- If no local changes but branch != main → review branch diff
- If no changes at all → ask user: which files or directories should be reviewed?
- Only review relevant files (Java, Properties, YAML, SQL, Dockerfile, docker-compose) – ignore generated files (target/, .class)
Read files: Read all changed files completely, not just the diff. Context is important for evaluation.
Step 2 – Perform Review
Check each changed file against the review catalog (references/review-checklist.md).
Review categories (summary):
2.1 Architecture (BCE)
- Classes in the correct layer? (
boundary/rest/, boundary/messaging/, control/, entity/)
- No direct repository calls from the boundary layer
- No REST/messaging logic in the entity layer
- Controller/Resource delegates to Service (Control), not to Repository (Entity)
2.2 Lessons-Learned Comparison
Check .claude/lessons-learned.md against the changed code:
| Rule |
Check |
@Blocking for Quarkus consumers |
@Incoming without @Blocking with DB access? |
| Flyway instead of ddl-auto |
ddl-auto=create or update in properties? |
| Health checks |
Actuator/SmallRye-Health dependency present? |
| Dev Services disabled |
Quarkus Dev Services still active? |
| Dockerfile convention |
Spring Boot → root, Quarkus → src/main/docker/ |
| RabbitMQ config |
Wrong property keys (quarkus.rabbitmq.* instead of rabbitmq-host)? |
2.3 Coding Standards
- Language: Comments/Javadoc in English, code (classes, methods, variables) in English
- Naming: Java conventions (CamelCase classes, camelCase methods, UPPER_SNAKE constants)
- Packages:
{{groupId}}.boundary.rest, {{groupId}}.control, {{groupId}}.entity
- Domain neutrality: No domain-specific names in templates
2.4 Security
- SQL injection: No string concatenation in queries (
"SELECT ... " + param)
- Input validation:
@Valid on controller/resource methods for request bodies
- Secrets: No hardcoded passwords, tokens, or keys in source code/properties
- CORS: Not
allowedOrigins("*") in production
- Security config: Swagger UI paths permitted, but not everything
permitAll()
2.5 Code Quality
- Unnecessary complexity or over-engineering
- Duplication (same logic in multiple places)
- Missing or incorrect exception handling
- Unused imports, dead code paths
- Lombok used sensibly (not overloaded)
2.6 Configuration
application.properties complete (DB, messaging, health, Flyway)
docker-compose.yml: Health checks for all services
- Flyway migration present for every new entity
versions-maven-plugin in the POM
renovate.json in the project root
2.7 Tests
- Architecture test (Taikai) present?
- New business logic (control layer) has unit tests?
- Test classes in the correct package?
Step 3 – Create Report
Result as structured Markdown output in the chat:
## Review Result
### Summary
- X files reviewed
- X findings (Y critical, Z warnings, W notes)
### Critical
| # | File | Line | Problem | Solution |
|---|------|------|---------|----------|
| 1 | ... | ... | ... | ... |
### Warning
| # | File | Line | Problem | Solution |
|---|------|------|---------|----------|
### Note
| # | File | Line | Problem | Solution |
|---|------|------|---------|----------|
### Positive
- What is well done (don't just look for bugs!)
Categorization:
| Category |
Criteria |
| Critical |
Security vulnerability, possible data loss, architecture violation, ddl-auto=create |
| Warning |
Convention violation, missing test, missing validation |
| Note |
Improvement suggestion, style, readability |
After the report: Ask if findings should be fixed directly.
Only fix after explicit confirmation – never automatically.
References
| File |
Description |
.claude/lessons-learned.md |
Findings and corrections – read before every review |
| references/review-checklist.md |
Detailed review catalog with rules per category |
Conventions
- The review skill does not change code without confirmation
- Give positive feedback – don't just list errors
- When uncertain, classify as note rather than critical
- No findings for generated code (target/, build/)
- Detect framework (Spring Boot vs. Quarkus) and apply appropriate rules
Position in Workflow
[spec-feature] optional – business requirements
|
[openapi] if OpenAPI spec needed
|
[java-scaffold] framework: DB, messaging, infra
|
[review] <-- code review
|
[doc] project documentation
1---2name: review-23description: Reviews changed or existing code against project conventions, architecture rules (BCE), and best practices. Automatically captures staged/unstaged changes or branch diffs. Use this skill for "review code", "check the code", "code review", "look at the code", "quality check" or when code should be reviewed before a commit or merge.4---56# Review Skill78Systematic code review against project conventions, architecture rules, and best practices.910> **Philosophy:** A good review doesn't just find bugs – it ensures that code11> follows the project's conventions and remains maintainable long-term.1213---1415## What This Skill Does16171. **Captures changes** – Staged/unstaged changes, branch diff, or user-specified files182. **Checks against rules** – BCE architecture, lessons-learned, security, code quality, configuration, tests193. **Creates report** – Structured output with findings (Critical / Warning / Note) and positive feedback204. **Offers fixes** – After confirmation, findings can be corrected directly2122## How to Use2324```25Check the code I changed26```2728```29Review the changes on the current branch30```3132```33Do a code review for src/main/java/com/example/34```3536---3738## Instructions3940> **Before every review**:41> 1. Read `.claude/lessons-learned.md`42> 2. Use [references/review-checklist.md](references/review-checklist.md) as the review catalog4344## Dynamic Context (automatically preloaded)4546The following Git information is automatically injected on invocation:4748- Staged changes: !`git diff --cached --name-only 2>/dev/null`49- Unstaged changes: !`git diff --name-only 2>/dev/null`50- Untracked files: !`git ls-files --others --exclude-standard 2>/dev/null`51- Current branch: !`git branch --show-current 2>/dev/null`5253### Step 1 – Capture Changes5455If `$ARGUMENTS` was provided (e.g. `/review src/main/java/`), review those files/directories.5657Otherwise, evaluate the **dynamic context** above – in this order:5859| Priority | Source |60|----------|--------|61| 1 | `$ARGUMENTS` (explicitly provided files/directories) |62| 2 | Staged changes (from dynamic context) |63| 3 | Unstaged changes (from dynamic context) |64| 4 | Branch diff against main: `git diff main...HEAD --name-only` |6566**Rules:**67- If staged or unstaged changes exist → review those68- If no local changes but branch != main → review branch diff69- If no changes at all → ask user: which files or directories should be reviewed?70- Only review relevant files (Java, Properties, YAML, SQL, Dockerfile, docker-compose) – ignore generated files (target/, .class)7172**Read files:** Read all changed files completely, not just the diff. Context is important for evaluation.7374### Step 2 – Perform Review7576Check each changed file against the review catalog (`references/review-checklist.md`).7778**Review categories (summary):**7980#### 2.1 Architecture (BCE)8182- Classes in the correct layer? (`boundary/rest/`, `boundary/messaging/`, `control/`, `entity/`)83- No direct repository calls from the boundary layer84- No REST/messaging logic in the entity layer85- Controller/Resource delegates to Service (Control), not to Repository (Entity)8687#### 2.2 Lessons-Learned Comparison8889Check `.claude/lessons-learned.md` against the changed code:9091| Rule | Check |92|------|-------|93| `@Blocking` for Quarkus consumers | `@Incoming` without `@Blocking` with DB access? |94| Flyway instead of ddl-auto | `ddl-auto=create` or `update` in properties? |95| Health checks | Actuator/SmallRye-Health dependency present? |96| Dev Services disabled | Quarkus Dev Services still active? |97| Dockerfile convention | Spring Boot → root, Quarkus → `src/main/docker/` |98| RabbitMQ config | Wrong property keys (`quarkus.rabbitmq.*` instead of `rabbitmq-host`)? |99100#### 2.3 Coding Standards101102- **Language:** Comments/Javadoc in English, code (classes, methods, variables) in English103- **Naming:** Java conventions (CamelCase classes, camelCase methods, UPPER_SNAKE constants)104- **Packages:** `{{groupId}}.boundary.rest`, `{{groupId}}.control`, `{{groupId}}.entity`105- **Domain neutrality:** No domain-specific names in templates106107#### 2.4 Security108109- SQL injection: No string concatenation in queries (`"SELECT ... " + param`)110- Input validation: `@Valid` on controller/resource methods for request bodies111- Secrets: No hardcoded passwords, tokens, or keys in source code/properties112- CORS: Not `allowedOrigins("*")` in production113- Security config: Swagger UI paths permitted, but not everything `permitAll()`114115#### 2.5 Code Quality116117- Unnecessary complexity or over-engineering118- Duplication (same logic in multiple places)119- Missing or incorrect exception handling120- Unused imports, dead code paths121- Lombok used sensibly (not overloaded)122123#### 2.6 Configuration124125- `application.properties` complete (DB, messaging, health, Flyway)126- `docker-compose.yml`: Health checks for all services127- Flyway migration present for every new entity128- `versions-maven-plugin` in the POM129- `renovate.json` in the project root130131#### 2.7 Tests132133- Architecture test (Taikai) present?134- New business logic (control layer) has unit tests?135- Test classes in the correct package?136137### Step 3 – Create Report138139Result as structured Markdown output in the chat:140141```142## Review Result143144### Summary145- X files reviewed146- X findings (Y critical, Z warnings, W notes)147148### Critical149| # | File | Line | Problem | Solution |150|---|------|------|---------|----------|151| 1 | ... | ... | ... | ... |152153### Warning154| # | File | Line | Problem | Solution |155|---|------|------|---------|----------|156157### Note158| # | File | Line | Problem | Solution |159|---|------|------|---------|----------|160161### Positive162- What is well done (don't just look for bugs!)163```164165**Categorization:**166167| Category | Criteria |168|----------|----------|169| **Critical** | Security vulnerability, possible data loss, architecture violation, `ddl-auto=create` |170| **Warning** | Convention violation, missing test, missing validation |171| **Note** | Improvement suggestion, style, readability |172173**After the report:** Ask if findings should be fixed directly.174Only fix after explicit confirmation – never automatically.175176---177178## References179180| File | Description |181|------|-------------|182| `.claude/lessons-learned.md` | Findings and corrections – read before every review |183| [references/review-checklist.md](references/review-checklist.md) | Detailed review catalog with rules per category |184185---186187## Conventions188189- The review skill **does not change code** without confirmation190- Give positive feedback – don't just list errors191- When uncertain, classify as note rather than critical192- No findings for generated code (target/, build/)193- Detect framework (Spring Boot vs. Quarkus) and apply appropriate rules194195### Position in Workflow196197```198[spec-feature] optional – business requirements199 |200[openapi] if OpenAPI spec needed201 |202[java-scaffold] framework: DB, messaging, infra203 |204[review] <-- code review205 |206[doc] project documentation207```