あなたのコードに claude-opus-… のようなモデルの完全な名前が書かれていたら、そのコードは新しい世代に自動では移りません。自分のエージェントでは、記事の採点や判定をする LLM-as-judge のスクリプト3本がこの形で、「Opus で採点しています」と報告しながら、実際には1世代前のモデルで動いていました。自分の環境ではエラーも警告も出ず、点数は普通に出ました。Opus 5 が出た翌日の2026年7月25日に気づいて最新世代に替えると、ある記事の採点が109点から102点に下がりました。ただし、同じ本文を1回ごとに採点し直した記録でも点数は動くので、7点が世代の違いなのかぶれなのかは、この1件からは言い切れません。この記事では、まず自分のコードを確かめる方法を置き、そのあと、何が起きていたのか、別名と明示 ID の違い、9月にもう一度起きたことを書きます。
言葉の説明
モデルを指定する書き方は、2つに分けて呼びます。明示 ID は、claude-opus-5 のようにモデルの完全な名前を書く形で、ハイフンでつながった数字の部分が版です。別名は、opus、sonnet、haiku のような短い名前。世代は、Opus 5 から Opus 5.5 のように、新しいモデルが出たことを指します。書く場所も2つあります。1つはエージェント定義ファイルで、Claude Code のサブエージェントごとの設定を書く md に、model: opus のように指定します。もう1つはスクリプトで、Python などから claude コマンドを --model つきで呼ぶ形です。点数は、記事の出来を120点満点で採る自作の基準のもの。当時の合格線は105点でした。
自分のコードで明示 ID を探す
まず、明示 ID の文字列を探します。次の1行は例で、bash を前提にしています。ID の形は環境によって違うので、使っている形に合わせて直してください。claude-3-5-sonnet-20241022 のような旧い形や claude-fable-5-1 も拾うように広げ、依存パッケージの置き場は除いてあります。
grep -rnE "claude-([0-9.-]+-)?(opus|sonnet|haiku|fable)[a-z0-9.:-]*" --include="*.py" --include="*.js" --include="*.ts" --include="*.md" --include="*.json" --include="*.sh" --include="*.ps1" --include="*.yaml" --include="*.yml" --include="*.toml" --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=.git .
環境変数で固定している場合は、別の1行で探します。見えるのは今のシェルの環境だけで、settings.json の env は見ません。
env | grep -i "ANTHROPIC_DEFAULT\|ANTHROPIC_MODEL"
試験用のファイルで、claude-opus-4-8、claude-3-5-sonnet-20241022、claude-3-opus-20240229、claude-3-5-sonnet-latest、us.anthropic.claude-opus-5-5-v1:0、claude-fable-5-1 が拾われ、claude-code は拾われないことを確かめました。.env は、秘密を含みうるので範囲に入れていません。md も拾うので、説明文の中の言及も当たります。
見つかったものは、次のように振り分けます。点数を比べたい用途(採点など)は、明示 ID のまま固定し、見直す期日と担当を決めて書きます。それ以外の用途は、別名に替えるのが基本です。報告やログにモデルの世代が出ているかも、あわせて見ます。報告の文言が「Opus」とだけ言っていて、コードのほうが版まで固定している。この組み合わせなら、今回と同じことが起きえます。
実行時に実際に使われたモデルは、claude -p の JSON 出力の modelUsage に出ます。次の1行で、別名がいま何に解決されるかも確かめられます。
claude -p "ok とだけ答えて" --model haiku --output-format json < /dev/null | python -c "import sys,json; print(list(json.load(sys.stdin)['modelUsage']))"
2026年11月3日に Claude Code 2.1.317 で動かすと、['claude-haiku-5-5'] と出ました。採点のたびにこの値をログに残しておけば、報告が「Opus」でも、動いた版を後から追えます。
固定されていた3本
記事の品質を上げるために、Sonnet で回していた部分を最新世代の Opus に替えたい、という話が出ました。モデルの配分を調べたところ、採点系のスクリプトの中に、旧世代の明示 ID が文字列で書かれていました。
該当したのは3本です。1本目は記事の採点です。Opus を CLI から呼び、3回採点して中央値を取る作りで、モデルの ID は OPUS という名前の定数に書いていました。サムネイルの採点は、関数の引数の既定値と --model の既定値の両方に、品質判定は --model の既定値と説明文に、同じ旧世代の ID を書いていました。報告の上では3本とも「Opus で採点している」ことになっていましたが、実際に動いていたのは1世代前の Opus で、最新世代は一度も使われていませんでした。
気づけなかった理由
原因は、「Opus と指定しているのだから最新のはずだ」という思い込みでした。報告の文面には世代が出ませんでした。採点中のログに版まで出ていたのはサムネイルと品質判定の2本で、記事の採点中の行は「Opus CLI採点モード」としか出さず、その行からは世代が分かりませんでした。
もう一つやっかいだったのは、この取りこぼしに気づく合図が無いことです。自分の環境では、エラーも警告も出ませんでした。採点は正常に終わり、点数もきちんと出ます。ただ、採点しているモデルが1世代前のままでした。落ちるわけではないので、見に行くきっかけが自然には生まれません。1世代前で動いていたのは、Opus 5 が出た翌日に気づくまでの1日半ほどでした。
替えたあとの点数
7月に、3本の ID を claude-opus-4-8 から claude-opus-5 に更新しました。更新の直後に、ある記事を採点し直しました。
| 時点 | モデル | 点数 | 採点の回数 |
|---|---|---|---|
| 更新の前 | 旧世代 | 109点 | 3回の中央値 |
| 更新の直後 | 最新世代 | 102点 | 初回の計測で、回数は記録なし |
| 指摘された箇所を直したあと | 最新世代 | 105点 | 記録は「105点PASS」のみ。当時の合格判定は3回の中央値 |
102点は合格線の105点を下回り、直して再び採点して、105点で合格しました。
下がり幅の7点は、自分の記録にある1回ごとの採点のぶれと同じくらいの大きさです。同じ本文を1回ずつ採点し直した記録では、小さいもので7〜9点、7月10日に測ったときは10〜22点の幅がありました。3回の中央値どうしのぶれは測っておらず、旧世代で採り直した記録もありません。確かめられたのは、固定されていたモデルを替えると、点数が動きうる、というところまでです。
別名と明示 ID の違い
公式の説明は、2026年11月3日に https://code.claude.com/docs/en/model-config で読みました。それによると、opus、sonnet、haiku の別名は、Anthropic API では最新の版に解決され、一部の他の提供元では以前の版に解決されます。版を固定したいときは、完全なモデル名を使うか、ANTHROPIC_DEFAULT_OPUS_MODEL のような環境変数を設定します。
自分の環境で確かめた記録は2つです。9月23日に、Claude Code 2.1.280 の内蔵のモデル一覧で、opus が claude-opus-5-5 を指すのを見ました。10月9日には、2.1.295 で claude --model haiku -p を動かし、modelUsage に出たモデルが claude-haiku-5-5 だったことを確かめました。公式の更新履歴は、2.1.293 で Anthropic API の既定の Haiku が 5.5 になったと書いています。エージェント定義の model: opus が新しい世代に付いていくかは、自分では確かめた記録がありません。公式の sub-agents のページ(同日取得)には、エージェント定義に opus と書いた場合、メインの会話が Opus で動いていれば、メインの会話と同じ版が使われる、とあります。書く場所で結果が変わる場合があります。
明示 ID を書いた文字列は、メジャー更新があっても自動では追従しません。公式のドキュメントには、廃止予定のモデルや、自動で新しい版に読み替えられたモデルを要求したときは警告を出す、という記述があります。自分の3本では、この警告を一度も見ていません。どの ID が読み替えられるかの条件は、公式に書かれていません。自分の環境で確かめたのは、10月9日に明示 ID の claude-haiku-4-5-20251001 が書いたとおりに使われたことだけです。別名と明示 ID が混ざっていると、同じ環境の中で、ある部分は最新世代、ある部分は1世代前、というねじれが生まれえます。気づきにくいのは、このねじれのほうです。
書き方の違いを並べると次のとおりです。
# エージェント定義:別名指定。指す先は提供元と環境で決まる
model: opus
# 明示 ID を書いた定数:自動では追従しない
OPUS = "claude-opus-5"
9月にもう一度起きたこと
7月は、3本の旧世代の ID を更新し、あわせて、記事の投稿フローを定めたルール文書に、モデルの世代が上がったらこの3ファイルの定数を必ず更新する、という趣旨の一文を足しました。
9月22日に Opus の新しい世代(5.5)が出ました。翌23日の点検で、採点の3本が claude-opus-5 の固定のままだと確かめ、採点の点数の分布を測るまで替えない、と決めました。7月に足した「必ず更新する」という一文には、分布を測るまで待つという理由で、わざと従いませんでした。この日に点検したのは採点の3本だけで、据え置きを解く期日と担当も決めませんでした。固定はそのまま続き、9月29日に「sonnet5.5を使う設定になっている?」と聞かれて見に行くまで、思い出す仕組みがありませんでした。
見に行くと、固定された ID は採点の3本の外にもありました。コードに3か所、手順書の md に2か所です。コードの3か所には、当時最新だった Haiku の ID も含まれていました。手順書のうち、題を作る手順は claude-opus-4-8 のまま、サムネイルの仕様を作る手順は claude-opus-5 のままでした。ルールの一文は、思い出す人がいなければ働かず、期日の無い据え置きは、解く合図を決めない限り終わりませんでした。
そこで、無人で呼ぶスクリプトのモデルを1つの設定ファイルにまとめ、それ以外のコードに明示 ID を書いたら検査で落ちるテストを入れました。テストが見るのは、git で管理している Python・PowerShell・JavaScript のコードだけです。markdown と JSON、テスト用のフォルダ、試作の置き場、# 以降のコメントは見ません。手順書の md の2か所は、まさにこのテストが見ない種類の場所でした。採点は、点数を比べられるようにあえて明示 ID で固定します。生成は別名にして、新しい世代に自動で付いていくようにしました。
9月29日は、新旧のモデルで同じ記事を並べて採点してから、ID を更新しました。過去に合格した記事3本を、新旧のモデルでそれぞれ2回ずつ採点した平均は、Opus 5 が106.0(6回中1回は読み取りの失敗で、残り5回の平均)、Opus 5.5(思考量の設定は medium)が100.0で、6点ほど低く出ました。合格線は、モデルを替えたのに合わせて、暫定で105点から90点に下げています。合否そのものは、点数とは別に用意した、読み手の立場で記事を読んで判定する検査に移しました。点数は、90点に届かない記事を落とすためだけに使っています。
同じ種類のリスクは、デフォルト値、フォールバック先、タイムアウト値にも潜むと整理しています。どれも一度書いたら動き続け、落ちないので誰も見に行かない場所です。
AIエージェントに任せた作業で起きた事故と、その防ぎ方は、Kindle 本にまとめています。『AIエージェントに仕事を任せる前に知っておきたい、実際に起きた事故と防ぎ方』(Kindle・680円)
https://tony-kinot.github.io/kdp-book1/go/?from=advent