GitHubのIssueを自動バグ修正PRに変換するSweepの設定と運用ガイド

日々のソフトウェア開発において、軽微な不具合や定型的なタスクの蓄積は、シニアエンジニアの開発リソースを著しく圧迫します。Nullチェックの追加、非推奨ライブラリの呼び出し変更、例外処理の是正、不足しているユニットテストの補完といったバグは、リスクが低いにもかかわらず、バックログに何週間も放置されがちです。

Sweepは、この開発現場のボトルネックを解消するために設計された自律型AIジュニアエンジニア（AI Junior Developer）です。GitHub Appとしてリポジトリに連携することで、Issueの起票を検知し、ベクトル検索とAST（抽象構文木）解析によってコードベース全体を把握した上で、複数ファイルにまたがる修正コードを記述し、自動でPull Request（PR）を作成します。さらに、GitHub ActionsによるCIテストの失敗ログを読み取って自動修正を行い、エンジニアからのインラインレビューにもリアルタイムに応答します。

本記事では、エンジニアリングチームがSweepを導入し、Issueから高精度な修正PRを自動生成するための設定手順、sweep.yamlの構成、効果的なプロンプトの書き方、そして運用の安全基準を解説します。

1. Sweepによる「IssueからPR作成」の仕組み

Sweepを運用するにあたり、まずは工単処理のライフサイクルを理解することが重要です。

1. トリガーの発火: 開発者がSweep:を接頭辞にしたGitHub Issue（例: Sweep: Fix KeyError when user metadata payload is missing）を作成するか、既存のIssueにsweepラベルを付与、またはコメントで@sweepaiをメンションします。
2. コードベースの文脈検索: SweepのWebhookハンドラー（on_ticket）が起動し、コード埋め込み（Vector Embeddings）とASTチャンキングを用いて、Issueに関連するファイル、クラス、既存テストを特定します。
3. 修正計画の策定: SweepはIssue内のコメントとして、修正対象のファイル一覧と実装方針を明記したタスク計画を提示します。
4. コード生成とブランチ作成: Sweepは専用ブランチ（sweep/fix-...など）を自動生成し、リポジトリのルールに準拠した修正コードをコミットします。
5. Pull Requestの発行: 解決対象のIssue番号（Fixes #<id>）や変更概要、チェックリストを含むPRを作成します。
6. フィードバックの循環:
   • CI自己修復ループ: GitHub Actionsとの連携が有効（gha_enabled: true）な場合、テスト失敗時にエラーログを解析し、修正コミットを追加します。
   • 人間によるレビュー対応: レビュアーがPRのDiffにコメントを残すと、Sweepがそれを読み取り、コードを再修正します。

2. GitHubへのインストールとアクセス権限

Sweepを組織のリポジトリに接続するには、以下の設定を行います。

1. GitHub Appのインストール: SweepのGitHub App設定画面から、対象のリポジトリまたは組織全体を選択して連携します。
2. 必要な権限の付与:
   • Repository Contents（読み取り/書き込み）: コードの取得および修正ブランチのプッシュに必須。
   • Issues（読み取り/書き込み）: Issue内容の取得、ラベル更新、進行状況コメントの投稿に必須。
   • Pull Requests（読み取り/書き込み）: PRの作成、Diffの参照、レビューコメントへの返信に必須。
   • Actions / Checks（読み取り）: テスト失敗時にCIログを取得するために必要。
3. Draftモードの検討: 導入初期は、通知の氾濫を防ぐためにPRをDraft状態（draft: true）で作成させ、人間が初動を確認した後にReady for Reviewへ移行する運用が推奨されます。

3. sweep.yamlによるリポジトリ固有ルールの定義

Sweepの挙動は、リポジトリのルートに配置するsweep.yaml（または.sweep/config.yaml）によって細かく制御できます。適切な設定を行うことで、ハルシネーション（幻覚）による存在しないパッケージのインポートを防ぎ、チームのコーディング規約を遵守させることができます。

