Skip to content

AGENTS.md

Latest commit

 

History

History
88 lines (62 loc) · 3.85 KB

AGENTS.md

File metadata and controls

88 lines (62 loc) · 3.85 KB

AGENTS — Directives pour les agents IA travaillant sur Q-Ready

Ce fichier s'adresse aux agents IA (GitHub Copilot, Claude, Cursor, etc.) qui interviennent sur ce repo. Lire ce fichier en entier avant toute modification.

Principe fondamental : ne pas empiler du code pour corriger un problème

Un agent qui corrige un bug ne doit pas :

  • Essayer de corriger le bug en ajoutant du code inutile
  • Ajouter de la gestion d'erreur qui n'a aucun rapport
  • Ajouter des commentaires sur du code qu'il n'a pas modifié
  • Introduire une nouvelle abstraction pour un cas d'usage unique

Avant de coder : réfléchir d'abord

Pour tout changement non trivial, produire mentalement (ou dans un commentaire temporaire) :

  1. Quel est le problème exact ? (pas une paraphrase de la demande, mais la cause racine)
  2. Quelle est la solution minimale ? (nombre de lignes modifiées le plus petit possible)
  3. Quels fichiers sont concernés ? (lister avant de toucher quoi que ce soit)
  4. Y a-t-il un effet de bord ? (changement de type, de contrat d'interface, de comportement)

Si la réponse à (4) est "oui", signaler avant d'implémenter.

Règles de code

Général

  • Modifier uniquement les fichiers nécessaires à la tâche
  • Conserver le style existant (indentation, quotes, conventions de nommage)
  • Ne pas ajouter de console.log / print de debug dans un commit final
  • Ne pas ajouter de dépendances sans justification explicite, et ajouter les imports en haut du fichier, sauf cas exceptionnel documenté

TypeScript / React

  • Les types vivent dans frontend/src/types/api.ts — les modifier en même temps que les modèles Pydantic
  • Ne pas utiliser any sauf cas exceptionnel documenté
  • Préférer les composants fonctionnels, pas de classes React
  • Les hooks React Query sont dans frontend/src/hooks/ — ne pas faire de fetch directement dans les composants

Python / FastAPI

  • Les modèles Pydantic sont dans backend/models.py — source de vérité pour les types
  • Les requêtes SQL passent par backend/repository.py, jamais directement dans les routers
  • Les scanners sont dans agent/scanners/ — chaque fichier = un type d'asset
  • Pas de logique métier dans main.py ou les routers — déléguer à repository/scanner

Sécurité (non négociable)

  • Ne jamais commiter de secret, clé, token ou mot de passe
  • Ne jamais désactiver une validation Pydantic
  • Ne pas exposer de stack trace dans les réponses API (utiliser les handlers d'erreur FastAPI)
  • Le champ DATABASE_URL vient toujours de os.getenv, jamais hardcodé

Documentation

  • Après avoir fait un grand changement de code qui a été validé par l'utilisateur, il faut faire les changements à la documentation du projet

Corrections de bugs : protocole

  1. Reproduire le bug avant de le corriger (comprendre, pas deviner)
  2. Isoler la cause minimale
  3. Corriger au niveau le plus bas possible (ne pas contourner avec un workaround haut niveau)
  4. Vérifier que tsc --noEmit et les tests passent après la correction
  5. Ne pas profiter du bug fix pour faire du refactoring non demandé

Ce qu'un agent ne doit jamais faire sans confirmation explicite

  • Supprimer ou renommer un fichier existant
  • Changer un schéma de base de données (migrations Alembic = changement critique)
  • Modifier docker-compose.yml ou .env.example
  • Changer une URL d'endpoint API (contrat entre frontend et backend)
  • Faire un commit ou un push des modifications, cela doit toujours être fait par l'utilisateur après une review du code généré
  • Installer une nouvelle dépendance npm ou pip

Structure de référence

Voir PROJET.md pour l'architecture technique complète. Voir docs/roadmap.md pour la liste des tâches et leurs dépendances. Voir SETUP.md pour lancer le projet localement.