Codexでバグ修正を自動化する - Issue解決からPRまで

はじめに

ソフトウェア開発において、バグ修正は避けて通れない作業です。しかし、バグの原因調査、修正コードの実装、テストの追加、PRの作成という一連のプロセスは時間がかかり、開発者の集中力を奪います。

OpenAI Codexは、このバグ修正ワークフローを大幅に効率化できます。GitHubのIssueやSlackでの報告を起点に、Codexがコードベースを分析し、原因を特定し、修正を実装し、回帰テストを追加し、PRを自動作成するところまで、一連の流れを自律的に実行できます。

本記事では、バグ修正の一連のプロセスをCodexに委任し、効率的なデバッグワークフローを構築する方法を解説します。

前提条件

本記事の内容を実践するには、以下の準備が必要です。

要件	詳細
ChatGPTプラン	Plus、Pro、Business、Edu、Enterpriseのいずれか
GitHub連携	Codexとの接続設定が完了していること
環境設定	対象リポジトリの環境が作成済みであること
テスト環境	自動テストが実行可能な状態であること

基本操作やタスク管理については、シリーズの前回までの記事を参照してください。

バグ修正ワークフローの全体像

Codexを活用したバグ修正は、以下のフローで進行します。

flowchart TD
    A[バグレポート受領] --> B[Codexへタスク作成]
    B --> C[コードベース分析]
    C --> D[原因調査・特定]
    D --> E[修正コード実装]
    E --> F[回帰テスト追加]
    F --> G[テスト実行・検証]
    G --> H{テスト成功?}
    H -->|No| E
    H -->|Yes| I[PR作成]
    I --> J[人間によるレビュー]
    J --> K{承認?}
    K -->|No| L[フィードバック]
    L --> B
    K -->|Yes| M[マージ]

このフローにおいて、Codexは「タスク作成」から「PR作成」までの工程を自律的に実行します。人間が介入するのは、最初のバグレポートの確認と、最終的なコードレビューのみです。

バグレポートからタスクを作成する

GitHub Issueからの直接起動

2025年10月のアップデートで、GitHub上で@codexをメンションすることでCodexタスクを直接起動できるようになりました。これにより、Issueからシームレスにバグ修正を開始できます。

Issueでのメンション例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


@codex このバグを調査して修正してください。

## 再現手順
1. ユーザーログイン後、プロフィール画面に遷移
2. 「設定を保存」ボタンをクリック
3. エラーが発生し、設定が保存されない

## 期待される動作
設定が正常に保存され、成功メッセージが表示される

## 実際の動作
「TypeError: Cannot read property 'id' of undefined」エラーが発生

## 環境
- ブラウザ: Chrome 120
- OS: Windows 11

Codexはこのメンションを検知すると、自動的にタスクを開始し、進捗をIssueのコメントとして報告します。

Codex Webからのタスク作成

Codexダッシュボードから直接タスクを作成することもできます。

手順

Codexダッシュボード（https://chatgpt.com/codex）にアクセス
対象リポジトリの環境を選択
「コード」タブでプロンプトを入力
タスクを送信

効果的なプロンプトの書き方

バグ修正タスクでは、以下の情報を含めると精度が向上します。

要素	説明	例
症状	何が起きているか	「保存時にエラーが発生」
再現手順	どうすれば再現できるか	「プロフィール画面で保存ボタンをクリック」
期待動作	本来どうあるべきか	「設定が保存されて成功メッセージが表示される」
エラー情報	スタックトレースやログ	「TypeError: Cannot read property…」
該当箇所	心当たりがあれば	「src/services/UserService.ts 付近」

プロンプト例

以下のバグを修正してください。

## 症状
ユーザープロフィールの保存時に TypeError が発生し、
設定が保存されない。

## エラーメッセージ
TypeError: Cannot read property 'id' of undefined
    at UserService.updateProfile (src/services/UserService.ts:45)
    at ProfileController.save (src/controllers/ProfileController.ts:28)

## 再現手順
1. /profile にアクセス
2. 任意のフィールドを変更
3. 「保存」ボタンをクリック

## 期待動作
設定が保存され、「保存しました」というメッセージが表示される。

修正後は、この問題を検出する回帰テストも追加してください。

Slackからのタスク起動

Codex for Slackを利用すれば、Slackでのバグ報告から直接タスクを起動できます。

@Codex リポジトリ myorg/myapp の以下のバグを修正してください:
ログイン時にセッションが正しく保存されない問題が発生しています。
Chrome DevToolsでCookieを確認すると、secure属性が設定されていないようです。

Codexによる原因調査

コードベースの自動分析

