Issue駆動型エージェント自動実行システム マニュアル¶

📁 docs/dev-environment/artifact/20260429_231805_issue_driven_agent_manual.md

本システムは、GitHub Issue に特定のラベルを付与するだけで、Google Antigravity エージェントが自律的に課題を調査・実装・記録・プッシュまでを行う仕組みです。

1. 概要¶

• トリガー: Issue への claude-ok ラベルの付与
• 実行環境: ローカル PC の tmux セッション（バックグラウンド実行）
• 主な機能:
  • 5分間隔での Issue 自動抽出（常駐監視モード）
  • 作業開始時の macOS デスクトップ通知
  • 作業中の tmux ステータスバーの色変化（黒→赤）
  • 全自動モード（承認スキップ）でのエージェント起動
  • 作業進捗の Issue コメントへの自動記録
  • git commit & git push (Closes #Issue番号 を含む)
  • 作業完了後の Gmail 通知送信

2. 事前準備¶

GitHub リポジトリに以下のラベルが存在することを確認してください。 - claude-ok: エージェントに実行を依頼するトリガー - agent:in-progress: 作業開始時に自動付与 - agent:completed: 正常終了時に自動付与 - agent:failed: 異常終了時に自動付与

3. 環境別セットアップ¶

Mac の場合¶

brew install tmux

Windows の場合 (WSL推奨)¶

Windowsで本システムを動かすには、WSL (Windows Subsystem for Linux) の使用を強く推奨します。 1. tmuxのインストール: WSL（Ubuntu等）のターミナルで以下を実行します。

sudo apt update && sudo apt install tmux

sudo apt install gh
gh auth login

4. 使い方¶

① エージェントに仕事を任せる¶

GitHub Issue を作成し、タイトルと本文に指示を記載して、claude-ok ラベルを付けます。

② オーケストレーターの起動¶

ターミナルで以下の起動スクリプトを実行します。

./scripts/launch_agent_tmux.sh

③ 動作の「気づき」ポイント¶

裏でエージェントが動いているかどうかは、以下の方法で確認できます。 1. デスクトップ通知: 作業開始時に macOS の通知センターからポップアップが出ます。 2. tmux ステータスバー: - 待機中: 黒色背景 - 作業中: 赤色背景（太字） に変化します。 3. Gmail: 作業が正常に完了すると、詳細なサマリーがメールで届きます。

③ 作業状況の確認（アタッチ）¶

エージェントが現在何をしているかを確認するには、tmux セッションに接続します。

tmux attach -t antigravity-worker

④ 画面から抜ける（デタッチ）¶

作業を裏で続けさせたまま画面を閉じるには、以下のキー操作を行います。 - Ctrl + b を押した後に d キー

5. コンテキスト管理のコツ¶

• イシューごとのリセット: 本システムは、1つの Issue が終わるたびにエージェントのプロセスを再起動します。これにより、トークン消費の肥大化を防ぎ、常に高い精度を維持します。
• 手動介入: tmux でアタッチしている間は、必要に応じてエージェントに直接指示を出すことも可能です。

6. ファイル構成¶

• scripts/agent_issue_executor.py: 監視・実行のコアロジック（Python）
• scripts/launch_agent_tmux.sh: tmux セッション起動用スクリプト
• configs/tmux.conf: セッションの設定（マウス操作、履歴など）
• docs/dev-environment/20260429_224351_tmux_vs_docker_comparison.md: 実行環境の検討記録