Règles pour agents IA
Ces règles s'appliquent à tous les agents IA travaillant sur le projet : Claude Code, Codex, Cursor, Windsurf, GitHub Copilot.
Objectif principal
Générer du code Laravel maintenable, sécurisé, modulaire et production-grade, pleinement aligné avec l'architecture et les conventions du projet.
Workflow obligatoire
Avant de coder
- Lire
.ai/architecture-summary.md - Lire la documentation du module concerné
- Inspecter le code existant similaire dans le projet
- Réutiliser l'architecture existante autant que possible
Après avoir codé
- Mettre à jour la documentation impactée
- Vérifier la cohérence d'architecture
- Vérifier la cohérence de nommage
- Vérifier l'autorisation
- Vérifier la validation
- Vérifier les logs et la gestion d'erreurs
Règles obligatoires
| Couche | Règle |
|---|---|
| Architecture | Préserver les frontières de module, respecter les conventions Laravel et projet |
| Controllers | Minces — autoriser, orchestrer, appeler services, retourner réponses |
| Validation | Toutes les entrées externes via Form Requests |
| Autorisation | Policies, Gates, middleware — jamais contourner |
| Services | Toute la logique métier dans les services |
| Modèles | Relations, casts, scopes — pas de workflow |
| Vues | Présentation uniquement — jamais de requêtes DB |
| Base de données | FK en id_* — soft deletes quand nécessaire |
| Transactions | DB::transaction() pour les opérations multi-write |
| Logging | Logs sur les workflows sensibles — jamais de secrets |
À faire
- Réutiliser les services existants
- Réutiliser les patterns existants
- Inspecter les modules similaires d'abord
- Préférer la composition à la duplication
- Garder les méthodes focalisées
- Ajouter le typage explicite
- Utiliser des noms clairs
À ne pas faire
- Inventer des patterns architecturaux
- Dupliquer la logique métier
- Contourner l'autorisation
- Mettre de la logique dans les vues Blade
- Créer des contrôleurs géants
- Créer des services géants
- Hardcoder les permissions
- Faire confiance à la sécurité frontend
- Créer des repositories pour du CRUD trivial
- Supprimer définitivement des données historiques sans approbation explicite