← ブログ一覧
IT

エージェント型AIを活用したソフトウェア開発の設計と運用

Claude CodeやCodexなどのエージェント型AIを、GitHub・CI/CDと統合して安全に運用するための設計思想と基本パイプラインを解説します。

#エージェント型AI#Claude Code#Codex#CI/CD#GitHub#開発プロセス

近年、ソフトウェア開発ではAIを使ってコードを生成するだけでなく、AI自身にコードを書かせ、テストを実行し、修正まで行わせる「エージェント型AI」の活用が進んでいます。

代表的なものとして、OpenAIのCodexやAnthropicのClaude Codeがあります。

従来の生成AIでは、

人間がコードを書き、AIに一部分を生成してもらう

という使い方が中心でした。

一方、エージェント型AIでは、

IssueをもとにAIが実装し、テストを実行し、Gitで変更を管理し、Pull Requestを作成する

といった開発工程そのものをAIに担当させることができます。

しかし、AIに開発を任せるほど重要になるのが、AIそのものよりも開発プロセスの設計です。

本記事では、CodexやClaude CodeなどのAIエージェントを、GitHub・プロジェクト管理・CI/CDと統合して運用するための基本的な考え方を解説します。

この記事で学べること

  • エージェント型AIとは何か
  • AIとCI/CDをどのように組み合わせるか
  • IssueやPull RequestをAI開発にどう活用するか
  • AIにどこまで権限を与えるべきか
  • AI開発で重要になるテストとレビュー
  • AIを組み込んだ開発パイプラインの基本構成

1. エージェント型AIとは

エージェント型AIとは、単に文章やコードを生成するだけではなく、目的を達成するために複数の作業を自律的に実行するAIです。

例えば、ソフトウェア開発では次のような作業を一貫して行えます。

ステップ内容
1Issueを確認
2コードベースを調査
3コードを変更
4テストを実行
5エラーを確認
6コードを修正
7Gitにコミット
8Pull Requestを作成

Claude CodeやCodexのようなツールでは、このような一連の作業をAIに任せることができます。

そのため、エージェント型AIは「コード生成AI」というより、

AIによるソフトウェア開発エージェント

と考えたほうが分かりやすいでしょう。

2. AIだけで開発を完結させない

AIエージェントが高性能になっても、すべてをAIに任せればよいわけではありません。

重要なのは、AIと既存の開発ツールに役割を分担させることです。

役割主な担当
人間要件定義・設計判断・最終承認
AIエージェント実装・テスト作成・修正
Gitソースコード管理
GitHub Issuesタスク・要件管理
Pull Request変更内容のレビュー
CI自動テスト・品質チェック
CDデプロイ
Monitoring本番環境の監視

つまり、

AIが作業し、CIが検証し、人間が判断する

という構造を作ることが重要です。

3. AI開発の基本パイプライン

AIエージェントを開発プロセスに組み込むと、基本的には次のような流れになります。

ステップ内容備考
1Project Management-
2Issue-
3AI Agent-
4Branch-
5Pull Request-
6CI/CDFAILの場合はAIが修正して再度CI/CDへ、PASSの場合は次のステップへ
7Human ReviewCI/CDがPASSした場合のみ到達
8Merge-
9Deploy-

この構成のポイントは、AIが直接本番環境を変更するのではなく、GitとCI/CDを経由させることです。

こうすることで、AIが作成したコードも通常のソフトウェア開発と同じように検証できます。

4. IssueをAIへの作業指示書にする

エージェント型AIを使う場合、Issueの書き方が非常に重要になります。

例えば、

ログイン機能を作ってください。

だけではAIが判断しなければならないことが多すぎます。

そこで、次のように具体化します。

## Goal

メールアドレスとパスワードによるログイン機能を実装する。

## Requirements

- POST /api/auth/login を追加
- email/passwordを受け取る
- 認証成功時は200を返す
- 認証失敗時は401を返す
- 入力値をバリデーションする
- パスワードをログに出力しない

## Acceptance Criteria

- 正しい認証情報でログインできる
- 間違った認証情報では401になる
- 不正なメールアドレスでは400になる
- Unit Testが存在する
- Integration Testが存在する

ここで重要なのが**Acceptance Criteria（受け入れ条件）**です。

AIに「何を作るか」だけではなく、

何を満たせば完成なのか

を明確にします。

5. Issue → Branch → Pull Requestを基本単位にする

AIにコードを書かせる場合でも、Gitの基本的な開発フローは維持します。

ステップ内容
1Issue #123
2feature/123-login ブランチを作成
3AI Agentが実装
4Commit
5Pull Requestを作成
6CIを実行
7Review
8Merge

AIにmainブランチへ直接変更させるのではなく、BranchとPull Requestを経由させます。

これによって、

  • 変更履歴を残せる
  • 差分を確認できる
  • CIを実行できる
  • 人間がレビューできる
  • 問題があれば変更を取り消せる

というメリットがあります。

