Codex・Claude Codeで「動くけれど間違った」研究コードを防ぐ方法

コーディングエージェントに文章で依頼すると、ファイルを作成し、コードを実行し、エラーを修正し、すべてのテストに成功したと報告してくれます。それでも、研究結果が間違っていることはあります。

変数を取り違える、生の値に補正済みデータ用の品質フラグを組み合わせる、単位を取り違える、欠損値をゼロで埋める、意図した手法とわずかに違う式を実装する。こうした間違いは、必ずしもエラーとして表面化しません。もっともらしい図と正常終了したコマンドが、間違いを覆い隠すことがあります。

CodexやClaude Codeは、チャット画面で一つのコード断片を返すだけでなく、リポジトリ全体を扱えます。既存コードを読み、複数のファイルを変更し、コマンドを実行し、テストを追加し、差分を要約できます。実装やレビューは速くなりますが、科学的な判断まで自動化できるわけではありません。

この記事は、こうした支援を使いたいものの、ソフトウェア開発を専門としていない研究者を対象としています。エージェントがアクセスできる範囲を制限し、実装前に解析方法を決め、「コードが動いた」だけでは終わらせない確認手順を説明します。

コーディングエージェントを使うと何が変わるか

通常のチャット型AIが返すのは文章やコードブロックで、それを別の場所へ貼り付けるのは利用者です。コーディングエージェントは、プロジェクトの中で直接作業できます。

できること	研究上の利点	必要な確認
リポジトリを読む	既存のローダー、テスト、規則に合わせて実装する	指定した解析条件とデータ仕様を読んでいるか確認する
複数ファイルを変更する	コード、テスト、文書を同時に整える	差分全体を読む
コマンドを実行する	構文、import、実行時の不具合を見つける	READMEやDockerfileで定めた環境で実行し、出力を確認する
テストを書く	前提条件を繰り返し確認できる形にする	実装とは別に正解を用意する
失敗後に修正する	デバッグを速める	テストを弱めたり手法を変えたりしていないか確認する

実装、リファクタリング、テストの土台作り、文書化、定型的な確認はエージェントに向いています。次の判断は研究者が担います。

• 何を明らかにしたいのか
• その目的に合う変数と単位は何か
• どの品質管理方針を採用するか
• どの式、補間方法、統計モデルが適切か
• 実装とは別に求めた正解を用意できるか
• 結果を研究に使ってよいと判断できる根拠が揃ったか

エージェントを起動する前に土台を作る

作業を始める前に、次の三つを用意しておくと、エージェントの変更を確認しやすくなります。

• GitとGitHub：何を変更したか記録し、レビューできるようにする
• Docker：解析を動かす環境と手順を記録する
• 解析条件：使用する変数や計算方法を事前に決めておく

まだ使ったことがなければ、先に次の記事を参照してください。

• 研究コードの変更履歴と再現性を残す方法：Git・GitHub入門
• 研究の解析環境を再現可能にする方法：Docker入門

エージェントにはGitブランチで作業させ、すべての変更を差分として確認できるようにします。解析とテストは、READMEなどに記載したDockerコマンドで実行します。こうすると、作業中のパソコンにしか入っていないライブラリに、気づかないまま依存してしまう事態を防げます。

エージェントが書き込める範囲を限定する

一つのリポジトリに、コード、指示、テスト、機密性のない小さなテストデータをまとめます。失うと復元できない元データや利用制限のあるデータは、エージェントが書き込める範囲の外に置きます。

research-project/
├── AGENTS.md
├── CLAUDE.md
├── README.md
├── Dockerfile
├── compose.yaml
├── requirements.txt
├── method/
│   └── analysis-contract.yaml
├── src/
├── tests/
│   └── fixtures/
└── output/

research-data/              # エージェントが書き込めるリポジトリの外

解析をDockerで実行するときは、外部のデータを読み取り専用でマウントします。認証情報もリポジトリの外で管理し、プロンプトや指示ファイルに秘密情報を貼り付けてはいけません。

指示ファイルは、エージェントへ作業ルールを伝えるためのものであり、アクセスを制限する機能ではありません。実際に読み書きできる範囲は、エージェントのサンドボックスと承認設定、OSの権限、読み取り専用マウントで制限します。

エージェントは解析用コンテナの外で動かす