タスクを受け取ると、Codexはまずコードベース全体を読み込み、問題の原因を調査します。この際、AGENTS.mdファイルに記述された情報が重要な手がかりとなります。

AGENTS.mdでのデバッグ支援設定

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


# AGENTS.md

## デバッグ時の参照ポイント

バグ修正時は以下の順序で調査してください：

1. エラーログの確認
   - 開発: `logs/dev.log`
   - 本番: CloudWatch Logs

2. 関連コンポーネントの依存関係
   - サービス層: `src/services/`
   - リポジトリ層: `src/repositories/`
   - コントローラー層: `src/controllers/`

3. 設定ファイル
   - 環境変数: `.env.example`
   - アプリ設定: `src/config/`

## よくある問題パターン

- 認証エラー → `src/middleware/auth.ts` を確認
- DB接続エラー → `src/config/database.ts` を確認
- 型エラー → `src/types/` の定義を確認

調査プロセスの可視化

Codexは調査プロセスをリアルタイムで報告します。ダッシュボードの「進捗」タブで、以下のような情報を確認できます。

[調査開始] エラースタックトレースを分析中...
[ファイル読み込み] src/services/UserService.ts
[分析] updateProfile メソッドで user オブジェクトが undefined の可能性
[ファイル読み込み] src/controllers/ProfileController.ts
[分析] リクエストからユーザー情報を取得する箇所を確認
[ファイル読み込み] src/middleware/auth.ts
[原因特定] 認証ミドルウェアで req.user が設定されていないケースを発見

引用による根拠の提示

Codexは調査結果を報告する際、該当コードの引用を提示します。これにより、分析の妥当性を検証できます。

Codexの報告例

## 調査結果

原因を特定しました。`AuthMiddleware` において、トークンの検証に失敗した場合でも
`next()` が呼び出され、`req.user` が `undefined` のまま後続の処理に進んでいます。

【F:src/middleware/auth.ts†L23-L28】

該当箇所：
```typescript
if (!token) {
  // ここで return せずに next() を呼んでいる
  next();
}
```

これにより、`UserService.updateProfile` で `user.id` にアクセスした際に
TypeError が発生しています。

修正コードの実装

自動修正の実行

原因を特定したCodexは、修正コードを自動的に実装します。GPT-5.2-Codexモデルでは、複雑なバグ修正においてもより精度の高い修正が可能になっています。

修正の実装例

Codexは問題を修正し、変更内容をdiff形式で表示します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


// src/middleware/auth.ts

 export const authMiddleware = async (req: Request, res: Response, next: NextFunction) => {
   const token = req.headers.authorization?.split(' ')[1];
   
   if (!token) {
-    next();
+    return res.status(401).json({ error: 'Authentication required' });
   }
   
   try {
     const decoded = await verifyToken(token);
     req.user = decoded;
     next();
   } catch (error) {
-    next();
+    return res.status(401).json({ error: 'Invalid token' });
   }
 };

修正方針の選択肢

複雑なバグの場合、Codexは複数の修正方針を提案することがあります。2025年6月に追加された「Best of N」機能を使えば、複数の解決策を並行して生成し、最適なアプローチを選択できます。

複数の修正方針の例

## 修正方針A: 早期リターンによるガード
- メリット: シンプルで明確
- デメリット: エラーレスポンスが統一されない可能性

## 修正方針B: カスタムエラークラスの導入
- メリット: エラーハンドリングの一貫性
- デメリット: 追加のコード変更が必要

## 修正方針C: ミドルウェアの分離
- メリット: 責務の分離が明確
- デメリット: 影響範囲が広い

推奨: 修正方針Aを採用し、今後の拡張に備えて
修正方針Bへのリファクタリングを別タスクとして提案します。

回帰テストの追加

テスト駆動型の修正検証

Codexは修正コードを実装した後、回帰テストを自動的に追加します。これは、同じバグが再発しないことを保証するために不可欠です。

自動生成されるテスト例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53


// src/middleware/__tests__/auth.test.ts

