Le JSON Roadmap à donner à ton agent IA

JSON Roadmap pour agent IA

Donner une roadmap structurée à ton agent en début de session longue évite les dérives et les tâches oubliées. L'agent s'y réfère, coche les étapes, et sait quand s'arrêter.

Template complet

{
  "project": "Nom du projet",
  "objective": "Ce qu'on veut avoir à la fin, en une phrase",
  "stack": ["Python 3.11", "FastAPI", "PostgreSQL", "Docker"],
  "constraints": [
    "Pas de breaking changes sur l'API v1",
    "Tests obligatoires avant chaque merge",
    "Secrets uniquement via variables d'environnement"
  ],
  "phases": [
    {
      "id": "phase-1",
      "name": "Foundation",
      "status": "todo",
      "tasks": [
        "Initialiser la structure de projet (src/, tests/, docs/)",
        "Configurer Docker Compose avec Postgres",
        "Mettre en place Ruff + Pyright + pre-commit hooks",
        "Écrire le README avec les instructions de setup"
      ],
      "tests_required": [
        "docker compose up fonctionne sans erreur",
        "ruff check . passe sans warning"
      ],
      "done_when": "L'environnement de dev est reproductible sur une machine vierge"
    },
    {
      "id": "phase-2",
      "name": "Core Feature",
      "status": "todo",
      "depends_on": "phase-1",
      "tasks": [
        "Implémenter le modèle de données (Pydantic + SQLAlchemy)",
        "Créer les endpoints CRUD",
        "Ajouter la pagination et les filtres"
      ],
      "tests_required": [
        "Tests unitaires sur les modèles",
        "Tests d'intégration sur les endpoints (pytest + httpx)"
      ],
      "done_when": "Tous les endpoints répondent aux cas nominaux et aux cas d'erreur"
    },
    {
      "id": "phase-3",
      "name": "CI/CD",
      "status": "todo",
      "depends_on": "phase-2",
      "tasks": [
        "GitHub Actions : lint + test sur chaque PR",
        "Build Docker et push sur registry",
        "Deploy automatique sur merge main"
      ],
      "tests_required": [
        "Le pipeline passe en < 3 minutes",
        "Un rollback est possible en < 5 minutes"
      ],
      "done_when": "Un merge sur main déclenche un déploiement automatique"
    }
  ],
  "success_criteria": [
    "Toutes les phases marquées done",
    "Couverture de tests > 80%",
    "Pas de secrets dans le code",
    "README à jour"
  ],
  "eval_metrics": {
    "performance": "p95 < 200ms sur les endpoints principaux",
    "reliability": "0 erreur 5xx en production sur 24h"
  }
}

Comment l'utiliser avec Claude Code

Voici la roadmap du projet (roadmap.json).
Commence par la phase-1. Valide chaque tâche avec moi avant de passer à la suivante.
Ne passe pas à la phase suivante sans que done_when soit validé.

Pourquoi ça marche

Les agents dérivent sur les longues sessions — ils oublient le contexte initial et commencent à sur-optimiser ou inventer des tâches. Un JSON de référence agit comme une ancre de contexte : l'agent peut relire l'objectif à tout moment, et tu peux l'y renvoyer avec "relis la roadmap et dis-moi où on en est".