So konfigurieren Entwicklungsteams sweep.yaml-Regeln und Repository-Richtlinien für automatisierte Pull Requests nach bestehenden Codierungsstandards

Wenn Software-Engineering-Teams Sweep AI einsetzen, um routinemäßige Bugfixes, kleinere Funktionserweiterungen oder Refactorings zu automatisieren, stehen sie vor einer zentralen Herausforderung: Wie stellt man sicher, dass die automatisierten Pull Requests (PRs) exakt den gewachsenen Architektur- und Codierungsstandards des Repositories entsprechen? Ohne explizite Leitplanken neigen Sprachmodelle dazu, Formatierungsregeln zu verletzen, Unit-Tests zu vergessen, veraltete Bibliotheksfunktionen aufzurufen oder versehentlich kritische CI/CD- und Sicherheitsdateien zu verändern.

Um diesen Qualitätsverlust zu verhindern, etablieren Teams ein mehrstufiges Governance-Modell mit der Konfigurationsdatei sweep.yaml im Root-Verzeichnis als zentraler Schaltstelle. Durch präzise Verhaltensregeln, architektonische Kontextbeschreibungen, Verzeichnissperren und eine geschlossene CI-Rückkopplung über GitHub Actions agiert Sweep wie ein disziplinierter Junior-Entwickler, dessen Code nahtlos in die bestehende Codebasis passt.

1. Die Anatomie von sweep.yaml: Das zentrale Kontrollmanifest

Die Datei sweep.yaml liegt im Stammverzeichnis des Projekts und dient als primäres deklaratives Steuerungsinstrument für die Sweep-Engine. Jeder Konfigurationsschlüssel beeinflusst direkt, wie das System den Quellcode liest, Änderungen plant und PRs erstellt.

Die wesentlichen Konfigurationsparameter im Überblick:

2. Formulierung verbindlicher Regeln in sweep.yaml

Das Array rules fungiert als Übersetzer teaminterner Qualitätsrichtlinien in strikte Prompt-Bedingungen für das Sprachmodell. Vage Aufforderungen wie „schreibe sauberen Code“ erzielen kaum Wirkung. Regeln müssen präzise, imperativ und idealerweise maschinell überprüfbar formuliert sein.

Relevante Regelkategorien

1. Testanforderungen und Testabdeckung

   • Vorschreiben, dass jede neue Geschäftslogik von entsprechenden Unit-Tests im vorgegebenen Verzeichnis begleitet werden muss.
   • Beispiel: "All new business logic must include corresponding unit tests in the same directory or tests/. Use pytest and unittest.mock."

2. Typisierung und statische Code-Analyse

   • Erzwingen moderner Sprachsyntax und vollständiger Typannotationen für alle Funktionen.
   • Beispiel: "Annotate all function parameters and return types with type hints. Use built-in generics (list, tuple, dict) instead of importing from typing."

3. Logging-Vorgaben und Bereinigung von Debug-Code

   • Festlegen der Standard-Logging-Bibliothek und striktes Verbot von temporären Konsolenausgaben in Produktionscode.
   • Beispiel: "Use loguru for application logging. In except blocks, call logger.exception with structured f-strings. Never leave print() statements in production code."

4. Modularität und Refactoring-Disziplin

   • Begrenzen der Komplexität einzelner Methoden und Beseitigen offener Aufgabenkommentare.
   • Beispiel: "Keep functions modular; refactor procedures longer than 50 lines. Remove redundant comments that merely restate the code. Handle all leftover TODOs."

3. Praxistaugliche sweep.yaml-Vorlage für Produktionsumgebungen

Nachfolgend ist eine beispielhafte sweep.yaml-Konfiguration für einen modernen Python-Backend-Dienst mit FastAPI und PostgreSQL dargestellt:

# sweep.yaml - Sweep AI Repository-Konfiguration

# Basis-Branch für automatisierte PRs
branch: main

# Architekturüberblick, Frameworks und Entwicklungsleitlinien
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.

# PRs zunächst als Entwurf anlegen, um vorab manuelle Sichtprüfungen zu ermöglichen
draft: false

# CI/CD-Rückkopplung aktivieren: Sweep analysiert CI-Fehlerlogs zur Selbstreparatur
gha_enabled: true

# Schutz kritischer Pfade: Workflows, Datenbankmigrationen und Secrets sperren
blocked_dirs:
  - ".github/"
  - "alembic/versions/"
  - "deploy/"
  - "config/secrets/"

# Verbindliche Programmierregeln für die Code-Generierung
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. Erweiterte Steuerung über SWEEP.md und Repository-Richtlinien

Neben den technischen Flags in sweep.yaml ergänzen Entwicklungsteams ihre Repositorys häufig um eine dedizierte Dokumentationsdatei: SWEEP.md.

Die Funktion von SWEEP.md

Vergleichbar mit Dateien wie CLAUDE.md oder .cursorrules stellt SWEEP.md persistenten Kontext bereit. Diese Informationen leiten nicht nur die autonome PR-Erstellung auf GitHub, sondern stehen Entwicklern auch bei der Nutzung von IDE-Erweiterungen (wie dem Sweep-Plugin für JetBrains) zur Verfügung.

