当软件工程团队引入 Sweep AI 来处理常规 Bug 修复、小型功能开发和代码重构时，最常面临的挑战是如何确保 AI 自动提交的 Pull Request（PR）严格符合团队既有的编码规范与架构约定。如果缺乏明确的规则约束，AI 往往会写出风格脱节的代码、遗漏单元测试、使用已被废弃的内部工具函数，甚至误改核心 CI/CD 流水线与安全配置文件。
为了让自动化 PR 真正具备生产可用性，研发团队通常以仓库根目录下的 sweep.yaml 配置文件为核心，结合仓库规范文档（如 SWEEP.md）、目录保护机制以及 GitHub Actions 闭环反馈，构建一套完整的 AI 代码治理流程。
1. 核心控制平面：sweep.yaml 结构解析
sweep.yaml 位于代码仓库的根目录，是 Sweep AI 代理行为的核心声明文件。文件中的各项参数直接影响 AI 如何理解代码库、规划修改范围以及提交 PR。
以下是 sweep.yaml 的关键配置字段：
| 参数 | 类型 | 默认值 | 作用说明 |
|---|---|---|---|
rules | list[str] | [] | 明确的代码规范与指令列表，直接注入 Sweep 的代码生成提示词中。 |
description | str | "" | 仓库全局架构、技术栈、核心路由与设计模式的高层次说明。 |
blocked_dirs | list[str] | [] | 禁止 Sweep 修改的目录或文件列表（如 CI 配置、数据库迁移脚本、安全凭据）。 |
gha_enabled | bool | true | 是否允许 Sweep 读取 GitHub Actions 的执行日志，在 CI 报错时自动提交修复代码。 |
draft | bool | false | 是否默认创建草稿（Draft）PR，避免频繁触发耗时的完整测试流水线。 |
branch | str | "main" | Sweep 读取代码以及提交 PR 的目标基线分支。 |
sandbox | dict | {} | 沙箱环境下的安装与代码检查指令（如格式化、静态分析工具）。 |
2. 如何在 sweep.yaml 中编写可落地的规则
rules 字段是团队把编码规范转化为大模型约束条件的主战场。大模型对“保持代码整洁”这类抽象要求通常缺乏执行力，规则必须具体、具备命令式口吻并能够被自动化验证。
重点规则类别与实践技巧
-
测试与覆盖率规范
- 强制要求新增逻辑必须配有对应目录下的单元测试。
- 示例：
"All new business logic must include corresponding unit tests in the same directory or tests/. Use pytest and unittest.mock."
-
类型系统与静态检查
- 规定函数的类型注解风格，避免过时或非推荐语法。
- 示例：
"Annotate all function parameters and return types with type hints. Use built-in generics (list, tuple, dict) instead of importing from typing."
-
日志规范与调试清理
- 统一日志输出库，禁止将调试语句或明文日志推送到生产环境。
- 示例：
"Use loguru for application logging. In except blocks, call logger.exception with structured f-strings. Never leave print() statements in production code."
-
架构边界与代码精简
- 控制单个函数的圈复杂度，清理冗余注释与残留标记。
- 示例：
"Keep functions modular; refactor procedures longer than 50 lines. Remove redundant comments that merely restate the code. Handle all leftover TODOs."
3. 生产级 sweep.yaml 配置蓝图
以下是一份适用于现代后端或全栈项目的典型 sweep.yaml 配置示例：
# sweep.yaml - Sweep AI 代码库自动化配置文件
# 指定 PR 的基线分支
branch: main
# 代码库的高层架构背景与规范总览
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.
# 新 PR 是否作为草稿创建（团队可在初检后再转为正式 PR）
draft: false
# 启用 GitHub Actions 闭环：CI 失败时由 Sweep 自动拉取日志并修复
gha_enabled: true
# 目录保护：严禁 AI 修改工作流、数据库迁移版本或敏感部署配置
blocked_dirs:
- ".github/"
- "alembic/versions/"
- "deploy/"
- "config/secrets/"
# 具体编码约束列表
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. 扩展治理：SWEEP.md 与仓库多层规范协作
在实践中，除了用于配置机器参数的 sweep.yaml，团队常在根目录下放置 SWEEP.md 文件。
SWEEP.md 的定位与价值
SWEEP.md 类似于 CLAUDE.md 或 .cursorrules，主要提供持久化的上下文信息。它不仅适用于 GitHub 端的自主 PR 生成，也同时为 IDE 插件端（如 JetBrains 插件）的开发者助手提供一致的项目背景。
标准的 SWEEP.md 通常包含以下核心模块：
- 常用构建与验证命令： 声明日常测试、类型检查和代码格式化的具体命令（如
npm run lint、pytest tests/unit/ -v）。 - 代码风格偏好： 命名约定（如文件名统一采用 kebab-case）、函数长度限制以及推荐使用的内部工具包。
- 架构与数据流说明： 各模块的依赖方向、状态管理策略与接口规范。
- PR 提交自查清单： PR 标题命名格式、关联 Issue 规则以及变更日志要求。
团队可以在 Sweep 设置页面的 Rules 选项卡中，通过 Generate SWEEP.md 按钮，一键从现有的规范文件中提炼并生成初始化文件。
5. CI/CD 闭环机制：基于 GitHub Actions 的自愈循环
即便在提示词中声明了严密的规则，大语言模型在面对多文件联动、全局类型推导或括号匹配时仍偶有失误。Sweep 保证代码质量的关键利器在于其与 GitHub Actions 的自动化闭环（gha_enabled: true）。
+------------------+ +--------------------+ +--------------------+
| GitHub 创建 Issue | ------> | Sweep AI 规划并生成 | ------> | 向目标分支提交 PR |
| / 需求工单 | | 代码与方案 | | |
+------------------+ +--------------------+ +--------------------+
|
v
+--------------------+
| GitHub Actions |
| 执行 Lint、类型检查 |
| 与单元测试 |
+--------------------+
|
+----------------------------------+
|
[通过] | [报错失败]
v | v
+-------------------+ | +--------------------+
| 进入人工评审阶段 | | | Sweep 自动读取 CI |
| (Code Review) | | | 报错日志与错误行号 |
+-------------------+ | +--------------------+
| |
| v
| +--------------------+
+--------| 针对性修改并推送修复 |
| 提交 (Commit) |
+--------------------+
闭环工作流程：
- 自动建分支与提交 PR： Sweep 根据 Issue 需求与
sweep.yaml规则编写代码并提交 PR。 - 触发 CI 检查： GitHub Actions 运行仓库中的代码检查工具（如 ESLint、Ruff、Trunk）、类型检查器（
tsc、pyright）和单元测试框架。 - 日志自动捕获： 若检查失败，Sweep 自动拉取失败步骤的标准输出与错误堆栈。
- 针对性修复： Sweep 锁定报错文件名、出错行以及具体错误信息（如缺失导入、类型不兼容、未用变量），利用差异更新算法生成补丁并直接向该 PR 分支追加 Commit。
- 减轻人工负担： 开发者无需在代码审查时重复指出缩进、类型或测试遗漏等基础问题，审查重心回归业务逻辑本身。
6. 团队落地与防护最佳实践
为了在保证研发效率的同时规避潜在风险，建议团队遵循以下规范：
- 严格封锁核心目录： 在
blocked_dirs中务必加入.github/、基础设施配置、数据库迁移目录及证书密钥目录，防止 AI 无意修改造成流水线中断或安全风险。 - 控制单次任务规模： 保持任务轻量聚焦。将改动范围控制在 3 到 5 个文件、300 行代码以内，能够大幅提高生成的准确率与自愈成功率。
- 工单编写使用命令式与明确路径： 在创建 Issue 时提供明确的目标文件、具体行为调整以及参考实现（例如：
"In app/services/billing.py, refactor discount calculation using Decimal instead of float; follow patterns in app/services/tax.py"）。 - 善用 PR 评论互动： 若发现细节偏差，团队成员可在 PR 评论区输入以
sweep:开头的指令，Sweep 会自动读取该意见并在分支上迭代修改，无需工程师手动检出分支。 - 初期启用 Draft 模式： 在初次引入 Sweep 或面对复杂遗留代码库时，可先在
sweep.yaml中设置draft: true，待人工快速评估后再转为正式 PR 触发完整测试。