convez.ai
MCP ServerDesenvolvimento WebIntermediário
rrezartprebreza

Spring Boot Skills para Claude Code

rrezartprebreza/spring-boot-skills

Skills que fazem IA gerar código Spring Boot como sua equipe, não como tutorial genérico

Ver no GitHub
BomPluginScore · de 0 a 100

Coleção de skills em produção para Claude Code que ensina agentes de IA a entender e codificar como engenheiros sênior em projetos Spring Boot. Inclui 18+ skills cobrindo padrões, convenções e armadilhas comuns da stack (JPA, REST, exceptions, Flyway, Spring AI).

Instalação

$npx convez-ai rrezartprebreza/spring-boot-skills

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
362
Forks
57
Acompanhando
4
Saúde
57%
Último commit
há 2 dias
Versão
—
Issues abertas
0
Contribuidores
4

Casos de uso

  • Gerar endpoints REST com envelopes e mapeamento de status customizados
  • Implementar camadas de persistência com Spring Data JPA seguindo convenções do projeto
  • Criar handlers de exceção alinhados com hierarquia existente
  • Acelerar desenvolvimento com agentes que entendem Flyway, Spring AI GA e padrões de injeção de dependência

Veredito

Solução pragmática que resolve um problema real: agentes de IA gerando código genérico em Spring Boot. A abordagem de skills é simples e acoplada ao ecossistema Claude Code, ideal para times que já usam Claude para coding. Requer disciplina para manter skills sincronizadas com evolução da arquitetura.

README

A tradução para o português deste README ainda está na fila.

Drop a skill into your project. Your AI coding agent instantly understands your Spring Boot codebase — architecture, patterns, conventions — and codes like a senior engineer who's been on your team for years.

skills Spring Boot Java License

Claude Code Spring AI MCP Java SDK GitHub Stars

Quick Start · Skills Catalog · Before / After · Skill Anatomy · Contributing


Why this exists

AI coding agents are great at Python. They hallucinate in Spring Boot.

They generate @Autowired field injection instead of constructor injection. They use ResponseEntity<?> where you have a standard response wrapper. They ignore your existing exception hierarchy and invent a new one. They don't know your project uses Flyway, so they generate schema SQL by hand. They emit pre-GA Spring AI artifact names that no longer exist in Maven Central.

Skills fix this. A skill is a markdown file your agent reads before touching your code. It tells the agent your conventions, your stack, your gotchas — not generic Spring Boot from 2020.

flowchart LR
    A["💬 You ask:<br/>&quot;add an orders endpoint&quot;"] --> B{Claude matches<br/>skill triggers}
    B -->|"REST code?"| C["📜 rest-api-conventions"]
    B -->|"persistence?"| D["📜 spring-data-jpa"]
    C --> E["🤖 Agent codes with<br/>YOUR envelope, YOUR<br/>status mapping, YOUR<br/>pagination contract"]
    D --> E
    E --> F["✅ Code that looks like<br/>your team wrote it"]

    style A fill:#0f172a,stroke:#38bdf8,color:#e2e8f0
    style B fill:#1e293b,stroke:#94a3b8,color:#e2e8f0
    style C fill:#10241a,stroke:#6DB33F,color:#a7f3d0
    style D fill:#10241a,stroke:#6DB33F,color:#a7f3d0
    style E fill:#0f172a,stroke:#d97757,color:#e2e8f0
    style F fill:#10241a,stroke:#6DB33F,color:#a7f3d0

This repo is a collection of battle-tested skills. Copy, adapt, drop in.


🧠 Concepts

ConceptDescription
SkillsMarkdown files loaded into agent context — tell the agent how to work in your codebase
SubagentsIsolated Claude instances for parallel work — use for reviews, test generation, migration tasks
CLAUDE.mdProject-level persistent memory — your agent's onboarding doc
MCP Java SDKOfficial Java SDK for building MCP servers — connect your Spring Boot app to any AI agent
CommandsSlash commands for repeatable workflows — /generate-endpoint, /write-test, /db-migrate

📦 Skills

Drop any skill folder into .claude/skills/ in your project. Claude Code auto-discovers them.

🏗️ Architecture