6. CIはAIが作ったコードを検証する

AIがコードを書けるようになると、CIの重要性はさらに高くなります。

例えばPythonプロジェクトなら、次のようなチェックを積み重ねます。

ステップチェック内容
1Pull Request作成
2Lint
3Type Check
4Unit Test
5Integration Test
6Security Scan
7Build

AIはコードを生成できますが、

「このコードは本当に正しいのか？」

を機械的に検証するのはCIの役割です。

そのため、

AIとCIは競合するものではなく、相互補完するもの

と考えることが重要です。

7. CIの失敗をAIにフィードバックする

エージェント型開発では、CIの結果をAIに戻すことでさらに強力な開発ループを作れます。

ステップ内容
1AIが実装
2Pull Request作成
3CI実行
4FAIL
5エラー内容をAIが確認
6原因を調査
7コードを修正
8CI再実行
9PASS

例えば、

pytest failed
Expected: 200
Actual: 401

というエラーが発生した場合、AIにエラー内容を渡して原因を調査させます。

AIが、

  1. エラーを確認
  2. 関連コードを調査
  3. 原因を特定
  4. コードを修正
  5. テストを再実行

というサイクルを回せるようになります。

この仕組みを作ると、AIは単なるコード生成ツールではなく、CIからのフィードバックを利用して自分の実装を改善するエージェントになります。

8. AIにプロジェクトのルールを理解させる

AIエージェントを継続的に利用する場合、毎回プロジェクトの説明をするのは非効率です。

そこで、プロジェクト固有のルールをリポジトリに保存します。

例えば、

  • README.md
  • AGENTS.md
  • CLAUDE.md
  • docs/
  • architecture/

などです。

内容としては、

# Project Rules

## Architecture

Frontend: Next.js
Backend: FastAPI
Database: PostgreSQL

## Development Rules

- TypeScriptはstrict modeを使用
- API変更時は仕様書を更新する
- DB変更時はmigrationを作成する
- 新しいライブラリを追加する場合は理由を記載する
- Secretをソースコードに保存しない

などを記述します。

ここが重要です。 AGENTS.mdとCLAUDE.mdは同じ役割の別名ではありません。AGENTS.mdはCodexやCursorなど複数のツールが横断的に読み込むオープンな標準規格として広がっており、一方CLAUDE.mdはClaude Code固有のメモリファイルで、グローバル設定・プロジェクト直下・ディレクトリごとの階層読み込みなど独自の機能を持ちます。Claude CodeはAGENTS.mdをそのままでは読み込まないため、両方を使い分けたい場合はCLAUDE.md側からAGENTS.mdを参照させる、あるいはシンボリックリンクを作るといった運用が必要です。複数のAIエージェントを併用するプロジェクトでは、どちらを「正」の設定ファイルにするか事前に決めておくとルールの重複や矛盾を防げます。

こうすることで、AIはプロジェクトのルールやアーキテクチャを理解した上で作業できます。

AIエージェントの性能を考える場合、

どのモデルを使うか

だけではなく、

AIにどれだけ正確なコンテキストを与えられるか

も非常に重要です。

9. AIへの指示とシステムによる制御を分ける

AIに、

本番環境を変更しないでください。

と指示するだけでは、本当のセキュリティ対策にはなりません。

これはあくまでAIへの「指示」です。

一方で、システム側では次のような段階を設けます。

ステップ内容
1AI Agentが変更を実施
2Development環境
3Staging環境
4Human Approval
5Production

このようにシステム側で制御すれば、AIが誤って本番環境へ変更を加えることを防ぎやすくなります。

つまり、

AIに守ってもらうルールと、システム側で強制するルールを分ける

ことが重要です。

10. AIエージェントには最小限の権限を与える

AIに必要以上の権限を与えるのは危険です。

例えば、AIエージェントに与える権限は以下の範囲に留め、

  • ソースコード
  • 開発環境
  • テスト環境
  • Git操作

以下のような重要リソースには直接アクセスさせない設計が望ましいでしょう。

  • Production Database
  • Production Credentials
  • 決済システム
  • 重要なSecret

基本的な考え方は、

必要な権限だけを与える

という最小権限の原則です。

11. Development・Staging・Productionを分離する

AIを使う場合、環境分離も重要です。

ステップ内容
1Development
2AIが実装・テスト
3Staging
4CI
5Human Review
6Production

特にProductionについては、

CI PASS ↓ Human Approval ↓ Production Deploy

という承認ゲートを設けると安全性を高められます。

AIが高速にコードを変更できるからこそ、本番環境への変更には人間による承認を残すことが重要です。

12. AIにすべての設計判断を任せない

AIは実装だけでなく、アーキテクチャについても提案できます。

しかし、

  • データベース構成
  • 認証方式
  • API設計
  • クラウド構成
  • セキュリティ設計

などの重要な判断をすべてAIに任せるのは危険です。

例えば、次のような流れにします。

ステップ内容
1Issue
2AIが設計案を作成
3Human Review
4設計を決定
5AIが実装