describe('AuthMiddleware', () => {
  describe('when token is missing', () => {
    it('should return 401 status', async () => {
      const req = mockRequest({ headers: {} });
      const res = mockResponse();
      const next = jest.fn();

      await authMiddleware(req, res, next);

      expect(res.status).toHaveBeenCalledWith(401);
      expect(res.json).toHaveBeenCalledWith({ 
        error: 'Authentication required' 
      });
      expect(next).not.toHaveBeenCalled();
    });
  });

  describe('when token is invalid', () => {
    it('should return 401 status', async () => {
      const req = mockRequest({ 
        headers: { authorization: 'Bearer invalid_token' } 
      });
      const res = mockResponse();
      const next = jest.fn();

      await authMiddleware(req, res, next);

      expect(res.status).toHaveBeenCalledWith(401);
      expect(res.json).toHaveBeenCalledWith({ 
        error: 'Invalid token' 
      });
      expect(next).not.toHaveBeenCalled();
    });
  });

  describe('when token is valid', () => {
    it('should set req.user and call next', async () => {
      const validToken = generateValidToken({ id: '123' });
      const req = mockRequest({ 
        headers: { authorization: `Bearer ${validToken}` } 
      });
      const res = mockResponse();
      const next = jest.fn();

      await authMiddleware(req, res, next);

      expect(req.user).toEqual({ id: '123' });
      expect(next).toHaveBeenCalled();
    });
  });
});

AGENTS.mdでのテスト要件指定

AGENTS.mdでテストの要件を明示することで、Codexが生成するテストの品質を向上させられます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


# AGENTS.md

## テスト要件

### 必須テストパターン
バグ修正時は以下のテストを必ず含めてください：

1. **異常系テスト**: バグを再現するテストケース
2. **正常系テスト**: 修正後の期待動作を確認
3. **境界値テスト**: エッジケースの検証

### テストの命名規則
- describe: 対象のクラス/関数名
- it: 「should + 期待動作」の形式

### カバレッジ要件
- 修正したファイルのカバレッジは80%以上を維持
- 新規追加コードは100%カバレッジ必須

テスト実行と検証

Codexは修正とテストを実装した後、自動的にテストを実行します。テストが失敗した場合は、修正を繰り返します。

flowchart TD
    A[修正コード実装] --> B[テスト追加]
    B --> C[テスト実行]
    C --> D{全テスト成功?}
    D -->|No| E[失敗原因分析]
    E --> F[修正の調整]
    F --> C
    D -->|Yes| G[コミット作成]

テスト実行ログの例

[テスト実行] npm test

PASS src/middleware/__tests__/auth.test.ts
  AuthMiddleware
    when token is missing
      ✓ should return 401 status (5ms)
    when token is invalid
      ✓ should return 401 status (3ms)
    when token is valid
      ✓ should set req.user and call next (4ms)

Test Suites: 1 passed, 1 total
Tests:       3 passed, 3 total
Coverage:    92% (target: 80%)

[検証完了] すべてのテストが成功しました

PRの作成とレビュー

自動PR作成

テストが成功すると、Codexは変更をコミットし、PRを自動作成します。

生成されるPRの例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


## Fix: AuthMiddleware で未認証リクエストが通過するバグを修正

### 概要
認証ミドルウェアにおいて、トークンが存在しない場合や無効な場合でも
`next()` が呼ばれ、後続の処理に進んでしまう問題を修正しました。

### 変更内容
- `src/middleware/auth.ts`: トークン検証失敗時に401レスポンスを返すよう修正
- `src/middleware/__tests__/auth.test.ts`: 回帰テストを追加

### テスト結果
- 全テスト: 通過 ✅
- カバレッジ: 92%

### 関連Issue
Fixes #123

### 引用
【F:src/middleware/auth.ts†L23-L35】

PRへのフォローアップ

PRに対するコメントやレビュー依頼にもCodexは対応できます。@codexをメンションすることで、追加の修正を依頼できます。

フォローアップ例

1
2
3


@codex このPRに以下の変更を追加してください：
- エラーレスポンスにタイムスタンプを含める
- ログ出力を追加する

Codexはこのフィードバックを受けて、既存のPRを更新します。

コードレビューの自動化

2025年8月のアップデートで追加された「Code Review」機能を使えば、Codexが自動的にPRをレビューします。

flowchart LR
    A[PR作成] --> B[Codex Code Review]
    B --> C{問題検出?}
    C -->|Yes| D[改善提案]
    D --> E[自動修正または人間が対応]
    C -->|No| F[承認推奨]

Code Reviewでは、以下の観点から分析が行われます。

観点	説明
意図との整合性	PRの目的と変更内容が一致しているか
コードベースとの一貫性	既存のコーディング規約に準拠しているか
依存関係の影響	変更が他のコンポーネントに影響を与えないか
動作検証	テストが十分で、期待通りに動作するか

実践的なバグ修正シナリオ

シナリオ1: Null参照エラー

バグレポート

Issue #234: ユーザー一覧画面でNullPointerExceptionが発生

再現手順:
1. 管理者でログイン
2. ユーザー管理 > ユーザー一覧
3. 退会済みユーザーを含むページを表示

