Claude 5世代のモデル向けにコンテキストエンジニアリングの考え方が変わっているよという公式記事。↓は自分用メモ。 ・Claude Codeのシステムプロンプトを80%以上削減しても、コーディングの精度は維持している ・以前は事故を防ぐため「コメントを書くな」等の強い制約を設けていた ・ただ、それがかえって指示の衝突を生み、AIの判断を難しくさせる原因になっていた ・最新モデルは判断力が向上しているため、細かいルールよりAIの裁量に任せた方が良い ・ツールの具体的な使用例を提示すると、逆にAIの探索範囲を狭める ・例を見せるよりも、パラメーター設計などを工夫して意図を伝える方が良い ・ツールの使い方はシステムプロンプトではなく、各ツールの説明文に記載する ・すべてのベストプラクティスをCLAUDE.mdに詰め込むのは良くない ・必要な時に情報を読み込ませるprogressive disclosure（段階的に開示）が良い ・長いドキュメントは分割し、適切なタイミングで参照させる ・CLAUDE.mdは軽量に保つ ・コードベース特有の注意点の記載にとどめる ・また、単純なMarkdownの仕様書より、もっと情報量を増やしていい。例えば、HTMLのモックアップやテストコードを渡す方が精度が上がる

長時間動くAIエージェントが抱える「コンテキストの腐敗」問題に、LangChainが5つの具体的な処方箋を示しました。 タイトル: Context Engineering with Deep Agents: How To Remember Without Keeping Everything In Context URL: 🧩 解決する課題 エージェントが指示・ツール結果・ファイルを蓄積し続けると、やがてコンテキストウィンドウの容量を超え、推論の精度が落ちてしまいます。情報過多で以前の知識が薄れる、人間の記憶にも似た現象です。 💡 5つの手法 オフロード（大きな結果をファイルシステムに退避）、サマライゼーション（古いメッセージを要約しファイルに保存）、スキル（必要な時だけ完全な指示を読み込む段階的開示）、サブエージェント（ノイズの多い作業を隔離されたコンテキストに任せる）、長期記憶（markdownファイルでセッションを越えて学習内容を保持）という5つの補完的な技術で、情報を「捨てずに」管理します。 🔧 テクニカルな特徴 これらはすべてエージェントループにフックされた「ミドルウェア」として実装されており、約2万トークンを超える結果や5万トークンを超えるユーザーメッセージを自動的にファイルへオフロードします。記憶はユーザーが管理するプレーンファイルとして存在するため、モデルプロバイダーを切り替えても学習内容を保てます。 📊 ユースケース 5社の競合分析レポートを作る「市場調査エージェント」の例では、蓄積される生データや検索結果、ドラフトの反復版が、最終レポート作成時の推論品質を落とさないようにコンテキストエンジニアリングで守られています。 #AIエージェント# #コンテキストエンジニアリング#

ハーネスエンジニアリングのアンチパターン AP1. コンテキストの溜め込み（The Context Hoarder） 🎯 ポイント 「念のため全部入れておこう」——その安心感が、エージェントの性能を静かに殺しています。情報は多いほど安全ではなく、しばしば害です。 ❗ 発生する課題 コンテキストウィンドウに無関連な情報が溢れ、エージェントの注意が希釈されます。重要な情報が中盤に埋もれ、本来必要なコードや仕様を載せるスペースが不足します。結果として、エージェントの判断精度が低下し、コストとレイテンシが線形以上に悪化します。 🔍 メカニズムと症状 このアンチパターンが魅力的に見えるのは、「情報は多いほど安全」という直感が強いからです。取得設計（何をいつ取りに行かせるか）は手間がかかるため、全部入れる方が楽に感じます。しかし、コンテキストウィンドウはCPUのL1キャッシュに相当する希少資源です。効用は単調増加しません。一定量を超えると無関連トークンが注意メカニズムを希釈し、重要情報の中盤埋没（lost in the middle）が発生します。症状としては、リポジトリ全体や長い会話履歴の丸ごと注入、全ツール定義の毎回ロード、「なぜか前に読んだはずの情報を無視する」といった現象が現れます。 📋 シナリオ ・issue-to-PRエージェントに、issueの内容だけでなくリポジトリ全体のREADME・設定ファイル・過去のPR履歴をすべて注入している。エージェントは肝心のissueの要点を見落とし、無関係なファイルを編集し始める。 ・マイグレーションエージェントに数千ファイルの情報を一度に渡し、コンテキストが溢れてエージェントが途中で一貫性を失う。 ・ペアプログラミングで、開いていないファイルや過去の長い会話履歴がコンテキストを圧迫し、レスポンスが遅くなる。 🛡 回避方法 ・コンテキストの使用量をカテゴリ別に計測し、メモリプロファイラのように配分を可視化します ・取得はpull既定（エージェント自身に必要な情報を取りに行かせる）とし、push（強制注入）は破ると致命的な不変条件だけに絞ります ・会話履歴は古いターンから要約・圧縮し、ツール定義は現在のタスクに必要なものだけを動的にロードします ・「全部入れれば安心」という思考に気づいたら、それがこのアンチパターンのサインだと認識してください #HarnessEngineering# #AIAgent#

