Claude Opus 5対応とAIエージェントの自律性を高めるドキュメント・ログ設計手法

Claude Codeの最新版v2.1.219がリリースされ、デフォルトモデルが「Claude Opus 5」に移行しました。このアップデートに伴い、AIエージェントを効率的に動作させるためのプロンプトやドキュメントの設計手法が変化しています。本記事では、Opus 5への移行手順や、ツールの誤呼び出しを防ぐ「ツール記述契約」、AIのレビュー指摘を蓄積して開発フローを改善する自己学習ループの構築方法を解説します。

Claude Code最新版とOpus 5の登場

Claude Codeの最新版v2.1.219がリリースされ、デフォルトのOpusモデルが「Claude Opus 5」に移行しました。Opus 5は1Mコンテキストに対応しており、価格は100万トークンあたり入力$5、出力$25と旧モデルと同額に据え置かれています。開発者はモデルIDを1行書き換えるだけで移行でき、キャッシュの最小長さが1,024トークンから512トークンに半減したため、何もしなくてもコスト効率が向上します。

本バージョンでは、サブエージェントのネスト深度がデフォルトで3に拡張され、より複雑なタスクの自律処理が可能になりました。また、動的ワークフローのデフォルトサイズが15エージェント未満を目指す「medium」に変更され、ステータスラインで現在のサイズを確認できるようになっています。さらに、サンドボックスコマンドで許可リスト外のホストへの接続をプロンプトなしで拒否する設定など、セキュリティ面も強化されました。

出典: v2.1.219 / Claudeに聞いたOpus5で変える方が良いプロンプト等の俺用まとめ

Opus 5移行に伴うプロンプトとAPIの調整

Claude Opus 5の性能を最大限に引き出すためには、API設定の調整と不要なプロンプト指示の削除が必要です。Opus 5は標準で思考してから回答する特性を持つため、応答の途切れを防ぐためにmax_tokensの上限を引き上げる必要があります。また、思考を切らずに「effort」設定を調整することで、品質を維持しながらコストを下げることが可能になり、lowやmediumの品質向上を活かした段階的な調整が推奨されます。

プロンプトからは、「最後に確認して」といった検証指示や「重要度の高いものだけ」という制限表現を削除することが推奨されています。公式ガイドによると、これらの指示を消しても品質は落ちず、不要なトークン消費を削減できます。CLAUDE.mdに記載された「〜するな」という禁止命令は「〜に合わせろ」という基準提示に書き換え、不要な指示の削除候補は「/doctor」コマンドを実行して確認するのが効率的です。

出典: Claudeに聞いたOpus5で変える方が良いプロンプト等の俺用まとめ

AIエージェント向けドキュメントの3分類

AIエージェントが参照するドキュメントは、考えさせるか否かを基準に「使い方系」「ワークフロー系」「リファレンス系」の3つに分類して記述する必要があります。社内ライブラリなどの使い方系ドキュメントでは、具体的なサンプルコードを載せるよりも、インターフェースや制約を明確に記述します。サンプルを過剰に提示すると、エージェントの探索範囲を狭めてしまい、かえって性能を低下させる原因になるためです。

一方で、リリース手順などのワークフロー系や仕様書などのリファレンス系は、エージェントが勝手に手順を補完して事故を起こさないよう、省略せずに網羅します。導出できるものはインターフェースを示して考えさせ、導出できない手順や事実は網羅して渡すのがドキュメント設計の原則です。CLAUDE.mdに記述された長い手順書は「スキル」として切り出し、必要なときだけ読み込ませることで常時読み込む文章量を削減できます。

出典: Claudeに聞いたOpus5で変える方が良いプロンプト等の俺用まとめ / Claude Code / Codex がドキュメントをもっと上手に使えるようにするテクニック

誤動作を防ぐ「ツール記述契約」の定義

AIエージェントが自作ツールを誤って呼び出す問題は、説明文を「ツール記述契約」として定義することで改善できます。ツール記述契約では、いつ呼ぶか（when-to-use）、いつ呼ばないか（when-not-to-use）、各入力の意味と形式、副作用の有無の4点を明示します。モデルはツール名と説明文、引数スキーマだけを見て呼び出しを判断するため、説明文にこれらの判断材料を盛り込むことで選択のブレを防ぎます。

この契約フォーマットは、副作用を必須の列挙型にしたテンプレ関数を用いることで、記述の抜け漏れを構造的に防ぐことができます。ただし、ツール記述契約は選択確率を上げるものであり、モデルの非決定性やツールが多すぎる場合には効果が薄れる限界があります。そのため、期待するツール名を並べた小さなケース集を作成し、説明文の変更前後で選択一致率を継続的に測定して効果を評価することが不可欠です。

出典: AIエージェントが「間違ったツール」を呼ぶのは説明文のせい ― 10分で直すツール記述契約入門

「追記専用ログ」による自己学習ループ

開発フローの最終フェーズに「retrospective」を組み込み、レビュー指摘を追記専用ログに蓄積することで、AIエージェントの自己学習ループを構築できます。タスク完了時に、再発しそうな指摘を「1指摘=1行」の形式でログファイル（review-findings-log.md）の末尾に追記します。この追記専用の設計により、並行開発時にGitでマージを行う際、カウンタの更新のようにサイレントに増分データが消失するのを防ぎます。

蓄積されたログは、レビューエージェントの「頻出違反ランキング」表として集計し、定義ファイルに埋め込んでチェックの優先順位付けに利用します。ログファイル内の未集計行数がしきい値（例: 20行）を超えると、自作のlintスクリプトが検知して「再集計メンテPR」の作成を推奨します。この再集計作業を機能の実装PRとは別に単独のメンテPRで行うことで、レビューのノイズや並行ブランチとの競合を回避できます。

出典: AIレビューの指摘を資産化する — 追記専用ログと予防DoDで作る自己学習ループ

「予防DoD」による実装ミス防止と測定

実装エージェントが提出前に自己チェックを行う「予防DoD」を導入することで、レビュー前の手戻りコストを削減できます。予防DoDのチェック項目はすべてYES/NOで判定できる形式に統一し、項目自体に「grepで確認すること」などの具体的な検証方法を記載します。自己申告だけに頼るとエージェントが虚偽の申告を行うリスクがあるため、判定を宣言ではなく実際の検証行為に紐づけることが重要です。

予防DoDに追記する項目には、ルールの根拠をいつでもたどれるよう、出典となるチケット番号を付与して管理します。また、予防DoDで漏れた指摘をレビューエージェントが独立して検査する多層的な防御体制を整える必要があります。さらに、開発フローの実行時に「metrics」行をログに必ず記録するルールを設け、初回レビュー時の指摘数を記録することで、予防策が実際に効いているかを継続的に測定します。

出典: AIレビューの指摘を資産化する — 追記専用ログと予防DoDで作る自己学習ループ

この日の動きをどう見るか

AIエージェントを自律的に動作させる開発・運用において、モデルの進化（Claude Opus 5）に合わせたプロンプトやドキュメントの最適化が急速に進んでいます。開発者は、単にエージェントに指示を与えるだけでなく、ドキュメントの分類やデータ構造の設計、継続的な効果測定を通じて、エージェントが自律的かつ正確に動作する環境を整えることが求められています。

ツール呼び出しの精度を上げる「ツール記述契約」や、レビュー指摘を蓄積して再利用する「自己学習ループ」など、エージェントの行動を制御・改善する仕組みの重要性が増しています。これらのアプローチは、一人で開発や運用を行うエンジニアにとって、手戻りを減らし開発速度を維持するための強力な武器となります。