Codex NumPyの使い方｜修正・高速化・テストの実践手順

CodexでNumPyコードを扱う前に知っておきたいこと

Codex CLIは、開いているプロジェクトのファイルを調べ、変更し、手元にあるコマンドを使って結果を確認できる開発支援ツールです。公式のCodex CLIページでも、コードの調査、編集、コマンドの実行をターミナルから行えると説明されています。NumPyの修正では、複数の関数やテストを追いながら原因を絞り込める点が役立ちます。

ただし、Codexがリポジトリを読めることと、数値計算の意図を正しく推測できることは別です。同じshapeの出力が返っても、dtypeがfloat32からfloat64へ変わったり、ビューだった配列がコピーになったりすれば、速度やメモリ量、呼び出し元への影響が変わります。依頼者が守る条件を言葉とテストで示し、Codexが確認できる形にすることが欠かせません。

直近の更新で反復確認がしやすくなった

OpenAIのCodex changelogによると、2026年7月21日のCodex CLI 0.145.0では、長い対話での表示応答やストリーミング出力が改善されました。NumPyの不具合調査は、失敗例の確認、修正、テスト、追加条件の確認を何度も往復しがちです。長い対話を追いやすくなった今は、途中の前提を保ちながら数値計算を段階的に検証する使い方と相性が良いタイミングです。

NumPyでは「動いた」だけでは不十分

通常の業務ロジックなら、期待する文字列や状態が返ることを確認すれば十分な場合があります。一方、NumPyでは丸め誤差、オーバーフロー、欠損値、軸の取り違えがあり、例外が出なくても誤った結果になることがあります。高速化でPythonのループを配列演算へ置き換えたときも、入力のshapeによっては偶然だけ正しい結果になるため、代表例だけでなく境界値を含めた確認が必要です。

依頼前にshape・dtype・期待値をそろえる

Codexへの指示は長ければ良いわけではありません。OpenAIの指示の書き方では、目的、参考になる情報、求める出力、変えてはいけない境界を必要に応じて示す考え方が紹介されています。NumPyでは、この四点を数値計算に合わせて具体化すると、修正の方向がぶれにくくなります。

依頼前に確認したいのは、対象関数の入出力、通常時のshape、受け付けるdtype、欠損値の扱い、許される誤差、速度やメモリ量の目標です。公開されている関数の引数や戻り値を変えてよいかも明記します。条件が未確定なら、すぐ修正させず、まず既存コードから現在の挙動を説明させると、暗黙の前提を見つけやすくなります。

shapeは具体例と軸の意味まで伝える

(n, m)とだけ書くより、nはサンプル数、mは特徴量数というように各軸の意味を伝えます。単一サンプルの(m,)を受け付けるのか、常に二次元配列を要求するのかも重要です。軸を省略すると、Codexがaxis=0とaxis=1を取り違えても、小さな正方行列ではテストを通ることがあります。行数と列数が異なる入力例を用意すると、この誤りを検出しやすくなります。

dtypeと欠損値の扱いを明文化する

整数配列の平均や除算は、戻り値のdtypeに注意が必要です。float32を維持したい処理で暗黙にfloat64へ広がると、大きな配列ではメモリ量が増えます。NaNを無視するのか伝播させるのか、正負の無限大を受け付けるのか、整数のオーバーフローをどう扱うのかも決めます。判断が必要な条件を先に示せば、Codexが都合のよい仮定で処理を書き換える余地を狭められます。

成功条件は数値とテスト名で示す

「高速にする」だけでは完了条件が曖昧です。たとえば「既存テストをすべて通す」「新しい回帰テストを追加する」「10万行の入力で変更前より遅くしない」「公開関数の引数は変えない」と書けば、結果を客観的に判定できます。速度の厳密な秒数は実行環境で変わるため、絶対値を求める場合は測定環境も示します。再現性のある確認方法を依頼文に含めることが、レビューの負担を減らします。

CodexにNumPyの修正を依頼する5つの手順

