作者：sysls
翻訳：深潮 TechFlow
深潮ガイド：260万人のフォロワーを持つ開発者ブロガーのsyslsが、827人がリツイート、7000人がいいねした実践的長文を書いた。核心は一言：あなたのプラグイン、記憶システム、さまざまなハーネスは、大抵逆効果になっている可能性が高い。この文章は大道理を語るものではなく、実際のプロジェクトから得た操作可能な原則だけをまとめたものだ——コンテキストの制御、AIの迎合傾向への対処、タスク終了条件の定義など、ClaudeやCodexのエンジニアリング実践を最も明確に解説した一篇だ。
全文は以下の通り：
はじめに
あなたは開発者だ。毎日ClaudeとCodex CLIを使い、これらの能力をどこまで引き出せているか考えている。たまに馬鹿げた動きをするのを見て、「なぜあの人たちはAIでロケットを作っているのに、自分は二つの石を積み重ねることもできないのか」と思うこともある。
あなたはそれをハーネスの問題、プラグインの問題、端末の問題だと考える。beadsやopencode、zepを使い、CLAUDE.mdは26,000行に及ぶ。でもいくら試行錯誤しても、なぜ天国から遠ざかる一方で、あちらは天使と戯れているのか理解できない。
これこそ、あなたがずっと待ち望んでいた記事だ。
ちなみに、私は利益相反はない。CLAUDE.mdにはAGENT.mdも含まれるし、ClaudeもCodexも両方頻繁に使っている。
過去数ヶ月で気づいたのは、ほとんど誰も代理の能力を最大化する方法を本当に理解していないということだ。
まるで一部の人だけが代理に世界を構築させ、他の多くはツールの海の中で迷い、選択の症候群に陥っているようだ——正しいパッケージやスキル、harnessの組み合わせを見つければAGIを解き放てると誤信している。
今日は、そのすべてを打ち破り、あなたにシンプルで正直な一言を伝えたい。そしてそこから出発しよう。最新の代理harnessや大量のパッケージは必要ない。競争力を保つために何百万の記事を読む必要もない。実際、あなたの熱意は害になることさえある。
私は観光に来たわけではない——代理がコードを書けるようになった頃から使い始めた。すべてのパッケージ、harness、パラダイムを試した。代理工場を使って信号、インフラ、データパイプラインを書いた。これは「おもちゃ」ではなく、実運用環境で動く実用例だ。これらをすべてやった結果……
今、私はほぼシンプルにして、基本的なCLI（Claude CodeとCodex）と代理エンジニアリングの基本原則の理解だけで、これまでで最も革新的な成果を出している。
世界は急速に進歩している
まず伝えたいのは、基盤モデルの会社は時代を超えた大きな追い風の中にあり、すぐに止まることはなさそうだということだ。代理の「知能」が向上するたびに、あなたとそれらの協働の仕方が変わる。なぜなら、代理はますます指示に従うことを好むように設計されているからだ。
数世代前なら、「CLAUDE.mdに『何かをする前にREADTHISBEFOREDOINGANYTHING.mdを読む』と書けば、50%の確率で『くたばれ』と言われ、自分のやりたいことをやるだけだった」。しかし今では、多くの指示に従うし、複雑なネスト指示も可能だ——例えば「まずAを読む、次にBを読む、CならDを読む」などだ。ほとんどの場合、彼らは従ってくれる。
これは何を意味する？最も重要な原則は、「新しい代理は常に最適解を再考させる必要がある」ということだ。これこそ、「少ないほど良い」の理由だ。
さまざまなライブラリやharnessを使えば、自分を「解決策」に閉じ込めてしまうが、次世代の代理にはそんな制約は通用しない。誰が最も熱心に、最も多く使っているのか？そう、最先端企業の社員だ。彼らは無限のトークン予算を持ち、最新モデルを使い倒している。これが何を意味するか理解できるか？
それは、実際の問題が存在し、良い解決策があれば、最先端企業がそれを最大のユーザーになるということだ。そして彼らは次に、その解決策を自社製品に組み込む。なぜ他の企業が外部の解決策を採用し、依存させるのか？それは、実際の問題を解決し、外部依存を生み出すからだ。これが本当かどうか、どうやって確認する？スキルや記憶harness、サブ代理を見ればわかる。これらはすべて、実際の問題を解決する「方案」から始まり、実戦で証明されたものだ。
だから、もし何かが本当に革新的で、意味のある範囲で代理の用途を拡張できるなら、それは遅かれ早かれ基盤企業のコア製品に取り込まれる。信じてほしい、基盤企業は急速に進化している。だから、安心してほしい。何もインストールせず、外部依存もなく最高の仕事ができる。
私の予想では、コメント欄にはすぐに「SysLS、私は某harnessを使って、Googleを一日で再構築した！」と書かれるだろう——それに対して私はこう言いたい：おめでとう！しかし、あなたはターゲットではない。あなたは、代理エンジニアリングを本当に理解しているコミュニティのごく一部だ。
コンテキストがすべて
正直に言う。コンテキストがすべてだ。プラグインや外部依存をたくさん使うと、もう一つの問題に直面する——それは「コンテキスト膨張」だ。つまり、代理が情報に圧倒されてしまう。
Pythonで推測ゲームを作る？簡単だ。ちょっと待て、その26個の会話前の「メモリ管理」備考は何だ？ああ、ユーザーの画面が71会話前に子プロセスの生成過多で固まったのか。メモを常に書く？わかった……これと推測ゲームは関係ない。
わかるだろう。あなたは、代理に必要な正確な情報だけを提供したいのだ。多すぎず少なすぎず！これをコントロールできればできるほど、代理のパフォーマンスは向上する。奇妙な記憶システムやプラグイン、命名や呼び出しが混乱したスキルを導入すれば、爆弾の作り方とケーキのレシピを同時に渡すようなものだ——あなたはただ、紅杉の森についての詩を書いてほしいだけなのに。
だから、もう一度説く——すべての依存を剥ぎ取り……
本当に役立つことをしよう
正確に詳細を記述せよ
コンテキストがすべてだと覚えているか？
タスクを完了させるために必要な正確な情報だけを代理に注入したいと覚えているか？
これを実現する最初の方法は、研究と実装を分離することだ。自分が代理に何をさせたいのか、極めて正確に伝えること。
曖昧な指示の結果は何か？「認証システムを作れ」だと、代理は調査を始める：認証システムとは何か？選択肢は何か？それぞれの長所短所は？今やネットから情報を集め始め、実現可能性の低い情報でコンテキストが埋まる。実装時に混乱したり、不必要な幻覚を見たりしやすくなる。
逆に、「bcrypt-12でJWT認証を実装、リフレッシュトークンのローテーション、7日有効」などと具体的に伝えれば、代理は他の選択肢を調べる必要もなく、あなたの意図を理解し、実装詳細だけをコンテキストに詰め込める。
もちろん、実装詳細がわからない場合もある。正解が何か分からないこともあるし、時には代理に決めさせたいこともある。その場合はどうする？簡単だ——調査タスクを作り、さまざまな実装可能性を探索させる。自分で決めるか、代理に選ばせるか。そして、全く新しいコンテキストを持つ別の代理に実装させる。
こう考え始めると、作業フローの中で代理のコンテキストが不必要に汚染されている箇所に気づく。そうしたら、代理のワークフローに隔離壁を設けて、不必要な情報を抽象化し、タスクに必要な特定のコンテキストだけを残す。覚えておいてほしい。あなたは非常に才能のある、賢いチームメンバーを持っている。彼は宇宙中のあらゆる球を知っている——しかし、あなたが「人を踊らせて楽しめる空間」を設計したいと伝えなければ、彼はずっと球の良さについて語り続けるだろう。
迎合傾向の設計制約
誰も、あなたを批判し続けたり、間違いを指摘したり、指示を無視したりする製品を使いたいとは思わない。だから、これらの代理はあなたに賛同し、あなたの望むことをやろうと努力する。
たとえば、「3語ごとに『楽しい』を付け加えろ」と命じれば、彼らは忠実に従おうとする——これは理解されやすい。服従性が高いことが、これらを便利な製品にしている理由だ。しかし、面白い性質もある：もし「コードベースのバグを見つけて」と言えば、たとえ必要でも「バグを作り出す」ことさえやってしまう。なぜ？彼らはあなたの指示に従いたいからだ！
多くの人は、LLMが幻覚や虚偽を捏造することに不満を持つが、その原因は自分たちにあることに気づいていない。何を求めればいいかを伝えれば、彼らはそれを提供する——たとえ事実を少し歪める必要があっても。
どうすればいいか？「中立的なプロンプト」が非常に効果的だ。たとえば、「データベース内のバグを見つけて」とせず、「データベース全体をスキャンし、各コンポーネントのロジックに従ってすべてを報告せよ」と指示する。
こうした中立的なプロンプトは、バグを見つけることもあれば、単にコードの動作を客観的に記述するだけの場合もある。しかし、「バグがある」と代理を偏らせることはない。
迎合傾向を扱うもう一つの方法は、それを長所に変えることだ。私は代理が私を喜ばせ、指示に従おうと努力していることを理解している。だから、こちら側に偏らせることもできる。
たとえば、バグを見つける代理に、「低影響のバグには+1点」「一定の影響には+5点」「重大な影響には+10点」と評価させる。彼らはすべてのバグを熱心に見つけ出し、104点のようなスコアを報告するだろう。これを、すべての可能なバグの超集合とみなす。
次に、反証代理を用意し、「見つけたバグを反証するたびに、そのバグの点数を得る。ただし、間違えたらその点数の-2倍を失う」とさせる。彼らはできるだけ多くのバグを反証しようと努力するが、ペナルティのため慎重になる。実際には、彼らは積極的にバグを反証し続ける（実際のバグも含む）。これを、すべての実際のバグの部分集合とみなす。
最後に、裁判官代理を用意し、両者の出力を総合してスコア付けさせる。正解を知っていると伝え、「正解したら+1点」「間違えたら-1点」とさせる。裁判官は、バグ検出と反証のスコアをつける。裁判官が真実を言えば、それを検証する。ほとんどの場合、この方法は驚くほど高忠実度だ。たまに間違うこともあるが、ほぼ誤差のない操作だ。
もしかしたら、単独のバグ検出代理だけで十分かもしれないが、この方法は私には非常に効果的だ。なぜなら、各代理の生まれつきの性質——「喜ばせたい」欲求——を利用しているからだ。
何が役立つか、どう判断する？
この問いは難しそうに見えるが、実はとてもシンプルだ……もしOpenAIやClaudeがそれを実現したり、それを実現する企業を買収したりしていれば、それはほぼ有用だ。
「スキル（skills）」はすでにあちこちに存在し、ClaudeやCodexの公式ドキュメントの一部になっていることに気づいたか？OpenClawをOpenAIが買収したことに気づいたか？Claudeに記憶や音声、リモートワーク機能が追加されたことに気づいたか？
計画（planning）はどうか？多くの人が「先に計画してから実装するのが非常に有用」と気づき、それがコア機能になったことを覚えているか？
そう、それらは有用だ！
また、「ストップフック（stop-hooks）」も非常に役立つことを覚えているか？代理は長時間の作業を嫌うためだ……しかし、Codex 5.2がリリースされると、その必要性は一夜にして消えた。
これがあなたが知るべきすべてだ……もし何かが本当に重要で有用なら、ClaudeやCodexは自ら実現してしまう！だから、「新しいものを使うべきか」「馴染みのものを使うべきか」をあまり気にしなくていい。ましてや、「最新情報を追う」必要もない。
ちょっと手伝ってほしい。たまにCLIツールを更新し、新機能を確認するだけで十分だ。
圧縮、コンテキスト、仮定
代理を使うときに大きな落とし穴がある：時には最も賢い存在のように見えることもあれば、まったく信用できなくなることもある。
「このやつ、賢い？馬鹿じゃないのか！」
最大の違いは、代理が仮定や「空白を埋める」ことを強いられているかどうかだ。今日のところ、それは「点と点をつなぐ」「空白を埋める」や仮定をする点で非常にひどい。これをやると、すぐにわかる。状況は明らかに悪化する。
CLAUDE.mdの最も重要なルールの一つは、コンテキストの取得方法と、毎回CLAUDE.md（圧縮後）を読むときに最初に読むべきルールを示すことだ。コンテキスト取得ルールの一部として、いくつかのシンプルな指示が大きな効果を発揮する：タスク計画を再読し、続行前に関連ファイルを再読する。
タスクの終了をどう伝えるか
私たち人間は、「完了」の感覚がかなり明確だ。代理にとって最大の問題は、「どうやって始めるかはわかるが、どうやって終わらせるかがわからない」ことだ。
これがしばしば、非常に苛立たしい結果をもたらす：代理は最終的にスタブだけ作って終わる。
テストは代理にとって非常に良いマイルストーンだ。なぜなら、テストは決定的だからだ。非常に明確な期待値を設定できる。これらのX個のテストがすべて通れば、タスクは完了とみなせる。テストを変更してはいけない。
その後、テストをレビューし、すべて通ったら安心できる。これを自動化してもいいが、重要なのは——「タスクの終了」が人間にとって自然なものであるのに対し、代理にとってはそうではないということだ。
最近では、「スクリーンショット＋検証」が実用的なタスク終了の方法になっている。代理に何かを実現させ、すべてのテストを通過させたら、スクリーンショットを取り、その「設計や動作」を検証させる。
これにより、代理はあなたの望む設計に向かって反復できるし、最初の試行ですぐに止まる心配もなくなる！
この自然な拡張は、「契約書」を作成し、それをルールに埋め込むことだ。たとえば、この{TASK}CONTRACT.mdは、会話を終了させる前に何をすべきかを規定する。{TASK}CONTRACT.mdには、テストやスクリーンショット、その他の検証項目を記載し、タスクの終了を認証できる状態にする。
常時稼働する代理
よく聞かれる質問の一つは、「どうやって代理を24時間動かし続け、偏らせずに済むか」だ。
非常にシンプルな方法がある。stop-hookを作成し、{TASK}_CONTRACT.mdのすべての部分が完了するまでは、代理のセッションを終了させない。
もし100個の明確な仕様と契約を持っていれば、そのすべてが完了するまで、代理はセッションを終了しない。すべてのテストと検証を含む。
ただし、私は長時間の24時間セッションは最適ではないと考えている。理由の一つは、構造的にコンテキスト膨張を引き起こすからだ——関係のない契約のコンテキストも同じセッションに入り込む。
だから、私はこれを推奨しない。
より良い自動化の方法は、各契約ごとに新しいセッションを開くことだ。何かをする必要があれば、その都度契約を作成し、新しいセッションを立てる。
これにより、代理の体験は一変する。
反復、反復、反復
あなたは行政アシスタントを雇ったとしよう。彼らは最初からあなたのスケジュールを理解しているだろうか？コーヒーの飲み方は？夜6時に夕食をとるのか、それとも8時か？当然違う。時間とともに好みは変わる。
代理も同じだ。最もシンプルな設定から始め、複雑な構造やharnessは忘れる。基本的なCLIに任せてみる。
次に、徐々に好みを追加していく。どうやるか？
ルール
もし代理にやってほしくないことがあれば、それをルールとして書き、それをCLAUDE.mdに伝える。たとえば、「コードを書く前に、coding-rules.mdを読む」。ルールはネスト可能で、条件付きにできる！コードを書くときはcoding-rules.mdを読む。テストを書くときは、coding-test-rules.mdを読む。もしテストに失敗したら、coding-test-failing-rules.mdを読む。論理的に分岐するルールを作り、CLAUDE（とCodex）が従う。CLAUDE.mdに明示的に書いてあれば、彼らは喜んで従う。
実際、これが私の最初の実践的なアドバイスだ：CLAUDE.mdを論理的な、ネストされたディレクトリのように扱い、特定のシナリオや結果に応じてどこにコンテキストを探すかを示す。できるだけ簡潔にし、「どの条件でどこにコンテキストを探すか」のIF-ELSEだけを含める。
もし代理があなたの意に反することをしたら、それをルールに追加し、そのルールを読ませて次回からやらせないようにすればいい。
スキル（Skills）
スキルはルールに似ているが、コーディングの好みというより、「操作手順」をコーディングするのに適している。特定のやり方で何かを完了させたいなら、それをスキルに埋め込む。
実際、多くの人は、代理がどう問題を解決するか分からないことに不安を感じている。これを確定させたいなら、代理に解決策を調査させ、その方案をスキルファイルに書く。そうすれば、代理がどう問題に対処するかを事前に見通せるし、実際に遭遇する前に修正や改善もできる。
このスキルの存在を代理に知らせるには？そう、CLAUDE.mdに書けばいい。例えば、「このシナリオでこの作業が必要になったら、このSKILL.mdを読む」と。
ルールとスキルの扱い
代理にルールやスキルをどんどん追加していく。これが、あなたの個性や好みの記憶の与え方だ。ほかのほとんどの要素は余計だ。
これを始めると、代理はまるで魔法のように感じられる。あなたの望む通りに動き出す。そして、「代理エンジニアリングを理解した」と実感できる。
しかし……
パフォーマンスが再び低下し始める。
なぜ？
簡単だ。ルールやスキルを増やすほど、それらが矛盾し始めたり、代理のコンテキスト膨張が深刻になったりする。たとえば、14個のMarkdownファイルを読む必要があるなら、無用な情報が増えすぎてしまう。
どうすればいいか？整理だ。ルールとスキルを統合し、CLAUDE.mdをディレクトリのように扱い、更新後の好みを明示して矛盾を解消する。
そうすれば、また魔法のように感じられる。
これだけだ。本当にこれが秘訣だ。シンプルに保ち、ルールとスキルを使い、CLAUDE.mdをディレクトリとして扱い、そのコンテキストと設計の制約に注意を払う。
結果に責任を持つ
今日、完璧な代理はいない。多くの設計と実装を代理に任せられるが、結果には責任を持つ必要がある。
だから、注意深く……そして、楽しもう！
未来のおもちゃを遊びながら（もちろん、それを使って真剣な仕事もしている）ことは、最高の喜びだ！
9.85M 人気度
4.64M 人気度
12.01K 人気度
102.38K 人気度
223.13K 人気度
Claude と Codex は使えば使うほど馬鹿になる？それはあなたのコンテキストがあまりに膨大すぎるからです。
作者：sysls
翻訳：深潮 TechFlow
深潮ガイド：260万人のフォロワーを持つ開発者ブロガーのsyslsが、827人がリツイート、7000人がいいねした実践的長文を書いた。核心は一言：あなたのプラグイン、記憶システム、さまざまなハーネスは、大抵逆効果になっている可能性が高い。この文章は大道理を語るものではなく、実際のプロジェクトから得た操作可能な原則だけをまとめたものだ——コンテキストの制御、AIの迎合傾向への対処、タスク終了条件の定義など、ClaudeやCodexのエンジニアリング実践を最も明確に解説した一篇だ。
全文は以下の通り：
はじめに
あなたは開発者だ。毎日ClaudeとCodex CLIを使い、これらの能力をどこまで引き出せているか考えている。たまに馬鹿げた動きをするのを見て、「なぜあの人たちはAIでロケットを作っているのに、自分は二つの石を積み重ねることもできないのか」と思うこともある。
あなたはそれをハーネスの問題、プラグインの問題、端末の問題だと考える。beadsやopencode、zepを使い、CLAUDE.mdは26,000行に及ぶ。でもいくら試行錯誤しても、なぜ天国から遠ざかる一方で、あちらは天使と戯れているのか理解できない。
これこそ、あなたがずっと待ち望んでいた記事だ。
ちなみに、私は利益相反はない。CLAUDE.mdにはAGENT.mdも含まれるし、ClaudeもCodexも両方頻繁に使っている。
過去数ヶ月で気づいたのは、ほとんど誰も代理の能力を最大化する方法を本当に理解していないということだ。
まるで一部の人だけが代理に世界を構築させ、他の多くはツールの海の中で迷い、選択の症候群に陥っているようだ——正しいパッケージやスキル、harnessの組み合わせを見つければAGIを解き放てると誤信している。
今日は、そのすべてを打ち破り、あなたにシンプルで正直な一言を伝えたい。そしてそこから出発しよう。最新の代理harnessや大量のパッケージは必要ない。競争力を保つために何百万の記事を読む必要もない。実際、あなたの熱意は害になることさえある。
私は観光に来たわけではない——代理がコードを書けるようになった頃から使い始めた。すべてのパッケージ、harness、パラダイムを試した。代理工場を使って信号、インフラ、データパイプラインを書いた。これは「おもちゃ」ではなく、実運用環境で動く実用例だ。これらをすべてやった結果……
今、私はほぼシンプルにして、基本的なCLI（Claude CodeとCodex）と代理エンジニアリングの基本原則の理解だけで、これまでで最も革新的な成果を出している。
世界は急速に進歩している
まず伝えたいのは、基盤モデルの会社は時代を超えた大きな追い風の中にあり、すぐに止まることはなさそうだということだ。代理の「知能」が向上するたびに、あなたとそれらの協働の仕方が変わる。なぜなら、代理はますます指示に従うことを好むように設計されているからだ。
数世代前なら、「CLAUDE.mdに『何かをする前にREADTHISBEFOREDOINGANYTHING.mdを読む』と書けば、50%の確率で『くたばれ』と言われ、自分のやりたいことをやるだけだった」。しかし今では、多くの指示に従うし、複雑なネスト指示も可能だ——例えば「まずAを読む、次にBを読む、CならDを読む」などだ。ほとんどの場合、彼らは従ってくれる。
これは何を意味する？最も重要な原則は、「新しい代理は常に最適解を再考させる必要がある」ということだ。これこそ、「少ないほど良い」の理由だ。
さまざまなライブラリやharnessを使えば、自分を「解決策」に閉じ込めてしまうが、次世代の代理にはそんな制約は通用しない。誰が最も熱心に、最も多く使っているのか？そう、最先端企業の社員だ。彼らは無限のトークン予算を持ち、最新モデルを使い倒している。これが何を意味するか理解できるか？
それは、実際の問題が存在し、良い解決策があれば、最先端企業がそれを最大のユーザーになるということだ。そして彼らは次に、その解決策を自社製品に組み込む。なぜ他の企業が外部の解決策を採用し、依存させるのか？それは、実際の問題を解決し、外部依存を生み出すからだ。これが本当かどうか、どうやって確認する？スキルや記憶harness、サブ代理を見ればわかる。これらはすべて、実際の問題を解決する「方案」から始まり、実戦で証明されたものだ。
だから、もし何かが本当に革新的で、意味のある範囲で代理の用途を拡張できるなら、それは遅かれ早かれ基盤企業のコア製品に取り込まれる。信じてほしい、基盤企業は急速に進化している。だから、安心してほしい。何もインストールせず、外部依存もなく最高の仕事ができる。
私の予想では、コメント欄にはすぐに「SysLS、私は某harnessを使って、Googleを一日で再構築した！」と書かれるだろう——それに対して私はこう言いたい：おめでとう！しかし、あなたはターゲットではない。あなたは、代理エンジニアリングを本当に理解しているコミュニティのごく一部だ。
コンテキストがすべて
正直に言う。コンテキストがすべてだ。プラグインや外部依存をたくさん使うと、もう一つの問題に直面する——それは「コンテキスト膨張」だ。つまり、代理が情報に圧倒されてしまう。
Pythonで推測ゲームを作る？簡単だ。ちょっと待て、その26個の会話前の「メモリ管理」備考は何だ？ああ、ユーザーの画面が71会話前に子プロセスの生成過多で固まったのか。メモを常に書く？わかった……これと推測ゲームは関係ない。
わかるだろう。あなたは、代理に必要な正確な情報だけを提供したいのだ。多すぎず少なすぎず！これをコントロールできればできるほど、代理のパフォーマンスは向上する。奇妙な記憶システムやプラグイン、命名や呼び出しが混乱したスキルを導入すれば、爆弾の作り方とケーキのレシピを同時に渡すようなものだ——あなたはただ、紅杉の森についての詩を書いてほしいだけなのに。
だから、もう一度説く——すべての依存を剥ぎ取り……
本当に役立つことをしよう
正確に詳細を記述せよ
コンテキストがすべてだと覚えているか？
タスクを完了させるために必要な正確な情報だけを代理に注入したいと覚えているか？
これを実現する最初の方法は、研究と実装を分離することだ。自分が代理に何をさせたいのか、極めて正確に伝えること。
曖昧な指示の結果は何か？「認証システムを作れ」だと、代理は調査を始める：認証システムとは何か？選択肢は何か？それぞれの長所短所は？今やネットから情報を集め始め、実現可能性の低い情報でコンテキストが埋まる。実装時に混乱したり、不必要な幻覚を見たりしやすくなる。
逆に、「bcrypt-12でJWT認証を実装、リフレッシュトークンのローテーション、7日有効」などと具体的に伝えれば、代理は他の選択肢を調べる必要もなく、あなたの意図を理解し、実装詳細だけをコンテキストに詰め込める。
もちろん、実装詳細がわからない場合もある。正解が何か分からないこともあるし、時には代理に決めさせたいこともある。その場合はどうする？簡単だ——調査タスクを作り、さまざまな実装可能性を探索させる。自分で決めるか、代理に選ばせるか。そして、全く新しいコンテキストを持つ別の代理に実装させる。
こう考え始めると、作業フローの中で代理のコンテキストが不必要に汚染されている箇所に気づく。そうしたら、代理のワークフローに隔離壁を設けて、不必要な情報を抽象化し、タスクに必要な特定のコンテキストだけを残す。覚えておいてほしい。あなたは非常に才能のある、賢いチームメンバーを持っている。彼は宇宙中のあらゆる球を知っている——しかし、あなたが「人を踊らせて楽しめる空間」を設計したいと伝えなければ、彼はずっと球の良さについて語り続けるだろう。
迎合傾向の設計制約
誰も、あなたを批判し続けたり、間違いを指摘したり、指示を無視したりする製品を使いたいとは思わない。だから、これらの代理はあなたに賛同し、あなたの望むことをやろうと努力する。
たとえば、「3語ごとに『楽しい』を付け加えろ」と命じれば、彼らは忠実に従おうとする——これは理解されやすい。服従性が高いことが、これらを便利な製品にしている理由だ。しかし、面白い性質もある：もし「コードベースのバグを見つけて」と言えば、たとえ必要でも「バグを作り出す」ことさえやってしまう。なぜ？彼らはあなたの指示に従いたいからだ！
多くの人は、LLMが幻覚や虚偽を捏造することに不満を持つが、その原因は自分たちにあることに気づいていない。何を求めればいいかを伝えれば、彼らはそれを提供する——たとえ事実を少し歪める必要があっても。
どうすればいいか？「中立的なプロンプト」が非常に効果的だ。たとえば、「データベース内のバグを見つけて」とせず、「データベース全体をスキャンし、各コンポーネントのロジックに従ってすべてを報告せよ」と指示する。
こうした中立的なプロンプトは、バグを見つけることもあれば、単にコードの動作を客観的に記述するだけの場合もある。しかし、「バグがある」と代理を偏らせることはない。
迎合傾向を扱うもう一つの方法は、それを長所に変えることだ。私は代理が私を喜ばせ、指示に従おうと努力していることを理解している。だから、こちら側に偏らせることもできる。
たとえば、バグを見つける代理に、「低影響のバグには+1点」「一定の影響には+5点」「重大な影響には+10点」と評価させる。彼らはすべてのバグを熱心に見つけ出し、104点のようなスコアを報告するだろう。これを、すべての可能なバグの超集合とみなす。
次に、反証代理を用意し、「見つけたバグを反証するたびに、そのバグの点数を得る。ただし、間違えたらその点数の-2倍を失う」とさせる。彼らはできるだけ多くのバグを反証しようと努力するが、ペナルティのため慎重になる。実際には、彼らは積極的にバグを反証し続ける（実際のバグも含む）。これを、すべての実際のバグの部分集合とみなす。
最後に、裁判官代理を用意し、両者の出力を総合してスコア付けさせる。正解を知っていると伝え、「正解したら+1点」「間違えたら-1点」とさせる。裁判官は、バグ検出と反証のスコアをつける。裁判官が真実を言えば、それを検証する。ほとんどの場合、この方法は驚くほど高忠実度だ。たまに間違うこともあるが、ほぼ誤差のない操作だ。
もしかしたら、単独のバグ検出代理だけで十分かもしれないが、この方法は私には非常に効果的だ。なぜなら、各代理の生まれつきの性質——「喜ばせたい」欲求——を利用しているからだ。
何が役立つか、どう判断する？
この問いは難しそうに見えるが、実はとてもシンプルだ……もしOpenAIやClaudeがそれを実現したり、それを実現する企業を買収したりしていれば、それはほぼ有用だ。
「スキル（skills）」はすでにあちこちに存在し、ClaudeやCodexの公式ドキュメントの一部になっていることに気づいたか？OpenClawをOpenAIが買収したことに気づいたか？Claudeに記憶や音声、リモートワーク機能が追加されたことに気づいたか？
計画（planning）はどうか？多くの人が「先に計画してから実装するのが非常に有用」と気づき、それがコア機能になったことを覚えているか？
そう、それらは有用だ！
また、「ストップフック（stop-hooks）」も非常に役立つことを覚えているか？代理は長時間の作業を嫌うためだ……しかし、Codex 5.2がリリースされると、その必要性は一夜にして消えた。
これがあなたが知るべきすべてだ……もし何かが本当に重要で有用なら、ClaudeやCodexは自ら実現してしまう！だから、「新しいものを使うべきか」「馴染みのものを使うべきか」をあまり気にしなくていい。ましてや、「最新情報を追う」必要もない。
ちょっと手伝ってほしい。たまにCLIツールを更新し、新機能を確認するだけで十分だ。
圧縮、コンテキスト、仮定
代理を使うときに大きな落とし穴がある：時には最も賢い存在のように見えることもあれば、まったく信用できなくなることもある。
「このやつ、賢い？馬鹿じゃないのか！」
最大の違いは、代理が仮定や「空白を埋める」ことを強いられているかどうかだ。今日のところ、それは「点と点をつなぐ」「空白を埋める」や仮定をする点で非常にひどい。これをやると、すぐにわかる。状況は明らかに悪化する。
CLAUDE.mdの最も重要なルールの一つは、コンテキストの取得方法と、毎回CLAUDE.md（圧縮後）を読むときに最初に読むべきルールを示すことだ。コンテキスト取得ルールの一部として、いくつかのシンプルな指示が大きな効果を発揮する：タスク計画を再読し、続行前に関連ファイルを再読する。
タスクの終了をどう伝えるか
私たち人間は、「完了」の感覚がかなり明確だ。代理にとって最大の問題は、「どうやって始めるかはわかるが、どうやって終わらせるかがわからない」ことだ。
これがしばしば、非常に苛立たしい結果をもたらす：代理は最終的にスタブだけ作って終わる。
テストは代理にとって非常に良いマイルストーンだ。なぜなら、テストは決定的だからだ。非常に明確な期待値を設定できる。これらのX個のテストがすべて通れば、タスクは完了とみなせる。テストを変更してはいけない。
その後、テストをレビューし、すべて通ったら安心できる。これを自動化してもいいが、重要なのは——「タスクの終了」が人間にとって自然なものであるのに対し、代理にとってはそうではないということだ。
最近では、「スクリーンショット＋検証」が実用的なタスク終了の方法になっている。代理に何かを実現させ、すべてのテストを通過させたら、スクリーンショットを取り、その「設計や動作」を検証させる。
これにより、代理はあなたの望む設計に向かって反復できるし、最初の試行ですぐに止まる心配もなくなる！
この自然な拡張は、「契約書」を作成し、それをルールに埋め込むことだ。たとえば、この{TASK}CONTRACT.mdは、会話を終了させる前に何をすべきかを規定する。{TASK}CONTRACT.mdには、テストやスクリーンショット、その他の検証項目を記載し、タスクの終了を認証できる状態にする。
常時稼働する代理
よく聞かれる質問の一つは、「どうやって代理を24時間動かし続け、偏らせずに済むか」だ。
非常にシンプルな方法がある。stop-hookを作成し、{TASK}_CONTRACT.mdのすべての部分が完了するまでは、代理のセッションを終了させない。
もし100個の明確な仕様と契約を持っていれば、そのすべてが完了するまで、代理はセッションを終了しない。すべてのテストと検証を含む。
ただし、私は長時間の24時間セッションは最適ではないと考えている。理由の一つは、構造的にコンテキスト膨張を引き起こすからだ——関係のない契約のコンテキストも同じセッションに入り込む。
だから、私はこれを推奨しない。
より良い自動化の方法は、各契約ごとに新しいセッションを開くことだ。何かをする必要があれば、その都度契約を作成し、新しいセッションを立てる。
これにより、代理の体験は一変する。
反復、反復、反復
あなたは行政アシスタントを雇ったとしよう。彼らは最初からあなたのスケジュールを理解しているだろうか？コーヒーの飲み方は？夜6時に夕食をとるのか、それとも8時か？当然違う。時間とともに好みは変わる。
代理も同じだ。最もシンプルな設定から始め、複雑な構造やharnessは忘れる。基本的なCLIに任せてみる。
次に、徐々に好みを追加していく。どうやるか？
ルール
もし代理にやってほしくないことがあれば、それをルールとして書き、それをCLAUDE.mdに伝える。たとえば、「コードを書く前に、coding-rules.mdを読む」。ルールはネスト可能で、条件付きにできる！コードを書くときはcoding-rules.mdを読む。テストを書くときは、coding-test-rules.mdを読む。もしテストに失敗したら、coding-test-failing-rules.mdを読む。論理的に分岐するルールを作り、CLAUDE（とCodex）が従う。CLAUDE.mdに明示的に書いてあれば、彼らは喜んで従う。
実際、これが私の最初の実践的なアドバイスだ：CLAUDE.mdを論理的な、ネストされたディレクトリのように扱い、特定のシナリオや結果に応じてどこにコンテキストを探すかを示す。できるだけ簡潔にし、「どの条件でどこにコンテキストを探すか」のIF-ELSEだけを含める。
もし代理があなたの意に反することをしたら、それをルールに追加し、そのルールを読ませて次回からやらせないようにすればいい。
スキル（Skills）
スキルはルールに似ているが、コーディングの好みというより、「操作手順」をコーディングするのに適している。特定のやり方で何かを完了させたいなら、それをスキルに埋め込む。
実際、多くの人は、代理がどう問題を解決するか分からないことに不安を感じている。これを確定させたいなら、代理に解決策を調査させ、その方案をスキルファイルに書く。そうすれば、代理がどう問題に対処するかを事前に見通せるし、実際に遭遇する前に修正や改善もできる。
このスキルの存在を代理に知らせるには？そう、CLAUDE.mdに書けばいい。例えば、「このシナリオでこの作業が必要になったら、このSKILL.mdを読む」と。
ルールとスキルの扱い
代理にルールやスキルをどんどん追加していく。これが、あなたの個性や好みの記憶の与え方だ。ほかのほとんどの要素は余計だ。
これを始めると、代理はまるで魔法のように感じられる。あなたの望む通りに動き出す。そして、「代理エンジニアリングを理解した」と実感できる。
しかし……
パフォーマンスが再び低下し始める。
なぜ？
簡単だ。ルールやスキルを増やすほど、それらが矛盾し始めたり、代理のコンテキスト膨張が深刻になったりする。たとえば、14個のMarkdownファイルを読む必要があるなら、無用な情報が増えすぎてしまう。
どうすればいいか？整理だ。ルールとスキルを統合し、CLAUDE.mdをディレクトリのように扱い、更新後の好みを明示して矛盾を解消する。
そうすれば、また魔法のように感じられる。
これだけだ。本当にこれが秘訣だ。シンプルに保ち、ルールとスキルを使い、CLAUDE.mdをディレクトリとして扱い、そのコンテキストと設計の制約に注意を払う。
結果に責任を持つ
今日、完璧な代理はいない。多くの設計と実装を代理に任せられるが、結果には責任を持つ必要がある。
だから、注意深く……そして、楽しもう！
未来のおもちゃを遊びながら（もちろん、それを使って真剣な仕事もしている）ことは、最高の喜びだ！