ハーネスエンジニアリングのアンチパターン AP1. コンテキストの溜め込み（The Context Hoarder） 🎯 ポイント 「念のため全部入れておこう」——その安心感が、エージェントの性能を静かに殺しています。情報は多いほど安全ではなく、しばしば害です。 ❗ 発生する課題 コンテキストウィンドウに無関連な情報が溢れ、エージェントの注意が希釈されます。重要な情報が中盤に埋もれ、本来必要なコードや仕様を載せるスペースが不足します。結果として、エージェントの判断精度が低下し、コストとレイテンシが線形以上に悪化します。 🔍 メカニズムと症状 このアンチパターンが魅力的に見えるのは、「情報は多いほど安全」という直感が強いからです。取得設計（何をいつ取りに行かせるか）は手間がかかるため、全部入れる方が楽に感じます。しかし、コンテキストウィンドウはCPUのL1キャッシュに相当する希少資源です。効用は単調増加しません。一定量を超えると無関連トークンが注意メカニズムを希釈し、重要情報の中盤埋没（lost in the middle）が発生します。症状としては、リポジトリ全体や長い会話履歴の丸ごと注入、全ツール定義の毎回ロード、「なぜか前に読んだはずの情報を無視する」といった現象が現れます。 📋 シナリオ ・issue-to-PRエージェントに、issueの内容だけでなくリポジトリ全体のREADME・設定ファイル・過去のPR履歴をすべて注入している。エージェントは肝心のissueの要点を見落とし、無関係なファイルを編集し始める。 ・マイグレーションエージェントに数千ファイルの情報を一度に渡し、コンテキストが溢れてエージェントが途中で一貫性を失う。 ・ペアプログラミングで、開いていないファイルや過去の長い会話履歴がコンテキストを圧迫し、レスポンスが遅くなる。 🛡 回避方法 ・コンテキストの使用量をカテゴリ別に計測し、メモリプロファイラのように配分を可視化します ・取得はpull既定（エージェント自身に必要な情報を取りに行かせる）とし、push（強制注入）は破ると致命的な不変条件だけに絞ります ・会話履歴は古いターンから要約・圧縮し、ツール定義は現在のタスクに必要なものだけを動的にロードします ・「全部入れれば安心」という思考に気づいたら、それがこのアンチパターンのサインだと認識してください #HarnessEngineering# #AIAgent#

ハーネスエンジニアリングのアンチパターン AP10. 観測なきブラックボックス（The Unobservable Black Box） 🎯 ポイント 失敗の原因がモデルか、プロンプトか、ツールか、コンテキストか、環境か——誰にも切り分けられない。改善が迷信と勘で行われるハーネスは、改善不能です。 ❗ 発生する課題 失敗をサブシステムに帰属できないため、何を直すべきかが分かりません。改善が迷信と勘で行われ、ハーネスの振り返りループが回らなくなります。単一指標だけを追う「指標モノカルチャー」と結びつくと、測定されていない品質が静かに犠牲になります。 🔍 メカニズムと症状 可観測性は地味なインフラ作業であり、エージェントは「だいたい動く」ため、このアンチパターンは後回しにされがちです。しかし、サブシステムに失敗を帰属できなければ、振り返りループが回せず、ハーネスは改善不能になります。さらに、単一指標（例：成功率だけ）を追うと、測られていない美徳（レビュー時間・リグレッション率・コードの保守性）が静かに犠牲になる「指標モノカルチャー」が発生します。症状としては、「なぜ失敗したか分からない」が頻発する、改善施策が「プロンプトをいじる」一辺倒になる、モデルの問題かハーネスの問題か区別がつかない、成功率は上がっているのにレビュアーの不満が増える、といった現象が見られます。 📋 シナリオ ・エージェントがタスクに失敗するが、原因がモデルの推論ミスか、コンテキストの不足か、ツールのバグか、環境の問題か誰にも分からない。チームは「プロンプトをもう少し詳しくしよう」と対症療法を繰り返す。 ・成功率を唯一の指標として追跡。成功率は80%に向上したが、成功した案件のレビュー時間が3倍に膨れ上がっていることに気づかない。 ・モデルをアップグレードしたが性能が変わらない。原因がモデルの問題なのか、ハーネスの足場が制約しているのか（AP3）切り分けられず、投資判断が迷信になる。 🛡 回避方法 ・決定・ツール呼び出し・コンテキスト変遷をトレースし、7サブシステム（知覚・行為・フィードバック・制御・記憶・ガードレール・インターフェース）に帰属可能化します ・単一指標でなく束で測定します（成功率・介入率・手戻り率・リグレッション率・コスト・レビュー時間・確信度の較正） ・モデルを固定してハーネスの変更をA/Bテストし、改善をハーネスに帰属させます ・ハーネスの可観測性を「地味だが不可欠なインフラ」として投資し、改善ループの基盤を整えてください #HarnessEngineering# #AIAgent#

