Cómo configurar las reglas de sweep.yaml y las directrices del repositorio para alinear los Pull Requests automatizados con los estándares de código

Cuando los equipos de desarrollo de software incorporan Sweep AI para automatizar correcciones de errores, pequeñas funcionalidades y tareas de refactorización, se enfrentan a un desafío crucial: asegurar que los Pull Requests (PR) generados automáticamente cumplan rigurosamente con los estándares y la arquitectura existentes del repositorio. Si no se establecen límites precisos, los modelos de lenguaje pueden generar discrepancias de estilo, omitir pruebas unitarias, utilizar métodos obsoletos o alterar accidentalmente archivos críticos de CI/CD e infraestructura.

Para evitar estas desviaciones, los equipos de ingeniería establecen un sistema de control centrado en el archivo de configuración raíz sweep.yaml. Al combinar reglas imperativas, descripciones contextuales de la arquitectura, bloqueo de directorios sensibles y retroalimentación de CI en bucle cerrado con GitHub Actions, Sweep se transforma en un desarrollador junior disciplinado que entrega código alineado con las prácticas del equipo.

1. Estructura de sweep.yaml: El manifiesto de control principal

El archivo sweep.yaml se ubica en la raíz del repositorio y actúa como el panel de configuración declarativo para el motor de Sweep AI. Cada parámetro define la manera en que el asistente analiza el código base, planifica las modificaciones y publica los PR.

A continuación se detallan los parámetros principales de configuración:

2. Definición de reglas efectivas en sweep.yaml

El array rules es el núcleo donde las convenciones internas del equipo se convierten en restricciones directas para el modelo de lenguaje. En lugar de directrices ambiguas como "escribir código limpio", las reglas deben ser claras, imperativas y verificables mediante herramientas de análisis.

Categorías clave de reglas a implementar

1. Requisitos de pruebas unitarias y cobertura

   • Exigir que cualquier lógica de negocio o endpoint nuevo incluya sus correspondientes pruebas unitarias en la ruta adecuada.
   • Ejemplo: "All new business logic must include corresponding unit tests in the same directory or tests/. Use pytest and unittest.mock."

2. Tipado estático y estándares de lenguaje

   • Forzar el uso estricto de tipos y la adopción de las características modernas del lenguaje.
   • Ejemplo: "Annotate all function parameters and return types with type hints. Use built-in generics (list, tuple, dict) instead of importing from typing."

3. Políticas de registro (logging) y limpieza de depuración

   • Estandarizar la biblioteca de logs y eliminar sentencias de impresión sueltas en producción.
   • Ejemplo: "Use loguru for application logging. In except blocks, call logger.exception with structured f-strings. Never leave print() statements in production code."

4. Modularidad y eliminación de deuda técnica residual

   • Evitar funciones excesivamente extensas y asegurar la resolución de comentarios residuales durante refactorizaciones.
   • Ejemplo: "Keep functions modular; refactor procedures longer than 50 lines. Remove redundant comments that merely restate the code. Handle all leftover TODOs."

3. Plantilla de sweep.yaml lista para producción

El siguiente ejemplo muestra un archivo sweep.yaml configurado para un microservicio moderno en Python con FastAPI y PostgreSQL:

# sweep.yaml - Configuración del repositorio para Sweep AI

# Rama base para los PR automatizados
branch: main

# Descripción del contexto arquitectónico y estándares globales
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.

# Abrir PRs como borrador para revisión humana previa
draft: false

# Habilitar integración de CI con GitHub Actions para reparación automática
gha_enabled: true

# Blindaje: Evitar que la IA modifique flujos de CI/CD, migraciones o credenciales
blocked_dirs:
  - ".github/"
  - "alembic/versions/"
  - "deploy/"
  - "config/secrets/"

# Conjunto de reglas obligatorias de codificación
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. Gobernanza extendida con SWEEP.md y directrices del repositorio

Además de los parámetros estructurados de sweep.yaml, los equipos suelen mantener un archivo complementario: SWEEP.md.

El papel de SWEEP.md

Ubicado en la raíz del proyecto, SWEEP.md funciona de manera análoga a CLAUDE.md o .cursorrules. Proporciona un contexto detallado y persistente tanto para la automatización en GitHub como para las extensiones de IDE (por ejemplo, el plugin de Sweep para JetBrains).

