Comment configurer les règles de sweep.yaml et les directives du dépôt pour aligner les Pull Requests automatisées avec les standards de code

Lorsque les équipes d'ingénierie logicielle intègrent Sweep AI pour automatiser la correction de bugs, l'ajout de fonctionnalités mineures ou les refactorisations de routine, elles font face à un défi stratégique : veiller à ce que les Pull Requests (PR) générées respectent scrupuleusement les conventions architecturales et les standards de code établis. Sans directives explicites, les modèles de langage peuvent produire du code aux formats disparates, omettre les tests unitaires nécessaires, invoquer des fonctions internes obsolètes ou modifier involontairement des fichiers critiques de CI/CD et de sécurité.

Pour prévenir toute dérive de la base de code, les équipes déploient une gouvernance à plusieurs niveaux articulée autour du fichier de configuration racine sweep.yaml. En combinant des règles impératives, une description contextuelle du projet, le verrouillage des répertoires sensibles et une boucle de rétroaction avec GitHub Actions, Sweep se comporte comme un développeur junior rigoureux dont les propositions de code s'intègrent harmonieusement aux pratiques de l'équipe.

1. Structure de sweep.yaml : Le manifeste de contrôle central

Placé à la racine du dépôt, le fichier sweep.yaml constitue le point d'entrée déclaratif pour le moteur de Sweep AI. Chaque paramètre détermine la façon dont l'agent explore le projet, planifie les modifications et publie les PR.

Voici le récapitulatif des paramètres de configuration fondamentaux :

2. Définir des règles concrètes dans sweep.yaml

Le tableau rules permet de traduire les exigences de qualité internes en contraintes d'invite strictes pour le modèle. Les formules vagues telles que « écrire du code propre » sont inefficaces ; les règles doivent être précises, rédigées à l'impératif et vérifiables par des outils automatisés.

Principales catégories de règles à instaurer

1. Obligation de tests et couverture

   • Exiger systématiquement que toute nouvelle logique métier s'accompagne de tests unitaires dans le répertoire approprié.
   • Exemple : "All new business logic must include corresponding unit tests in the same directory or tests/. Use pytest and unittest.mock."

2. Typage statique et rigueur syntaxique

   • Imposer l'annotation stricte des signatures de fonction et privilégier les types génériques natifs récents.
   • Exemple : "Annotate all function parameters and return types with type hints. Use built-in generics (list, tuple, dict) instead of importing from typing."

3. Standardisation des journaux (logging) et nettoyage

   • Définir le framework officiel de journalisation et interdire les instructions d'impression brutes en production.
   • Exemple : "Use loguru for application logging. In except blocks, call logger.exception with structured f-strings. Never leave print() statements in production code."

4. Modularité et élimination de la dette résiduelle

   • Fixer un seuil maximal pour la taille des fonctions et s'assurer que les repères de refactorisation temporaires soient résolus.
   • Exemple : "Keep functions modular; refactor procedures longer than 50 lines. Remove redundant comments that merely restate the code. Handle all leftover TODOs."

3. Modèle de sweep.yaml prêt pour la production

Voici une configuration sweep.yaml adaptée à un microservice backend moderne reposant sur Python, FastAPI et PostgreSQL :

# sweep.yaml - Configuration du dépôt pour Sweep AI

# Branche cible pour les PR automatisées
branch: main

# Synthèse architecturale, dépendances et directives de développement
description: >
  This is a Python 3.10 microservice built on FastAPI with PostgreSQL.
  The primary API routes are registered in app/api/v1/.
  Use SQLAlchemy 2.0 async sessions for database access.
  Strictly adhere to PEP 8 standards and asynchronous I/O paradigms.

# Créer les PR sous forme de brouillon pour vérification préliminaire
draft: false

# Boucle fermée de CI : autorise la lecture des logs GitHub Actions pour l'autocorrection
gha_enabled: true

# Protection stricte : interdire toute modification de la CI, des migrations et des secrets
blocked_dirs:
  - ".github/"
  - "alembic/versions/"
  - "deploy/"
  - "config/secrets/"

# Règles de codage impératives appliquées lors de la génération
rules:
  - "All new endpoints and service logic must include corresponding unit and integration tests using pytest."
  - "Annotate all function parameters and return values with strict type hints."
  - "Use structured logging via loguru; use logger.exception inside catch blocks. Never use print() statements."
  - "Use list, dict, and tuple built-ins for type annotations instead of importing from typing."
  - "Resolve any remaining TODO items created during refactoring before finalizing the PR."
  - "Follow existing repository import conventions: group external libraries first, then internal module imports."
  - "Do not modify database migrations or schema files without explicit issue instructions."

4. Gouvernance élargie avec SWEEP.md et directives locales

En complément des indicateurs techniques de sweep.yaml, les équipes techniques ajoutent fréquemment un fichier documentaire nommé SWEEP.md à la racine de leur dépôt.

Le rôle de SWEEP.md

