この記事について
この記事は、生成AIを活用した自動生成フローで作成しています。OpenAIの現在のモデルガイダンスを確認し、旧版の「詳細な処理説明を出力させる」構成を、再現ログ・状態観測・最小修正・実テスト中心に見直しました。検証ステータス：📘 OpenAI公式情報確認済み／特定言語・特定リポジトリでの横断評価は未実施
難しいロジックバグほど、コードを眺めるだけでは原因が見えません。入力によって状態がどう変化したか、どの時点で期待値から外れたかを観測する必要があります。
LLMを使う場合も、「何が起きたか」をログやテストで与える方が、抽象的な「バグを直して」より再現性が高くなります。
入力はコードだけでは足りない
対象コード: [必要な最小範囲]
再現入力: user_id=42, retry=2
期待結果: status="completed"
実際結果: status="pending"
再現率: 100%
関連ログ: [該当箇所だけ]
再現情報があると、モデルは一般論ではなく具体的な差分へ集中できます。
状態を表にする
| 時点 | 入力 | 状態 | 期待 |
|---|---|---|---|
| 開始 | retry=0 | pending | pending |
| 1回目 | retry=1 | processing | processing |
| 2回目 | retry=2 | pending | completed |
このような観測値を渡すと、「どこから違うか」を絞りやすくなります。
修正依頼では変更範囲を制限する
制約:
- public APIは変更しない
- 依存ライブラリを追加しない
- 問題に無関係なリファクタリングをしない
- 変更理由を3行以内で説明する
- 修正を確認するテストを追加する
実行できるなら実際にテストする
モデルの説明だけで「直った」と判断しません。テスト環境があるなら、修正後に対象テストを実行します。
pytest tests/test_retry_state.py -q
テスト環境がない場合は、未実施と明示し、最低限のテストケース案を残します。
ログを増やすときは観測目的を決める
大量のdebugログを追加すると、かえって原因が見えにくくなります。次のような「分岐点」を優先します。
- 状態を書き換える直前と直後
- 外部APIの戻り値
- 再試行回数
- 例外が握りつぶされる箇所
- キャッシュやDBから読み直した値
修正後は元の再現ケースをもう一度使う
flowchart LR
A[再現ケース] --> B[状態を観測]
B --> C[原因候補を絞る]
C --> D[最小修正]
D --> E[同じケースで再テスト]
E --> F[回帰テスト]
レビューで見るポイント
- 再現ケースが本当に直ったか
- 別の状態遷移を壊していないか
- 例外を隠しただけになっていないか
- 修正が必要以上に広がっていないか
- 追加テストが期待動作を確認しているか
まとめ
難解なバグでは、説明の巧さより観測可能な事実が重要です。再現入力、状態、ログ、期待値、テストをそろえ、最小差分で修正し、同じケースで再確認します。
LLMは原因候補や修正案の作成に使い、最終確認は実行結果へ戻す。この流れにすると、モデルが変わってもデバッグ工程を維持しやすくなります。
公式情報・一次情報
この記事の更新履歴
- 2026-09-13 追加：再現ログ、状態表、観測ポイント、実テスト、回帰確認を追加。
- 2026-09-13 変更：長い説明を要求する方式から、状態観測と実行結果を中心とするデバッグフローへ変更。
- 2026-09-13 削除：style_prompt、本文H1、旧モデル固有の記述、未検証の精度向上表現を削除。
