Build a Spring Boot Code Review Skill: Turn Claude Code into Your Senior Architect

Why AI‑Driven Code Review

Manual code review incurs high labor cost, produces inconsistent results, and makes knowledge transfer difficult. An AI‑driven Skill can encode team standards, architectural principles, and security guidelines into a reusable assistant that automatically reviews code and produces a structured report.

Skill Core Concepts

The Skill is defined by a SKILL.md file containing YAML metadata ( name, description) and Markdown instructions. It uses progressive disclosure: Claude loads only the metadata (≈30‑50 tokens) to match a request, then loads the full instruction set when activated. The Skill auto‑activates when the user’s request matches the description and is installed project‑wide under .claude/skills/, version‑controlled via Git.

Design of the Spring Boot Review Skill

Design Goals

Comprehensiveness : cover Controller, Service, Repository, Entity, Config, Security, and optional Test layers.

Operability : each check has a clear pass/fail criterion and remediation suggestion.

Structured Output : generate a standardized report with scores, critical issues, suggestions, and next actions.

Customizability : teams can add or remove checks to fit their project.

Skill File Structure

.claude/skills/spring-boot-review/
└── SKILL.md

SKILL.md Core Content

---
name: spring-boot-review
description: Systematic review of Java code in Spring Boot 3.x projects, covering controllers, services, repositories, configuration, security, and tests. Auto‑triggered on keywords like "code review", "review", or "Spring Boot project".
---

Review Process Overview

Understand Context : read pom.xml (or build.gradle) to determine Spring Boot version and dependencies.

Layered Review : inspect each architectural layer in order.

Generate Report : use a fixed Markdown template to produce a structured output.

Interaction & Follow‑up : ask clarification questions and optionally provide fix snippets.

Layer‑Specific Checks

Controller Layer

Require @RestController; flag misuse of @Controller that returns views.

Enforce path pattern /api/v1/… and versioning.

Require parameter validation with @Valid or @Validated.

Prohibit returning Entity objects directly; require DTO/VO.

Ensure exceptions are not caught in controllers but delegated to global handlers.

Disallow business logic inside controllers.

Service Layer

Prefer constructor injection over field @Autowired injection.

Use @Transactional with appropriate boundaries.

Throw custom business exceptions instead of generic RuntimeException.

Avoid large if/else blocks; consider strategy pattern.

Handle external calls with timeout/retry logic.

Repository Layer

Detect SQL‑injection risk in @Query string concatenation.

Encourage use of Pageable for pagination and sorting.

Check method naming follows Spring Data conventions.

Entity & DTO

Separate Entity from DTO; use @JsonIgnore on sensitive fields.

Use Lombok cautiously; avoid exposing no‑arg constructors unintentionally.

Global Exception Handling

Require a class annotated with @ControllerAdvice or @RestControllerAdvice.

Standardize error response format (code, message, timestamp).

Handle MethodArgumentNotValidException to avoid 500 responses.

Configuration & Security

Prefer type‑safe binding with @ConfigurationProperties over scattered @Value.

Ensure Spring Security config sets proper authorities, encodes passwords, and configures CORS correctly.

Detect logging of sensitive data (passwords, tokens).

Report Template Design

# Spring Boot Code Review Report
**Project**: [Project Name]
**Scope**: [Package/File]
**Date**: [Date]

## Overall Rating
- **Score**: Excellent / Good / Pass / Needs Improvement
- **Strengths**: (2‑3 items)
- **Weaknesses**: (2‑3 items)

## Critical Issues (must fix)
| File | Line | Issue | Recommendation |
|------|------|-------|----------------|

## General Issues (suggestions)
| File | Line | Issue | Recommendation |
|------|------|-------|----------------|

## Best‑Practice Recommendations
- (2‑4 actionable items)

## Next Steps
- [ ] Action 1
- [ ] Action 2

How to Use the Skill

Installation Steps

Create the directory .claude/skills/spring-boot-review/ at the project root.

Place the SKILL.md content inside that directory.

(Optional) Add project‑specific conventions to CLAUDE.md so the Skill inherits them.

Triggering the Skill

Automatic : type phrases like "review my UserController " or "run a code quality check on the whole project" in a Claude Code session.

Manual : send the command /spring-boot-review to force activation.

Interaction Example

User: "Please review my com.example.demo.controller.UserController and com.example.demo.service.UserService files."

Claude reads the two files.

It checks controller and service items in order.

If an issue is found, Claude asks for confirmation, e.g., "I see UserController.create returns the User entity directly; should I suggest using UserDto?"

Claude generates the full report with remediation snippets.

Extension and Customization

Add team‑specific rules, such as enforcing @Slf4j and banning System.out.println.

Split the Skill into focused modules like spring-boot-security-review, spring-boot-performance-review, and spring-boot-test-review.

Integrate the Skill into CI/CD (e.g., GitHub Actions) to run automatically on pull requests.

Key Knowledge Points

Constructor injection vs field injection : constructor injection makes dependencies immutable and easier to test.

Transaction propagation : choose REQUIRED, REQUIRES_NEW, etc., based on business needs to avoid deadlocks.

Global exception handling : centralizes error handling and returns a uniform response format.

DTO vs Entity separation : prevents sensitive data leakage and decouples API from persistence model.

Spring Security method‑level permissions : use @PreAuthorize for fine‑grained access control.

SQL‑injection prevention : prefer JPA parameter binding ( :name) over string concatenation.

Conclusion

Building a Spring Boot code‑review Skill codifies architectural and security expertise into an AI assistant that automatically spots issues, suggests fixes, and accelerates onboarding. The Skill can serve as a foundation for further automation such as performance checks or micro‑service governance.