AGENTS.md est un format ouvert destiné à fournir aux agents d'IA un contexte structuré sur un projet. Lorsqu'il est relié à une chaîne d'intégration et de déploiement continus (CI/CD), il devient un levier d'automatisation et de cohérence. Cet article présente cinq pratiques concrètes pour y parvenir.

1. Versionner AGENTS.md avec le reste du dépôt

Le fichier AGENTS.md doit résider à la racine du projet et être traité comme un fichier source critique. Sa présence garantit que tout agent, humain ou automatique, dispose du même référentiel.

mon-projet/
├── AGENTS.md
├── .github/
│   └── workflows/
├── package.json
├── src/
└── README.md

Contenu minimal recommandé :

• Cosneils d'environnement : commandes pour lancer le serveur de dévelopement.
• Instructions de test : scripts à exécuter avant toute contribution.
• Convention de contribution : format des messages de commit et des titres de pull request.

2. Valider AGENTS.md dans la CI

Une étape dédiée peut vérifier que le fichier existe et qu'il contient les sections obligatoires. Cela évite les dérives suite à un oubli ou une suppression accidentelle.

name: Validate AGENTS.md
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
jobs:
  check-agents-file:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Verify AGENTS.md presence and content
        run: |
          if [ ! -f "AGENTS.md" ]; then
            echo "AGENTS.md is missing"
            exit 1
          fi
          for section in "## Environment" "## Tests" "## Contribution"; do
            grep -q "$section" AGENTS.md || echo "Warning: missing $section"
          done

3. Automatiser l'installation et la synchronisation des dépendances

L'environnement doit être reproductible. La chaîne CI doit installer les dépendances exactement comme l'agent d'IA les utiliserait localement.

steps:
  - name: Checkout repository
    uses: actions/checkout@v4
  - name: Setup Node.js
    uses: actions/setup-node@v4
    with:
      node-version: '20'
  - name: Install dependencies
    run: yarn install --frozen-lockfile
  - name: Verify lockfile consistency
    run: yarn install --check-files

Important : évitez d'exécuter un build complet lors d'une session de développement, car cela désactive le rechargement à chaud et ralentit l'itération.

4. Harmoniser les tests et les contrôles qualité

AGENTS.md peut décrire les commandes de test attendues. La CI se charge de les exécuter et de bloquer la fusion en cas d'échec.

jobs:
  quality-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install dependencies
        run: yarn install --frozen-lockfile
      - name: Run linter
        run: yarn lint
      - name: Run unit tests
        run: yarn test:ci
      - name: Type check
        run: yarn type-check

5. Gouverner les pull requests et le déploiement

Les règles de contribution écrites dans AGENTS.md peuvent être automatiquement vérifiées : format du titre de la PR, présence d'une description suffisante, ou encore branches autorisées.

jobs:
  validate-pr:
    runs-on: ubuntu-latest
    steps:
      - name: Check PR title format
        env:
          TITLE: ${{ github.event.pull_request.title }}
        run: |
          if [[ ! "$TITLE" =~ ^\[[a-z0-9-]+\]\ .+ ]]; then
            echo "PR title must follow [scope] Description"
            exit 1
          fi

Exemple concret : pipeline pour une application Vite et TypeScript

Le workflow ci-dessous combine les pratiques précédentes pour une application frontend moderne.

name: Vite CI/CD
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Install dependencies
        run: yarn install --frozen-lockfile
      - name: Lint code
        run: yarn lint
      - name: Run tests
        run: yarn test:ci
      - name: Type check
        run: yarn type-check
      - name: Build for production
        if: github.ref == 'refs/heads/main'
        run: yarn build

En suivant ces pratiques, AGENTS.md devient un véritable contrat entre le projet et les agents d'IA, tandis que la CI/CD garantit que chaque changement respecte ce contrat avant d'atteindre la branche principale.