SkillDescriptionTags
layered-architectureEnforces Controller → Service → Repository separation. Prevents business logic leaking into controllers or repositories.architecture
hexagonal-architecturePorts and adapters pattern for Spring Boot. Keeps domain clean of framework dependencies.architecture ddd
domain-driven-designAggregates, value objects, domain events with commit-safe publication. Includes JPA mapping conventions.ddd jpa
multi-module-mavenParent POM conventions, shared BOM, inter-module dependency rules. Prevents circular deps.maven architecture

🔌 API Design

SkillDescriptionTags
rest-api-conventionsYour project's response envelope, error codes, pagination contract, versioning strategy. Fill in the template.rest api
openapi-firstGenerate controllers and DTOs from OpenAPI spec. Uses openapi-generator-maven-plugin.openapi codegen
problem-details-rfc9457RFC 9457 compliant error responses with Spring's ProblemDetail. Replaces ad-hoc error envelopes.error-handling rest
hateoasSpring HATEOAS link building conventions. Teaches agent when and how to add hypermedia links.hateoas rest

🗄️ Data & Persistence

SkillDescriptionTags
spring-data-jpaEntity conventions, N+1 prevention, projections, keyset pagination, batch inserts.jpa hibernate
flyway-migrationsMigration naming convention, safe multi-step schema changes, team workflow for concurrent migrations.flyway migrations
spring-data-redisCache-aside pattern, key naming, TTL strategy, stampede protection, serialization config.redis caching
transactional-patterns@Transactional propagation rules, self-invocation pitfall, after-commit side effects, saga pattern.transactions

🔒 Security

SkillDescriptionTags
spring-security-jwtJWT auth filter chain, token rotation, RBAC with method security. Opinionated, production-ready.security jwt
oauth2-resource-serverOAuth2 resource server config, JWT claim extraction, scope-based authorization.security oauth2

🤖 AI & MCP

SkillDescriptionTags
spring-ai-integrationSpring AI 1.0 GA ChatClient, chat memory, RAG pipeline, structured output. GA artifact names — no dead pre-1.0 coordinates.spring-ai llm
mcp-serverBuild MCP servers with the official Java SDK 1.0 + Spring AI starters. Tool registration, transports, stdio pitfalls.mcp ai-agents
ai-observabilityToken usage tracking, latency monitoring, prompt/response logging for Spring AI apps.observability spring-ai

🧪 Testing

SkillDescriptionTags
testing-pyramidUnit → Slice → Integration conventions. @WebMvcTest, @DataJpaTest, @MockitoBean, Testcontainers.testing

⚡ Quick Start

1. Install Claude Code (if not already)

npm install -g @anthropic-ai/claude-code

2. Drop a skill into your project

mkdir -p .claude/skills
cp -r spring-boot-skills/skills/rest-api-conventions .claude/skills/
cp -r spring-boot-skills/skills/spring-data-jpa .claude/skills/

3. Tell Claude what you want

claude
> Generate a CRUD endpoint for the Order entity following our REST conventions

That's it. Claude reads the skill before writing a single line.


⚔️ Before / After

The value of these skills is not generic Spring Boot advice. The value is preventing the small mistakes AI agents make when they do not know your backend conventions.

@RestController
public class OrderController {
    @Autowired
    private OrderRepository repository;

    @PostMapping("/orders")
    public ResponseEntity<?> create(
            @RequestBody Order order) {
        return ResponseEntity.ok(
            repository.save(order));
    }
}
@RestController
@RequestMapping("/api/v1/orders")
@RequiredArgsConstructor
class OrderController {
    private final OrderService orderService;

    @PostMapping
    ResponseEntity<ApiResponse<OrderResponse>> create(
            @Valid @RequestBody CreateOrderRequest request) {
        OrderResponse response = orderService.create(request);
        return ResponseEntity.status(HttpStatus.CREATED)
            .body(ApiResponse.ok(response));
    }
}
  • Business logic leaks into the controller
  • No request DTO or validation boundary
  • Repository called directly from the web layer
  • Response shape ignores project conventions
  • Status codes left to framework defaults
  • Controller as a pure HTTP adapter
  • Service owns the business rules
  • DTO validation at the boundary
  • Consistent response envelope
  • Correct 201 Created semantics

