AI-Driven Development : Le Guide Complet

Pour les débutants

Pensez à l'évolution comme ceci : Gen 1 = votre GPS vous dit de tourner à droite. Gen 2 = votre GPS vous explique pourquoi tourner à droite et propose des alternatives. Gen 3 = votre GPS conduit la voiture pour vous, mais vous gardez le volant et pouvez reprendre le contrôle à tout moment.

Exemple avec Claude Code

Vous pouvez créer un projet complet en une seule commande :

$ claude
> Crée une API REST en Go avec :
  - CRUD utilisateurs avec PostgreSQL
  - Authentification JWT
  - Middleware de logging
  - Tests unitaires
  - Dockerfile + docker-compose.yml
  - Documentation OpenAPI

Claude Code va créer toute l'arborescence, écrire le code, lancer les tests, et itérer jusqu'à ce que tout compile et passe.

Exemple avec Cursor

Sélectionnez un fichier de 500 lignes et demandez :

@codebase Refactore ce fichier en suivant les principes SOLID.
Extrait les responsabilités dans des fichiers séparés.
Ajoute des interfaces pour l'injection de dépendances.
Garde la rétrocompatibilité avec les tests existants.

Exemple avec Aider

$ aider --model claude-sonnet-4
> /add src/services/payment.go
> Écris des tests unitaires complets pour PaymentService.
  Inclus les cas : paiement réussi, carte refusée,
  timeout réseau, montant invalide, devise non supportée.
  Utilise des mocks pour le client Stripe.

Workflow de Debug

$ claude
> Le test TestPaymentTimeout échoue avec "context deadline exceeded".
  Analyse le code de PaymentService.ProcessPayment(),
  identifie la cause, propose un fix,
  et vérifie que tous les tests passent après le fix.

L'agent va lire le code, comprendre le flow, identifier le problème, appliquer le fix, et relancer les tests automatiquement.

Générer la doc d'une API

> Analyse toutes les routes HTTP dans cmd/server/
  et génère une documentation OpenAPI 3.0 complète
  avec des exemples de requêtes/réponses pour chaque endpoint.

Exemple : Migration Python 2 → 3

> Migre ce module de Python 2 à Python 3.
  Gère les changements de print, unicode, division,
  imports relatifs, et dict.keys()/values()/items().
  Vérifie que les tests passent après migration.

Dans une PR GitHub

# .github/workflows/ai-review.yml
- name: AI Code Review
  run: |
    claude --print "Review cette diff git pour :
    - Bugs potentiels et edge cases
    - Problèmes de sécurité
    - Violations des conventions du projet (voir CLAUDE.md)
    - Opportunités d'optimisation"

Le Test des 3 Questions (à faire AVANT de coder)