使用するエージェントの最新の公式手順に従って導入・認証し、リポジトリのルートで起動します。

cd research-project

# 一つの作業ディレクトリでは片方のツールだけを起動する
codex

# またはClaude Codeを使います
claude

CodexやClaude Codeは、解析用のDockerイメージには入れず、Dockerコンテナの外側（ホスト側）で動かします。コーディングエージェントは頻繁に更新されますが、解析用イメージは動作を確認した計算環境を保つためのものです。

二つのエージェントに同じ作業ディレクトリを同時に編集させてはいけません。別々に実装させたり、別のエージェントにレビューさせたりする場合は、Gitブランチやworktreeも分けます。

作業ルールをリポジトリに置く

CodexはリポジトリのAGENTS.mdから指示を読みます。Claude CodeはCLAUDE.mdを読み、公式ドキュメントでは既存のAGENTS.mdを読み込む方法が案内されています。

簡潔なAGENTS.mdを作ります。

# Research analysis instructions

## Scientific contract

- Treat raw input data as immutable.
- Do not choose raw or adjusted variables silently.
- Record variable names, units, quality filters, and missing-value rules.
- Keep pressure in dbar unless an approved method defines a conversion.
- Ask before changing a threshold, equation, interpolation method,
  coordinate convention, or statistical model.

## Working rules

- Run analysis and tests through Docker Compose.
- Write generated files only under `output/`.
- Add a small known-answer test for each derived calculation.
- Never change an expected value merely to make a test pass.
- Report assumptions, failed checks, and unresolved scientific choices.

## Done when

- The requested code and tests are implemented.
- The documented checks pass.
- The diff has been reviewed for units, filters, equations, and tolerances.
- Output metadata identifies the data snapshot, parameters, and Git commit.

同じリポジトリをClaude Codeでも扱う場合は、隣にCLAUDE.mdを作ります。

@AGENTS.md

これらのルールは、短く具体的にします。教科書のように長い指示ファイルでは、その作業に必要な情報が埋もれ、内容を正確に保つことも難しくなります。変数、品質基準、計算式などの詳しい条件は、別のファイルにまとめます。

コードを書く前に解析条件を決める

結果に影響する計算では、エージェントに実装を頼む前に、使用するデータ、変数、品質基準、計算方法を研究者が決めて書き出します。

question: Compare upper-ocean temperature across selected profiles

inputs:
  snapshot: "provider, retrieval date, and checksum go here"
  pressure:
    variable: PRES_ADJUSTED
    unit: dbar
  temperature:
    variable: TEMP_ADJUSTED
    unit: degree_Celsius

quality:
  accepted_flags: ["1", "2"]
  missing_values: reject

method:
  pressure_interval_dbar: [0, 500]
  interpolation: none
  aggregation: none

validation:
  - dimensions and units match this contract
  - pressure is strictly increasing after filtering
  - a synthetic profile has an independently calculated answer
  - representative real profiles are inspected visually

先に条件を書いておけば、研究者が決めることと、コード上の実装を分けて確認できます。エージェントは曖昧な点を指摘してかまいませんが、TEMPとTEMP_ADJUSTEDのどちらを使うか、複数あるQC配列のどれを使うかを、黙って決めてはいけません。

手法がまだ固まっていないなら、すぐにコード編集を頼まず、既存の実装や資料の調査と作業計画を先に依頼します。使用する変数や処理方法を決めてから、実装へ進みます。

確認方法と完了条件も依頼に含める

複雑なプロンプト技法は必要ありません。目的、参照する文書、変更してはいけないもの、確認方法、完了条件を伝えます。

Goal:
Implement method/analysis-contract.yaml.

Context:
Read AGENTS.md, the method contract, and the existing loaders under src/.

Constraints:
Do not modify raw data, the method contract, or existing expected results.
Run Python only through Docker Compose.
Stop and report if a required variable or unit is unavailable.

Validation:
Add synthetic tests whose expected values were determined independently.
Run focused tests and inspect one representative output for impossible values.

Done when:
Show changed files, commands run, test results, assumptions, and every
scientific decision that still needs human approval.

この形で依頼を書くと、変数や確認方法の指定漏れに気づきやすくなります。どの変数を使い、どの値を正解とし、何を確認したら完了なのかを示せないうちは、実装を研究に取り込めません。

