java-spring-boot-structure

A cross-agent skill that teaches AI coding tools the exact package layout, naming conventions, and architectural rules for production Spring Boot microservices — including Spring AI integration and Claude Code agent file placement.

Author: Israfil Iskandarov

Compatible with Claude Code, Codex CLI, Cursor, GitHub Copilot, Windsurf, and Aider.

---

What this skill does

Without this skill, AI tools generate Spring Boot code that compiles but violates the architectural patterns senior engineers enforce — wrong package placement, manual mapping instead of MapStruct, business logic in controllers, and AI-related code scattered with no clear home.

This skill enforces:

• Domain/feature-first packaging — each domain is fully self-contained; no cross-domain imports
• Service layer conventions — interface in service/abstraction, implementation (suffix Handler) in service/concrete, strategy pattern under service/strategy
• Spring AI placement — advisor, client, prompt, tool scoped inside each domain's ai/ package
• Claude Code file placement — CLAUDE.md, .claude/agents/, skills/ at project root, never inside src/
• MapStruct-only mapping — no manual mapping in services, ever
• Strict DTO/entity separation enforced by rule, not convention
• shared/ only for genuinely cross-cutting code with no domain owner

---

Installation

Claude Code

claude skills install israf1l/java-spring-boot-structure

Or manually — add to your CLAUDE.md:

## Skills
- java-spring-boot-structure: https://raw.githubusercontent.com/israf1l/java-spring-boot-structure/main/SKILL.md

Codex CLI

# Personal (all projects)
cp -r java-spring-boot-structure ~/.codex/skills/

# Or project-level
cp -r java-spring-boot-structure .codex/skills/

Invoke explicitly: $java-spring-boot-structure or let Codex auto-detect from your prompt.

Cursor

Add to .cursor/rules/java-structure.mdc:

Use the conventions defined in:
https://raw.githubusercontent.com/israf1l/java-spring-boot-structure/main/SKILL.md

Copilot / Windsurf / Aider

Reference SKILL.md directly in your instructions file or system prompt.

---

Package structure at a glance

<root-package>
├── Application.java
├── shared/                     # Cross-cutting, no domain ownership
│   ├── annotation/
│   ├── aspect/
│   ├── config/
│   ├── exception/
│   └── util/
└── <domain>/                   # e.g. order/, payment/, loyalty/
    ├── api/                    # Controllers + request/response DTOs
    │   └── dto/
    ├── service/
    │   ├── abstraction/        # Interfaces only
    │   ├── concrete/           # Implementations (*Handler)
    │   └── strategy/           # abstraction / concrete / factory
    ├── persistence/            # Entities, projections, repositories
    │   ├── entity/
    │   ├── projection/
    │   └── repository/
    ├── client/                 # Outbound integrations
    │   ├── decoder/
    │   └── interceptor/
    ├── mapper/
    │   ├── factory/
    │   └── mapstruct/
    ├── model/
    │   ├── constants/
    │   ├── criteria/
    │   └── enums/
    ├── queue/
    │   ├── kafka/
    │   └── rabbitmq/
    ├── scheduler/
    └── ai/                     # Spring AI — scoped to this domain
        ├── advisor/
        ├── client/
        ├── prompt/
        └── tool/

AI files at project root (outside src/):

<project-root>/
├── CLAUDE.md
├── .claude/
│   └── agents/
│       ├── java-reviewer.md
│       ├── sql-writer.md
│       └── test-writer.md
└── skills/
    └── java-structure/
        └── SKILL.md

---

Compatibility

Agent	Supported	Install path
Claude Code	✅	~/.claude/skills/ or .claude/skills/
Codex CLI	✅	~/.codex/skills/ or .codex/skills/
GitHub Copilot	✅	instructions file
Cursor	✅	.cursor/rules/
Windsurf	✅	instructions file
Aider	✅	system prompt

Language	Supported
Java	✅
Kotlin	✅

---

License

MIT