#❌Prompt vague
"Fix the bug in my code"

#✅Prompt structuré
"Contexte: API FastAPI avec endpoints REST.
Problème: Le endpoint POST /users retourne 500.
Fichier: src/api/routes/users.py, ligne 42.
Erreur: IntegrityError sur email duplicata.
Objectif: Ajouter une validation avant l'insertion."

#❌Tout en un
"Refactor toute l'application pour ajouter l'authentification"

#✅Étapes distinctes
"Étape 1: Analyser le système d'auth actuel
Étape 2: Proposer une architecture JWT
Étape 3: Implémenter le middleware d'auth
Étape 4: Ajouter les tests"

#✅Format demandé
"Réponds en format tableau:

| Fichier | Changement | Complexité |
|---------|------------|------------|"

#✅Contraintes claires
"- Ne pas utiliser de librairies externes
- Garder la compatibilité Python 3.11
- Préserver les tests existants
- Maximum 50 lignes ajoutées"

# AGENTS.md - Contexte pour les agents IA

## Project
API REST pour gestion d'utilisateurs.

## Stack
- FastAPI 0.104+
- SQLAlchemy ORM
- PostgreSQL 15
- Pytest pour les tests

## Conventions
- Snake_case pour les variables
- docstrings Google style
- Tests dans tests/ avec pytest

## Architecture
- src/api/routes/ : endpoints REST
- src/models/ : modèles SQLAlchemy
- src/services/ : logique métier

## À NE PAS FAIRE
- Ne pas créer de nouvelles migrations DB
- Ne pas modifier .env
- Ne pas ajouter de dépendances sans validation

src/
├── api/
│   ├── README.md      # "Ce dossier contient les endpoints..."
│   └── routes/
├── models/
│   └── README.md      # "Modèles SQLAlchemy..."
└── services/
    └── README.md      # "Logique métier isolée..."

# Services Layer

Contient la logique métier isolée des controllers.

## Conventions
- Un service par domaine métier
- Injection de dépendances via __init__
- Pas d'imports circulaires

## Exemple
```python
# services/user_service.py
class UserService:
    def __init__(self, db: Session):
        self.db = db

---

# Gestion du contexte de session

L'IA ne "se souvient" de rien entre les sessions — et dans une même session, **trop de contexte dégrade la qualité des réponses**. Ce n'est pas seulement une question de coût : un contexte pollué (nombreux fichiers lus, chemins abandonnés, erreurs accumulées) crée du bruit qui fait dériver l'agent.

Signal d'alarme : si l'agent propose des solutions déjà essayées, oublie des contraintes données en début de session, ou semble "confus" — c'est le signe que le contexte est saturé.

**Règles pratiques :**

- **Une session = un problème.** Ne mélangez pas deux bugs ou deux features dans la même session.
- **Plusieurs sessions courtes > une longue session.** Des sessions ciblées donnent de meilleurs résultats qu'une session marathon.
- **Commencez propre régulièrement.** Plutôt que continuer une session qui accumule trop, ouvrez-en une nouvelle — ou utilisez `/compact` (résume sans perdre le fil) quand le contexte dépasse 70%, `/clear` quand il dépasse 85%.

## Le cas particulier du "reasoning"

Certains modèles (o3, Claude avec extended thinking…) génèrent une chaîne de réflexion interne avant de répondre. Ces tokens de raisonnement sont invisibles dans la réponse mais comptent dans la facture — et peuvent multiplier le coût par 5 sur une tâche complexe.

C'est une **feature propriétaire et opaque** : chaque provider l'implémente différemment (`thinking_budget`, `reasoning_effort`, mode automatique…), vous ne voyez pas ce qui a été raisonné, et certains outils l'activent silencieusement. À utiliser intentionnellement pour des problèmes qui le méritent, pas comme réglage par défaut.

---

# Anti-patterns courants

| Anti-pattern | Conséquence | Solution |
|--------------|-------------|----------|
| Prompt trop long | Confusion, tokens gâchés | Découper en étapes |
| Pas de contraintes | Code non idiomatique | Spécifier les conventions |
| Oublier les tests | Code non testé | Demander tests explicites |
| Ignorer l'existant | Duplication | Référencer les fichiers existants |

---



#  Gérer son contexte — /compact et /clear

Le contexte s'accumule à chaque échange : historique de la conversation, fichiers lus, résultats de commandes, sorties de tests.

**Ce n'est pas que pour les coûts c'est une question de focus.** Un contexte saturé dégrade la qualité des réponses : l'agent commence à oublier des contraintes, à reproduire des erreurs déjà corrigées, à se perdre dans des chemins abandonnés. La performance chute bien avant que le token limit soit atteint.

**Règles de session :**

- **Une session = un problème.** Mélanger deux issues dans la même session pollue le contexte des deux.
- **Plusieurs sessions courtes > une longue session.** Recommencer proprement est souvent plus rapide que de gérer un agent qui dérive.
- **Commencez une nouvelle session régulièrement**, surtout après un changement de sujet ou une longue exploration.

Et chaque token d'entrée se paie à chaque nouvel échange — gérer le contexte réduit aussi les coûts.

## /compact — résumer sans perdre le fil

Ce que ça fait :
- Résume le contenu de la conversation en un bloc condensé
- Remplace l'historique détaillé par ce résumé dans le contexte
- L'agent conserve les décisions prises, les fichiers connus, l'état du projet
- Vous continuez la session sans payer pour les anciens échanges

Ce que ça ne fait **pas** :
- Ne supprime pas le contexte — `/clear` fait ça
- N'aide pas une session déjà à 90%+ — les tokens sont déjà brûlés

**Quand l'utiliser :**
- À 70% du contexte, pas après — vérifiez `Ctx(u)` dans la statusline
- Après un long passage de lecture de fichiers (tool spam)
- Avant de changer de phase : après le Plan, avant le Build

## /clear — repartir de zéro

`/clear` vide complètement le contexte. À réserver aux sessions vraiment bloquées — l'agent perd tout ce qu'il savait du projet. Préparez un résumé court à lui redonner avant de reprendre.

**Claude Code uniquement :**
```bash
claude -c          # Reprend la dernière session compactée
claude -r <id>     # Reprend une session spécifique par son ID