Bâtir une application Java Spring Boot avec Claude Code

🎯 Contexte du projet

Nous avons créé une application Java Spring Boot complète avec Claude Code, l'assistant IA d'Anthropic. L'objectif était de développer une solution backend robuste, scalable et maintenable, en appliquant une méthodologie structurée qui tire parti du développement augmenté par l'IA.

📁 Structure du projet Java Spring Boot

La clé d'un projet Claude Code réussi réside dans une structure Maven standard enrichie d'une configuration Claude Code détaillée. Voici l'architecture adoptée :

mon-application/
├── .claude/                      # 🤖 Configuration Claude Code
│   ├── CLAUDE.md                 # Guide référence (architecture, règles)
│   ├── BASE_CONNAISSANCE.md      # Erreurs récurrentes et solutions
│   ├── SESSION_ACTIVE.md         # Contexte session en cours
│   ├── TODO_STATUS.md            # État des tâches
│   └── commands/                 # Slash commands personnalisés
│
├── src/
│   ├── main/
│   │   ├── java/com/uitguard/app/
│   │   │   ├── config/           # Configuration Spring
│   │   │   ├── controller/       # API REST Controllers
│   │   │   ├── service/          # Business Logic
│   │   │   ├── repository/       # JPA Repositories
│   │   │   ├── model/            # Entités JPA
│   │   │   ├── dto/              # Data Transfer Objects
│   │   │   ├── mapper/           # Mappers (Entity ↔ DTO)
│   │   │   ├── exception/        # Exceptions métier
│   │   │   └── Application.java  # Main Spring Boot
│   │   │
│   │   └── resources/
│   │       ├── application.yml   # Configuration app
│   │       ├── application-dev.yml
│   │       ├── application-prod.yml
│   │       └── db/
│   │           └── migration/    # Scripts Flyway/Liquibase
│   │
│   └── test/
│       └── java/com/uitguard/app/
│           ├── controller/       # Tests Controllers
│           ├── service/          # Tests Services
│           └── repository/       # Tests Repositories
│
├── docs/                         # Documentation technique
│   ├── API.md                    # Documentation API REST
│   ├── ARCHITECTURE.md           # Architecture détaillée
│   └── DEPLOYMENT.md             # Guide déploiement
│
├── travaux/                      # Gestion des travaux
│   ├── spec/                     # Spécifications fonctionnelles
│   └── analyses/                 # Analyses techniques
│
├── pom.xml                       # Maven dependencies
├── .gitignore
└── README.md

⚙️ Configuration Claude Code : le CLAUDE.md

Le fichier .claude/CLAUDE.md est le cerveau du projet. Claude Code le lit automatiquement au démarrage de chaque session. Pour un projet Java Spring Boot, ce fichier doit contenir toutes les décisions architecturales et conventions de code.

Contenu essentiel pour Java Spring Boot

# 🚀 APPLICATION JAVA SPRING BOOT - Guide Claude Code

## 🎯 DESCRIPTION
Application backend REST API pour [description métier].

## 🏗️ STACK TECHNIQUE
- Java 17+
- Spring Boot 3.2+
- Spring Data JPA + Hibernate
- PostgreSQL 15+
- Maven 3.8+
- Lombok
- MapStruct (mappers)

## ✅ RÈGLES NON NÉGOCIABLES

### Architecture
- ❌ **INTERDIT** : Business logic dans Controllers
- ✅ **OBLIGATOIRE** : Layered architecture stricte
- ✅ **OBLIGATOIRE** : DTOs pour toutes les API

### Conventions Nommage
- Controllers : `[Entity]Controller` (ex: UserController)
- Services : `[Entity]Service` + `[Entity]ServiceImpl`
- Repositories : `[Entity]Repository`
- DTOs : `[Entity]RequestDTO` / `[Entity]ResponseDTO`

### API REST Standards
- POST   : Créer → 201 Created
- GET    : Lire → 200 OK
- PUT    : Modifier → 200 OK
- DELETE : Supprimer → 204 No Content
- GET collection : Pagination obligatoire (page, size, sort)

