How to Configure sweep.yaml and Repository Guidelines for Clean, Standardized AI Pull Requests

Software engineering teams using Sweep AI to automate routine bug fixes, feature requests, and refactoring tasks face a common challenge: keeping automated pull requests strictly compliant with existing repository standards. Left unguided, AI agents can introduce stylistic inconsistencies, skip unit tests, use deprecated utility functions, or inadvertently modify critical infrastructure files.

To prevent drift, development teams establish a layered governance system centered on the repository root configuration file, sweep.yaml. By combining granular rule definitions, explicit repository descriptions, directory access blocks, and closed-loop GitHub Actions integration, teams turn Sweep into a disciplined contributor that writes code matching their team's established engineering practices.

1. Anatomy of sweep.yaml: The Core Configuration Manifest

The sweep.yaml file resides at the root of the repository and serves as the primary control manifest for the Sweep AI engine. Each parameter regulates how the agent navigates the codebase, plans modifications, and submits pull requests.

Here is a breakdown of the core configuration parameters:

2. Defining Enforceable Rules in sweep.yaml

The rules array is where teams translate internal coding standards into enforceable LLM prompt constraints. Rather than vague statements like "write clean code," effective rules must be concrete, imperative, and testable.

Key Rule Categories to Implement

1. Testing and Coverage Requirements

   • Mandate that every new business function or endpoint must include matching unit tests in the appropriate directory.
   • Example: "All new business logic must include unit tests located alongside the source file or in tests/. Use pytest and unittest.mock."

2. Typing and Static Analysis Standards

   • Direct the model to adhere to the repository's type system and avoid legacy patterns.
   • Example: "Annotate all function signatures with type hints. Use built-in generics (list, tuple, dict) rather than typing module imports."

3. Logging, Observability, and Error Handling

   • Standardize logging frameworks and prevent accidental leaks of debugging statements to production.
   • Example: "Use loguru for application logging. In except blocks, call logger.exception with structured f-strings. Do not include raw print statements."

4. Code Quality and Architectural Modularity

   • Enforce architectural layers, modular boundaries, and clean comments.
   • Example: "Keep functions focused on a single responsibility; refactor routines longer than 50 lines. Remove obvious or redundant comments."

3. Production-Ready sweep.yaml Blueprint

Below is an annotated, production-grade sweep.yaml configuration suitable for a modern full-stack or backend repository:

# sweep.yaml - Sweep AI Repository Configuration

# Target base branch for automated PRs
branch: main

# Architecture overview, runtime requirements, and entry points
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.

# Create draft PRs to allow human triage before running expensive test suites
draft: false

# Closed-loop CI/CD: read GitHub Actions failure logs to self-heal code
gha_enabled: true

# Guardrail: Prevent AI from altering CI/CD workflows, migrations, or security secrets
blocked_dirs:
  - ".github/"
  - "alembic/versions/"
  - "deploy/"
  - "config/secrets/"

# Project-specific coding standards enforced during code planning and generation
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. Expanding Governance with SWEEP.md and Repository Guidelines

While sweep.yaml handles declarative flags and concise constraints, modern teams frequently complement it with a dedicated markdown file: SWEEP.md.

The Role of SWEEP.md

Placed in the repository root, SWEEP.md operates similarly to files like CLAUDE.md or .cursorrules. It provides persistent, detailed context that can be referenced across both GitHub-based automated PRs and local IDE coding assistants (such as Sweep for JetBrains).

Teams structure SWEEP.md into four primary sections:

• Build & Verification Commands: Clear recipes for installing dependencies, compiling, linting, and running specific test suites (npm run lint, pytest tests/unit/ -v).
• Code Style Preferences: Directory layouts, file naming conventions (e.g., kebab-case vs. camelCase), and favored utility libraries.
• Architectural Guidelines: Data flow diagrams, state management patterns, and API contract specifications.
• Review Checklists: Requirements for PR titles, commit message formats, and changelog updates.

Teams can automatically generate an initial SWEEP.md from their existing repository rules by navigating to Sweep Settings > Rules and selecting Generate SWEEP.md.

5. The CI/CD Closed Loop: Aligning PRs via GitHub Actions

Even with rigorous rules, generative models can miss edge cases, forget import statements, or produce subtle typing discrepancies. The most powerful mechanism for aligning automated PRs with repository standards is Sweep's closed-loop integration with GitHub Actions (gha_enabled: true).

+------------------+         +--------------------+         +--------------------+
|  GitHub Issue /  | ------> | Sweep AI Generates | ------> | Opens Pull Request |
|  Ticket Created  |         | Code & Plan        |         | on Target Branch   |
+------------------+         +--------------------+         +--------------------+
                                                                      |
                                                                      v
                                                            +--------------------+
                                                            | GitHub Actions     |
                                                            | CI Runs (Linter,   |
                                                            | Typecheck, Tests)  |
                                                            +--------------------+
                                                                      |
                                   +----------------------------------+
                                   |
                [Checks Pass]      |      [Checks Fail]
                      v            |            v
            +-------------------+  |  +--------------------+
            | Ready for Human   |  |  | Sweep Reads CI Log |
            | Code Review       |  |  | & Error Messages   |
            +-------------------+  |  +--------------------+
                                   |            |
                                   |            v
                                   |  +--------------------+
                                   +--| Pushes Corrective  |
                                      | Fix Commit to PR   |
                                      +--------------------+

How the Feedback Loop Operates:

1. Initial PR Creation: Sweep creates a branch and opens a pull request adhering to sweep.yaml rules.
2. Automated CI Execution: GitHub Actions executes the repository's standard linters (e.g., ESLint, Ruff, Trunk), type checkers (tsc, pyright), and test suites (pytest, jest).
3. Log Consumption: If any CI step fails, Sweep captures the output logs from GitHub Actions.
4. Iterative Repair: Sweep extracts the exact file name, line numbers, and compiler/linter error messages (e.g., missing imports, undefined variables, formatting violations). It then generates a targeted diff, applies the patch, and pushes an incremental commit.
5. Human Review Readiness: Human engineers only review pull requests after automated verification succeeds, saving significant time during code reviews.

6. Practical Recommendations for Engineering Teams

To maximize efficiency and maintain trust in automated pull requests, teams should observe several operational guidelines:

1. Protect Sensitive Infrastructure: Always include .github/, deployment manifests, database migrations, and authentication configurations in blocked_dirs.
2. Scope Issue Size: Keep automated tasks focused. Issues targeting fewer than 5 files or under 300 lines of modification produce significantly higher accuracy and cleaner PR diffs.
3. Use Imperative Prompting in Issues: When filing issues, provide clear context: specify the file to inspect, the desired behavior change, and any existing patterns to follow (e.g., "In app/services/billing.py, refactor discount calculation using Decimal instead of float; follow patterns in app/services/tax.py").
4. Employ Interactive PR Feedback: If a pull request needs refinement, developers can leave comments on the PR prefixed with sweep:. Sweep reads the inline comment and updates the code accordingly without manual branch checkouts.
5. Start in Draft Mode: When onboarding Sweep to a legacy codebase, set draft: true in sweep.yaml. This enables engineering leads to inspect proposed diffs before triggering expensive CI pipelines or team notifications.

References

• 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