1. Quel problème réel je résous ? — Si la réponse est vague (« c'est cool », « tout le monde en a un »), arrêtez. Un bon problème se formule en une phrase : « Les data engineers perdent 4h/semaine à débugger des pipelines cassés parce qu'il n'y a pas de monitoring standardisé. »
2. Qui souffre de ce problème et combien paierait pour la solution ? — Si personne ne paierait, ce n'est pas un vrai problème. L'IA peut créer des solutions à l'infini — votre job est de trouver le vrai problème.
3. Puis-je le résoudre avec 3 features maximum ? — La simplicité est le filtre ultime. Si vous avez besoin de 20 features, vous ne comprenez pas encore le problème. Réduisez, simplifiez, focalisez.

Template : Le One-Pager de Vision

# Vision Product — [Nom du Projet]

## Le Problème (1 phrase)
Les [UTILISATEURS] perdent [TEMPS/ARGENT] parce que [CAUSE RACINE].

## La Solution (1 phrase)
Un [TYPE DE PRODUIT] qui [ACTION PRINCIPALE] pour [RÉSULTAT MESURABLE].

## Les 3 Features Essentielles (pas 4, pas 5 — TROIS)
1. [Feature 1] — résout [aspect du problème]
2. [Feature 2] — résout [aspect du problème]
3. [Feature 3] — résout [aspect du problème]

## Ce qu'on ne fait PAS (aussi important que ce qu'on fait)
- Pas de [feature tentante mais hors scope]
- Pas de [technologie à la mode mais inutile ici]
- Pas de [perfectionnisme prématuré]

## Métrique de Succès (1 seule)
Le projet est un succès si [MÉTRIQUE MESURABLE].
Exemple : "Si 100 utilisateurs l'utilisent quotidiennement après 30 jours."

Template : CLAUDE.md Structuré pour un Nouveau Projet

# CLAUDE.md — [Nom du Projet]

## Vision
[Copiez votre one-pager ici]

## Stack Technique
- Backend : Go 1.22 + Chi router + PostgreSQL 16
- Frontend : Aucun (API-only pour le MVP)
- Infra : Docker + GitHub Actions
- Tests : Go testing + testcontainers

## Architecture
```
cmd/server/         → Point d'entrée HTTP
internal/domain/    → Logique métier (AUCUNE dépendance externe)
internal/adapters/   → PostgreSQL, HTTP clients, etc.
internal/handlers/   → Routes HTTP
```

## Conventions NON NÉGOCIABLES
- Hexagonal architecture : domain ne dépend de RIEN d'externe
- Tout endpoint a un test d'intégration
- Pas de ORM : SQL brut avec sqlx
- Erreurs wrappées avec contexte : fmt.Errorf("doing X: %w", err)
- Pas de framework magique : stdlib + quelques libs ciblées

## Commandes
- `make test` — lance tous les tests
- `make run` — lance le serveur en local
- `make docker` — build + run dans Docker

## User Stories (priorité MoSCoW)
### Must Have
- US1 : En tant que [user], je veux [action] pour [bénéfice]
  Critères : [critères d'acceptation testables]
### Should Have
- US2 : ...
### Won't Have (pour le MVP)
- Pas d'auth OAuth
- Pas de rate limiting
- Pas de multi-tenant

Workflow de Build Supervisé

# Étape 1 : Demander un plan AVANT le code
$ claude
> Lis le CLAUDE.md et propose un plan d'implémentation
  pour US1. Liste les fichiers à créer, les dépendances,
  et les tests. Ne code rien encore.

# Étape 2 : Valider le plan, puis exécuter
> OK, implémente le plan. Commence par le domain,
  puis les adapters, puis les handlers.
  Fais un commit après chaque couche.

# Étape 3 : Vérifier
> Lance make test et montre-moi les résultats.
  Si un test échoue, corrige et recommence.

Checklist Deploy AI-Assisted

# Demandez à l'agent de créer tout le pipeline
$ claude
> Crée un pipeline CI/CD complet avec :
  1. GitHub Actions : test → build → deploy
  2. Dockerfile multi-stage optimisé
  3. docker-compose.yml avec PostgreSQL
  4. Health check endpoint /healthz
  5. Structured logging (JSON) sur stdout
  6. Métriques Prometheus sur /metrics
  7. Alerting basique (webhook Slack si le health check échoue)
  8. Rollback automatique si les smoke tests post-deploy échouent

Résumé : Votre Nouvelle Fiche de Poste

En 2026, vous êtes un PO-Developer. Vos responsabilités :

• ✅ Trouver les vrais problèmes à résoudre
• ✅ Écrire des specs claires et des critères d'acceptation testables
• ✅ Dire NON à 90% des features
• ✅ Reviewer le code de l'IA avec un œil critique
• ✅ Tester manuellement les edge cases et l'UX
• ✅ Décider quand déployer, quand scaler, quand pivoter
• ✅ Parler aux utilisateurs et comprendre leurs vrais besoins
• ❌ Écrire du code boilerplate
• ❌ Configurer des pipelines CI/CD from scratch
• ❌ Rédiger de la documentation basique
• ❌ Débugger des typos et erreurs de syntaxe

Template : Section Sécurité du CLAUDE.md

## Sécurité — Règles NON NÉGOCIABLES

### Secrets
- JAMAIS de secret dans le code, les logs, ou les commentaires
- Tous les secrets passent par des variables d'env ou un vault
- Le fichier .env est dans .gitignore
- Les secrets de prod ne sont JAMAIS sur la machine de dev

### Authentification & Autorisation
- Auth : JWT avec expiration courte (15 min) + refresh token
- Mots de passe : bcrypt avec cost ≥ 12, JAMAIS de MD5/SHA1
- Authz : RBAC ou ABAC vérifié côté serveur sur CHAQUE endpoint
- Pas de logique d'autorisation côté client uniquement

### Inputs
- TOUS les inputs sont validés côté serveur (Zod, pydantic...)
- Paramétrage SQL : requêtes paramétrées UNIQUEMENT, jamais
  de concaténation de strings dans les requêtes
- Upload fichiers : whitelist de types MIME, limite de taille

### Dépendances
- `npm audit` / `pip audit` / `govulncheck` tourne en CI
- Dépendances majeures épinglées (pas de ^latest)
- Renovate ou Dependabot activé pour les mises à jour

### Données Personnelles (RGPD/GDPR)
- PII chiffré at rest (AES-256)
- Logs purgés de toute PII
- Endpoint de suppression de compte (droit à l'oubli)
- Consentement explicite pour la collecte de données

### Headers & Transport
- HTTPS obligatoire (HSTS activé)
- CORS restrictif (pas de Access-Control-Allow-Origin: *)
- Headers de sécurité : CSP, X-Frame-Options, X-Content-Type
- Rate limiting sur tous les endpoints publics

CI/CD Security Pipeline

# .github/workflows/security.yml
name: Security Checks
on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      # 1. Scan des secrets accidentellement commités
      - uses: trufflesecurity/trufflehog@main
        with:
          extra_args: --only-verified

      # 2. Audit des dépendances vulnérables
      - run: npm audit --audit-level=high

      # 3. Analyse statique de sécurité (SAST)
      - uses: returntocorp/semgrep-action@v1
        with:
          config: p/owasp-top-ten

      # 4. Scan de l'image Docker
      - uses: aquasecurity/trivy-action@master
        with:
          image-ref: myapp:latest
          severity: CRITICAL,HIGH

      # 5. Review IA des changements sensibles
      - run: |
          claude --print "Analyse cette diff pour des
          failles de sécurité : injection SQL, XSS,
          secrets exposés, auth bypass, IDOR."

Résumé : La Sécurité en 1 Phrase

Spécifiez la sécurité dans le CLAUDE.md dès le jour 0, automatisez les checks dans la CI, et reviewez manuellement tout code touchant à l'auth, aux paiements, et aux données personnelles. Le reste peut être délégué à l'IA et aux outils automatiques.

Pourquoi les couches sont essentielles avec l'IA

L'IA est tentée de tout mélanger dans un seul fichier. Les couches forcent la séparation des responsabilités :

• Si l'IA génère un mauvais handler HTTP (couche 4), la logique métier (couche 3) n'est pas affectée
• Si vous changez de base de données (couche 2), les règles métier ne bougent pas
• Si l'IA modifie la validation (couche 2), les tests de la couche 3 détectent les régressions
• La couche Domain (3) est votre forteresse : c'est là que résident les invariants métier que l'IA ne doit JAMAIS modifier sans votre validation

Problème sans Semantic Layer

« Le revenu mensuel » signifie-t-il le revenu brut ou net ? Avec ou sans taxes ? Avec les remboursements déduits ? Chaque développeur (ou chaque agent IA) interprète différemment. Résultat : 3 dashboards montrent 3 chiffres différents pour la même métrique.

Comment implémenter une Semantic Layer

# semantic/metrics.yml — Source de vérité unique
metrics:
  monthly_revenue:
    label: "Revenu Mensuel"
    description: "Revenu net après remboursements, hors taxes"
    formula: "SUM(amount) - SUM(refunds)"
    filters:
      - "status = 'completed'"
      - "refunded = false"
    grain: monthly
    owner: finance-team

  active_users:
    label: "Utilisateurs Actifs"
    description: "Utilisateurs avec au moins 1 action dans les 30 derniers jours"
    formula: "COUNT(DISTINCT user_id) WHERE last_action > NOW() - 30d"
    grain: daily
    owner: product-team

  churn_rate:
    label: "Taux de Churn"
    description: "Proportion d'abonnés perdus sur le mois"
    formula: "churned_users / total_users_start_of_month * 100"
    grain: monthly
    owner: growth-team

Mettez ce fichier dans votre CLAUDE.md ou référencez-le. Quand l'IA doit calculer une métrique, elle utilise toujours la définition officielle. Plus d'ambiguïté.

Exemple : Contrats en Go

// internal/domain/ports.go — LES CONTRATS
// L'IA implémente ces interfaces, mais NE LES MODIFIE JAMAIS
// sans validation humaine.

// Port primaire : ce que le monde extérieur demande au domain
type OrderService interface {
    CreateOrder(ctx context.Context, req CreateOrderRequest) (Order, error)
    CancelOrder(ctx context.Context, orderID string) error
    GetOrder(ctx context.Context, orderID string) (Order, error)
}

// Port secondaire : ce que le domain attend de l'infrastructure
type OrderRepository interface {
    Save(ctx context.Context, order Order) error
    FindByID(ctx context.Context, id string) (Order, error)
    FindByCustomer(ctx context.Context, customerID string) ([]Order, error)
}

// Port secondaire : notifications
type Notifier interface {
    SendOrderConfirmation(ctx context.Context, order Order) error
}

// RÈGLE : Si l'IA veut ajouter un champ à Order ou
// modifier une interface, elle doit D'ABORD proposer
// le changement et obtenir votre validation.

Exemple : Agent Auto-Healing en CI/CD

# .github/workflows/auto-heal.yml
name: Auto-Healing Agent
on:
  schedule:
    - cron: '0 6 * * *'  # Tous les jours à 6h

jobs:
  auto-heal:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # 1. Vérifier la couverture de tests
      - run: |
          coverage=$(go test ./... -coverprofile=cover.out | grep total)
          if [ "$coverage" -lt 80 ]; then
            claude --print "La couverture est à $coverage%.
            Génère des tests pour les fichiers non couverts.
            Crée une branche fix/coverage et pousse." \
            | gh pr create --title "[Auto] Improve test coverage"
          fi

      # 2. Vérifier les dépendances vulnérables
      - run: |
          if govulncheck ./... 2>&1 | grep -q "FOUND"; then
            claude --print "Des CVE ont été trouvées dans les deps.
            Mets à jour les packages concernés, lance les tests,
            et crée une PR si tout passe."
          fi

      # 3. Vérifier la fraîcheur de la documentation
      - run: |
          stale_docs=$(find docs/ -mtime +30 -name "*.md")
          if [ -n "$stale_docs" ]; then
            claude --print "Ces fichiers de doc n'ont pas été
            mis à jour depuis 30+ jours : $stale_docs.
            Vérifie qu'ils sont toujours à jour avec le code."
          fi

Résumé : Architecture Bulletproof en 5 Règles

1. Couches strictes : Raw → Staging → Domain → Marts → Semantic. Pas de raccourcis.
2. Contrats (interfaces) : Définissez les interfaces AVANT l'implémentation. L'IA remplit, vous contractez.
3. Semantic Layer : Une définition unique pour chaque métrique, partagée par code, dashboards, et agents.
4. Immutabilité des faits : Les événements sont append-only. L'histoire ne se réécrit pas.
5. Agents auto-évolutifs : Tests, sécurité, docs, monitoring — automatisés par des agents avec validation humaine aux étapes clés.

Exemple : CLAUDE.md comme spécification vivante

Le fichier CLAUDE.md à la racine de votre projet sert de documentation vivante que l'IA lit à chaque session. Il contient les conventions, la structure du projet, les commandes, et les règles métier. C'est le pattern le plus important de l'AI-Driven Dev.

# Dans GitHub Actions
claude --print --dangerously-skip-permissions \
  "Analyse cette PR et génère un rapport de review"

Règle d'or : Plus le risque est élevé, moins l'IA doit être autonome.

• Risque faible (tests, doc, formatting) → autonomie totale
• Risque moyen (nouveau code, refactoring) → autonomie avec review
• Risque élevé (production, sécurité, données sensibles) → validation humaine obligatoire

Le multi-modèle est la meilleure approche. Chaque modèle a ses forces :

• Claude (Anthropic) — Excellent pour le raisonnement, l'architecture, et la compréhension de code complexe
• GPT-4o (OpenAI) — Rapide, bon pour le code simple et la complétion
• Gemini (Google) — Fenêtre de contexte massive (1M tokens), idéal pour les gros projets
• Modèles locaux (Ollama) — Pour la privacy et l'offline, mais qualité moindre

Astuce : utilisez Aider qui supporte nativement le multi-modèle, ou configurez des fallbacks (Claude → Gemini → GPT).

Exemple : Configurer un MCP Server

// .claude/mcp.json
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres",
               "postgresql://user:pass@localhost/mydb"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    }
  }
}

Avec cette configuration, l'IA peut directement interroger votre base de données et interagir avec GitHub pendant le développement.