Eine typische SWEEP.md gliedert sich in vier Abschnitte:

• Build- und Prüfbefehle: Genaue Kommandos zum Ausführen von Tests, Lintern und Typüberprüfungen (npm run lint, pytest tests/unit/ -v).
• Codestil-Konventionen: Vorgaben für Dateinamen (z. B. striktes kebab-case), bevorzugte Hilfsbibliotheken und Modulstrukturen.
• Architektur & Datenfluss: Abhängigkeitsrichtungen zwischen Komponenten, Statusverwaltung und API-Schnittstellendefinitionen.
• Checkliste für Code-Reviews: Format von PR-Titeln, Zuordnung zu Issues und Aktualisierung von Änderungsprotokollen (CHANGELOG).

Teams können eine initiale SWEEP.md direkt über die Sweep-Einstellungen unter Sweep Settings > Rules über die Funktion Generate SWEEP.md erzeugen lassen.

5. Geschlossener CI/CD-Kreislauf: Automatische Fehlerbehebung via GitHub Actions

Selbst bei strikten Vorgaben können LLMs syntaktische Feinheiten, globale Typinferenzen oder fehlende schließende Klammern übersehen. Der stärkste Hebel zur Gewährleistung von Codequalität ist Sweeps automatisierte Rückkopplungsschleife mit GitHub Actions (gha_enabled: true).

+--------------------+         +--------------------+         +--------------------+
| GitHub Issue /     | ------> | Sweep AI entwirft  | ------> | Eröffnet Pull      |
| Ticket erstellt    |         | Plan und Code      |         | Request auf Branch |
+--------------------+         +--------------------+         +--------------------+
                                                                        |
                                                                        v
                                                              +--------------------+
                                                              | GitHub Actions     |
                                                              | führt Linter, Typ- |
                                                              | check & Tests aus  |
                                                              +--------------------+
                                                                        |
                                    +-----------------------------------+
                                    |
                    [CI erfolgreich]|              [CI schlägt fehl]
                         v          |                     v
            +--------------------+  |           +--------------------+
            | Bereit für         |  |           | Sweep liest CI-    |
            | manuelles Review   |  |           | Fehlerprotokolle   |
            +--------------------+  |           +--------------------+
                                    |                     |
                                    |                     v
                                    |           +--------------------+
                                    +-----------| Sendet Reparatur-  |
                                                | Commit auf Branch  |
                                                +--------------------+

Phasen des geschlossenen Regelkreises:

1. PR-Eröffnung: Sweep erzeugt die Änderungen anhand des Issues und der Vorgaben aus sweep.yaml.
2. Automatisierte CI-Validierung: GitHub Actions führt die konfigurierten Linter (z. B. ESLint, Ruff, Trunk), Typ-Checker (tsc, pyright) und Test-Suites aus.
3. Erfassung von Fehlerprotokollen: Bricht ein Job ab, ruft Sweep die Standardausgaben und Tracebacks automatisch ab.
4. Gezielte Korrektur: Das System identifiziert betroffene Dateien, Zeilennummern und Fehlermeldungen (z. B. ungenutzte Imports oder fehlerhafte Rückgabetypen), berechnet einen minimalen Patch und committet diesen direkt auf den PR-Branch.
5. Entlastung der Reviewer: Menschliche Entwickler prüfen den Pull Request erst, wenn sämtliche automatisierten Checks bereits erfolgreich durchlaufen wurden.

6. Praxistipps für Entwicklungsteams

Um die Effizienz zu maximieren und Störungen im Entwicklungsalltag zu vermeiden, sollten Teams folgende Grundregeln beachten:

1. Sperrung essenzieller Pfade: Tragen Sie .github/, Bereitstellungsskripte, Datenbankmigrationen und Verzeichnisse mit Geheimnissen stets in blocked_dirs ein.
2. Fokussierte Aufgabenstellung: Begrenzen Sie Issues auf weniger als 5 Dateien und maximal 300 Zeilen Änderung. Kleine, abgegrenzte Aufgaben weisen eine signifikant höhere Erfolgsquote auf.
3. Konkrete Kontextangaben in Issues: Nennen Sie die zu bearbeitende Datei, das gewünschte Verhalten und ggf. eine Referenzimplementierung (z. B.: "In app/services/billing.py, refactor discount calculation using Decimal instead of float; follow patterns in app/services/tax.py").
4. Interaktive Anpassung im PR: Falls Detailkorrekturen nötig sind, genügt ein Kommentar im PR mit dem Präfix sweep:. Sweep liest die Anmerkung und aktualisiert den Code direkt im Branch.
5. Schrittweise Einführung im Draft-Modus: Bei der Einführung in bestehende oder historisch gewachsene Repositories empfiehlt sich zunächst draft: true in sweep.yaml, um Ergebnisse vor dem Anstoßen vollständiger CI-Läufe manuell gegenzuprüfen.

Referenzen

• 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