データ構造の確認と科学的確認を分ける

最初のテストでは、入力の形が想定どおりか確認できます。

from math import isfinite


def validate_profile(
    pressure_dbar: list[float],
    temperature_c: list[float],
) -> None:
    if len(pressure_dbar) != len(temperature_c):
        raise ValueError("pressure and temperature lengths differ")
    if len(pressure_dbar) < 2:
        raise ValueError("profile needs at least two levels")
    if not all(isfinite(value) for value in pressure_dbar + temperature_c):
        raise ValueError("profile contains a non-finite value")
    if any(
        upper <= lower
        for lower, upper in zip(pressure_dbar, pressure_dbar[1:])
    ):
        raise ValueError("pressure must be strictly increasing")

対応するテストは次のように書けます。

import unittest

from src.profile_checks import validate_profile


class ValidateProfileTest(unittest.TestCase):
    def test_accepts_increasing_pressure(self) -> None:
        validate_profile([0.0, 10.0, 20.0], [24.0, 22.0, 19.0])

    def test_rejects_mismatched_lengths(self) -> None:
        with self.assertRaisesRegex(ValueError, "lengths differ"):
            validate_profile([0.0, 10.0], [24.0])

    def test_rejects_reversed_pressure(self) -> None:
        with self.assertRaisesRegex(ValueError, "strictly increasing"):
            validate_profile([0.0, 20.0, 10.0], [24.0, 19.0, 22.0])

このテストで検出できるのは、要素数が合わないなど、構造に問題のある配列です。混合層の計算、回帰、補間、水塊分類が科学的に正しいことまでは証明できません。配列の形を確かめるテストと、計算方法の妥当性を確かめるテストでは目的が異なります。

実装とは別に正解を用意する

派生量を計算する処理には、エージェントが書いたコードを使わずに正解を求められる小さな例を、少なくとも一つ用意します。

• 一行ずつ確認できる小さな手計算
• 結果が明らかになるよう設計した合成プロファイル
• レビュー済みの参照実装
• 定義が一致する論文や標準文書の計算例
• 入力や作成条件が記録された、検証済みパイプラインの出力

エージェントにテストコードを書かせることはできます。ただし、同じエージェントにアルゴリズムを考えさせ、その実装が出した値をテストの正解として採用してはいけません。

数値の許容誤差は、手法と精度に基づいて決めます。テストが失敗したら、単位、定数、前処理、定義、浮動小数点演算を調べます。テストを成功させることだけを目的に許容範囲を広げてはいけません。

順を追って検証する

エージェントが生成した解析コードを、次の順で確認します。

1. 実行：READMEやDockerfileで定めた環境で、手順書に記載したコマンドが完了するか
2. 入力条件：次元、座標、単位、型、欠損値が事前に決めた条件と一致するか
3. 既知の正解：小さな入力から、実装とは別に求めた結果が得られるか
4. 参照比較：代表的なデータで、信頼できる実装や計算例と一致するか
5. 感度：妥当な範囲でパラメーターを変えたとき、想定できる傾向を示すか
6. 科学的な確認：中間値、プロファイル、地図、分布が物理的に妥当か
7. 再実行：新しくcloneしたリポジトリで、記録した入力とコマンドから結果を作れるか

前の項目に問題がなくても、後の項目まで正しいとは限りません。ソフトウェアテストは欠かせませんが、科学的なレビューの代わりにはなりません。

最終的な図より先に差分を確認する

見栄えのよい完成図だけを見て判断せず、その前にGitの差分を読みます。特に次の項目を確認します。

• 式、定数、数値の許容誤差
• 単位変換
• 生、補正済み、QC変数の選択
• フィルタリングと並べ替えの順序
• 欠損値の処理
• データのない大きな区間をまたぐ補間
• 解析条件を記したファイルと、テストで正解とする値の変更

計算に影響する変更ごとに、事前に決めた解析条件のどれに対応するのかをエージェントに説明させます。対応関係を説明できないなら、図がもっともらしく見えるという理由だけで変更を取り込んではいけません。

テスト、代表的な出力、差分を確認してからコミットします。小さなコミットに分けると、計算条件を変更した箇所と時点を後から特定できます。

権限を必要な範囲に限定する

各ツールの標準的なサンドボックスと承認設定から始めます。

