un exemple de workflow GitHub Actions :

Je te donne un exemple complet et adaptable :

• ① Un workflow GitHub Actions avec :
  • validation OpenAPI
  • diff OpenAPI
  • tests API
  • appel à un agent Claude si le contrat n’est pas respecté
• ② Un pseudo-code de script pour appeler Claude et générer un rapport.

(Je reste volontairement “agnostique” sur le SDK exact Anthropic : tu pourras brancher Node, Python, etc.)

1️⃣ Workflow GitHub Actions : openapi-contract-check.yml

À mettre dans .github/workflows/openapi-contract-check.yml

name: OpenAPI Contract Check

on:
  pull_request:
    paths:
      - "docs/openapi.yaml"
      - "src/**"
      - ".github/workflows/openapi-contract-check.yml"

jobs:
  contract-check:
    runs-on: ubuntu-latest

    env:
      OPENAPI_SPEC_PATH: docs/openapi.yaml
      GENERATED_SPEC_PATH: docs/generated-openapi.yaml

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Node
        uses: actions/setup-node@v4
        with:
          node-version: "20"

      # 1. Installer les outils OpenAPI (validation + diff)
      - name: Install OpenAPI tools
        run: |
          npm install -g @redocly/cli @openapitools/openapi-generator-cli

      # 2. Valider la spec de référence
      - name: Validate reference OpenAPI spec
        run: |
          redocly lint $OPENAPI_SPEC_PATH

      # 3. Générer une spec OpenAPI depuis le code (optionnel / à adapter)
      #    Ici, c'est un placeholder: tu peux remplacer par un script maison
      - name: Generate OpenAPI from code (placeholder)
        run: |
          # TODO: remplacer par ton outil ou script (NestJS, FastAPI, etc.)
          # Par exemple: npm run generate-openapi
          # Pour l'exemple, on copie juste la spec = "pas de changement"
          cp $OPENAPI_SPEC_PATH $GENERATED_SPEC_PATH

      # 4. Faire un diff entre la spec de référence et la spec générée
      - name: Diff OpenAPI specs
        id: openapi_diff
        run: |
          # Exemple avec redocly (ou tout autre outil de diff)
          # redocly diff $OPENAPI_SPEC_PATH $GENERATED_SPEC_PATH
          # Pour avoir un résultat machine-friendly, on fait un simple diff texte :
          diff -u $OPENAPI_SPEC_PATH $GENERATED_SPEC_PATH > openapi.diff || echo "DIFF_EXIT_CODE=$?" >> $GITHUB_ENV

      # 5. Lancer les tests (Jest, Playwright, Supertest, etc.)
      - name: Install dependencies
        run: |
          npm install

      - name: Run tests
        run: |
          npm test

      # 6. Si il y a un diff OpenAPI → appel à l’agent Claude pour analyse
      - name: Check if OpenAPI diff exists
        id: check_diff
        run: |
          if [ -s openapi.diff ]; then
            echo "has_diff=true" >> $GITHUB_OUTPUT
          else
            echo "has_diff=false" >> $GITHUB_OUTPUT
          fi

      - name: Run Claude contract review
        if: steps.check_diff.outputs.has_diff == 'true'
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          echo "Running Claude OpenAPI contract review..."
          node scripts/claude-openapi-review.js \
            --spec $OPENAPI_SPEC_PATH \
            --generated $GENERATED_SPEC_PATH \
            --diff openapi.diff \
            --output contract-report.md

      # 7. Upload du rapport comme artefact
      - name: Upload contract report
        if: steps.check_diff.outputs.has_diff == 'true'
        uses: actions/upload-artifact@v4
        with:
          name: openapi-contract-report
          path: contract-report.md

      # 8. (Optionnel) Ajouter un commentaire automatique dans la PR
      - name: Post PR comment with contract report
        if: steps.check_diff.outputs.has_diff == 'true'
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          path: contract-report.md

👉 Idée clé :

• La CI reste déterministe pour la validation/diff.
• Claude n’intervient que comme “analyste” pour expliquer les écarts, prioriser, proposer des corrections.

2️⃣ Script d’agent Claude : scripts/claude-openapi-review.js

Exemple en Node.js (pseudo-code très proche de la réalité).

#!/usr/bin/env node

import fs from "fs";
import path from "path";
import process from "process";
import { Anthropic } from "@anthropic-ai/sdk"; // à installer: npm i @anthropic-ai/sdk
import yargs from "yargs";
import { hideBin } from "yargs/helpers";

const argv = yargs(hideBin(process.argv))
  .option("spec", { type: "string", demandOption: true })
  .option("generated", { type: "string", demandOption: true })
  .option("diff", { type: "string", demandOption: true })
  .option("output", { type: "string", default: "contract-report.md" })
  .parseSync();

async function main() {
  const anthropic = new Anthropic({
    apiKey: process.env.ANTHROPIC_API_KEY,
  });

  const spec = fs.readFileSync(path.resolve(argv.spec), "utf8");
  const generated = fs.readFileSync(path.resolve(argv.generated), "utf8");
  const diff = fs.readFileSync(path.resolve(argv.diff), "utf8");

  const systemPrompt = `
Tu es un expert API / OpenAPI / QA contrat.
Ta mission :
- analyser les différences entre la spec de référence et la spec générée,
- identifier les problèmes de compatibilité,
- proposer des corrections concrètes (soit côté code, soit côté spec),
- prioriser ce qui est bloquant vs ce qui est mineur.

Réponds en Markdown structuré, avec :
- Résumé global
- Liste des endpoints impactés
- Problèmes détectés (par gravité)
- Suggestions de correction
  `;

  const userPrompt = `
# OpenAPI Spec de référence

\`\`\`yaml
${spec}
\`\`\`

# OpenAPI générée

\`\`\`yaml
${generated}
\`\`\`

# Diff (unifié)

\`\`\`diff
${diff}
\`\`\`
  `;

  const msg = await anthropic.messages.create({
    model: "claude-3-5-sonnet-20241022",
    max_tokens: 2000,
    system: systemPrompt,
    messages: [
      {
        role: "user",
        content: userPrompt,
      },
    ],
  });

  const content = msg.content?.[0]?.text ?? "Aucun contenu généré.";
  fs.writeFileSync(argv.output, content, "utf8");
  console.log(`Contract report generated in ${argv.output}`);
}

main().catch((err) => {
  console.error("Error in Claude OpenAPI review:", err);
  process.exit(1);
});

3️⃣ Comment ça s’insère dans ta logique Spec-Kit / Taskflow ?

1. Spec-Kit (GitHub)
   → décrit :
   • les endpoints attendus
   • les validations
   • le contrat OpenAPI à respecter (/docs/openapi.yaml)
2. Code (humain + IA)
   → produits par devs + Claude Code / Copilot / Replit / etc.
3. CI
   • Vérifie la spec OpenAPI (lint/validate)
   • Compare référence vs généré (diff)
   • Lance les tests auto
4. Claude Agent “Contract Review”
   • lit la spec + le diff
   • te produit un rapport lisible, priorisé, exploitable
   • potentiellement : génère des patchs de spec ou de code (prochaine étape)

Résultat : tu as un garde-fou dur (openapi-validate/diff/tests)

• une couche d’intelligence (Claude) pour le diagnostic et la correction.