104 lines
5.9 KiB
Markdown
104 lines
5.9 KiB
Markdown
---
|
||
name: code
|
||
description: Règles de qualité du code, patterns, architecture et tests. À appliquer lorsqu'il y a du code à produire (évolutions ou correctifs).
|
||
model: inherit
|
||
is_background: false
|
||
---
|
||
|
||
# Agent code (qualité du code et bonnes pratiques)
|
||
|
||
**Contexte projet :** La configuration et la documentation du projet sont dans `projects/<id>/`. L'identifiant `<id>` est résolu **uniquement** par **MAIL_TO** (adresse « to » des mails) ou **AI_AGENT_TOKEN** (token des requêtes) ; pas de fallback. Voir `projects/README.md`. Rappeler ce chemin en début d'exécution.
|
||
|
||
**Documentation** : La doc des projets gérés est dans **`projects/<id>/docs`** ; la doc ia_dev est dans **`projects/ia_dev/docs`**.
|
||
|
||
Tu appliques les règles ci-dessous **lorsqu'il y a du code à produire** (évolution ou correctif). Les agents evol et fix invoquent cet agent dans ce cas.
|
||
|
||
## Liste ordonnée d'actions obligatoires pour coder
|
||
|
||
1. **Texte i18n et secrets**
|
||
Utiliser un texte i18n systématique pour tout libellé utilisateur. Tenir à jour `.secrets/<env>/env-full-<env>-for-bdd-injection.txt` selon l'environnement.
|
||
|
||
2. **Référence aux standards**
|
||
Consulter et respecter la page wiki **Code-Standards** du projet (URL dans `projects/<id>/conf.json` → `git.wiki_url`) pour la qualité, la sécurité, les patterns et la documentation fonctionnelle comme point d'entrée unique.
|
||
|
||
3. **Conventions du projet**
|
||
Adhérer au style de code et aux conventions existantes du projet.
|
||
|
||
4. **Sécurité**
|
||
Ne jamais coder en dur d'informations sensibles (y compris dans la documentation) ; valider systématiquement les entrées utilisateur.
|
||
|
||
5. **Performances**
|
||
Optimiser les performances du code, en particulier pour les opérations critiques et les boucles.
|
||
|
||
6. **Clarté et maintenabilité**
|
||
S'assurer que le code est clair, lisible et facile à maintenir par d'autres développeurs.
|
||
|
||
7. **Backend – helpers centralisés**
|
||
Utiliser les helpers centralisés : `errorHandlers.ts` (handleInternalError, handleValidationError, etc.), `errorLoggers.ts` (logError, logValidationError, etc.), `errorMessages.ts`, `userHelpers.ts` (isSuperAdminUser, extractUserData, etc.).
|
||
|
||
8. **Frontend – hooks et services**
|
||
Utiliser `useApiClient` pour les appels API, le pattern Controller/Vue (hook contrôleur + sous-composants présentateurs), et LoggerService pour le logging (pas de console brut).
|
||
|
||
9. **Frontend – feature complexe**
|
||
Pour chaque feature complexe : (1) hook contrôleur `useFeatureController` pour états, appels API et calculs ; (2) sous-composants présentateurs pour découper l'UI ; (3) helpers mutualisés dans utils/services.
|
||
|
||
10. **Environnement – .env**
|
||
Ne pas modifier les fichiers `.env` de production (inaccessibles) ; ne jamais intégrer de paramétrage sensible directement dans le code.
|
||
|
||
11. **Environnement – env.example**
|
||
Maintenir `env.example` systématiquement à jour.
|
||
|
||
12. **Environnement – ports**
|
||
Ne jamais modifier les ports, même s'ils ne sont pas ceux par défaut ; fixer en 1 lorsque possible.
|
||
|
||
13. **Environnement – configurations**
|
||
Privilégier les configurations en base de données plutôt que dans les `.env`.
|
||
|
||
14. **Logging – centralisation**
|
||
Centraliser les logs dans les répertoires `logs/` des applications et dans le répertoire `logs/` du projet pour les logs hors applications (déploiement, etc.).
|
||
|
||
15. **Logging – système**
|
||
Implémenter une gestion d'erreurs robuste et utiliser le système de logging Winston pour toutes les sorties (info, warn, error, debug, etc.).
|
||
|
||
16. **Logging – traçabilité**
|
||
Logger toutes les valeurs, états clés et retours d'API.
|
||
|
||
17. **Interactions – base de données**
|
||
Être vigilant lors des interactions avec la base de données, notamment pour les migrations et les requêtes complexes.
|
||
|
||
18. **Interactions – APIs externes**
|
||
Gérer les interactions avec les API de manière appropriée, en respectant les limites d'utilisation et en gérant les erreurs.
|
||
|
||
19. **Interactions – emails**
|
||
Gérer les envois d'emails de manière appropriée pour éviter le spam et gérer les erreurs.
|
||
|
||
20. Lancer obligatoirement un lint
|
||
Utiliser l'agent `.cursor/agents/fix-lint.md` (commande /fix-lint)
|
||
|
||
21. **Documentation** : Compléter le wiki avec l'objectif, les impacts, les modifications, les modalités de déploiement et d'analyse. **`docs/` est hors versionnement** : maintenir les fichiers dans `docs/` localement (ne pas les supprimer), puis exécuter `./gitea-issues/wiki-migrate-docs.sh` pour pousser vers le wiki ; ou éditer la page wiki directement. Ne pas committer `docs/`. **Avant d'exécuter wiki-migrate-docs.sh :** lire le script, présenter un résumé de ce qu'il fait, puis l'exécuter.
|
||
|
||
22. **Commit** : Préparer le commit avec le format de `.cursor/agents/push-by-script.md` (lignes 15-32) :
|
||
|
||
- Etat initial
|
||
- Motivation du changement
|
||
- Résolution
|
||
- Root cause (si non applicable : N/A ou cause du besoin d'évolution)
|
||
- Fonctionnalités impactées
|
||
- Code modifié
|
||
- Documentation modifiée
|
||
- Configurations modifiées
|
||
- Fichiers dans déploy modifiés
|
||
- Fichiers dans logs impactés
|
||
- Bases de données et autres sources modifiées
|
||
- Modifications hors projet
|
||
- fichiers dans .cursor/ modifiés
|
||
- fichiers dans .secrets/ modifiés
|
||
- nouvelle sous sous version dans VERSION
|
||
- CHANGELOG.md mise à jour (oui/non)
|
||
|
||
23. **Push** : Lancer et **exécuter intégralement** l'agent `.cursor/agents/push-by-script.md` (commande /push-by-script) avec ce message de commit. En cas d'erreur ou d'optimisation remontée par l'agent invoqué : traiter obligatoirement (corriger ou mettre en œuvre), puis relancer cet agent jusqu'à ce qu'aucune erreur ni optimisation non traitée ne soit remontée.
|
||
|
||
## Clôture complète (obligatoire, sans exception)
|
||
|
||
Appliquer **intégralement** `.cursor/rules/cloture-evolution.mdc`. Aucune dérogation, y compris pour un simple alignement de branches, tous les points de la règle sont applicables et à faire.
|