ここからは、既存関数の不具合修正と高速化を例に、Codexへ渡す順序を整理します。最初から広い範囲を書き換えさせず、現状確認、失敗の固定、最小変更、性能確認、境界値確認の順に進めます。各段階で得られた結果を次の指示へ加えると、Codexが推測で補う部分を減らせます。

題材は、行ごとに値を正規化するnormalize_rows関数です。ゼロだけの行でNaNが生じ、Pythonのループが速度のボトルネックになっていると仮定します。実際の依頼では、関数名、対象ファイル、利用中のテストコマンドをプロジェクトに合わせて置き換えてください。

Step 1: 現在の挙動を説明させる

最初の指示ではコードを変更させず、入力から出力までの流れ、配列のshapeとdtypeが変化する場所、ゼロ除算が起こる条件を説明させます。分析だけを先に受け取ることで、Codexが問題を正しく理解しているかを変更前に確認できます。既存テストがどの条件を扱い、何を扱っていないかも挙げさせると、次に追加する失敗例が明確になります。

src/features.py の normalize_rows を調べてください。
コードはまだ変更せず、入力と出力のshape・dtype、ゼロ除算が起きる条件、
既存テストで不足しているケースを説明してください。
公開関数の引数と戻り値は変更しない前提です。

Step 2: 小さな失敗例をテストにする

原因が確認できたら、まず変更前に失敗するテストを追加させます。ゼロだけの行、通常の行、負数を含む行を小さな配列にまとめ、期待値を人が読める大きさにします。NumPy公式のTesting guidelinesも、見つかった不具合ごとにテストを追加し、再発を防ぐ考え方を示しています。失敗を先に固定すると、修正が本当に問題を解いたか判断できます。

def test_normalize_rows_keeps_zero_row_finite():
    x = np.array([[0.0, 0.0], [3.0, 4.0]], dtype=np.float32)
    actual = normalize_rows(x)
    expected = np.array([[0.0, 0.0], [0.6, 0.8]], dtype=np.float32)
    np.testing.assert_allclose(actual, expected, rtol=1e-6, atol=1e-7)
    assert actual.dtype == np.float32

Step 3: 最小の変更で修正させる

テストの失敗を確認した後で、対象関数だけを最小限に変更するよう依頼します。ループを配列演算へ置き換える場合は、ブロードキャストする配列のshapeを説明し、ゼロ除算を避ける条件が見える書き方を求めます。変更後は新しいテストと既存テストの両方を実行させ、結果を報告させます。無関係な整形や名前変更を含めないよう境界を置くと、差分を追いやすくなります。

追加した回帰テストを通す最小の変更を行ってください。
Pythonの行単位ループはNumPyの配列演算へ置き換えます。
ゼロ行はゼロのまま、戻り値は入力がfloat32ならfloat32を維持してください。
対象関数以外の整理は行わず、関連テストの結果を示してください。

Step 4: ブロードキャストとメモリ量を確認する

NumPy公式のBroadcastingでは、異なるshapeの配列を一定の規則で演算でき、不要なデータコピーを避けやすい一方、使い方によってはメモリ効率が悪くなると説明されています。Codexが生成した式について、中間配列のshapeを列挙させ、元データと同じ大きさの一時配列が何個できるか確認します。速度が上がっても、ピーク時のメモリ量が大幅に増える変更なら採用前に再検討が必要です。

Step 5: 境界値と性能を別々に判定する

最後に、空配列、1行だけの入力、整数、float32、float64、NaN、無限大、非常に大きい値を確認します。すべてを一つの巨大なテストにせず、仕様ごとに分けると失敗理由が明確です。性能測定は正しさのテストと分け、同じデータを複数回処理して代表値を比較します。速度が改善しても数値結果やdtypeが変わっていれば不合格とし、正しさを先に満たしてから性能を評価します。

NumPy特有の落とし穴をレビューする

Codexが提案したコードは、見た目が短くても安全とは限りません。NumPyでは一行の演算に配列全体の処理が隠れ、shape、dtype、メモリ共有の違いが呼び出し元へ波及します。レビューでは「短くなったか」より、「入力条件ごとに同じ意味を保てるか」を見ます。