本番環境向け sweep.yaml の構成例

# sweep.yaml - Sweepの自動Issue処理設定ファイル

# Sweepがブランチを切り、PRを作成するターゲットブランチ
branch: 'main'

# PRをDraft状態で作成するかどうか（初期導入時はtrue、運用安定後はfalseを推奨）
draft: false

# GitHub Actionsのテスト失敗ログを読み取り、自律修正を行うか
gha_enabled: true

# プロジェクトのアーキテクチャ概要（AIの全体理解をサポート）
description: >
  Python 3.10とFastAPIで構築されたREST APIバックエンドです。
  DB操作にはSQLAlchemy 2.0を使用し、PostgreSQLをバックエンドとしています。
  ビジネスロジックはservices/、データモデルはmodels/、エンドポイントはapi/v1/に配置されています。
  モジュールのインポートはすべて絶対パス（例: `from services.auth import verify_token`）を使用してください。

# Sweepが読み取りや変更を行ってはならない除外ディレクトリ（保護領域）
blocked_dirs:
  - "deploy/"
  - "terraform/"
  - ".github/workflows/"
  - "migrations/"
  - "*.env*"
  - "security/"

# PR作成前にSweepの独立サンドボックスで実行される検証コマンド
sandbox:
  install:
    - "poetry install --no-root"
  check:
    - "poetry run ruff check {file_path}"
    - "poetry run pytest tests/unit"

# AIエージェントに遵守させるコーディング規約
rules:
  - "すべてのバグ修正には、tests/配下にpytestのユニットテストを追加または更新すること。"
  - "ワイルドカードインポート（`from module import *`）は禁止。"
  - "APIのリクエストおよびレスポンス検証にはPydantic v2スキーマを使用すること。"
  - "ログ出力にはloguruを使用し、例外ブロック内ではlogger.exception()でスタックトレースを残すこと。"
  - "明示的な指示がない限り、DBスキーマの変更やalembicマイグレーションを作成しないこと。"
  - "すべての関数シグネチャに完全な型アノテーションを記述すること。"

主要ディレクティブの解説

• branch: ベースブランチの指定。developブランチ運用を行っているチームは適宜変更します。
• blocked_dirs: 安全性の担保に不可欠な設定。インフラ定義、CI設定、シークレット情報、DBマイグレーションなど、AIに変更させてはならないパスを完全にブロックします。
• gha_enabled: trueに設定することで、CIが落ちた際にSweepがログを解析して自動修正コミットを追加します。
• rules: チームのスタイル規約を自然言語で指定します。プロンプトに注入されるため、チームのコーディング標準から外れた実装を防げます。
• sandbox: サンドボックス環境でのインストールコマンド（install）とリント・テストコマンド（check）を定義し、ローカル検証をパスしたコードのみをPRにします。

4. 高精度なPRを導くIssueの書き方

Sweepの出力精度は、GitHub Issueに記載された情報の具体性に大きく依存します。人間のエンジニアであればSlackで不明点を確認できますが、AIは提供されたテキストとリポジトリ情報のみから判断します。

推奨されるIssueフォーマット

タイトル: Sweep: Fix 400 Bad Request on empty user metadata payload in /api/v1/profile

### 不具合の概要
`PUT /api/v1/profile`でユーザープロファイルを更新する際、リクエスト本文の`metadata`に空の辞書`{}`を渡すと、初期値が補完されずにValidationErrorが発生する。

### 再現手順
1. `/api/v1/profile`に対してBody `{"metadata": {}}` でPUTリクエストを送信する。
2. APIがHTTP 400（詳細: `Value error, metadata must contain required fields`）を返すことを確認。

### 期待される挙動
空の`metadata`が渡された場合、デフォルト値（`{"theme": "light", "notifications": true}`）で初期化され、正常に保存されること。

### 関連ファイルと関数
- `api/v1/profile.py`: `update_profile` エンドポイントハンドラー。
- `schemas/profile.py`: `UserProfileUpdate` Pydanticモデル。
- `services/profile_service.py`: `save_profile_metadata` 処理関数。

