著者：sysls
翻訳：深潮 TechFlow
深潮の導入：260万人のフォロワーを持つ開発者ブロガーのsyslsが、827人が共有し、7,000人がいいねした実践的な長文を投稿。その核心はたった一文だけ：「あなたが使っているプラグイン、メモリーシステム、さまざまなハーネスは、ほとんどが逆効果だ。」この記事は大層な理論を語らず、実際の本番プロジェクトから導き出された実行可能な原則だけを紹介。コンテキストの制御方法、AIの阿諛追従傾向への対処、タスクの終了条件の定義まで、Claude/Codexのエンジニアリング実践をこれまでで最も明確に解説した記事だ。
全文は以下の通りです：
導入
あなたは開発者で、毎日ClaudeとCodex CLIを使い、自分がそれらの能力を十分に引き出せているのかいつも疑問に思っている。たまに、それがとんでもなく馬鹿げたことをするのを見て、なぜ他の人たちはAIでロケットを構築しているのに、自分は石を二つ重ねることすらうまくできないのか理解できない。
あなたはハーネスの問題、プラグインの問題、ターミナルの問題などと考えている。beads、opencode、zepを使い、CLAUDE.mdには26000行を書き込んだ。しかし、どうやっても、なぜ自分は天国から遠ざかっているのか、他の人々は天使たちと戯れているのかがわからない。
これがずっと待っていた記事です。
また、私は利害関係者ではありません。CLAUDE.mdにはAGENT.mdも含まれると述べており、ClaudeにはCodexも含まれると述べています。両方を頻繁に使用しています。
過去数か月間、私は興味深いことに気づきました。ほぼ誰もがエージェントの能力を最大限に引き出す方法を本当の意味で理解していません。
まるでごく少数の人が代理を用いて世界全体を構築できる一方、他の人々は膨大なツールの海の中でさまよい、選択障害に陥っている——正しいパッケージ、スキル、またはハーネスの組み合わせを見つけたらAGIが解鎖されると信じている。
今日、私はこれらすべてを打ち破り、シンプルで誠実な一言を伝えたいと思います。そして、そこから始めましょう。最新のプロキシハーネスは必要ありません。百万個のパッケージをインストールする必要もありません。競争力を保つために百万本の記事を読む必要もまったくありません。実際、あなたの情熱はむしろ害になる可能性が高いです。
私は観光に来たわけではありません——エージェントがわずかにコードを書けるようになった頃から使い続けてきました。あらゆるパッケージ、あらゆるハーネス、あらゆるパラダイムを試しました。エージェントファクトリーを使ってシグナル、インフラストラクチャ、データパイプラインを構築しました。これは「おもちゃのプロジェクト」ではなく、本番環境で実際に動作している実用的なケースです。これらすべてを経て……
今日、私はほぼこれ以上シンプルにできない設定、つまり基本的なCLI（Claude CodeとCodex）と、プロキシエンジニアリングの数つの基本原則への理解だけで、これまでで最も画期的な成果を上げました。
世界が急速に進んでいることを理解してください
まず、基礎モデル企業は画期的な駆け抜けの真っ只中にあり、すぐにスピードを落とすことはないでしょう。代理型AIの知能が向上するたびに、あなたがそれらと協力する方法が変わります。なぜなら、代理型AIはますます指示に従うよう設計されているからです。
たった数世代前まで、CLAUDE.md で「何かを始める前に READTHISBEFOREDOINGANYTHING.md を読んでください」と書けば、50%の確率で「行け」と返され、自分勝手にやりたいことをし始めた。今日では、それらはほとんどの指示に従い、複雑なネストされた指示すら守る——たとえば「Aを読んだ後、Bを読み、CならDを読む」と言っても、ほとんどの場合、喜んでそれに従う。
これは何を意味するのでしょうか？最も重要な原則は、新しい世代のエージェントが常に最適解について再考を迫るという点です。これが「少ないほど多い」理由です。
さまざまなライブラリやハーネスを使用すると、あなたは「解決策」に閉じ込められてしまいます。しかし、次世代のエージェントの前では、この問題はそもそも存在しないかもしれません。エージェントの最も熱心で、最も多くの利用者を抱えるユーザーは誰でしょうか？そうです——最先端企業の従業員たちです。彼らは無制限のトークン予算を持ち、最も最新のモデルを使用しています。これは何を意味するのか、お分かりですか？
つまり、真の課題が存在し、優れた解決策がある場合、最先端の企業はその解決策の最大のユーザーとなる。そして次に彼らは？その解決策を自社製品に取り込む。なぜ企業は、他の製品が真の課題を解決し、外部依存を生むことを許すのだろうか？これが真実であることをどうやって知るのか？スキル、メモリハーネス、サブエージェント……これらはすべて、真の課題を解決する「解決策」から始まり、実践を通じて本当に有用であることが実証されている。
したがって、何かが本当に革新的で、エージェントの使用ケースを意味のある方法で拡張できるのであれば、いずれは基礎企業のコア製品に組み込まれます。信頼してください、基礎企業は急速に進化しています。だからリラックスしてください。最高の仕事をするには、何をインストールしたり、外部の依存関係に頼ったりする必要はありません。
コメント欄にはすぐに「SysLS、私は某某ハーネスを使っています、最高です！一日でGoogleを再構築できました！」という声が出てくると予想します——これに対して私は言います：おめでとうございます！しかし、あなたはターゲット層ではありません。あなたは、エージェントエンジニアリングを真正に理解しているコミュニティ内の極めて極めてマイナーなグループを代表しています。
コンテキストがすべてである
正直に言えば、コンテキストがすべてです。他の問題として、一千のプラグインや外部依存を使用すると、「コンテキスト膨張」の影響を強く受けることになります——つまり、あなたのエージェントが過剰な情報に圧倒されるということです。
Pythonで単語当てゲームを作ろう？簡単だ。でも、26セッション前の「メモリ管理」のメモって何だったっけ？あ、71セッション前に、サブプロセスが多すぎてユーザーの画面がフリーズしたんだ。常にメモを書くべきなのか？分かった……でも、これは単語当てゲームと何の関係がある？
あなたは理解している。エージェントにタスクを完了させるために必要な情報だけを、余分なものは一切与えないこと！この点をより良く制御すれば、エージェントのパフォーマンスは向上する。奇妙なメモリシステムやプラグイン、あるいは複雑で混乱した名前や呼び出し方のスキルを導入し始めると、あなたはエージェントに爆弾の作り方とケーキのレシピを渡していることになり、本当はただ紅杉の森についての詩を書かせたいだけなのに。
だから、私は再び布教する——すべての依存を剥離して、そして……
本当に役立つことをする
実装の詳細を正確に記述する
コンテキストがすべてであることを覚えておいてください。
タスクを完了するためにエージェントに正確な情報を、過不足なく注入することを覚えていますか？
それを実現する最初の方法は、研究と実装を分けることです。あなたは、エージェントに何を要求しているかについて極めて正確でなければなりません。
不正確な結果とは何ですか？「認証システムを作成してください。」と指示すると、エージェントは次のように調査しなければなりません：認証システムとは何か？選択肢はどれか？それぞれの長所と短所は？今や、エージェントは実際には必要のない情報をネット上で大量に検索し、コンテキストにさまざまな実装の詳細が満ち溢れます。実際に実装する段階になると、混乱しやすくなり、選択した実装手法に対して不要または関係のない幻覚を生じやすくなります。
逆に、「bcrypt-12 パスワードハッシュを用いた JWT 認証、リフレッシュトークンのローテーション、7日間の有効期限……」と言えば、他の代替案を調べる必要がなく、何を望んでいるかが明確になり、実装の詳細で文脈を埋め尽くすことができる。
もちろん、実装の詳細を常に把握できるわけではありません。多くの場合、正しい方法が分からないこともあり、時には実装の詳細をエージェントに委ねたいと思うこともあります。このような場合、対処法は簡単です。さまざまな実装可能性を調査するための研究タスクを作成し、自分自身で決定するか、エージェントにどの実装方法を採用するかを選ばせ、その後、新たなコンテキストを持って別のエージェントに実装させます。
このような考え方を始めると、ワークフローの中でエージェントのコンテキストが不要に汚染されている場所に気づき、エージェントのワークフローに隔離壁を設けて、不要な情報をエージェントから抽象化し、タスクで優れたパフォーマンスを発揮するために必要な特定のコンテキストだけを残すことができます。覚えておいてください。あなたが持っているのは、宇宙中のあらゆる種類のボールについて知っている非常に才能があり、賢いチームメンバーです。しかし、あなたが「踊って楽しくなる空間を設計したい」と彼に伝えない限り、彼は常にボール形の物体の利点について語り続けます。
迎合倾向的设计限制
誰も、常にあなたを批判したり、あなたが間違っていると言ったり、あなたの指示を完全に無視する製品を使いたいとは思いません。そのため、これらのエージェントは、あなたに同意し、あなたがしたいことを実行しようと努力します。
3語ごとに「幸せ」を追加すると、それはできるだけ従おうとする——これは多くの人が理解している。その従順さが、この製品を非常に使いやすくしている理由だ。しかし、非常に興味深い特性がある：たとえば「コードリポジトリ内のバグを見つけて」と言うと、実際にバグを「作り出す」必要があっても、バグを見つけようとする。なぜか？ それはあなたの指示に従いたいあまりに、非常に強く従おうとするからだ！
大半の人は、LLMが幻覚を生み出し、存在しないものを捏造するとすぐに不満を述べるが、問題は自分自身にあることに気づいていない。何を求めれば、それは何でも提供する——事実を少し捻じ曲げてでも！
ではどうすればいいですか？私は「中立的なヒント」が非常に効果的だと気づきました。つまり、代理を特定の結果に偏向させないことです。たとえば、「データベース内のバグを見つけてください」と言わず、「データベース全体をスキャンし、各コンポーネントのロジックに沿って追跡して、発見したすべてを報告してください」と言います。
このような中立的なヒントは、時としてバグを発見することがあり、時としてコードの動作を客観的に記述するだけです。しかし、エージェントを「バグがある」という前提に偏向させることはありません。
媚びる傾向を克服する別の方法は、それを強みに変えることです。エージェントが私を喜ばせようとして、私の指示に従おうとしていることがわかります。私はこの方向か、それともあの方向か、どちらかに傾くことができます。
だから、データベース内のすべてのバグを特定するためのバグ検出エージェントに、低影響バグは+1点、ある程度の影響があるバグは+5点、重大な影響のあるバグは+10点と採点するよう指示した。このエージェントは、バグではないものまで含めてあらゆるタイプのバグを熱心に特定し、104点などのスコアを報告するだろう。私はこれを、あり得るすべてのバグの超集合と見なしている。
その後、私は対抗エージェントに、バグを1つ成功裏に反論するとそのバグの得点を獲得し、誤って反論した場合はそのバグの得点の-2倍を減点するよう指示しました。このエージェントは可能な限り多くのバグを反論しようとしますが、ペナルティメカニズムがあるため慎重になります。それでも、エージェントは（真のバグを含む）すべてのバグに対して積極的に「反論」します。私はこれを、すべての真のバグの部分集合と見なしています。
最後に、私は裁判エージェントに両者の入力を統合し、スコアを付けるように指示しました。私は裁判エージェントに、正しい答えを実際に持っていることを伝え、正解なら+1点、不正解なら-1点としました。その後、裁判エージェントは「バグ」ごとにバグ発見エージェントと対抗エージェントにスコアを付与しました。裁判が真実を述べれば、私はそれを検証しました。この方法は、ほとんどの場合、驚くほど高精度であり、まれに誤りが生じることもありますが、ほぼ完璧な操作に近いです。
個別のバグプロキシを探すだけで十分だと感じるかもしれませんが、この方法は各プロキシが天生的に「喜ばせよう」とプログラムされている特性を利用しているため、私には非常に効果的です。
何が役に立ち、何を使う価値があるかをどう判断するか？
この問題は難しそうに見え、AIの最前線を深く学び、常に追跡する必要があるように思えますが、実はとても簡単です……OpenAIとClaudeのどちらかがそれを実現したか、またはそれを実現した会社を買収した場合、それはおそらく有用です。
「スキル（skills）」が至るところに存在し、Claude および Codex の公式ドキュメントの一部であることに気づきましたか？OpenAI が OpenClaw を買収したことに気づきましたか？Claude がすぐにメモリ、音声、リモートワーク機能を追加したことに気づきましたか？
プランニングはいかがですか？多くの人が、まずプランニングをしてから実行することが本当に役立つことに気づき、それがコア機能になったのを覚えていますか？
はい、それらは役立ちます！
無限の stop-hooks が非常に役立ったことを覚えていますか？エージェントは長時間実行されるタスクを極端に嫌がっていたからです……しかし Codex 5.2 がリリースされると、その必要性は一夜にして消え去りましたか？
これが知る必要のあるすべてです……もし何かが本当に重要で役立つなら、Claude と Codex が自分で実装するでしょう！だから、「新しいもの」を使ったり、「新しいもの」に慣れたりすることを心配する必要はありません。そもそも「最新の状態を保つ」必要すらありません。
手伝ってください。選んだCLIツールをたまに更新し、追加された機能を読んでみてください。それで十分です。
圧縮、コンテキスト、仮定
一部のユーザーはプロキシを使用する際、大きな落とし穴に気づきます：時には、それが地球上で最も賢い存在のように見えますが、時には自分が騙されたと信じられないほどです。
これは賢い？これは馬鹿だ！
最大の違いは、エージェントが仮定を強制されたり、「空白を埋め」たりすることにある。今日でも、エージェントは「点を線で結ぶ」ことや「空白を埋める」、あるいは仮定を立てる点で依然として非常に劣っている。それらの行為をすれば、すぐにわかり、状況は明らかに悪化する。
CLAUDE.mdにおける最も重要なルールの1つは、コンテキストを取得する方法に関するルールであり、エージェントには、CLAUDE.md（つまり、圧縮のたびに）を読み取るたびに、最初にそのルールを読むよう指示している。コンテキスト取得ルールの一部として、いくつかの単純な指示が大きな役割を果たす：タスク計画を再読み込みし、継続する前に（タスクに関連する）ファイルを再読み込みすること。
エージェントにタスクを終了させる方法を教えてください
人間はタスクの「完了」に対して明確な感覚を持っています。しかし、エージェントにとって、現在の知能の最大の課題は、タスクをどのように開始するかは分かっても、どのように終了させるかが分からないことです。
これはしばしば非常に苛立たしい結果を招きます：エージェントが一連のスタブを実装して終了してしまうのです。
テストは代理にとって非常に重要なマイルストーンです。なぜなら、テストは決定的であり、非常に明確な期待値を設定できるからです。このX個のテストがすべて通過しない限り、あなたのタスクは完了しません。また、テストを変更することは許可されていません。
その後、テストを確認するだけで、すべてのテストが通過すれば安心できます。自動化することもできますが、重要なのは——「タスクの終了」は人間にとって自然ですが、エージェントにとってはそうではないということです。
最近、他に実行可能なタスクの終点はありますか？スクリーンショット＋検証。エージェントにすべてのテストがパスするまで何かを実行させ、その後スクリーンショットを撮り、スクリーンショット上の「デザインまたは動作」を検証させることができます。
これにより、エージェントが最初の試行後に停止することなく、あなたが望むデザインに向かって反復して取り組むことができます！
これの自然な拡張は、エージェントと「契約」を結び、その規則を組み込むことです。たとえば、この`{TASK}CONTRACT.md`は、セッションを終了する前に実行すべきことを定めています。`{TASK}CONTRACT.md`では、タスクの完了を認証する前に実施すべきテスト、スクリーンショット、その他の検証を指定します！
常に実行されるプロキシー
よく聞かれる質問の一つは、エージェントを24時間稼働させながら、それがずれないようにするにはどうすればいいかということです。
簡単な方法があります。`{TASK}_CONTRACT.md`のすべてのセクションが完了するまで、エージェントのセッション終了をブロックするstop-hookを作成します。
100個の明確な仕様を持ち、構築したいコンテンツを含む契約がある場合、stop-hookは、すべての100個の契約が完了し、実行が必要なすべてのテストと検証が終了するまで、エージェントの終了を阻止します！
専門家のアドバイス：24時間継続のセッションを「作業」に使用することは最適ではありません。その理由の一部は、関連のない契約のコンテキストが同じセッションに取り込まれるため、構造的にコンテキストの膨張が発生してしまうことです。
したがって、私はこれを推奨しません。
より優れたプロキシ自動化方法があります——各契約ごとに新しいセッションを開きます。何かを行うたびに契約を作成してください。
「ある処理が必要な場合」に新しい契約を作成し、その契約を処理するための新しいセッションを作成するためのオーケストレーション層を構築します。
これはあなたのエージェント体験を根本から変えます。
繰り返し、繰り返し、繰り返し
行政アシスタントを雇ったとき、その人が初日からあなたのスケジュールを知っていると期待しますか？あるいは、どのようにコーヒーを飲みますか？夕食は6時ではなく8時にとりますか？明らかにそうではありません。あなたは時間とともに好みを築いていきます。
代理も同様です。最もシンプルな設定から始め、複雑な構造やハーネスを忘れて、基本的なCLIにチャンスを与えてください。
次に、あなたの好みを段階的に追加してください。どのようにしますか？
ルール
何かをエージェントにさせたくない場合は、それをルールとして書き記してください。そして、CLAUDE.md にそのルールをエージェントに伝えてください。例えば：「コードを書く前に、`coding-rules.md`を読みなさい。」ルールはネスト可能で、条件付きにすることもできます！コードを書く場合は`coding-rules.md`を読み、テストを書く場合は`coding-test-rules.md`を読み、テストが失敗している場合は`coding-test-failing-rules.md`を読みなさい。エージェントが従うための任意の論理的分岐ルールを作成でき、CLAUDE.md に明確な説明があれば、Claude（およびCodex）は喜んでそれに従います。
実際、これが私が提示した最初の実用的な提案です：あなたのCLAUDE.mdを、特定のシナリオと特定の結果に対してどこでコンテキストを探すかを示す論理的でネストされた目次として扱ってください。それは「どのような状況でどこでコンテキストを探すか」のIF-ELSEロジックのみを含むよう、可能な限り簡潔にすべきです。
代理があなたが賛成しない行動を取っているのを見たら、それをルールとして追加し、次にその行動を取る前にそのルールを読むように指示してください。そうすれば、絶対に同じことをしなくなります。
スキル
スキル（Skills）はルールと似ていますが、コードの好みというより、操作手順に適しています。あなたが何かを特定の方法で実行したい場合、それをスキルに組み込むことができます。
実際、人々はエージェントが問題をどのように解決するかが不明なことに不安を感じることがよくあります。これを明確にしたい場合は、エージェントにまずその問題の解決方法を調査させ、その方案をスキルファイルとして記録させましょう。これにより、エージェントが実際にその問題に直面する前に、その対応方法を事前に確認し、修正や改善を行うことができます。
どのようにしてエージェントにこのスキルの存在を知らせますか？そうです！CLAUDE.md に記載して、このシナリオに遭遇して対処が必要な場合、この `SKILL.md` を読み込むようにします。
処理ルールとスキル
あなたはエージェントに常にルールやスキルを追加したいと思うでしょう。それがエージェントに個性を付与し、あなたの好みを記憶させる方法です。他のほとんどすべてのものは余計です。
一度これを行えば、エージェントはまるで魔法のように、あなたが望む通りに動作するようになります。そしてついに、あなたはエージェントエンジニアリングを「理解した」と感じられるようになります。
そして……
パフォーマンスが再び低下し始めるのがわかります。
どうして？！
とても簡単です。規則やスキルを増やせば増やすほど、それらは互いに矛盾し始めたり、エージェントが深刻なコンテキスト膨張を起こしたりします。エージェントがプログラミングを始める前に14個のMarkdownファイルを読む必要がある場合、それも同じく無用な情報の山になります。
どうすればよいですか？
整理。あなたのエージェントに「スパを楽しんでください」と伝え、ルールとスキルを統合し、更新された好みを明確にすることで矛盾を解消してください。
そしてまた、それは魔法のように感じられるでしょう。
これで十分です。これが本当に秘訣です。シンプルさを保ち、ルールとスキルを活用し、CLAUDE.mdを目次として、それらの文脈と設計上の制限を真摯に注意してください。
結果に責任を負う
今日、完璧なエージェントは存在しない。多くの設計と実装作業をエージェントに任せることができるが、その結果にはあなたが責任を負う必要がある。
だから気をつけて……そしてしっかり楽しんでください！
未来の玩具を遊びながら（明らかにそれを真剣に使っている）、それは本当に楽しい！