エラー:
NullPointerException at UserListService.java:67

Codexへのプロンプト

Issue #234 のバグを修正してください。

退会済みユーザー（deletedAtが設定されている）を含む一覧表示で
NullPointerExceptionが発生しています。

修正要件：
- 退会済みユーザーも安全に表示できるようにする
- 退会済みユーザーには「（退会済み）」ラベルを表示
- 回帰テストを追加

Codexの対応

UserListService.javaを分析し、user.getProfile().getName()でNullアクセスが発生する箇所を特定
Null安全なアクセス方法に修正
退会済みユーザーの表示ロジックを追加
単体テストと統合テストを追加
PRを作成

シナリオ2: 競合状態によるデータ不整合

バグレポート

Issue #345: 同時更新時にデータが消失する

再現手順（間欠的）:
1. ユーザーAとユーザーBが同じドキュメントを編集
2. ほぼ同時に保存
3. 一方の変更が失われる

Codexへのプロンプト

Issue #345 の競合状態バグを修正してください。

複数ユーザーが同時にドキュメントを更新した際に、
一方の変更が失われる問題が発生しています。

修正方針として以下を検討してください：
- 楽観的ロック（バージョン番号による制御）
- 最終更新日時のチェック
- 適切なエラーメッセージの表示

回帰テストは並行処理のシナリオを含めてください。

Codexの対応

ドキュメントエンティティにversionフィールドを追加
更新時にバージョンチェックを実装
競合時のエラーハンドリングを追加
並行更新の統合テストを作成
マイグレーションスクリプトを生成
PRを作成

シナリオ3: パフォーマンス問題

バグレポート

Issue #456: ダッシュボード画面の読み込みが30秒以上かかる

環境: 本番環境（データ量: 100万レコード）
期待: 3秒以内

Codexへのプロンプト

Issue #456 のパフォーマンス問題を調査・修正してください。

ダッシュボード画面の読み込みに30秒以上かかっています。
データ量は100万レコードです。

調査ポイント：
- N+1問題の有無
- インデックスの適切性
- 不要なデータの取得

修正後は、パフォーマンステストも追加してください。

Codexの対応

SQLクエリを分析し、N+1問題を検出
Eager loadingへの修正を実装
必要なインデックスを追加するマイグレーションを作成
ページネーションの最適化
パフォーマンステストを追加
PRを作成

効率的なバグ修正のためのベストプラクティス

1. AGENTS.mdでコンテキストを提供する

AGENTS.mdに以下の情報を記載しておくと、Codexの調査精度が向上します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


# AGENTS.md

## バグ調査のガイドライン

### ログの確認方法
- 開発環境: `docker-compose logs -f app`
- ステージング: AWS CloudWatch `/aws/ecs/staging/app`

### よくある問題の原因箇所
| 症状 | 確認箇所 |
|------|---------|
| 認証エラー | `src/auth/`, `src/middleware/auth.ts` |
| DB接続エラー | `src/config/database.ts`, `.env` |
| API 500エラー | `src/exceptions/`, エラーハンドラー |
| キャッシュ不整合 | `src/cache/`, Redis設定 |

