Dans les équipes d'ingénierie logicielle contemporaines, la gestion des anomalies récurrentes et des tâches de maintenance mineures constitue un goulet d'étranglement constant. La gestion des pointeurs nuls, la mise à niveau de dépendances obsolètes, la correction d'expressions régulières ou l'ajout de tests unitaires manquants restent souvent en attente dans le backlog pendant plusieurs semaines, mobilisant inutilement l'attention des développeurs seniors.
Sweep a été spécifiquement conçu comme un développeur junior autonome alimenté par l'intelligence artificielle (AI Junior Developer). Intégré sous forme de GitHub App dans votre dépôt, Sweep surveille l'ouverture des tickets (Issues), appréhende le code source grâce à des plongements vectoriels (embeddings) et à l'analyse d'arbres syntaxiques abstraits (AST), rédige des modifications sur plusieurs fichiers et soumet une Pull Request (PR) prête pour la revue. De surcroît, Sweep boucle la boucle d'ingénierie en analysant les échecs de tests d'intégration continue sur GitHub Actions pour s'autocorriger et en répondant aux commentaires de revue de code des développeurs.
Ce guide présente de manière approfondie la configuration de Sweep en production, l'élaboration du fichier sweep.yaml, la rédaction d'issues efficaces et l'instauration de garde-fous techniques rigoureux.
1. Fonctionnement du flux de traitement : de l'issue à la Pull Request
Avant de mettre en place la configuration, il convient de comprendre le cycle de traitement d'un ticket par Sweep :
- Événement déclencheur : Un ingénieur ouvre une issue GitHub dont le titre commence par le préfixe
Sweep:(par exemple,Sweep: Fix KeyError when user metadata payload is missing), lui attribue le labelsweepou mentionne@sweepaien commentaire. - Recherche de contexte dans le dépôt : La fonction d'entrée du webhook de Sweep (
on_ticket) s'exécute. Elle effectue une recherche vectorielle et un découpage syntaxique afin d'identifier les fichiers, classes, fonctions et tests associés au problème signalé. - Plan d'intervention : Sweep publie un commentaire sur l'issue détaillant son plan de travail, la liste des fichiers ciblés et l'approche technique retenue.
- Génération du code et branche dédiée : Sur une branche isolée (ex.
sweep/fix-...), Sweep applique les modifications requises conformément aux règles du projet. - Ouverture de la Pull Request : Sweep ouvre une PR formelle incluant la mention de clôture (
Fixes #<id>), un résumé synthétique des changements et une liste de contrôle. - Boucle de rétroaction continue :
- Autocorrection via la CI : Si l'intégration avec GitHub Actions est activée (
gha_enabled: true), Sweep analyse les journaux d'erreurs en cas d'échec des tests et soumet automatiquement des commits de correction. - Revue de code humaine : Lorsqu'un développeur commente une ligne dans le diff de la PR, Sweep prend en compte la remarque et pousse de nouveaux commits rectificatifs.
- Autocorrection via la CI : Si l'intégration avec GitHub Actions est activée (
2. Installation et gestion des permissions GitHub
Pour déployer Sweep sur vos dépôts :
- Installer la GitHub App : Rendez-vous sur la page d'installation de l'application Sweep sur GitHub et sélectionnez les dépôts à gérer.
- Accorder les permissions nécessaires :
- Repository Contents (Lecture et Écriture) : Indispensable pour explorer le code et créer des branches avec commits.
- Issues (Lecture et Écriture) : Nécessaire pour lire les descriptions, gérer les labels et publier les points d'étape.
- Pull Requests (Lecture et Écriture) : Requis pour créer des PRs, inspecter les diffs et réagir aux commentaires de revue.
- Actions / Checks (Lecture) : Requis pour accéder aux logs d'exécution lors d'échecs de builds ou de tests.
- Option Draft PR : Durant la phase de rodage, il est recommandé de configurer l'ouverture des PRs en mode brouillon (
draft: true) afin d'éviter de notifier prématurément toute l'équipe avant validation de l'approche.
3. Définir les standards de l'équipe avec sweep.yaml
Le comportement de Sweep est gouverné par le fichier sweep.yaml (ou .sweep/config.yaml) placé à la racine du dépôt. Une configuration soignée évite les hallucinations d'imports, standardise les conventions de style et sanctuarise les composants sensibles.
Modèle de production pour sweep.yaml
# sweep.yaml - Configuration pour la résolution automatisée des issues
# Branche cible sur laquelle Sweep base ses branches et ouvre ses PRs
branch: 'main'
# Ouvrir les PRs en mode brouillon (conseillé au démarrage)
draft: false
# Autoriser Sweep à exploiter les logs de GitHub Actions pour s'autocorriger
gha_enabled: true
# Description générale du projet pour guider la compréhension du modèle
description: >
API REST backend développée avec Python 3.10 et FastAPI.
Gestion de base de données assurée par SQLAlchemy 2.0 et PostgreSQL.
La logique métier se trouve dans services/, les modèles dans models/ et les routes dans api/v1/.
Tous les imports doivent être absolus (ex. `from services.auth import verify_token`).
# Répertoires et fichiers que Sweep ne doit JAMAIS lire ni modifier
blocked_dirs:
- "deploy/"
- "terraform/"
- ".github/workflows/"
- "migrations/"
- "*.env*"
- "security/"
# Commandes de sandbox exécutées avant l'ouverture de la Pull Request
sandbox:
install:
- "poetry install --no-root"
check:
- "poetry run ruff check {file_path}"
- "poetry run pytest tests/unit"
# Règles de programmation strictes injectées dans le prompt de l'agent
rules:
- "Toute correction de bug doit ajouter ou mettre à jour des tests unitaires pytest dans tests/."
- "Les imports génériques (`from module import *`) sont strictement interdits."
- "Utiliser systématiquement les schémas Pydantic v2 pour la validation des requêtes et réponses."
- "Utiliser loguru pour les logs ; inclure les traces d'appels dans les exceptions via logger.exception()."
- "Ne pas modifier le schéma de base de données ni créer de migration alembic sans consigne explicite."
- "Exiger des annotations de types complètes sur toutes les signatures de fonctions."
Explication des paramètres essentiels
branch: Détermine la branche de référence. Doit être ajusté si votre équipe travaille avec une branche d'intégration commedevelop.blocked_dirs: Barrière de sécurité incontournable. Tout fichier correspondant à ces motifs est rendu inaccessible aux modifications de Sweep (infrastructure, pipelines de CI, variables d'environnement, migrations).gha_enabled: Si activé àtrue, Sweep écoute les événements de GitHub Actions pour corriger de manière autonome les tests unitaires qui échouent.rules: Directives techniques formulées en langage naturel. L'agent les applique scrupuleusement, garantissant l'homogénéité avec vos pratiques d'équipe.sandbox: Spécifie les commandes d'installation (install) et de vérification (check) à exécuter dans un conteneur sécurisé avant toute soumission de PR.
4. Rédiger des issues précises pour maximiser la pertinence des PRs
L'efficacité du code produit par Sweep dépend directement du niveau de précision fourni dans l'issue GitHub. Contrairement à un collaborateur humain qui peut solliciter des clarifications sur Slack, l'agent IA s'en remet exclusivement à l'énoncé du problème et au dépôt de code.
Gabarit d'issue recommandé
Titre: Sweep: Fix 400 Bad Request on empty user metadata payload in /api/v1/profile
### Description de l'anomalie
Lors de la mise à jour du profil utilisateur via `PUT /api/v1/profile`, l'envoi d'un dictionnaire vide dans `metadata` déclenche une ValidationError au lieu d'initialiser les valeurs par défaut prévues.
### Étapes de reproduction
1. Envoyer une requête PUT à `/api/v1/profile` avec le corps `{"metadata": {}}`.
2. Constater que l'API renvoie une réponse HTTP 400 avec le message `Value error, metadata must contain required fields`.
### Comportement attendu
Un dictionnaire `metadata` vide doit être accepté, complété avec les valeurs par défaut (`{"theme": "light", "notifications": true}`) et sauvegardé correctement en base.
### Fichiers et fonctions concernés
- `api/v1/profile.py`: Gestionnaire de route `update_profile`.
- `schemas/profile.py`: Modèle Pydantic `UserProfileUpdate`.
- `services/profile_service.py`: Fonction utilitaire `save_profile_metadata`.
### Critères d'acceptation
- Modifier la validation dans `schemas/profile.py` afin d'accepter les dictionnaires vides avec valeurs de repli.
- Ajouter un test unitaire dans `tests/unit/test_profile_api.py` couvrant ce cas de figure.
- S'assurer que l'intégralité des tests dans `tests/unit/` réussissent.
Préfixes de titre et modes d'exécution
Le module de détection de Sweep (strip_sweep) prend en charge des préfixes de titre permettant de moduler l'exécution :
Sweep: <titre>: Traitement standard de la tâche.Sweep(sandbox): <titre>: Exécution et validation préalables obligatoires en sandbox.Sweep(fast): <titre>: Utilisation d'un modèle plus rapide pour les retouches élémentaires.Sweep(slow): <titre>: Raisonnement approfondi pour les anomalies impliquant plusieurs modules.Sweep(lint): <titre>: Contrôle renforcé du formatage et des outils d'analyse statique.Sweep(subissues): <titre>: Découpage automatique d'un ticket complexe en sous-tâches indépendantes.
5. Revue de code et processus d'itération
Une fois la Pull Request ouverte par Sweep, les échanges s'effectuent directement dans l'interface de GitHub :
[Issue GitHub] ──> Déclenchement Sweep ──> PR Créée ──> CI (GitHub Actions)
│
┌────────────────────────────────────┴─────┐
▼ ▼
CI en échec (gha_enabled) CI validée
│ │
▼ ▼
Sweep committe un correctif Revue de code humaine
│ │
└─────────► PR Actualisée ◄────────────────┘
│
(Commentaire dans le Diff :
"@sweepai réutilise la fonction
utilitaire existante")
Commentaires en ligne dans le diff
Les ingénieurs n'ont pas besoin de cloner la branche en local pour effectuer de menues corrections. Il suffit de laisser une remarque sur la ligne ciblée :
@sweepai Merci d'utiliser ici notre fonction utilitaire DateUtils.formatIso() plutôt que d'instancier un nouveau formateur de date.
Sweep intercepte le webhook du commentaire, contextualise la demande et publie un nouveau commit sur la même branche.
Régénération de la PR
Si les besoins exprimés dans l'issue initiale doivent être réorientés, inutile de fermer manuellement la PR : il suffit de modifier le titre ou la description de l'issue GitHub d'origine. Sweep détecte la mise à jour, réinitialise la branche et génère une nouvelle PR conforme aux nouvelles directives.
6. Pratiques de sécurité et gouvernance en entreprise
Pour intégrer un agent autonome en production sans risque opérationnel :
- Approbation humaine obligatoire : Ne configurez jamais la fusion automatique (Auto-merge) sur les PRs créées par Sweep. Maintenez des règles de protection de branche exigeant au minimum l'approbation d'un développeur senior et la validation complète de la CI.
- Isolation des répertoires sensibles : Verrouillez impérativement via
blocked_dirsle code d'infrastructure (terraform/,k8s/), les configurations de workflows (.github/), les scripts de migration de bases de données et les fichiers de secrets. - Délimitation du périmètre : Confiez à Sweep des résolutions de bugs bien circonscrites, l'écriture de tests et de petits refactorings. Évitez les chantiers d'architecture ou les demandes fonctionnelles aux spécifications imprécises.
- Rigueur de la suite de tests : La capacité d'autoguérison de Sweep repose intégralement sur la pertinence des messages d'erreur de votre suite de tests. Plus votre couverture de tests est robuste, plus l'intervention de l'agent est fiable et sécurisée.
Références
- GitHub - sweepai/sweep: Sweep: AI coding assistant for JetBrains
- GitHub - sweepai/sweep: sweep.yaml configuration file
- GitHub - sweepai/sweep: sweepai/config/client.py
- GitHub - sweepai/sweep: sweepai/handlers/on_ticket.py
- GitHub - sweepai/sweep: sweepai/utils/str_utils.py
- sweepai · PyPI
- Launch YC: Sweep: JetBrains AI Coding Assistant | Y Combinator