### 受け入れ基準
- `schemas/profile.py`のバリデーションを修正し、空辞書を許容してフォールバック値を適用すること。
- `tests/unit/test_profile_api.py`に空ペイロードのテストケースを追加すること。
- `tests/unit/`配下の全テストが通過すること。

Issueタイトルの修飾プレフィックス

Sweepのパーサー（strip_sweep）は、タイトルプレフィックスに応じて実行モードを切り替えます。

• Sweep: <タイトル>: 通常の自動処理モード。
• Sweep(sandbox): <タイトル>: サンドボックス検証を強制。
• Sweep(fast): <タイトル>: 高速軽量モデルによる迅速なコード修正。
• Sweep(slow): <タイトル>: 依存関係を深く探索する慎重モード。
• Sweep(lint): <タイトル>: 厳格なフォーマットおよびリント検証を実施。
• Sweep(subissues): <タイトル>: 複雑なタスクを自動的にサブIssueへ分割。

5. レビューと反復改善のプロセス

PRが作成された後は、GitHubの通常フローの中でエンジニアとAIが協調します。

[GitHub Issue] ──> Sweep起動 ──> PR作成 ──> CI (GitHub Actions)
                                                  │
                      ┌───────────────────────────┴───┐
                      ▼                               ▼
                CI失敗 (gha_enabled)              CI成功
                      │                               │
                      ▼                               ▼
             Sweepが自動コミット               エンジニアのReview
                      │                               │
                      └─────────► PR更新 ◄────────────┘
                                     │
                           (Diffにコメント:
                        "@sweepai 共通関数の
                         日付フォーマッタを使って")

インラインレビューコメント

エンジニアが手元でブランチをチェックアウトする必要はありません。PRの該当行に以下のようにコメントするだけで対応できます。

@sweepai ここは新しく日付処理を書くのではなく、既存の DateUtils.formatIso() を再利用してください。

Sweepはコメントを検知し、前後のコンテキストを考慮した上でPRに追加コミットをプッシュします。

Issueの再生成

Issueの初期指示に誤りがあったり、根本的な方針を変更したい場合は、PRを手動で閉じる必要はありません。元のGitHub Issueのタイトルや説明文を編集するだけで、Sweepが自動的に既存ブランチを破棄し、新しいPRを再作成します。

6. エンジニアリングチームにおける安全基準と限界

AIコーディングエージェントを本番パイプラインへ統合する際は、以下の安全基準を遵守してください。

1. 自動マージの禁止: Sweepが作成したPRにAuto-mergeを設定してはなりません。ブランチ保護ルールを設け、最低1名のシニアエンジニアによる承認とCI通過をマージの必須条件にします。
2. 危険領域の完全除外: blocked_dirsを活用し、インフラコード（Terraform、Kubernetes）、CI/CD定義、DBマイグレーション、機密環境変数ファイルへの書き込みを物理的に遮断します。
3. 適切なスコープ管理: Sweepの真価は、境界が明確なバグ修正、単体テストの追加、小規模なリファクタリングで発揮されます。要件が曖昧な大規模機能開発や分散アーキテクチャの改修を丸投げすることは避けてください。
4. テストスイートの整備: Sweepの自律修復機能は、テストのエラーメッセージを命綱として動作します。テストカバレッジが高いリポジトリほど、AIの修正精度と安全性は飛躍的に高まります。

参考文献

• GitHub - sweepai/sweep: Sweep: AI coding assistant for JetBrains
• GitHub - sweepai/sweep: sweep.yaml configuration file
• GitHub - sweepai/sweep: sweepai/config/client.py
• GitHub - sweepai/sweep: sweepai/handlers/on_ticket.py
• GitHub - sweepai/sweep: sweepai/utils/str_utils.py
• sweepai · PyPI
• Launch YC: Sweep: JetBrains AI Coding Assistant | Y Combinator