前回の投稿では、検証がエージェントと行うすべての作業の基盤である理由と、独自の検証スキルを作成する方法をご紹介しました。重要な教訓は、エージェントが自身の作業を検証できなければ、他のことは何も重要ではないということです。あなた自身がボトルネックとなり、一日中エージェントの監視に追われることになります。
https://x.com/poteto/status/2094457600259842065
しかし、検証が機能するようになったら、次に考えるべきは「では、実際に何を構築すべきかをどうやって見極めるのか？」ということです。
https://x.ai/bot/plugin/9717366
この投稿では、私が pstack を使ってどのようにリサーチ、計画、プロトタイピング、アーキテクチャ設計を行っているかをご説明します。これこそが、コード品質を極めて高く保ちながら、毎月何千もの PR を本番環境にリリースすることを可能にしている、まさにそのワークフローです。
8 月の終わりに、2,462 件の PR が本番環境にありました
自分より賢い誰かを監督する技術
2024 年の昔々、システムに変更を加えるには、まずシステムを十分に読んで、何が起こっているのかのメンタルモデルを構築する必要がありました。コードベースの規模と複雑さによっては、これに数時間から数日、場合によっては数ヶ月かかることもありました。小さな変更であれば、小さなサブシステムの局所的な理解だけで済むこともありました。しかし、コア部分をリファクタリングする場合は、リファクタリングを正確かつ効果的に行うために、システム全体がどのように機能するかのメンタルモデルが必要になるでしょう。
エージェントは明らかにこの障壁を取り除きます。コードについてどれだけ知っているかに関わらず、エージェントに指示するだけで簡単にシステムに変更を加えることができます。しかし、コードとユーザーエクスペリエンスの品質を高く保つことは依然として困難であり、特に、何を探し、何を尋ねるべきかを知っているドメインの専門家でない場合はなおさらです。
最先端のモデルは非常に高性能になっていますが、それでも私が常に観察している 2 つの失敗モードがあります。
- 指示が不十分または不適切であるため、あなたの意図を完全に理解できない。
- 作業を正しく行う方法に関する十分なコンテキストを持っていない。
これらの問題は両方とも関連しています。エージェントをうまく活用するには、エージェントのコンテキストウィンドウを高品質なコンテキストでどれだけうまく準備できるかにかかっています。これを行わなくても動作するコードを書くことは確かに可能ですが、エージェントに高品質な仕事をするために必要なすべてを提供するための準備をしておくと、成果と品質がはるかに向上することに気づいています。
あなた自身の言葉で
最先端のモデルは非常に有能なコーダーです。古いモデルでは、何をしてほしいかを非常に具体的に指示し、ほとんどマイクロマネジメントするようなプロンプトを与えていたかもしれませんが、最新のモデルはあなたや私よりも優れたコードを書くことができます。そのため、エージェントに達成してほしいことを伝えつつ、自分では思いつかなかった方法で解決する自由を与えるという、微妙なバランスを取る必要があります。
これこそが、自分より賢く、自分が書いたわけではないコードベースを扱い、人間がコードベース全体のメンタルモデルを頭の中に収めることがもはや不可能な相手を監督する技術なのです。
私が好んで使うテクニックの 1 つは、間接プロンプトです。エージェントに何をしてほしいかを正確に伝える代わりに、エージェント自身の言葉でそれを引き出そうとします。
例えば、誰かが Slack で問題を報告した場合、私は他の何よりも先に、エージェントにスレッドを読ませ、問題を自分の言葉で言い換えさせるように指示することがよくあります。
例えば、次のように言います。
/poteto-mode この Slack スレッドを読んで。根本的な問題は何だと思うか、あなた自身の言葉で平易な英語で言い換えて
これには 3 つの利点があります。
第一に、エージェントに騒がしい会話を構造化された問題文に圧縮するよう強制します。第二に、誤解を即座に発見できます。エージェントがスレッド内の偽の手がかりに固執した場合、コードを書き始める前にすぐに修正できます。
そして第三に、私自身の仮定や仮説（それが間違っていたり、エージェントが達成できる可能性を制限するものであったりする可能性があります）を述べることで、誤った方向に導いてしまう可能性を減らせます。
メンタルモデルの構築
エージェントに、自分が理解できる方法で言い換えさせることは、自分より賢い誰かと仕事をする上で重要な部分です。これが、エージェントが直感的な方法で物事を説明するのを助けるスキルである /teach のインスピレーションとなりました。エージェントが自分にとって意味のあることをしていることを確認する必要があるときはいつでもこれを使用します。
内部的には、/teach は /how と /why を呼び出します。
/how はランタイムのメカニクスをトレースします。/how を尋ねると、エージェントはサブシステムの複雑さを評価します。サブシステムが複数のディレクトリやサービスにまたがる場合、Grok のような高速で効率的なモデル上で並列エクスプローラーエージェントを起動します。
/how 仮想化はどのように実装されていますか？
/why は動機と意図を調査します。コードは何が起こるかを教えてくれます。なぜ誰かがそのように書いたのかを教えてくれることはほとんどありません。/why を実行すると、pstack は複数のソース（Git 履歴と PR レビューコメント、Linear チケット、Notion 設計ドキュメント、Slack での会話、Datadog モニター、Sentry エラー、コードの系統、分析ウェアハウスイベント）にわたる履歴エビデンスを並行して照会します。
/why なぜまだ古いバージョンの Node.js を使い続けているのですか？
エージェントに何かを言い換えさせて、その作業をよりよく理解し信頼したいときはいつでも /teach を使用します。
/teach なぜこの方法で実装して、<他の方法>では実装しなかったのか教えて。どのようなトレードオフを行い、なぜそうしたのか？
実際に、/teach スキルによって行われるリサーチは、人間だけでなくエージェントにとっても有用であることがわかりました。最新の最先端モデルであっても（これはハーネスの品質にも依存しますが）、一般的に、データで裏付けたり、それがどのように機能するかのメンタルモデルを構築するために必要なコードを実際に読んだりせずに、自信満々に物事を述べることがよくあることに気づきます。そのため、何をしようとしているのか、なぜそうするのかを教えるというこの行為は、結果的にエージェント自身も助けることになります。
歴史から学ぶ
私のプロジェクトの多くは、複数の会話にまたがっています。例えば、数ヶ月前、Cursor で人々が報告していた仮想化のバグとパフォーマンス問題を修正していました。新しいチャットを開始するたびに、以前に同様の問題を解決していたときにエージェントが持っていた豊富なコンテキストを、基本的にゼロから構築し直さなければならないことに気づきました。
私が気づいたのは、過去のトランスクリプトは豊富なコンテキストの宝庫であることが多いということです。pstack には、チャット履歴から最近のコンテキストを取得する /recall スキルが同梱されているため、新しいエージェントでも良好な状態に戻るために必要な適切なコンテキストを得ることができます。
/recall 昨日私が仮想化について行った作業を思い出して、それからこの Slack のバグレポートを読んで
/teach、/recall、/how、/why を使用することで、コードベースに関する自身のメンタルモデルを最新の状態に保ち、簡単に理解して覚えられる形式に圧縮しています。そして、これはエージェントも助けます！
逆算して考える
問題を理解したら、どのように解決策を指定するのでしょうか？
私の意見では、プランモードを持つほとんどのハーネスは、実装の詳細を過剰に指定し、その他すべてを過小に指定する傾向があります。そのため、pstack では、私は「計画を信じていない」と冗談めかして言いました。真実は、私は計画を立てますが、コードを通じて計画を立てるということです。
他の人が使用する共有コードやパッケージを作成するような特定の種類の作業では、私は Readme 駆動開発を強く信じています。ご存じない方のために説明すると、これは昔流行った開発手法で、最初に Readme を作成することから始めます。これにより、開発者体験の帽子をかぶることを強いられ、架空のユーザーに API を説明することから始め、実装とアーキテクチャへと逆算して考えます。
例えば、デスクトップアプリ向けの社内クライアントフレームワークである Dune を構築していたとき、まずチュートリアルを書くことから始めました。そうすることで、それを使ってアプリを構築することがどのようなものかを理解できるようにするためです。少なくとも、そうしようと試みました。エージェントに何か良いものや読みやすいものを生成させるのは本当に大変でした。そのため、まずは /technical-writing スキルを作成して、自分のナイフを研ぐことに時間を費やす必要がありました。
/technical-writing スキルなしでの Readme の最初のバージョンは、読むのが苦痛でした。なぜなら、チュートリアル、ハウツーガイド、アーキテクチャの説明、API リファレンスという異なる目的をすべて同じドキュメントに混在させており、ありきたりな AI の粗製濫造と気取った散文で書かれていたからです。
/technical-writing は Diátaxis フレームワーク を使用して、ドキュメントを 4 つの異なるモードに分離します。
- チュートリアル: 実際にやってみて学ぶ。新人を一連のステップに導き、目に見える何かを構築するレッスン。
- ハウツーガイド: 経験豊富なユーザーが特定の現実世界の問題を解決するための手順。
- リファレンス: 機械、API、設定フラグに関する、ドライで完全かつ信頼できる技術的な説明。
- 説明: 背景、設計上の選択、トレードオフを明確にし、照らし出す高レベルの議論。
また、/unslop も使用するため、非常に読みやすいドキュメントを生成します。
この方法で計画を書くことは、エージェントに具体的な目標を与え、自身の作業を照合できるようにするため、非常に役立ちます。そしてもちろん、エージェントが正確に何を構築しようとしているのかを理解するのもはるかに簡単になります。
pstack のスキルの多くは、この設計フェーズで複合的に機能します。例えば：
(1) /recall 過去 7 日間の仮想化バグとパフォーマンス問題の修正作業を思い出して。/how と /why を使って、現在の仮想化実装がどのように機能するかを理解して。
(2) 次に、/poteto-mode planning と /technical-writing を使って、ちらつきやジッターを根本的に排除する新しい仮想化エンジンを考案して。まず、この新しいパッケージを使って React アプリを仮想化する方法についてのチュートリアルを書くことから始めよう。
(3) 計画を書いたら、/teach で、なぜこの新しいアプローチが現在のエンジンより優れているのかを私に教え、証明して。
ここでのテクニックは、エージェントがあなたと同じように問題を見ることができるようにする、興味深く豊かなコンテキストを引き出すことです。単なる一部分としてではなく。
- プロンプトの最初の部分は、アプリ内で仮想化がどのように実装されているかに関する関連する過去と現在のコンテキストを呼び出します。
- 2 番目の部分は、エージェントがそのコンテキスト（以前に修正したバグなど）を使用して、それらの問題を完全に排除する新しい設計を考案するように導きます。
- 最後の部分は、エージェントにこの新しいパッケージが優れていることを証明するよう依頼することです。ここで、検証スキルのような高品質なツールが重要になります。
百回測って、一回切る
計画を立てる際に、私がよく目にする最も一般的な 2 つの間違いは次のとおりです。
- エージェントの最初の設計を受け入れてしまう。
- 経験的な証拠なしに計画を練りすぎてしまう。
人間がコードを書いていた時代、私たちはしばしば設計ドキュメントを通じて互いに協力していました。これらのドキュメントは、高レベルのアーキテクチャ、検討した代替案、トレードオフ、そして異常な実装上の注意事項について議論するものでした。最終的な設計に落ち着くまでに、これらのドキュメントを何度も繰り返し検討することは非常に一般的でした。
エージェントを使う場合、設計ドキュメントの儀式的な手続きを省略することはできますが、エージェントが最初に返してきたものを受け入れてしまうという間違いをよく見かけます。pstack を使えば、代わりに「百回測って、一回切る」というアプローチを限界まで追求し、並列エージェントを活用することができます。
これは、プロトタイピングプレイブックを使用して行います。
pstack において、プレイブックはスキルではなく、/poteto-mode 内の参照ファイルです。これらのプレイブックは、取り組んでいるタスクの種類に応じて（トークン効率のために）条件付きでロードされます。これら 23 のプレイブック（バージョン 0.15.0 時点）には、それぞれ私がタスクを実行する際に使用するワークフローが含まれています。
スキルとは異なり、プレイブックは /poteto-mode の一部としてエージェントによって自動的に使用されます。例えば：
/poteto-mode 新しいドロップダウンメニューのオプションをいくつかプロトタイプして /poteto-mode このバグを修正して /poteto-mode このスキルの変更を評価して
プロトタイピングは、私のお気に入りの pstack プレイブックの 1 つです。目標に対して複数の試行を提供し、エージェントが最適なオプションを推論するのを助けます。これは、ビジュアルプロトタイピングだけでなく、機能、バグ修正などのさまざまなソリューションをプロトタイプする場合にも役立ちます。
/poteto-mode <機能リクエスト>のオプションをいくつかプロトタイプして。/control-app* を使って、私がレビューして選択できるようにビデオ/スクリーンショットを撮って
\ 注: /control-app は [パート 1]([https://x.com/poteto/status/2094457600259842065](https://x.com/poteto/status/2094457600259842065)) で作成した検証スキルです*
ビジュアルの変更をプロトタイプする場合、エージェントはアプリ内またはスクラッチディレクトリに使い捨てのスケッチを構築します。UI インタラクションをテストする場合は、2 つまたは 3 つのバリエーションをシンプルなスイッチャーの背後に配置します。次に、/control-app スキルを使用してインタラクションを駆動し、各バリアントのスクリーンショットを撮り、実際のタイミングやレイアウトを測定します。
プロトタイピングは、コードを使った計画です。これにより、エージェントは問題空間を自由に探索し、あなた自身では思いつかなかったようなもので驚かせる機会を得ることができます。プロトタイプにより、エージェントは私の入力を待つのではなく、経験的な証拠を使って自身の疑問に答えることができます。
より大きな変更のアーキテクチャ設計
エージェント時代のエンジニアとして、アーキテクチャ設計、適切なデータ構造の選択、構築するシステムがどのように連携するかを考えることに時間を費やすことがより重要です。私のエージェントが実装の詳細を埋めてくれます。
pstack に同梱されているもう 1 つの便利なスキルは /architect です。設計を明確で規律あるフェーズに構造化します。
- 問題を基礎付ける。 エージェントは影響を受けるシステムに対して /how と /why を実行し、既存の所有権と制約に関する正確なメンタルモデルを構築します。
- スケッチする。 エージェントはアーキテクチャアリーナに入ります。独立した候補ランナーを並行して起動し、多くの場合、異なるモデルファミリーにわたって起動します。各ランナーは基礎付けのブリーフィングを受け取り、完全な設計パッケージ（呼び出し元の使用法スケッチ、コア型定義、公開関数シグネチャ、簡潔な根拠）を作成します。これらは通常、コールサイトをどのように見せたいかから導き出される、型シグネチャのみをスケッチすることで行われます。各ランナーはインターフェースの深さを評価し、弱いモデルでの失敗モードを調べ、設計上の危険信号のカタログと照合する必要があります。
- 相互評価と統合。 メインエージェントとは異なるモデルを使用する相互評価エージェントが、厳格な評価基準に照らして候補を評価します。
- スケッチに基づいて実装する。 エージェントはスケッチのプレースホルダーボディを実際のロジックに置き換えます。実装中に、関数に予期しないパラメーターや追加の状態が必要であることが判明した場合、エージェントはその不一致を表面化します。
- 設計が間違っている場合は破棄する。 実装中にスケッチが間違っていたことが判明した場合、エージェントはすべてを破棄して最初からやり直します。
ここでのポイントは、エージェントに自己完結型のミニループを与え、異なるモデルファミリーからの複数の競合する設計を 1 つの最適なアプローチに統合させ、厳密であることに注意を払い、経験的な証拠に基づいて自分が考え出したアーキテクチャが間違っていると判明した場合にはそれを破棄することを恐れないようにすることです。無関係なコールサイトで同じ回避策が現れた場合、または型が any や強制キャストのようなエスケープハッチを必要とする場合、それはアーキテクチャが間違っているという経験的な証拠です。
/architect この新しい<機能リクエスト>を設計して
ここでの大きな教訓は、/poteto-mode のプロトタイピングと /architect を使用してコードで計画を立てる方がはるかに効果的であるということです。
また、これが、私が抽象的な計画を対立的にレビューすることに一切時間を費やさない理由でもあります。エージェントは理論上のリスクをでっち上げ、決して発生しない問題から守るために複雑なエッジケースを発明し始めます。計画がまだ抽象的な段階にあるときに練りすぎないでください。エージェントに、プロトタイピングと自身の作業の検証を通じて、未解決の質問に自分で答えさせましょう。
でも、やっぱり計画書が欲しい
pstack には計画スキルは付属していませんが、マルチフェーズ計画プレイブックは同梱されています。私は通常、エージェントが私が満足する設計を考え出した後に、戦術的な実行計画を作成するためにこれを使用します。
/poteto-mode この設計を計画に変換して
計画内のすべてのタスクは、証明と検証を中心に構成されています。プレイブックは、テストだけでは十分な検証ではないことをエージェントに伝えます。実際にコードを実行し、それが機能することを確認した場合にのみ検証されたと見なされます。
すべての計画は、その構造とフォーマットを検証する自動化スクリプトによってチェックされます。承認されると、計画は項目ごとに実行されます。各 PR は小さく、自己完結型で、レビューが容易です。
本当に大規模なプロジェクト（例えば、丸々 1 週間かかるようなもの）の場合、進行中の作業を他のエージェントが認識できるように、計画を一時的にコードベースにコミットすることを選択することもあります。しかし、コードベースを混乱させたままにしないために、通常は完了したら削除します。計画を恒久的に残しておくことに価値はないと考えています。
実際のワークフロー
これらの要素がどのように連携するかを確認するために、これらのワークフローをどのようにプロンプトするかについて、3 つの具体的な例を見ていきましょう。
例 1: 原因不明のバグの調査
本番環境で問題が発生し、根本原因が不明な場合：
/poteto-mode バックグラウンドワーカーが定期的にタイムアウトエラーで失敗する原因を調査して。既知の情報、使用したデータ、そして最も可能性の高い仮説をまとめて。
エージェントはコードを探索し、メトリクスと過去のコミットを並行してチェックし、問題がどこにあるかについて最も可能性の高い推測を提供します。
例 2: 新しいサービス境界の設計
他のモジュールが依存することになる新しいサブシステムを導入する場合：
/poteto-mode 外部ウェブフックにレート制限を追加する必要があります。まず /architect で設計して、未解決の質問はプロトタイプで回答して。進める前にレビューさせて。
エージェントは既存のウェブフックアーキテクチャを基礎付け、複数のモデルにわたって競合する設計ランナーを起動し、使い捨てのプロトタイプでベンチマークを行い、クリーンで検証済みのインターフェースを生成します。
例 3: マルチ PR マイグレーションの実行
多くのファイルにわたる複雑なリファクタリングを実行する場合：
/poteto-mode UI ライブラリ全体を StyleX に移行する計画を作成して。移行を小さな検証可能な PR に分割して。各 PR にはビジュアルリグレッションテストとライブ検証手順が必要です。最終結果はオリジナルと 100% 同一であること（バグも含めて）を求めます。
エージェントは作業を独立したステップに分割し、監査可能なチェックリストを作成し、各ユニットを安全にビルド、検証、マージできるように準備します。
例 4: Slack で報告された問題を修正する
Slack の課題やフィードバックチャンネルで私を見かけたことがあれば、おそらくこれらの定番を見たことがあるでしょう：
# スレッドにはすでに十分なコンテキストがあります
/poteto-mode 実行して
/poteto-mode /control-app でこれを再現して。main ブランチで再現するなら、修正して証拠としてビデオを見せて
ここで説明したスキルの多くは、/poteto-mode によってすでに自動的に使用されているため、ほとんどの場合、/poteto-mode を使用して、あとは通常の生活に戻るだけで大丈夫です！
計画の技術
プランモードは、エージェントが正しいことを行うだろうと自分自身に納得させる方法としてよく使われます。しかし、現実には、抽象的な計画は進歩の錯覚を与えるだけです。長くて詳細な計画は、あなたとあなたのエージェントが非常に生産的であったように見せかけますが、おそらく実質を欠いています。
pstack は、徹底的な調査、経験的な証拠、そして厳格な検証を組み合わせるためのツールを提供します。このように計画を立てると、エージェントを使ったエンジニアリングはギャンブルのように感じられなくなります。予測可能で再現可能なものになります。
https://x.ai/bot/plugin/9717366
お読みいただきありがとうございます。パート 3 をお楽しみに！