Un archivo SWEEP.md típico se estructura en cuatro secciones:

• Comandos de construcción y verificación: Indicaciones precisas sobre cómo compilar, formatear y ejecutar suites de pruebas (npm run lint, pytest tests/unit/ -v).
• Preferencias de estilo: Convenciones de nomenclatura (kebab-case frente a camelCase), estructura de carpetas y librerías internas preferidas.
• Pautas arquitectónicas: Flujo de datos, gestión de estado y especificaciones de interfaces de API.
• Lista de verificación de revisión: Reglas para el formato de los títulos de los PR, vinculación de tickets e historiales de cambios (CHANGELOG).

Los equipos pueden generar un archivo inicial de SWEEP.md desde el panel de Sweep navegando a Sweep Settings > Rules y seleccionando Generate SWEEP.md.

5. El bucle cerrado de CI/CD: Autocorrección mediante GitHub Actions

Incluso con reglas rigurosas, los modelos generativos pueden incurrir en errores sintácticos sutiles o descuidos en las importaciones. La mayor fortaleza de Sweep reside en su integración en bucle cerrado con GitHub Actions (gha_enabled: true).

+--------------------+         +--------------------+         +--------------------+
| Creación de Issue / | ------> | Sweep AI genera el | ------> | Abre el Pull       |
| Ticket en GitHub   |         | plan y el código   |         | Request en la rama |
+--------------------+         +--------------------+         +--------------------+
                                                                        |
                                                                        v
                                                              +--------------------+
                                                              | GitHub Actions     |
                                                              | ejecuta Linters,   |
                                                              | Tipado y Tests     |
                                                              +--------------------+
                                                                        |
                                    +-----------------------------------+
                                    |
                    [CI Correcto]   |              [CI Falla]
                         v          |                  v
            +--------------------+  |        +--------------------+
            | Listo para Code    |  |        | Sweep extrae los   |
            | Review humano      |  |        | logs y mensajes    |
            +--------------------+  |        +--------------------+
                                    |                  |
                                    |                  v
                                    |        +--------------------+
                                    +--------| Aplica parche y    |
                                             | sube nuevo commit  |
                                             +--------------------+

Dinámica del bucle cerrado:

1. Creación del PR: Sweep envía los cambios iniciales siguiendo las directrices de sweep.yaml.
2. Ejecución de CI: GitHub Actions ejecuta linters (ESLint, Ruff, Trunk), comprobadores de tipos (tsc, pyright) y pruebas unitarias.
3. Lectura de errores: Si el flujo falla, Sweep captura los registros de error con nombres de archivo y líneas afectadas.
4. Iteración correctiva: Sweep interpreta las advertencias (por ejemplo, paréntesis faltantes, tipos incompatibles o pruebas fallidas), formula un parche diff y envía un commit adicional a la rama del PR.
5. Reducción de fatiga: Los revisores humanos intervienen únicamente cuando el código ya supera todas las pruebas automáticas, optimizando el tiempo del equipo.

6. Recomendaciones prácticas para equipos de desarrollo

Para maximizar el valor de los PR automáticos y salvaguardar la estabilidad del repositorio, se recomienda adoptar las siguientes prácticas:

1. Blindar rutas críticas: Añadir obligatoriamente .github/, archivos de migración, manifiestos de despliegue y directorios de certificados en blocked_dirs.
2. Acotar el tamaño de los tickets: Limitar los Issues a menos de 5 archivos y un máximo de 300 líneas de código modificadas. Las tareas pequeñas y acotadas tienen un índice de éxito drásticamente superior.
3. Instrucciones específicas en los Issues: Indicar con precisión los archivos afectados y el comportamiento esperado (ejemplo: "In app/services/billing.py, refactor discount calculation using Decimal instead of float; follow patterns in app/services/tax.py").
4. Comentarios interactivos en el PR: Para realizar ajustes tras la creación del PR, los desarrolladores pueden comentar en la línea correspondiente iniciando con sweep:, permitiendo que la IA aplique las correcciones sin intervención manual en local.
5. Comenzar en modo Draft: Al implementar Sweep en repositorios grandes o legacy, configurar draft: true en sweep.yaml permite evaluar los resultados antes de desencadenar pipelines completos de CI.

Referencias

• 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