opus-4-7-migration

Opus 4.7 移行スキャナー

Anthropic プラットフォームが Opus 4.7 にルーティングしたときに、リポジトリ内で問題が発生したり、気付かないうちに品質が低下したりするパターンを特定します。ファイルと行番号を参照できるカテゴリ別レポートを生成するため、メンテナーは事後に症状を追いかけるのではなく、対象を絞った移行 PR を計画できます。

参照ファイル

ファイル	内容	読み込むタイミング
scripts/scan.py	カテゴリ別の検出結果レポートを生成するリポジトリスキャナー	常に
references/migration-map.md	カテゴリ別の移行手順と変更前・変更後のコード例	カテゴリで検出結果が返されたとき

実行するタイミング

• サービスやエージェントスタックを Opus 4.7 にアップグレードする前
• 既存の Anthropic SDK 統合で、プラットフォームへの 4.7 のロールアウト後にエラーが発生し始めたとき
• リポジトリの拡大に伴う乖離を防ぐため、CI または週次監査で定期的に
• 下流ユーザーが 4.7 に対して実行するパッケージを公開する前

対象範囲 — スキャナーが検出する項目

このスキャナーの対象範囲は意図的に絞られています。確定的なパターンを 3 カテゴリ、手動レビューが必要なヒューリスティックなカテゴリを 2 つ報告します。

カテゴリ A — 固定予算の Extended Thinking（確定的）

Opus 4.7 は、固定の budget_tokens 値を使う Extended Thinking をサポートしていません。thinking={"type": "enabled", "budget_tokens": N} を渡すコードは、SDK のバージョンによって失敗するか、無視されます。

検出対象のパターン：

• Python ソース内のリテラル budget_tokens=
• thinking={...} の辞書リテラル内の "budget_tokens" キー
• .thinking.budget_tokens 属性参照

カテゴリ B — 廃止されたモデル ID エイリアス（確定的）

現行モデルにマッピングされなくなった、日付付きまたは置き換え済みの Claude モデルエイリアスです。使用しても動作自体は壊れませんが、プラットフォームのモデルルーティングが機能しなくなります。

検出対象のパターン：

• claude-opus-4-5、claude-opus-4-4、claude-opus-4-3、claude-opus-4-2、claude-opus-4-1、claude-opus-4-0
• claude-sonnet-4-5、claude-sonnet-4-4、claude-sonnet-4-3、claude-sonnet-4-2、claude-sonnet-4-1、claude-sonnet-4-0
• 日付付き形式のエイリアス：claude-*-20250514、claude-*-20241022 など
• claude-3-* ファミリー（置き換え済み）

カテゴリ C — 設定ファイル外のハードコードされたモデル参照（確定的）

armory の規約「モデル参照は設定ファイルのみ」に従い、config.toml、.env、またはテスト専用のセンチネル文字列以外の .py／.ts／.js ソースコード内にある claude-* リテラルは、設定への切り出し候補です。

カテゴリ D — Opus 4.6 の冗長さを前提としたプロンプト（ヒューリスティック）

Opus 4.7 は、Opus 4.6 よりデフォルトの冗長さが控えめです。Opus 4.6 の積極的な出力に依存していたプロンプトや、深さを示す指示が不要だったプロンプトでは、4.7 で想定より短い応答が生成される場合があります。

検出対象のパターン（レビューが必要）：

• 長さの指示を伴わずに「詳細な」または「包括的な」出力を求めるプロンプト
• 暗黙の冗長さに依存し、Opus 4.6 のデフォルトを超える出力を求めていたプロンプト
• エージェントのプロンプトにおける初回ターンの仕様の不足

カテゴリ E — 明示的でない並列サブエージェントのディスパッチ（ヒューリスティック）

Opus 4.7 は、Opus 4.6 より慎重に委任します。「並列に起動する」と指示していても、「1 つのメッセージ内で」という表現やサブタスクの独立性を示す記述がないエージェントのプロンプトは、4.7 で逐次実行されることがよくあります。

検出対象のパターン（レビューが必要）：

• 「1 つのメッセージ内で」または「独立して」という表現がない、エージェントのプロンプト内の Spawn と parallel を含む記述
• 並列実行を意図していたのに、ループや逐次ブロック内で行われる subagent_type のディスパッチ

ワークフロー

フェーズ 1：スキャナーを実行する