ハーネスエンジニアリングのプラクティス P4. サブエージェントは「蒸留器」として契約する 🎯 ポイント サブエージェントが50ファイルの生ログを親に返したら、親のコンテキストは即死します。返すべきは「議事録」ではなく「結論」です。 📝 概要 探索用サブエージェントの契約を「結論を返す、議事録は返さない」と定義します。50ファイル探索して5行の所見を返す。これは礼儀ではなく、文脈階層のメモリ管理規律です。 🔍 解説 サブエージェントを使う主な目的は、親エージェントのコンテキストウィンドウを守ることです。しかし、サブエージェントが生の探索結果をそのまま返してしまうと、その目的は完全に失われます。サブエージェントは「蒸留器」として機能すべきです。大量の情報を読み込み、本質だけを凝縮して返す。この契約を明示的にプロンプトで定義し、返答のフォーマットも制約することで、文脈階層全体の効率が保たれます。安価なモデルで広く探索し、高価なモデルで深く判断する、というトークン経済の原則とも合致します。 🛠 実践方法 ・サブエージェントのプロンプトに「結論を返す、議事録は返さない」と明記し、返答フォーマット（行数上限・構造）を制約します ・探索タスクには安価なモデルを使い、親エージェントの判断には高価なモデルを使うトークン経済を設計します ・サブエージェントの返答サイズを監視し、閾値を超えた場合は再蒸留を要求するガードを設けます ・蒸留の粒度をタスクに応じて調整します（分類タスクなら3行、分析タスクなら10行など） 💼 ユースケース ・大規模コードベースの調査で、複数のサブエージェントにファイル群を分担探索させ、各々が要約のみ返す場面 ・マイグレーションで、各ユニットの状況を調査するサブエージェントが「移行可／要手動対応／不明」の3分類だけを返す場面 ・インシデント対応で、ログ・メトリクス・トレースを別々のサブエージェントが調査し、相関する異常の要約だけを返す場面 ⚠ 落とし穴 サブエージェントの蒸留品質が低いと、重要な情報が失われるリスクがあります。「結論だけ返せ」と指示しても、何が結論に値するかの判断はモデルの能力に依存します。また、蒸留の過程で文脈が失われすぎると、親エージェントが誤った判断をする可能性もあります。蒸留の粒度は、タスクの性質に応じて調整が必要です。 #HarnessEngineering# #AIAgent#

ループエンジニアリングあたりから想像を膨らませてたのだが、将来のAIシステムは、単体の何かではなく「AIが有機的に作用しあう組織」になってくのかなあ コンテキスト集約プラットフォームとしてGoogle Workspace、MS365、あるいはNotionなどがいて、 その上で、営業AI、法務AI、開発AIのような業務特化エージェントが連携しながら勝手に動く（A2Aプロトコルとかあるしね） そして、人間組織がフェーズや事業ごとに形が違うように、AI構成も色々あるのだろう。事業初期はジェネラリストAIみたいなのが活躍するし、成熟してくると分解した業務に向いたAIが必要とされるかも そうしたら、色んなAIベンダーが群雄割拠するのかな、そうなるといいな〜〜

ハーネスエンジニアリングは「モデルを包む器」を作る技術。 本番グレードのハーネスは、だいたい5層でできてる。 ・ツールの呼び出し制御 ・検証ループ ・コンテキストとメモリ ・ガードレール ・可観測性 モデルが同じでも、この作り込みで信頼性が決まる。