### デバッグ用コマンド
\`\`\`bash
# ログ出力を詳細モードで起動
DEBUG=app:* npm start

# 特定のテストをデバッグ実行
npm test -- --grep "UserService" --inspect
\`\`\`

2. タスクを適切な粒度で分割する

大きなバグは、複数の小さなタスクに分割してCodexに依頼すると成功率が上がります。

悪い例（粒度が大きすぎる）

アプリケーション全体のパフォーマンスを改善してください。

良い例（適切な粒度）

タスク1: ダッシュボードAPIのN+1問題を修正
タスク2: ユーザー一覧のページネーション最適化
タスク3: 検索クエリへのインデックス追加

3. テスト環境を整備する

Codexがテストを正しく実行できるよう、環境を整備しておきます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


# AGENTS.md

## テスト実行

### 単体テスト
\`\`\`bash
npm test
\`\`\`

### 統合テスト
\`\`\`bash
npm run test:integration
\`\`\`

### E2Eテスト
\`\`\`bash
npm run test:e2e
\`\`\`

### テスト用データベース
テスト実行前に以下を実行してください：
\`\`\`bash
npm run db:test:setup
\`\`\`

4. 並列タスクで効率化する

複数の独立したバグがある場合は、並列でタスクを実行します。

flowchart TD
    A[バグトリアージ] --> B[独立性の評価]
    B --> C{相互依存あり?}
    C -->|Yes| D[順次実行]
    C -->|No| E[並列実行]
    E --> F[タスク1: 認証バグ]
    E --> G[タスク2: UIバグ]
    E --> H[タスク3: APIバグ]
    F --> I[統合・レビュー]
    G --> I
    H --> I

トラブルシューティング

Codexが原因を特定できない場合

対処法1: 追加情報の提供

前回のタスクでは原因を特定できませんでした。
以下の追加情報を参考にしてください：

- 本番環境でのみ発生（開発環境では再現しない）
- 特定の時間帯（午前9時〜10時）に集中して発生
- 直近でデプロイした変更: PR #789

対処法2: 調査範囲の限定

以下のファイルに限定して調査してください：
- src/services/PaymentService.ts
- src/repositories/OrderRepository.ts
- src/controllers/CheckoutController.ts

テストが通らない場合

対処法: フォローアップタスク

テストが失敗しています。以下のエラーを修正してください：

FAIL src/services/__tests__/UserService.test.ts
  ✕ should return user with profile (23ms)
  
  Expected: {"name": "John", "email": "john@example.com"}
  Received: {"name": "John", "email": null}

テストの期待値が間違っている可能性もあります。
実装とテストの両方を確認してください。

PRの品質が低い場合

対処法: 具体的な改善指示

@codex このPRに以下の改善を適用してください：

1. コミットメッセージを Conventional Commits 形式に修正
2. 変更理由をコードコメントとして追加
3. PR説明文にスクリーンショットを追加（該当する場合）

まとめ

本記事では、OpenAI Codexを活用したバグ修正の自動化ワークフローを解説しました。

重要なポイントは以下の通りです。

適切なバグレポート: 症状、再現手順、期待動作、エラー情報を明確に記述する
AGENTS.mdの活用: デバッグのガイドラインやテスト要件を事前に定義しておく
テスト駆動の修正: 回帰テストを追加し、同じバグの再発を防止する
段階的なレビュー: Codexの提案を鵜呑みにせず、人間がレビューして品質を担保する
フィードバックループ: PRへのコメントで追加修正を依頼し、品質を向上させる

Codexにバグ修正を委任することで、開発者は問題の本質的な分析や設計判断に集中できます。定型的なデバッグ作業から解放され、より創造的な開発活動に時間を使えるようになるでしょう。

次回は、Codexを活用したリファクタリングの効率化について解説します。

はじめに#

前提条件#

バグ修正ワークフローの全体像#

バグレポートからタスクを作成する#

GitHub Issueからの直接起動#

Codex Webからのタスク作成#

Slackからのタスク起動#

Codexによる原因調査#

コードベースの自動分析#

調査プロセスの可視化#

引用による根拠の提示#

修正コードの実装#

自動修正の実行#

修正方針の選択肢#

回帰テストの追加#

テスト駆動型の修正検証#

AGENTS.mdでのテスト要件指定#

テスト実行と検証#

PRの作成とレビュー#

自動PR作成#

PRへのフォローアップ#

コードレビューの自動化#

実践的なバグ修正シナリオ#

シナリオ1: Null参照エラー#

シナリオ2: 競合状態によるデータ不整合#

シナリオ3: パフォーマンス問題#

効率的なバグ修正のためのベストプラクティス#

1. AGENTS.mdでコンテキストを提供する#

2. タスクを適切な粒度で分割する#

3. テスト環境を整備する#

4. 並列タスクで効率化する#

トラブルシューティング#

Codexが原因を特定できない場合#

テストが通らない場合#

PRの品質が低い場合#

まとめ#

参考リンク#

はじめに

前提条件

バグ修正ワークフローの全体像

バグレポートからタスクを作成する

GitHub Issueからの直接起動

Codex Webからのタスク作成

Slackからのタスク起動

Codexによる原因調査

コードベースの自動分析

調査プロセスの可視化

引用による根拠の提示

修正コードの実装

自動修正の実行

修正方針の選択肢

回帰テストの追加

テスト駆動型の修正検証

AGENTS.mdでのテスト要件指定

テスト実行と検証

PRの作成とレビュー

自動PR作成

PRへのフォローアップ

コードレビューの自動化

実践的なバグ修正シナリオ

シナリオ1: Null参照エラー

シナリオ2: 競合状態によるデータ不整合

シナリオ3: パフォーマンス問題

効率的なバグ修正のためのベストプラクティス

1. AGENTS.mdでコンテキストを提供する

2. タスクを適切な粒度で分割する

3. テスト環境を整備する

4. 並列タスクで効率化する

トラブルシューティング

Codexが原因を特定できない場合

テストが通らない場合

PRの品質が低い場合

まとめ

参考リンク