はじめに
ITエンジニア5年目のたくわんです。よろです。
GitHub Actions という、GitHub 上の操作や Python プログラム、シェルコマンドなどをワークフロー形式でトリガー実行できる機能があります。
今回はこの GitHub Actions に目を付けて、Python プログラムから OpenAI API に接続し、コーディング、レビュー、修正、単体テスト、レポート作成、Issue 起票、コミットまでを自動化する AI エージェントワークフローを作成しました。
ざっくり言うと、以下のようなものです。
- GitHub Actions からワークフローを手動実行
- 入力された要件定義や設計内容を AI エージェントへ渡す
- AI が対象リポジトリの指定 branch にコードを生成
- レビューエージェントが品質チェック
- NG があれば Issue 起票
- 修正エージェントが再修正
- pytest による単体試験を実行
- テスト失敗時は原因を分析して再修正
- 試験結果を Markdown / HTML レポートとして branch に残す
- 最後に commit / push
- 必要なら Pull Request 作成
かなり雑に言うと、GitHub Actions 上に小さな開発チームっぽい AI ワークフローを作ったという感じです。
現時点では主に Python CLI アプリケーション向けオンリーですが(´；ω；`)
ただ、1000〜1500step 程度の CLI アプリであれば、一度の Actions 実行でローカル動作可能な成果物、単体試験、試験レポートまで作成できるレベルにはなってきました。
作ったものの概要
今回作ったものは、GitHub Actions を起点に動く AI 開発ワークフローです。
人間が GitHub Actions の AI Orchestrate というワークフローに要件を入力すると、AI エージェント群が対象リポジトリを clone し、指定 branch に対してコード生成、レビュー、テスト、修正、レポート作成、コミットまでを行います。
長文の要件定義や基本設計は GitHub Actions の入力欄に直接貼るとシェルコマンドと誤解されフローが破壊されたため、現在は GitHub Issue に要件を記載し、Actions 側では Issue 番号を指定する運用もできるようにしています。
これにより、以下のような流れが実現できます。
- GitHub Issue に要件定義・基本設計を書く
- GitHub Actions に Issue 番号と出力先 branch を指定して実行
- AI エージェントが Issue 本文、コメント、添付ログなどを読み込む
- 実装、レビュー、修正、単体試験を実行
- 試験レポートを branch 内に残す
- 人間が branch を確認し、必要なら Pull Request で main に取り込む
完全自動化ではなく、入口と出口は人間が見るという思想にしています。
AI に全部任せるのではなく、AI が作った成果物を branch に残し、人間が Pull Request の内容やレポートを確認して判断する構成です。
AI君はいかんせん信用ならないのでその為のフェールセーフだと思てもらえると良いかと。
使用した技術
| 技術 | 用途 |
|---|---|
| Python | 各エージェント、補助スクリプト、レビュー、試験制御 |
| OpenAI Python SDK | LLM へのプロンプト送信、コード生成、レビュー指示生成 |
| GitHub Actions | ワークフロー制御、Python 実行、shell 実行、成果物 upload |
| GitHub Repository | 入力元、出力先、branch 管理、Issue 管理 |
| Git CLI | clone、checkout、commit、push |
| pytest | 単体試験 |
| pytest-cov | カバレッジ取得 |
| Markdown | AI への system prompt 管理、試験レポート作成 |
| JSON | エージェント間 I/O、計画、レビュー結果、テスト結果 |
| shell script | clone、test、build、commit などを実行 |
実施イメージ
1,開発したいリポジトリのGitHub Issueに設計書を記載
2,本GitHub Actionsのソースを格納しているリポジトリに移動→Actionsに移動
3,AI Orchestrateの「Run_workflow」を選択し必要項目を埋める
4,「Run workflow」を選択し、タバコでも吸いに行く
→あら不思議、自動で成果物が指定branchに！？(マガジンマーク)
5,あとはローカルにチェックアウトして動作確認
6,試験結果レポートもばっちり
(サマリの集計がバグってますが3日かけても直せないので、こういう悲しい結果で、、、おわりぃですねぇ)
機能一覧
1. ワークフロー入力からの自動コード生成
GitHub Actions の workflow_dispatch から以下を指定できます。
- 出力先リポジトリ
- 作業元 branch
- コミット先 branch
- 参照 branch
- 要件プロンプト
- 長文要件を管理する Issue 番号
- プロジェクト種別
- テストレベル
- 出力言語
- 自動コミット有無
- Pull Request 作成有無
入力内容を Python で正規化し、AI エージェントが扱いやすい JSON に変換します。
2. 長文要件の Issue 管理
GitHub Actions の入力欄に長文の要件定義や設計書を直接貼ると、shell による解釈や改行、バッククォートの影響で壊れることがありました。
そのため、現在は以下の運用に対応しています。
- Issue に要件定義・基本設計を書く
- Actions では
task_issue_numberに Issue 番号だけ指定する - AI エージェントは Issue 本文、コメント、添付ログ、添付画像の解析結果を読む
- 人間が追記した Issue コメントも次回実行時に反映する
これにより、長い要件定義でも安定して AI に渡せるようになりました。
3. コーディングエージェント
コーディングエージェントは、対象リポジトリの構成、Issue、参照 branch、要件定義をもとにコードを生成します。
現在は主に Python CLI アプリを対象としており、以下を強制しています。
-
cli.pyをエントリポイントにする(いずれメインエントリポイントは自由に指定したいけど、今は力不足。許し亭許士) - root の
cli.pyからローカル実行できるようにする - Windows / Linux / macOS で動くようにする(バカ大事)
- OS 依存実装が必要な場合はコメントで明記する
- pytest のテストを作る
- テストメソッドには試験区分と確認項目を書く
など
4. レビューエージェント
レビューエージェントは、生成コードを静的に確認し、重大な問題や設計上の問題を検出します。
確認観点の例は以下です。
- Python 構文エラー(当たり前)
- 未定義シンボル(自作パッケージは一応除けるようにした)
- 入力値検証漏れ
- import 不整合
- OS 依存処理の検知
- 文字コード未指定
- ハードコードされた絶対パス
- 日本語 PNG 生成時のフォント不備
- モックなどでI/Oをごまかした危険な逃げ実装😡
レビューで NG になった場合は Issue を起票し、修正指示を生成します。
OpenAI社見てるかー！お前んとこの生成コードはすーぐモックでごまかすよな!?!?!?
全く困ったもんじゃい。
5. レビュー修復ループ
レビューで問題が出た場合、修正指示を作成し、再度コーディングエージェントに渡します。
現時点では暫定的に最大5回程度の修正ループを回す構成にしています。
- 第1レビュー(机上チェックと静的解析)
- 第2レビュー(本格的なコードレビュー)
- NG 内容から修正指示を生成
- Issue 起票
- コーディングエージェントが修正
- 再レビュー
- 通るまで繰り返す
人間でいうところの、レビュー指摘、修正、再レビューに近い流れです。
6. ローカル CLI 起動性の補強
GitHub Actions 上では Linux で動いていても、人間が Windows ローカルで checkout して動かすと壊れることがありました。
これだと人間が開発に関与できないので困ります(´・ω・｀)
そのため、root の cli.py からローカル実行できるかを確認するエージェントを作りました。
これにより、生成成果物を branch checkout 後に人間が継続開発しやすくなりました。
7. テスト実行とテスト修復ループ
pytest を実行し、失敗した場合はログを解析して原因分類します。
-
interface_mismatch
→I/Oの不備など -
dependency_missing
→プロジェクト同士の依存性問題
など
この辺をルールベースで分割して処理することでソース側が悪いのか、テスト側が悪いのかを判断して修正指示を出すようにしています。
8. run単位のテスト・レポート管理
以前は、前回の AI 実行で生成された古いテストが残り、次回実行時にそれが邪魔をすることがありました。
そこで、テストとレポートは run 単位で管理するようにしました。
tests/
run_001/
run_002/
run_003/
reports/
run_001/
run_002/
run_003/
これにより、過去 run のテストが新しい run の品質ゲートを壊しにくくなりました。
9. テストレポート生成
テスト結果は Markdown / HTML で出力します。
出力内容の例は以下です。
- 総試験件数
- 成功件数
- 失敗件数
- エラー件数
- スキップ件数
- 試験区分別件数
- ソースコード別カバレッジ
- テストケース一覧
- 失敗分析
- 実行ログ抜粋
これにより、単に Actions のログを見るだけでなく、branch 内に納品物に近い試験結果を残せるようにしています。
いずれここから試験報告書とかCL作成出来たらいいなって感じです。
10. Issue 連携
AI が検出したレビュー指摘やテスト失敗は GitHub Issue に起票します。
また、人間が起票した Issue も AI エージェントの入力として扱えます。
対応状況は Issue コメントとして追記されます。
- 対応中
- 対応済み候補
- 対応済み
- レビュー状態
- テスト状態
- 変更ファイル
- レポートパス
人間が Issue にコメントを追記した場合も、次回の Actions 実行で AI が参照できるようにしています。
- 実際にAIエージェントが自動作成したissue
複数エージェントでP検(プログラム修正後検定)を行い、根拠のあるクローズ処理が行われていることが何となくわかりますね。 - でも未対応のままクローズされちゃう事も、、、
全体アーキテクチャ
ざっくりした構成は以下です。
オーケストレータ単体のワークフロー
オーケストレータ単体で見ると、役割は「各工程を順番に呼ぶ進行役」です。
登場人物は以下です。
| 登場人物 | 役割 |
|---|---|
| GitHub Actions | 全体の実行基盤 |
| オーケストレータ | 工程順序の制御 |
| parse script | 入力を JSON 化 |
| repo context collector | リポジトリ、Issue、コメント、添付、参照branchを収集 |
| run context allocator |
run_001 などを採番 |
| shell scripts | clone、test、build、commit などを実行 |
| report generator | 試験結果を Markdown / HTML 化 |
| issue sync script | Issue の起票・更新・クローズ |
オーケストレータ + AIエージェントのワークフロー
AI エージェント込みで見ると、開発チームに近い構成になります。
登場人物は以下です。
| エージェント | 役割 |
|---|---|
| Orchestrator | 全体の進行役 |
| Code Writer Agent | 要件に基づきコードとテストを生成 |
| Reviewer Agent | 静的観点、設計観点、OS非依存観点でレビュー |
| Fix Instruction Writer | レビュー指摘から修正指示を生成 |
| CLI Bootstrap Agent | root cli.py からローカル実行できるよう補強 |
| Test Agent | pytest 実行 |
| Test Triage Agent | テスト失敗原因を分類 |
| Report Agent | test_report.md / html を生成 |
| Issue Sync Agent | Issue 起票・コメント更新・クローズ |
| Commit Agent | commit / push |
苦労した点
1. コーディング性能の向上
最初は、単に Markdown の system prompt に「この要件をコーディングして」と書いて OpenAI に投げていました。
しかし、それだけだと普通に危険です。
例えば、以下のようなことが起こります。
- 必要なフォントがないのに黙って先に進む
- 画像出力機能が壊れているのに PNG ヘッダとファイルサイズだけでテストを通す
- 実装できていない機能をそれっぽい関数名だけでごまかす
- テストコードが既存リポジトリの古いコード仕様に引っ張られる
→ソースの interface が変わったのにテストは古新聞
特に日本語入りのレシート PNG 出力では、なかなか強烈でした。
人間なら見た瞬間に「あーもうめちゃくちゃだよ」と分かります。しかし、AI とテストは PNG ファイルが存在して、サイズが一定以上あれば通してしまいます。
そこで、以下を追加しました。
- 日本語 PNG は Pythonの推奨フォント必須
- bitmap手打ちによる日本語描画は禁止(ある意味凄い)
- 自作 PNG エンコーダ禁止
- 文字を四角形で描く逃げ実装禁止
- GitHub Actions に Noto CJK フォントを install
- 画像の単色、透明、サイズ、bbox などを検査
ここまでやって、ようやくいけるか？といった感じです。
もう10kStep以上Python書いてやめたくなりますよ～部活ぅ～
2. レビュー観点が厳しすぎる
レビューエージェントは便利ですが、最初はかなり厳しすぎました。
人間であれば、静的解析や机上チェックリストで NG が出ても、文脈上問題なければ無視することがあります。しかし、AI レビューエージェントは容赦なく NG を返します。
例えば、画像ファイルの整合性チェックを作ったとき、対象外の拡張子まで片っ端から解析しようとして NG を出すようなことがありました。
人間なら PNG / JPEG / BMP 以外は最初から無視します。しかし、AI も Python も機械なので、この辺の「常識的に除外する」という判断を明示的に実装する必要があります。
実際には、以下のような調整を何度も行いました。
- blocking にする finding と warning にする finding を分ける
- tests/ 配下を画像レンダリング検査の対象から外す
- OS 依存の絶対パスでも、フォント候補リスト内なら許容する
-
input()を使っているだけで即NGにしない - CLI アプリとして自然な警告は許容する
- 重大度 high / medium / low を整理する
この調整がしんどかったです。レビューエージェントは優秀ですが、優秀すぎるレビュアーは普通に開発を止めます。あとメンバに嫌われます。
(そのうちエージェント同士に高感度とか実装してギャルゲーチックにしたらみんな紳士的に開発する可能性が微粒子レベルで存在している？)
3. ローカル環境やOSという発想が最初は弱い
普通の現代的なシステム開発では、Windows / Linux / macOS の差異をある程度考えます。
しかし、GitHub Actions は基本的に Linux runner 上で動きます。そのため、最初は Linux で動けばテストもレビューも OK という状態になりがちでした。
その結果、生成された branch を Windows ローカルで checkout して動かそうとすると、阿鼻叫喚でした。
例えば以下です。
-
python cli.pyで package import に失敗する -
src/が import path に入っていない - 文字コードが Windows で崩れる
-
/tmpや/home/runner前提のパスが混ざる - shell コマンド前提の処理が入る
- 日本語フォントが Linux runner 前提になる
この問題に対して、以下を入れました。
- コーディングエージェントの prompt に OS 非依存ルールを明記
-
pathlib.Pathを強制 -
encoding="utf-8"を強制 -
os.system/shell=Trueを検出 - OS 固有 import を検出
- root
cli.pyのローカル起動性を検査 - 依存ライブラリ不足なら動的に install
- package layout を自動補強
これ意外に大事ですが、基本GitHubの実行環境ってLinuxな気がするので気を付けよう。
4. 長文プロンプトが shell に壊される
1000〜1500step 規模の要件定義を GitHub Actions の input に直接貼ると、途中で壊れることがありました。
最初は「長すぎて切られているのかな」と思ったのですが、実際にはプロンプト中の以下のような文字列が Bash に解釈されていました。
python cli.py
`code`
$HOME
--task "${{ github.event.inputs.task }}" のように shell 引数として直接渡していたのが悪かったわけです。
現在は、以下のように修正しています。
-
taskは環境変数経由で Python に渡す - 長文要件は GitHub Issue に書く
- Actions では
task_issue_numberだけ指定する - Issue 本文、コメント、添付情報を repo context に入れる
これで、長文要件を安定してOpenAIにぶち込んでやるぜ！
ほら見ろよ見ろよ
OpenAiくん「やめてくれよ、、、」
現時点の性能
まだ検証中ですが、現時点での肌感は以下です。
| 項目 | 現状 |
|---|---|
| 対象 | Python CLI アプリ |
| 規模 | 1000〜1500step程度 |
| 成功率 | CLIオンリーならかなり安定 |
| 実行時間 | 5〜8分程度 |
| API利用料 | 1実行あたり約0.6〜1.0ドル程度 |
| 出力物 | ソース、テスト、レポート、Issue、commit |
| ローカル実行 | root cli.py から起動できるところまで補強 |
| テスト | pytest + coverage |
| レポート | Markdown / HTML |
| 制限 | WebアプリやGUIは未検証または不安定 |
実際に、1000〜1500step程度のターン制 CLI 2D ダンジョンゲームを作らせたところ、ローカルでも動作し、要件もおおむね満たしました。
コマンドラインインターフェースオンリーのモジュール群であれば、かなり安定して作成できるようになってきた印象です。
ただし、これはまだ Python CLI に限った話です。Flask、Django、GUI、Unity などは別物です。
生成された成果物の例
現在の成果物 branch には、だいたい以下のようなものが出ます。
src/
sample_package/
__init__.py
cli.py
models.py
engine.py
renderer.py
tests/
run_001/
conftest.py
test_engine.py
test_cli.py
reports/
run_001/
test_report.md
test_report.html
execution_summary.md
run_context.json
cli.py
pyproject.toml
README.md
reports/run_XXX/test_report.md には、以下のような情報が入ります。
総試験件数
成功件数
失敗件数
エラー件数
スキップ件数
試験区分別件数
ソースコード別カバレッジ
テストケース一覧
失敗分析
実行ログ抜粋
これにより、人間は GitHub Actions のログを全部読まなくても、branch 内のレポートである程度判断できます。
運用イメージ
自分の中では、以下のような運用を想定しています。
ポイントは、自動でmianマージにはしないことです。
AI が作った成果物、Issue、レポートを見て、人間が最終判断します。入口と出口は人間が持つ。ここはかなり大事だと思っています。(大事なことなどで何度も言います)
今後実装したい機能
1. Django / Flask 対応
現在は Python CLI アプリが中心です。
次は Django や Flask といった代表的な Python Web フレームワークでも、同じ水準で以下をできるようにしたいです。
- ルーティング実装
- template 実装
- DB モデル
- migration
- pytest
- セキュリティレビュー
- ローカル起動確認
- HTTP レベルの簡易テスト
CLI より難易度は上がりますが、業務アプリ感は一気に強くなります。
Htmlもcssもjsも動的Webページも畑違いな筆者に構築できるのだろうか。。。
2. C# エージェント
別エージェントとして、C# 向けの開発エージェントも作りたいです。
対象は以下です。
- C# CLI
- Windows Forms
- .NET アプリ
- Unity C# スクリプト
特に Unity は、ビルドや実行確認が GitHub Actions だけでは難しい部分もあるのでフローの柔軟性強化のために一度設計から考え直したいところ。
3. より高度なレビューエージェント
今のレビューはかなりルールベース寄りです。
単に「コードが動く」ではなく、「保守できる」「説明できる」「品質保証できる」方向へ寄せたいです。
モンキーテストとか、フールプルーフな部分も品質に入れられたらいいんですがLLMの学習がまだ甘い気がする(´ε｀；)
4. Issue と Pull Request の運用強化
現在も Issue 起票やコメント更新はできますが、まだ改善余地があります。
今は何でもAcutions流したユーザアカウントでの起票になっちゃうんですよね。なのでコーディング・レビュー・試験短答各エージェントのbot名義で起票できるようにしたい所さん!?何してるんですか!?やめてくださいよほんと!まずいですよ!!
まとめ
GitHub Actions と OpenAI Python SDK を使って、AI エージェントによるコーディング、レビュー、単体テスト、修正、レポート作成、Issue 管理、commit までを自動化するワークフローを作成しました。
最初はかなり不安定でした。
- コードは出るがローカルで動かない
- テストは通るが成果物が壊れている
- Linux でしか動かない
- レビューが厳しすぎて止まる
- テスト失敗時に同じ失敗を繰り返す
- 長文プロンプトが shell に壊される
- Issue を読んでいるようで読めていない
こうした問題を一つずつ潰していった結果、現時点では Python CLI アプリであれば、1000〜1500step程度の要件を一度の Actions 実行でかなり見せられる成果物にできるところまで来ました。
まだ万能ではありませんが、というか高校生でもできるようなレベルの内容ですがGitHub Actions を「AI開発チームの実行基盤」として使う足がかりにはなれたのかなといった印象。
特に、以下のような構成はかなり相性が良いです。
- 要件は Issue に書く
- Actions で AI ワークフローを実行する
- AI は branch に成果物を出す
- テスト結果とレポートも branch に残す
- Issue で指摘や修正過程を可視化する
- 最後は人間が Pull Request を見る
AI に全部任せるのではなく、人間が設計と出口判断を持ち、AI が製造・レビュー・単体試験を高速に回す。
そしてAIのやり取りをアウトプットとしてissueや成果物ファイルで確認できる。
この形なら、個人開発だけでなく、組織開発にもようやく応用の糸口が見えてきた、そんな気がします。