📐 Skill Anatomy

Every skill in this repo follows the same structure:

skills/rest-api-conventions/
├── SKILL.md          ← the skill: trigger description + conventions + gotchas
├── examples/         ← good and bad examples, side by side
│   ├── good-controller.java
│   └── bad-controller.java
└── templates/        ← copy-paste starting points
    ├── ApiResponse.java
    └── GlobalExceptionHandler.java

SKILL.md has two critical parts:

---
name: rest-api-conventions
description: >
  Use when generating REST controllers, response objects, DTOs, or error handlers.
  Defines the project's response envelope, HTTP status mapping, and error code conventions.
---

## Conventions
...

The description is a trigger — write it as "use when [condition]", not as a summary. This is what makes the agent actually load the skill.

The Gotchas section at the bottom of each skill is the secret weapon: a running list of the exact mistakes agents make in that domain, phrased as Agent does X — do Y instead.


💡 Tips from the trenches

The Gotchas section is the most valuable part — add to it every time the agent does something wrong. Your future self will thank you.

Don't describe what Spring Boot already knows. Skills should push Claude out of its default behavior, not repeat the docs.

Be opinionated about your project. Generic Spring Boot best practices belong in a blog post. Skills belong in your .claude/ folder.

Fork this repo and customize. Every team's conventions are different. These are starting points, not gospel.

Combine with CLAUDE.md. CLAUDE.md is for project-level memory (build commands, test runner, key architecture decisions). Skills are for domain-specific coding patterns.

Anti-patternFix
Giant SKILL.md with everythingSplit into focused skills, one concern each
"Always use constructor injection"Already Claude's default — skip it
No examplesAdd a good.java and bad.java — the contrast is what teaches
Prescriptive step-by-step instructionsGive goals and constraints, let agent decide how
Never updatingAdd a Gotchas section, update it when agent fails

🔥 Hot: MCP Server Skill

The mcp-server skill is the most powerful one here.

It teaches your agent to build production-ready MCP servers on MCP Java SDK 1.0 and the Spring AI GA starters — the same protocol used by Claude, Cursor, VS Code, and every major AI coding tool.

// What the agent generates with the skill loaded —
// real GA API: spring-ai-starter-mcp-server + annotation scanning
@Component
public class OrderMcpTools {

    private final OrderService orderService;

    @McpTool(name = "get_order",
             description = "Get a single order by ID including all line items and status history")
    public OrderResponse getOrder(
            @McpToolParam(description = "UUID of the order", required = true) String orderId) {
        return OrderResponse.from(orderService.findById(UUID.fromString(orderId)));
    }
}

Without the skill, the agent guesses: dead pre-GA artifact names, SDK 0.9.0 APIs, System.out logging that corrupts the stdio transport — or it gives up and writes Python.


🗺️ Roadmap

  • Skills for Spring Batch
  • Skills for Spring Cloud Gateway
  • Skills for Spring WebFlux / reactive patterns
  • Skills for multi-tenancy
  • CLAUDE.md template for Spring Boot projects
  • /generate-endpoint command
  • /write-test command
  • /db-migrate command
  • Integration with Hatch background job library
  • Integration with SpringPulse observability

🤝 Contributing

Skills get better with real-world use. If you find a gap — the agent did something stupid in your Spring Boot project — open a PR and add it to the Gotchas section of the relevant skill.

1. Fork the repo
2. Copy an existing skill as a template
3. Fill in conventions, examples, gotchas
4. PR with a one-line description of what problem it solves

🛠️ More from the same workbench

RepoDescription
HatchMulti-module background job library for Spring Boot — REST polling, retry, Redis/JDBC backends, SSE dashboard
SpringPulseRuntime observability for @Scheduled methods — AOP interception, WebSocket dashboard
rest-api-generatorCLI that scaffolds Spring Boot REST APIs from plain English prompts

If a skill saved your agent from writing @Autowired field injection today — ⭐ star the repo.

spring-boot · java · claude-code · mcp · spring-ai · skills · developer-tools

Built by @rrezartprebreza · Pristina, Kosovo

Ver o original no GitHub

Bom para

Relacionados