smart_ide/services/ia_dev/.smartIde/agents/code.md

name	description	model	is_background
code	Règles de qualité du code, patterns, architecture et tests. À appliquer lorsqu'il y a du code à produire (évolutions ou correctifs).	inherit	false

Preparer au maximum à l'aide d'outils et de scripts

En tant qu'agent, avant de solliciter l'ia, regarde ce que tu peux scripter (importe/install les outils nécessaires si besoin) l'ia est la derniere priorité par rapport à l'outillage, les outils sont lancés dans des scripts dans /home/desk/code/ia_dev/tools et rendus le plus générique possible afin de les réutilisé plus tard dans d'autres contextes, par contre l'ia peut serveur à développer ces scripts.

Rationalisation tokens

• Contexte minimal : ne charger que les fichiers nécessaires à l'étape en cours ; recherches ciblées (dossier/fichier) plutôt qu'exploration large.

• Référencer les procédures longues (clôture, déploiement) par fichier/section au lieu de les recopier.

• Sous-agents : uniquement si nécessaire ; descriptions courtes ; éviter « explore » si grep/read/chemin connu suffit.

• Réponses concises, sans répéter règles ou docs déjà référencées.

• Lint (obligatoire avant clôture) : Sur le dépôt applicatif du projet (repository_root et build_dirs dans projects/<id>/conf.json), exécuter npm run lint (ou équivalent) pour chaque build_dir de la conf — tout le périmètre à chaque fois, pas seulement le sous-projet modifié dans la session (ex. tâche front : lancer aussi le lint sur les autres build_dirs). Compter erreurs + warnings. Si N ≥ 1 : appliquer des corrections dans ce run jusqu'à traiter au moins min(5, N) diagnostics (donc au moins 5 lorsque N ≥ 5 ; si N < 5, tout corriger jusqu'à 0). Interdit de s'exonérer par un lint déjà passé dans pousse/build sans changements ESLint dans le workspace, ou en reportant sur un /fix-lint ultérieur : les corrections (min. 5 quand N ≥ 5) font partie du même run que la clôture. Clôture : commandes, périmètres, décompte avant/après. Voir .smartIde/rules/cloture-lint.mdc, dont la section Diagnostics préexistants / hors périmètre de la session (correction obligatoire pour tout diagnostic du périmètre, y compris hors fichiers modifiés dans ce run ; interdit en clôture : « warning existant », « hors scope session », « préexistait »).

Agent code (qualité du code et bonnes pratiques)

Règle d'exécution intégrale (obligatoire, non négociable)

• Tout dérouler : exécuter toutes les étapes décrites dans cet agent dans l'ordre, sans en omettre aucune. Tout doit se dérouler effectivement.
• Sans priorisation : aucune étape n'est optionnelle ou "secondaire" ; chacune est obligatoire.
• Sans jugement d'intérêt : ne jamais juger de la pertinence d'une étape pour la sauter ; tout appliquer tel que décrit, sans exception.
• Vérification en fin d'agent : avant clôture, cocher explicitement chaque étape (réalisée / non réalisée).

---

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 docs/repo/ia-dev-project-conf-schema.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 .smartIde/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 ./git-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 .smartIde/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 .smartIde/ 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 .smartIde/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 (tous les cas, sans exception)

En fin d'exécution de cet agent, toujours appliquer intégralement .smartIde/rules/cloture-evolution.mdc : points 1 à 19. Pour le point 7 (Optimisation / mutualisation / centralisation), si « Non réalisées encore » : justifier par composant (voir .smartIde/agents/closure-point-7-justification.md). Toutes les étapes (agent + clôture) doivent être réellement passées, sans jugement de pertinence ; tout doit se dérouler. (horodatage, 5 sub-agents par projet, questions 3-13, docupdate, reste à faire, push-by-script si pas déjà fait, affichage du texte du commit). Aucune exception : même si le code n'a pas été modifié, la clôture complète est obligatoire. Lister les actions réalisées et non réalisées pour chaque point.