特に注意したいのは、暗黙のブロードキャスト、ビューへの破壊的変更、不要なコピー、浮動小数点の厳密一致です。これらは小さなサンプルでは問題が見えず、本番に近い大きさや特殊値で初めて表面化します。Codexには差分の説明だけでなく、中間配列のshape、共有状態、テストしたdtypeを報告させると、確認漏れを減らせます。

ビューへの代入が元配列を変えないか

NumPy公式のCopies and viewsでは、基本的なスライスはビューを作り、ビューへの変更が元配列へ反映されると説明されています。Codexが一時変数だと思ってスライスへ代入すると、呼び出し元の配列まで変わる可能性があります。関数が入力を変更しない契約なら、テストの前後で入力配列が同じことを確認し、必要な場所だけ明示的にコピーします。

数値の一致には許容差を使う

ベクトル化や計算順序の変更によって、浮動小数点の末尾がわずかに変わることがあります。期待値との比較に==を使うと、意味のない差でテストが落ちたり、NaNの扱いを見誤ったりします。numpy.testing.assert_allcloseなどを使い、用途に合う相対許容差と絶対許容差を決めます。ただし許容差を広げすぎると本当の誤差を隠すため、扱う値の桁と業務上許される差から根拠を示します。

dtypeの変化を見逃さない

NumPyの演算では、入力の組み合わせによって出力dtypeが変わります。整数の除算、異なる精度の配列同士の演算、Pythonの数値リテラルとの演算は特に確認が必要です。値だけを比較するテストではdtypeの変化を検出できないため、重要な関数ではactual.dtypeも明示的に確認します。大規模配列では精度が一段上がるだけで必要メモリが増えるため、性能改善の評価にも直結します。

そのまま使えるCodexへの依頼例

最後に、ここまでの条件を一つの依頼文へまとめます。文章を長くすることが目的ではなく、Codexの判断を左右する情報だけを残すのがポイントです。対象ファイル、入出力、守る条件、確認方法がそろっていれば、背景説明を何段落も加える必要はありません。

以下の例では、最初に調査と計画を求め、承認後に変更へ進む形にしています。一度に広範囲を触らせたくないときは、調査結果を受け取った時点で対象範囲をさらに狭めます。プロジェクト固有のコマンドや性能条件は、実際に再現できる内容へ置き換えてください。

不具合修正と高速化をまとめて依頼する例

この依頼例は、目的、前提、境界、確認方法を順に示しています。入力を変更しないこと、dtypeを維持すること、回帰テストを先に置くことを明記しているため、Codexは短さだけを優先した変更を選びにくくなります。速度目標が未確定なら、まず変更前後の測定結果だけを求め、人が結果を見て採否を決める形でも構いません。

目的:
src/features.py の normalize_rows でゼロ行からNaNが生じる問題を直し、
行単位ループをNumPyの配列演算へ置き換えてください。

前提:
入力shapeは(n, m)、各行が1サンプルです。
float32とfloat64を受け付け、戻り値は入力dtypeを維持します。
入力配列そのものは変更しません。

境界:
公開関数の引数と戻り値を変えないでください。
新しい外部パッケージは追加せず、無関係なファイルは変更しません。

確認:
最初に小さな回帰テストを追加し、変更前に失敗することを確認してください。
変更後は既存テストと回帰テストを実行し、結果を報告してください。
中間配列のshapeと、入力のコピーが発生する箇所も説明してください。

まとめ

CodexにNumPyコードを任せる要点は、修正方法を細かく指定することではなく、守るべき数値上の契約を検証可能な形で渡すことです。shapeと軸の意味、dtype、欠損値、許容差、入力を変更するかどうかを示し、小さな失敗例をテストとして固定すれば、Codexは目的に沿った差分を作りやすくなります。

変更後は、テストが通ったという一言で終わらせず、ブロードキャストによる中間配列、ビューとコピー、dtypeの変化、境界値、性能を順に確認します。直近のCodex CLIは長い対話の扱いが改善されていますが、数値計算の正しさを最終的に保証するのは明文化した条件と再現可能なテストです。まずは一つの関数と小さな入力から試し、確認できた範囲だけを段階的に広げてください。