ソフトウェア開発チームが日常的なバグ修正、機能追加、リファクタリング作業を自動化するためにSweep AIを導入する際、直面する大きな課題の一つが「AIが作成するPull Request（PR）を、チーム既存のコーディング標準やアーキテクチャ規約に厳格に適合させること」です。制約を与えずに放置すると、AIはスタイルの不一致を起こしたり、単体テストを省略したり、非推奨の内部ユーティリティを使用したり、最悪の場合は重要なCI/CDワークフローやセキュリティ設定を意図せず変更してしまうリスクがあります。
この逸脱を防ぐため、開発チームはリポジトリのルートに配置する設定ファイル sweep.yaml を中核に据え、リポジトリ規約ファイル（SWEEP.md など）、ディレクトリ保護機能、そしてGitHub Actionsによるクローズドループ連携を組み合わせた統制体制を構築します。
1. sweep.yaml の基本構造と制御パラメータ
sweep.yaml はプロジェクトのルートディレクトリに配置され、Sweep AIエンジンの基本動作を司る宣言的設定マニフェストです。定義されたパラメータは、AIがコードベースを理解し、変更を計画し、PRを発行する挙動を直接制御します。
主要な設定項目は以下の通りです：
| パラメータ | 型 | デフォルト値 | 役割と動作 |
|---|---|---|---|
rules | list[str] | [] | Sweepのコード生成プロンプトに直接注入されるコーディング規約・制約の指示リスト。 |
description | str | "" | リポジトリの全体アーキテクチャ、技術スタック、主要エンドポイント、規約の概要。 |
blocked_dirs | list[str] | [] | Sweepによる変更を厳格に禁止する保護ディレクトリまたはファイルパスのリスト。 |
gha_enabled | bool | true | GitHub Actionsの実行ログを読み取り、CIエラー時に自動修正コミットを行うかどうかの設定。 |
draft | bool | false | PRをドラフト（Draft）モードで作成するかどうか。CIの過剰な実行を防ぐ際に有効。 |
branch | str | "main" | Sweepが作業ブランチを切り、PRのターゲットとするベースブランチ。 |
sandbox | dict | {} | コミット前のサンドボックス環境で実行する環境構築や検証コマンド（静的解析・整形など）。 |
2. sweep.yaml で実効性のあるルール（rules）を策定する
rules 配列は、チーム内のコーディング規約をLLMに対する強制力のあるプロンプト制約へ変換する場所です。「綺麗なコードを書く」といった曖昧な指示ではなく、具体的・命令的で、自動テストや静的解析で検証可能な内容を記載する必要があります。
推奨される主要ルール設計
-
テストとカバレッジの義務化
- 新規ビジネスロジックやAPIエンドポイントには、必ず同一ディレクトリまたはテストディレクトリ内に単体テストを配置するよう指定します。
- 例：
"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."
-
ロギング標準とデバッグコードの除去
- 標準出力の
print文の混入を防ぎ、プロジェクトで定めたロギングフレームワークを強制します。 - 例：
"Use loguru for application logging. In except blocks, call logger.exception with structured f-strings. Never leave print() statements in production code."
- 標準出力の
-
モジュール性とリファクタリング基準
- 関数の行数肥大化を防ぎ、作業中に発生した不要なコメントや残存TODOを確実に処理させます。
- 例：
"Keep functions modular; refactor procedures longer than 50 lines. Remove redundant comments that merely restate the code. Handle all leftover TODOs."
3. 本番環境向け sweep.yaml 設定設計例
以下は、FastAPIとPostgreSQLを採用したモダンなバックエンドプロジェクトを想定した、実践的な 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として作成するか
draft: false
# GitHub Actionsと連携してCI失敗時に自動自己修復を実行
gha_enabled: true
# 重要なCI定義、DBマイグレーション、認証設定を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自動生成だけでなく、JetBrainsプラグインなどのIDE拡張機能においても、開発者とAIアシスタントの前提知識を統一する役割を果たします。
通常、SWEEP.md には以下の内容を記述します：
- ビルド・検証コマンド： テスト実行、リンター、フォーマッタの具体的な実行コマンド（例：
npm run lint、pytest tests/unit/ -v）。 - コードスタイル詳細： ファイルの命名規則（kebab-caseの徹底など）、ディレクトリ構成、推奨ライブラリ。
- アーキテクチャとデータフロー： モジュール間の依存方向、状態管理パターン、APIインターフェース定義。
- PRレビューチェックリスト： PRタイトルの命名規約、関連Issueの指定方法、変更履歴（CHANGELOG）の更新手順。
既存の規約ファイルが存在する場合、Sweep設定画面の Rules タブにある Generate SWEEP.md 機能を利用して自動生成することも可能です。
5. CI/CDのクローズドループ：GitHub Actionsとの自動自己修復
プロンプトレベルでどれほど詳細なルールを定めても、LLMは複雑な依存関係やグローバルな型チェック、構文の括弧の整合性においてミスを起こすことがあります。Sweepが既存標準への準拠を実現する最大の強みは、GitHub Actionsとのクローズドループ連携（gha_enabled: true）にあります。
+-------------------+ +---------------------+ +---------------------+
| GitHub Issue / | ------> | Sweep AIが設計と | ------> | 対象ブランチへ |
| タスクの作成 | | コード修正を生成 | | PRを作成 |
+-------------------+ +---------------------+ +---------------------+
|
v
+---------------------+
| GitHub Actions実行 |
| (リンター、型チェック、|
| 単体テスト) |
+---------------------+
|
+------------------------------------+
|
[成功] | [失敗・エラー]
v | v
+--------------------+ | +---------------------+
| 人間による | | | SweepがCIログと |
| コードレビューへ | | | エラーメッセージ取得 |
+--------------------+ | +---------------------+
| |
| v
| +---------------------+
+----------| 差分修正パッチを生成 |
| 追記コミットをプッシュ|
+---------------------+
クローズドループの実行ステップ：
- PRの自動作成： SweepがIssueと
sweep.yamlのルールに沿ってコードを書き、PRを発行します。 - CIによる自動検証： GitHub Actionsが起動し、ESLint、Ruff、Trunkなどのリンター、TypeScriptやPyrightなどの型チェッカー、単体テストを実行します。
- エラーログの取得： CIが失敗すると、Sweepはログとエラー出力（標準出力／標準エラー出力）を自動取得します。
- 自己修復パッチの適用： 未定義変数、インポート漏れ、フォーマット違反、失敗したテストを特定し、AI修正エンジンが差分コミットを作成して同一PRブランチへプッシュします。
- 人間エンジニアの負担軽減： 人間レビュアーは、すべての静的チェックとテストが通過した状態でレビューを開始できるため、本質的なロジック検証に集中できます。
6. 実運用におけるプラクティスと防護策
安全かつ効率的に運用を進めるために、チームは以下の原則を遵守することが推奨されます：
- 重要ディレクトリを必ずブロックする：
.github/、デプロイ構成、データベースマイグレーション、認証鍵が格納されるディレクトリはblocked_dirsに指定し、AIの誤編集を完全に遮断します。 - Issueのスコープを限定する： 1つのIssueでの変更規模は、変更ファイル数3〜5個、修正行数300行以内を目安に設計します。タスクが小さく明確であるほど、AIの成功率は劇的に向上します。
- Issueに明確な対象と参照を示す： 指示を出す際は、対象ファイル名、変更内容、参照すべき既存実装を明記します（例：
"In app/services/billing.py, refactor discount calculation using Decimal instead of float; follow patterns in app/services/tax.py"）。 - PRコメントで直接対話修正する： レビュー時に微修正が必要な場合、PRのコメント欄に
sweep:で始まる指示を残すことで、手動でブランチをチェックアウトすることなくAIに修正を継続させることができます。 - 導入時はDraftモードを活用する： 既存の大規模リポジトリへ導入する際は、まず
draft: trueを設定し、人間が差分を確認してから通常のCI実行やチーム通知へ進める運用が安全です。