次を実行します。

python3 scripts/scan.py /path/to/repo

任意のフラグ：

• --categories A,B,C — 決定論的なカテゴリのみを実行します（ヒューリスティックはスキップします）
• --exclude tests/,vendor/,node_modules/ — パスを除外します
• --format json — CI 統合向けに機械可読な出力を生成します
• --exit-code — 該当項目がある場合は終了コード 1 を返します（pre-commit フックに便利です）

フェーズ 2：検出結果をトリアージする

検出結果をカテゴリ別にまとめ、重大度順に並べ替えます。決定論的なカテゴリ（A、B、C）は常に対応が必要です。ヒューリスティックなカテゴリ（D、E）は、編集前に周辺のプロンプトコンテキストを読む必要があります。

移行 PR の優先順位：

1. カテゴリ A を最初に対応します。4.7 ではエラーになるか、気付かないまま誤動作するためです
2. カテゴリ B — 現在の論理エイリアス（claude-opus-4-7、claude-sonnet-4-6、claude-haiku-4-5）またはプラットフォームの自動ルーティング名に変更します
3. カテゴリ C — リポジトリの規約に従い、config.toml に切り出します
4. カテゴリ D、E — 手動で確認し、動作を実質的に変えるものを修正します

フェーズ 3：移行 PR を作成する

検出結果があるカテゴリごとに、references/migration-map.md に記載された対応を適用します。大規模な PR を 1 つ作成するより、カテゴリごとに小規模な PR を作成することを優先してください。

移行には次の内容を含めます。

• Opus 4.7 で更新後のコードパスを実行する単体テストまたは統合テスト
• 「Opus 4.7 互換性：…から budget_tokens を削除」のような短い CHANGELOG エントリ
• サービスが本番環境で重要な場合は、ロールアウト計画（対象エージェントの作業量レベルが high／xhigh の場合）

出力形式

スキャナーは、カテゴリ別のレポートを生成します。

Opus 4.7 Migration Scan — /path/to/repo

Category A: Fixed-budget Extended Thinking       2 findings
  src/agent/reasoner.py:47   budget_tokens=8000
  src/agent/planner.py:112   thinking={"type": "enabled", "budget_tokens": 4096}

Category B: Retired model ID aliases             3 findings
  tests/test_agent.py:89     claude-opus-4-5
  config/dev.yaml:14         claude-sonnet-4-5
  src/llm/client.py:23       claude-sonnet-4-20250514

Category C: Hardcoded model refs outside config  1 finding
  scripts/bulk_process.py:8  DEFAULT_MODEL = "claude-sonnet-4-6"

Category D: Verbosity-assuming prompts          0 findings (heuristics disabled)
Category E: Non-explicit parallel dispatch      0 findings (heuristics disabled)

Total: 6 deterministic findings across 3 categories.

エラー処理

条件	対応
リポジトリのパスが存在しない	明確なエラーメッセージを表示して終了コード 2 を返します
リポジトリに Python／TypeScript／JS ファイルがない	カテゴリ A、C をスキップし、ほかのファイル形式で B、D、E を続行します
スキャナーの正規表現エラー	終了コード 3 を返し、問題のパターンを添えてバグを報告します
カテゴリ B で変更履歴に誤検出がある	デフォルトで CHANGELOG.md を除外します。--include-changelogs で上書きできます

制限事項

• カテゴリ D、E はヒューリスティックであり、慎重に作成されたプロンプトでも誤検出が発生します。変更前に確認してください。
• スキャナーはコードを実行しません。静的なパターンマッチングのみを行います。Anthropic SDK に渡されない budget_tokens 変数も検出対象になります。
• スキャナーは実行時の動的なモデル選択（例：model = config["models"][stage]）を検出できません。これらには静的解析ではなく、統合テストが必要です。
• 複数言語にまたがる解析で対象となるのは、Python、TypeScript、JavaScript、YAML、TOML、Markdown に限られます。ほかの言語はスキップされます。

関連項目

• rules/adaptive-thinking-control/RULE.md — 固定の思考予算に代わる、プロンプトレベルの制御
• skills/usage-audit/SKILL.md — より広範なコンテキスト肥大化の監査（補完的）
• skills/mcp-to-skill/SKILL.md — MCP からスキルへの変換（移行時に MCP の多用が明らかになった場合に関連）