💡 Base de connaissance : capitaliser sur l'expérience

Le fichier .claude/BASE_CONNAISSANCE.md est crucial : il stocke les erreurs récurrentes et leurs solutions. Claude Code y puise pour éviter de répéter les mêmes erreurs. Dans un projet Java Spring Boot, cela inclut les problèmes de configuration, de dépendances Maven, de transactions JPA, etc.

## Problème : LazyInitializationException dans Controller
**Symptôme** : Exception au chargement d'une collection lazy
**Cause** : Transaction fermée avant sérialisation JSON
**Solution** : Utiliser DTO + mapper OU @Transactional(readOnly=true)

## Problème : Circular dependency entre Services
**Symptôme** : BeanCurrentlyInCreationException au démarrage
**Cause** : ServiceA injecte ServiceB et inversement
**Solution** : Extraire logique commune dans ServiceC

## Problème : Tests échouent avec base de données
**Symptôme** : Tests passent isolément, échouent ensemble
**Cause** : Données non nettoyées entre tests
**Solution** : Utiliser @DirtiesContext ou @Sql(cleanup)

🏛️ Architecture en couches : la discipline au service de la qualité

Pour garantir un code maintenable, nous avons documenté précisément l'architecture en couches dans le CLAUDE.md. Chaque couche a un rôle clair et des règles strictes.

## 🏗️ ARCHITECTURE LAYERED

### 1. Controller Layer (API REST)
**Rôle** : Gérer les requêtes HTTP, validation des entrées
**Règles** :
- ❌ INTERDIT : Business logic
- ❌ INTERDIT : Accès direct Repository
- ✅ OBLIGATOIRE : DTOs en entrée/sortie
- ✅ OBLIGATOIRE : @RestController + @RequestMapping
- ✅ OBLIGATOIRE : Validation avec @Valid

### 2. Service Layer (Business Logic)
**Rôle** : Logique métier, orchestration
**Règles** :
- ✅ Interface + Implémentation
- ✅ @Service sur l'implémentation
- ✅ @Transactional sur méthodes métier
- ❌ INTERDIT : Manipulation HTTP (HttpServletRequest, etc.)

### 3. Repository Layer (Persistence)
**Rôle** : Accès base de données
**Règles** :
- ✅ Extend JpaRepository
- ✅ Méthodes query dérivées (findBy...)
- ✅ @Query pour requêtes complexes

### 4. Model Layer (Entités)
**Rôle** : Représentation BDD
**Règles** :
- ✅ @Entity + @Table
- ✅ @Id + @GeneratedValue
- ✅ Relations (@OneToMany, @ManyToOne)
- ❌ INTERDIT : Logique métier dans entités

Grâce à cette documentation, Claude Code génère automatiquement du code qui respecte l'architecture sans dévier, même après des centaines de modifications.

🚀 Workflow de développement avec Claude Code

Notre workflow pour développer une application Java Spring Boot suit un cycle vertueux qui garantit qualité et cohérence :

📊 Résultats obtenus

Voici les métriques de notre application Java Spring Boot après 3 semaines de développement avec Claude Code :

Temps de développement : 3 semaines au lieu des 8-10 semaines estimées en développement traditionnel. Qualité du code : Respect strict des conventions, 0 code smell critique (SonarQube), documentation exhaustive.

✨ Bonnes pratiques apprises

🎯 Conclusion

Développer une application Java Spring Boot avec Claude Code, ce n'est pas simplement générer du code. C'est appliquer une méthodologie rigoureuse qui transforme l'IA en véritable équipier technique :

• Une architecture documentée (CLAUDE.md) qui guide chaque décision technique
• Des conventions strictes qui garantissent la cohérence sur des milliers de lignes
• Une base de connaissance qui capitalise sur chaque erreur résolue
• Un workflow éprouvé (spec → implémentation → tests → doc) qui assure la qualité

Le résultat ? Une application backend professionnelle, production-ready, développée en 3 semaines au lieu de 10, avec un code maintenable, testé à 85%, et une documentation exhaustive. Le développement augmenté par l'IA n'est plus un concept : c'est une réalité quotidienne.