AI Agentを前提にしたIssue/PR運用を、個人開発で設計した話

個人開発で DevOps ポートフォリオ「terraform-hannibal」を作っています。

terraform-hannibal:

https://github.com/kmryst/terraform-hannibal

このプロジェクトでは、AWS や Terraform のリソースを作るだけではなく、Issue / Branch / Pull Request / GitHub Actions / IAM / CI/CD まで含めて、実務に近い変更管理の流れを設計することを重視しています。

特に意識しているのは、変更の目的、影響範囲、検証結果、rollback 方針をあとから追える状態にすることです。

個人開発ではありますが、単に「動くものを作る」だけではなく、チーム開発や運用を想定して、変更を安全に積み重ねられる仕組みを作っています。

AI Agentを使うほど、運用ルールが重要になる

最近は Claude Code などの AI Agent を開発に取り入れています。

実際に使ってみると、AI Agent はとても便利です。

一方で、単に「AIに作業を任せる」だけでは、Issue や Pull Request の運用が崩れやすいこともわかりました。

たとえば、次のようなズレが起きます。

・Issue テンプレートを使わない

・必要なラベルを付け忘れる

・PR本文にIssueリンクがない

・rollback観点が抜ける

・作業経路によって、守られるルールが変わってしまう

こうした小さなズレが積み重なると、Issue駆動開発やPRレビューの前提が崩れていきます。

そこで、AI Agent を前提にしても崩れにくい Issue / PR 運用を設計しました。

ルールを書くだけでは足りなかった

最初は、README や CONTRIBUTING にルールを書いておけば十分だと思っていました。

しかし、実際にはそれだけでは不十分でした。

人間は忘れます。

CLI 経由では、GitHub の Web UI で用意したテンプレートを通らないことがあります。

AI Agent は「だいたい合っているが、少し足りない」出力を返すことがあります。

つまり、ルールを文章として置くだけでは、運用品質は安定しません。

そこで、単に「こうしてください」と書くのではなく、Issue や Pull Request の作成経路ごとに、ルールから外れにくくする仕組みを作る必要があると考えました。

入口で補助し、最後に自動チェックで検出する

terraform-hannibal では、Issue や Pull Request の作成経路を大きく3つに分けて考えました。

・GitHub の Web UI から作る場合

・CLI から作る場合

・AI Agent が作業の一部として作る場合

どれか1つの経路だけを前提にすると、別の経路から作られたIssueやPRで運用が崩れます。

そのため、以下のように役割を分けました。

・Web UIでは Issue Forms を使い、必要項目を入力しやすくする

・CLI / AI Agent 経由では helper scripts を用意し、本文やラベルを揃えやすくする

・最終的には GitHub Actions で不足を検出し、Issue / PR の品質をチェックする

入口で補助し、最後にCIで止める構成です。

これにより、人間・CLI・AI Agent のどの経路から作業しても、Issue / PR の最低限の品質を保ちやすくなります。

重くしすぎないことも重視した

最初から approval や CODEOWNERS を強くする選択肢もありました。

ただ、個人開発や少人数開発で最初から承認フローを重くしすぎると、開発の速度が落ちます。

特に個人開発では、ルールを厳しくしすぎると、運用そのものを続ける負荷が高くなります。

今回解きたかった問題は、「承認フローを厳格にすること」ではありません。

まず必要だったのは、Issue や PR の入力品質を揃え、作業の入口で迷子にならないようにすることでした。

そのため、いきなり重い承認フローを作るのではなく、

・入力しやすくする

・作成経路ごとの揺れを減らす

・最後に自動チェックで検出する

という順番で設計しました。

現在の terraform-hannibal で実装していること

このIssue/PR運用は、単なる作業ルールではなく、terraform-hannibal 全体のDevOps基盤の土台として位置づけています。

現在の terraform-hannibal では、Issue → Branch → PR → CI → Merge の流れを前提に、変更の目的、影響範囲、rollback、レビュー観点を追跡できるようにしています。

Pull Request では、Issue link、必須ラベル、rollback欄などを確認する PR Policy Check を整備しています。

また、Terraform fmt / validate、TFLint、Trivy Config、Gitleaks などのチェックを組み込み、IaC・セキュリティ・シークレット混入の観点からも変更を確認できるようにしています。

最近の改善では、PR品質ゲートの整備、READMEのポートフォリオ訴求改善、CloudTrail / Athena 周辺の監査基盤整備、IAM Policy分割、Permission Boundary、public subnet の設定見直し、Trivy Config の検出結果整理などにも取り組みました。

つまり、単に「AI AgentがIssueやPRを作れるようにした」のではありません。

AI Agent・CLI・GitHub UI のどの経路から変更が入っても、人間がレビューできる形で履歴と判断材料を残すことを重視しています。

DevOpsで重要なのは、リソース作成だけではない

TerraformでAWSリソースを作れることは重要です。

GitHub ActionsでCI/CDを組めることも重要です。

しかし、それだけでは安全に開発を続けられる環境にはなりません。

誰が、どのIssueに対して、どの変更を行ったのか。

PRで何を確認すべきなのか。

AI Agentが作業に入っても、運用ルールが壊れないか。

間違った経路から作成されたIssueやPRを、どう検出するか。

コストやセキュリティのリスクを、どこまで自動化し、どこから人間が判断するか。

こうした変更管理や運用設計も、DevOpsでは重要な領域だと考えています。

terraform-hannibal では、単なる個人開発の成果物ではなく、チーム開発を想定した運用フローまで含めて設計しています。

現在残している課題

一方で、まだ改善中の課題もあります。

たとえば、PR品質ゲートをrequired化するかどうか、DynamoDB state locking を S3 lockfile 安定後に削除するか、public ALB の直アクセス制限をどう扱うか、CloudFront origin protocol や HTTP listener の扱いをどう整理するか、といったIssueを残しています。

これらは、単なる未実装タスクではなく、コスト、セキュリティ、運用負荷、リスクを見ながら判断するための検討Issueです。

すぐに全部を厳格化するのではなく、リスクと運用負荷を見ながら、どこまで自動化するか、どこで人間の判断を残すかを整理しています。

技術的な詳細

今回の詳しい設計内容は、Zennにまとめています。

https://zenn.dev/kmryst/articles/ai-agent-github-flow-guardrails

Zennの記事では、Issue Forms だけでは足りなかった理由、helper scripts を入れた理由、GitHub Actions でどこまで検出するか、approval / CODEOWNERS を最初から重くしなかった理由などを整理しています。

今後の方向性

今後は、すでに整備してきた Issue / PR 運用、PR品質ゲート、IAM設計、GitHub OIDC、Terraform plan、監査ログ基盤を土台にして、さらに実務運用に近い形へ育てていきたいと考えています。

インフラを作るだけでなく、変更を安全に積み重ねられる仕組みを作ること。

開発者が迷わず作業でき、レビューしやすく、問題を早く検出できる状態を作ること。

AI Agentが関与しても、判断と責任の所在が曖昧にならない運用を設計すること。

そうした DevOps / SRE / Platform Engineering 領域に継続して取り組んでいきたいです。