• 書き込みを研究用リポジトリ内だけに許可する
• 元データや利用制限のあるデータを、その書き込み範囲の外へ置く
• ネットワークアクセスや、プロジェクト外へアクセスするコマンドに承認を求める
• 認証情報ファイルと秘密情報のディレクトリへのアクセスを拒否する
• 見慣れないパッケージの追加やダウンロード、シェルコマンド、Dockerコマンドは実行前に確認する
• 信頼できないコンテナへDockerソケットを渡さない

Codexでは、コマンドがアクセスできる範囲を制限するサンドボックスと、利用者の許可が必要な場面を決める承認ポリシーが分かれています。Claude Codeには権限規則と拒否パターンがあります。リポジトリの指示ファイルは作業方法を伝えるために使い、実際のアクセスは各ツールの権限設定で制限します。

処理は成功しても結果を誤らせる例

海洋データ解析では、次のような誤りがあっても処理が停止しない場合があります。

• 生の値と補正済みデータ用のQCフラグを組み合わせる
• dbarで表した圧力を、メートルで表した幾何学的な深さと同一視する
• 実用塩分、絶対塩分、現場水温、ポテンシャル水温、保存水温を混同する
• 欠損値をゼロで置き換える
• 一つの変数だけを並べ替え、対応する変数に同じ順序を適用しない
• データのない大きな区間をまたいで補間する
• 漂流するフロートの取得順を、固定地点の時系列として扱う

Argoデータの品質管理：QCフラグ・補正済みデータ・データモード では、変数とQCの関係を説明しています。初心者向けArgo NetCDF形式の解説 では、変数やQCフラグが格納されるファイル構造を扱います。

OceanGraphでもプロファイルを見直す

独自コードを書く前後に、選んだArgoプロファイルをOceanGraphでも確認できます。位置、サイクル、鉛直構造を確かめ、自作コードで描いた図が解析対象のプロファイルと合っているか見比べます。

• Search and Bookmark（英語）
• Analysis Lab: Vertical Profiles（英語）

OceanGraphの表示だけで、独自アルゴリズムの数値的な正しさを検証することはできません。それでも、軸の反転、層の欠落、不適切なプロファイルの選択、調べたい内容に合わないデータを使っていることに気づく手掛かりになります。

研究で使う前のチェックリスト

エージェントが作った解析コードを研究で使う前に、次の点を確認します。

• 実装より前に解析方法を決めた
• 入力、単位、品質基準、パラメーターを記録した
• エージェントの変更をGitの差分として確認できる
• READMEやDockerfileで定めた環境でコマンドを実行した
• 既知の正解を使ったテストと参照比較に成功した
• 途中の計算値と最終出力を確認した
• テストを通すためだけに期待値や手法を変更していない
• まだ不確かな点と、専門家による確認が必要な判断を明記した

エージェントは、こうした確認作業を支援できます。しかし、最終的な科学的判断の責任を負うことはできません。

エージェントが生成した解析コードを検証する仕組みを自組織だけで整えるのが難しい場合は、下の問い合わせ導線から、環境構築・実装支援についてもご相談いただけます。

お問い合わせ

構築・実装支援とアノテーション業務

環境構築や設計・実装の支援、アノテーション業務の委託について、ご相談いただけます。

お問い合わせフォームへ

関連記事と公式資料

次に読む記事：

• 研究コードの変更履歴と再現性を残す方法：Git・GitHub入門
• 研究の解析環境を再現可能にする方法：Docker入門
• T-S図の作り方：Pythonとブラウザツールを比較
• 海洋データの機械学習で起きるデータリーク：空間・時間を考慮したデータ分割

製品・研究資料：

• Codexのベストプラクティス（英語）
• Codexの承認とセキュリティ（英語）
• CodexのAGENTS.mdによるカスタム指示（英語）
• Claude Codeのクイックスタート（英語）
• Claude Codeのプロジェクト指示とAGENTS.md読み込み（英語）
• Claude Codeの権限設定（英語）
• 生物医学研究のデータサイエンスでLLMの信頼性を評価した研究（英語）

最後に挙げたベンチマークが対象としているのは、一つの研究分野と限られたタスクです。どの解析にも当てはまる精度を示すものではありません。この論文から読み取るべき点は、生成された研究コードを使う前に、具体的な計画と、実装とは別の方法による検証が必要だということです。