ハーネスエンジニアリングのプラクティス P12. 意味的サーキットブレーカーと「文脈ごと捨てる」リスタート 🎯 ポイント 同じエラーを3回繰り返すエージェント、見たことがありますか？「押し通す」より「教訓つき仕切り直し」の方が圧倒的に速いです。 📝 概要 単なる最大反復数ではなく、「同じエラーが二度」「二つの編集を振動」「正味の進捗なし」を意味的に検出して停止します。行き詰まったら、汚染された文脈でこね続けず、最後の正常チェックポイントへロールバックし、失敗の経緯を文脈から捨て、一行の教訓だけ携えて別アプローチで再起動します。 🔍 解説 エージェントが行き詰まったとき、最も非効率な対応は「同じ文脈でもう少し頑張る」ことです。失敗の経緯がコンテキストに蓄積すると、エージェントはそれに引きずられて同じ轍を踏みやすくなります。意味的サーキットブレーカーは、単なる反復回数制限ではなく、「進捗があるか」を実質的に判定します。振動（AをBに変えてまたAに戻す）や同一エラーの反復を検出したら、gitで最後の正常状態にロールバックし、新しい文脈で「前回はXで失敗した。別のアプローチを試す」という一行の教訓だけを持って再起動します。gitはエージェントのUndoです。 🛠 実践方法 ・エラーメッセージやテスト結果を比較し、「同じエラーが2回」「編集のAB振動」を検出するロジックをハーネスに実装します ・停止時にgit checkoutで最後のクリーンなコミットにロールバックし、汚染された文脈を破棄します ・リスタート時に「前回はXで失敗した」という一行の教訓だけを新しい文脈に持ち込みます ・サーキットブレーカーの閾値をタスクの難易度に応じて調整します（簡単なタスクは厳しく、難しいタスクは余裕を持たせる） 💼 ユースケース ・issue-to-PRエージェントが同じテスト失敗を修正できずループする場面 ・コンパイルエラーの修正で、修正→別のエラー→戻す→の繰り返しを検出する場面 ・レガシーコード改修で、アプローチの根本的な変更が必要だと判断する場面 ⚠ 落とし穴 サーキットブレーカーが敏感すぎると、あと一歩で解決するところで打ち切ってしまいます。逆に鈍感すぎると、コストを浪費するだけの無限ループになります。「進捗」の定義をタスクに合わせて調整することが重要です。また、リスタート時に教訓を正確に蒸留することも難しく、間違った教訓を持って再起動すると、別の失敗パターンに陥ることがあります。 #HarnessEngineering# #AIAgent#

ハーネスエンジニアリングのプラクティス P10. 二相設計 —— 読み取り専用の探索 → 実装 🎯 ポイント 「まず理解してから書く」は人間の美徳です。エージェントにも同じ規律を、願望ではなく権限で強制しましょう。 📝 概要 まず書き込み禁止の探索フェーズを強制し、計画を出させてから実装フェーズに入ります。早すぎる編集を構造的に防ぐことで、計画の質が上がります。フェーズ境界は願望ではなくハーネスが権限で強制します。 🔍 解説 エージェントは「とりあえず書いてみる」傾向があります。コードの全体像を把握する前にファイルを編集し始め、後から「そもそもアプローチが間違っていた」と気づいて大幅な手戻りが発生する、というパターンは非常に多いです。二相設計では、最初のフェーズでファイル読み・検索・シンボル解決のみを許可し、編集ツールを無効化します。エージェントはコードベースを探索し、理解し、計画を立てることだけに集中します。計画が承認されて初めて編集権限が解放されます。これにより「思いつきで書いて壊す」リスクを構造的に排除できます。 🛠 実践方法 ・フェーズ1では編集ツールを無効化し、ファイル読み・検索・シンボル解決のみを許可するツールセットを設定します ・フェーズ1の出力として計画ファイル（plan.md）を要求し、計画の承認をフェーズ2への移行条件にします ・フェーズ境界はプロンプトのお願いではなく、ツールの権限レベルで強制します ・探索フェーズの時間・ステップ数に上限を設け、コンテキスト枯渇を防ぎます 💼 ユースケース ・issue-to-PRエージェントで、issueの分析と計画策定を読み取り専用で行い、計画承認後に実装に入る場面 ・レガシーコード改修で、まずモジュール地図化と理解を行い、その後に変更を加える場面 ・インシデント対応で、診断（読み取り・安全・自律）と是正（書き込み・ゲート付き）を分離する場面 ⚠ 落とし穴 探索フェーズが長すぎると、エージェントがコンテキストウィンドウを使い切ってしまいます。また、探索フェーズで得た知識が実装フェーズまでに陳腐化するリスクもあります（P3のTTLと組み合わせる）。フェーズ境界を「プロンプトでお願いする」だけでは不十分で、ツールの権限レベルで強制することが重要です。 #HarnessEngineering# #AIAgent#