AIには「実装」を任せ、人間は重要な「意思決定」を担当するという分担です。

13. AI開発では「Definition of Done」が重要

AIがコードを書いただけでは、タスクが完了したとは考えません。

例えば、次のように「完成条件」を定義します。

Definition of Done

  • 実装完了
  • Unit Test追加
  • Integration Test追加
  • Lint PASS
  • Type Check PASS
  • Security Check PASS
  • Documentation更新
  • Pull Request作成
  • Human Review完了

これにより、

AIがコードを書いた

から、

AIが開発工程を完了した

という状態へ変えることができます。

14. AIエージェントを複数に分ける

プロジェクトが大きくなれば、AIに役割を持たせることもできます。

例えば、Project Managerの下にDeveloper・Tester・Reviewerという役割を分担させ、それぞれの出力をCIとHuman Reviewに集約する構成です。

Project Manager ↓ Developer / Tester / Reviewer（役割分担） ↓ CI ↓ Human Review

ただし、最初から大量のAIエージェントを導入する必要はありません。

まずは、

1つのAIエージェント + GitHub + CI/CD

というシンプルな構成から始めるほうが管理しやすいでしょう。

15. 最終的な開発環境

CodexやClaude Codeを利用した開発環境は、最終的には次のような構成を目指せます。

ステップ内容
1Human
2Project Management
3Issue
4AI Agent
5Git / Branch
6Pull Request
7CI（Test / Security / Build）
8Human Review
9Merge
10Deployment
11Production

この構成では、人間はコードを書くことだけに時間を使うのではなく、

  • 要件定義
  • アーキテクチャ設計
  • AIへの指示
  • コードレビュー
  • 最終的な意思決定

に集中できます。

一方、AIは、

  • コード実装
  • テスト作成
  • エラー調査
  • リファクタリング
  • ドキュメント作成

などを担当します。

メリット・デメリット

観点メリットデメリット・注意点
開発速度実装・テスト作成が高速化するレビューが追いつかないと品質が担保できない
一貫性プロジェクトルールに沿った実装をAIが再現しやすいルール（CLAUDE.md等）のメンテナンスコストが発生する
権限管理最小権限設計により事故を防ぎやすい権限設計を誤ると誤操作のリスクが残る
意思決定人間は設計・レビューに集中できるAI任せにしすぎるとアーキテクチャの一貫性が崩れる可能性がある

セキュリティ・運用上の注意点

AIエージェントに開発作業を任せる場合、以下の点は特に注意が必要です。

  • Secretの取り扱い：APIキーやパスワードなどのSecretをソースコードやIssue本文に直接書き込まない。AIがログや差分にSecretを含めてしまうリスクを避ける。
  • 権限の最小化：AIエージェントの実行環境には、本番データベースや決済システムへの認証情報を持たせない。
  • 承認ゲートの設置：本番環境へのデプロイは、CIのPASSだけでなく人間の承認を必須にする。
  • 監査ログの保持：AIがどのIssueを元に、どのような変更を行ったかを追跡できるようにする（Git履歴・Pull Requestのコメントなど）。

ここが重要です。 「AIに指示すれば安全」という考え方はリスクがあります。指示はあくまで努力目標であり、権限やデプロイフローなど、システム側で強制できる仕組みと組み合わせることが重要です。

まとめ

CodexやClaude CodeなどのAIエージェントを活用する上で重要なのは、単純に「AIにコードを書かせる」ことではありません。

重要なのは、Project Management → Issue → AI Agent → Git → PR → CI → Human Review → Deployという開発プロセス全体にAIを組み込むことです。

特に重要なポイントをまとめると、以下の通りです。

  • IssueでAIに作業内容と完成条件を伝える
  • AIの変更はBranchとPull Requestを経由させる
  • CIでAIが作ったコードを自動検証する
  • CIのエラーをAIにフィードバックする
  • プロジェクト固有のルールをAIに与える（AGENTS.mdとCLAUDE.mdは役割が異なる点に注意する）
  • AIの権限を最小限にする
  • Productionへの変更には人間の承認を残す
  • AIと人間の責任範囲を明確にする

最終的な目標は、

AIにコードを書かせることではなく、人間が要件と意思決定を行い、AIが実装・テスト・修正を行い、CI/CDが品質と安全性を担保する開発システムを作ること

です。

AIエージェントが高性能になるほど、「どのAIを使うか」以上に、AIを安全かつ効率的に働かせる開発基盤をどう設計するかが重要になっていきます。

次に学びたい技術

エージェント型AIを実際の開発環境へ導入する場合、次のような技術を順番に理解すると全体像を掴みやすくなります。

  • Git / GitHub
  • GitHub Issues / Projects
  • Pull Request
  • GitHub Actions
  • CI/CD
  • Docker
  • Infrastructure as Code
  • IAM・Secret Management
  • AI Agent
  • MCP
  • Observability
← ブログ一覧に戻る