Comparable à CLAUDE.md ou .cursorrules, le fichier SWEEP.md procure un contexte persistant. Il guide à la fois les agents automatisés opérant sur GitHub et les développeurs interagissant avec les extensions d'IDE (notamment le plugin Sweep pour JetBrains).

Un fichier SWEEP.md standard s'articule généralement autour de quatre volets :

• Commandes de compilation et de contrôle : Commandes exactes pour lancer les tests, le formatage et l'analyse statique (npm run lint, pytest tests/unit/ -v).
• Préférences de style de code : Conventions de nommage des fichiers (ex. kebab-case strict), arborescence des modules et bibliothèques internes recommandées.
• Architecture et flux de données : Sens des dépendances entre couches, gestion d'état et contrats d'interfaces d'API.
• Check-list de revue de code : Structure des titres de PR, règles de liaison aux tickets et tenue du journal des modifications (CHANGELOG).

Il est possible de générer une ébauche de ce fichier depuis l'interface de Sweep via l'onglet Rules dans les paramètres, en cliquant sur Generate SWEEP.md.

5. La boucle fermée CI/CD : L'autoréparation via GitHub Actions

Même avec des consignes bien calibrées, les modèles génératifs peuvent trébucher sur des dépendances complexes, des inférences de types globales ou des parenthèses non refermées. Le mécanisme le plus puissant de Sweep pour garantir la conformité du code repose sur sa boucle d'autocorrection avec GitHub Actions (gha_enabled: true).

+--------------------+         +--------------------+         +--------------------+
| Création du ticket | ------> | Sweep AI conçoit   | ------> | Ouvre une Pull     |
| Issue sur GitHub   |         | le plan et le code |         | Request sur cible  |
+--------------------+         +--------------------+         +--------------------+
                                                                        |
                                                                        v
                                                              +--------------------+
                                                              | GitHub Actions     |
                                                              | exécute Linters,   |
                                                              | Types & Tests      |
                                                              +--------------------+
                                                                        |
                                    +-----------------------------------+
                                    |
                    [CI validée]    |                 [CI en échec]
                         v          |                       v
            +--------------------+  |           +--------------------+
            | Prêt pour la revue |  |           | Sweep capture les  |
            | de code humaine    |  |           | logs et les erreurs|
            +--------------------+  |           +--------------------+
                                    |                       |
                                    |                       v
                                    |           +--------------------+
                                    +-----------| Pousse un commit   |
                                                | de patch correctif |
                                                +--------------------+

Étapes du cycle d'autocorrection :

1. Création de la PR : Sweep prépare la branche et soumet la PR selon les règles définies dans sweep.yaml.
2. Exécution des contrôles de CI : GitHub Actions lance les outils d'assurance qualité (ESLint, Ruff, Trunk), les vérificateurs de types (tsc, pyright) et les suites de tests.
3. Récupération des anomalies : En cas d'échec, Sweep intercepte automatiquement la sortie standard et les traces d'erreur.
4. Application du correctif : L'agent repère le fichier, la ligne exacte et la cause de l'erreur (import manquant, incompatibilité de type, problème de syntaxe), calcule un patch ciblé et applique un commit correctif sur la branche.
5. Gain de temps pour les relecteurs : Les ingénieurs humains n'interviennent que lorsque l'ensemble des validations automatisées est au vert, concentrant ainsi leur attention sur la logique métier.

6. Bonnes pratiques opérationnelles pour les équipes

Pour instaurer une collaboration fiable et pérenne avec l'IA, les équipes doivent respecter quelques principes clés :

1. Verrouiller les répertoires sensibles : Inscrivez obligatoirement .github/, les scripts de déploiement, les migrations de bases de données et les répertoires de clés privées dans blocked_dirs.
2. Délimiter la portée des tickets : Ciblez des tâches restreintes n'affectant pas plus de 3 à 5 fichiers et moins de 300 lignes modifiées. La précision de l'agent est nettement supérieure sur des périmètres réduits.
3. Fournir des consignes précises dans l'Issue : Spécifiez le fichier à examiner, la modification souhaitée et des exemples existants (ex. : "In app/services/billing.py, refactor discount calculation using Decimal instead of float; follow patterns in app/services/tax.py").
4. Ajuster interactivement sur la PR : Si une modification mineure est requise, ajoutez un commentaire sur la ligne concernée préfixé par sweep:. L'agent mettra à jour le code sans intervention locale manuelle.
5. Débuter en mode Draft : Lors de l'adoption de Sweep sur un projet d'envergure, configurez draft: true dans sweep.yaml pour auditer les premiers résultats avant d'engager les pipelines de test complets.

Références

• GitHub - sweepai/sweep: Sweep: AI coding assistant for JetBrains
• Sweep Config Documentation
• Sweep Advanced Features Guide
• Sweep Official Repository sweep.yaml
• CodeCrafters Frontend sweep.yaml Configuration
• Sweep Client Configuration Parser
• AI-powered junior dev meets Trunk, a super-linter