pstack をマスターする：AI 検証スキルでエンジニアリングをスケールさせる

この一連の投稿では、私が厳格なエンジニアリング業務を行うために使用している、個人用スキルセット pstack の使い方をご紹介します。このスキルセットにより、私は月に 2,000 件もの PR を高い信頼性で本番環境にリリースすることができています。

個人的に、私はこれまでコードの行数や PR の数にあまり重きを置いていませんでした。エージェントが登場する前は、誰も気にしていませんでしたし、それは当然のことです。なぜなら、単純な生産性は必ずしも品質やユーザーにとって目に見える成果とイコールではなかったからです。それは単なる虚栄の指標に過ぎませんでした。

しかし、pstack を構築する過程で、量が重要であることを発見しました。特に、エージェントを使用して製品の品質を維持または向上させることができる場合はなおさらです。例えば、約 2 ヶ月前に Grok @Bot の開発を始めたとき、コードベースはまだ初期段階で、新しくはありましたが、成長し始めているところでした。チームが成長し、現在では Grok @Bot のコードベースに毎日数百件の PR が取り込まれているにもかかわらず、pstack のおかげで、コードを常に監視し、リファクタリングし、新しい lint やチェックを追加し、機能開発も行いながら、全員にとってコードの品質を高く保つことができています。

https://x.com/poteto/status/2090546476464451907

https://x.com/poteto/status/2078527882499150286

Grok @Bot の庭師兼メンテナーとして活動できたのは、pstack のおかげです。プロトタイプを構築した後の初期の勢いは非常に大きく、多くの人がチームに参加していました。私は、コードベースが構築・拡張されている最中に、しかもダウンタイムなしで、強固な基盤を持つものへとリファクタリングするという、極めて重要な機会を得ました。エンジニアはもちろん、最も重要なことに、エンジニア以外の人がどれだけ貢献しても、スケールする高品質なコードベースです。この作業にはすべて、Grok Bot の基盤が構築されている最中にそれをリファクタリングし、改善することが必要であり、それは基盤が貢献の数に対応できる場合にのみ可能です。

Grok Bot は、市場に出回っている中で最も効率的で高性能な AI デスクトップアプリの 1 つです

その証拠は Grok @Bot 自体にあります。今後数週間かけて、pstack を使用して高品質なアプリを構築し、維持するために知っておくべきことをすべてお伝えします。

パート 1 – 検証こそがすべて

あなたのツールボックスに持つべき最も重要なスキルは、高品質な検証スキルです。このスキルは非常に重要であるため、私は「単なる」スキルではなく、重要なインフラストラクチャのように考えています。優れた検証スキルは、エンジニア以外のメンバーを含むチーム全体のアウトプットを増幅させます。うまく機能すれば、チーム全体のアウトプットを 100 倍から 1000 倍にすることができます。

この用語に馴染みがなければ、検証とは、エージェントが自身の作業を検証できることを意味します。あなたがボトルネックになることなくループを閉じることができるため、タスクが成功するまでエージェントは作業を続けることができます。Cursor 用に最初の検証スキルを作成した経緯についてもっと知りたい方は、以前の投稿 信頼できるループ をご覧ください。

一緒に検証スキルを作ってみましょう

まず、pstack をインストールし、次に /create-verification-skill を実行します。また、高品質なボットの作成を支援する私のボット Dr Eggbot をあなたのロスターに追加することをお勧めします。Dr Eggbot は pstack に同梱されています。コーディングボットにその使い方を教え、同じ厳格さでコーディング以外のボットも作成できます。

Dr Eggbot にエンジニアボットを作成するよう依頼し、そのボットに /create-verification-skill を実行させ、/maintain-verification-skill を実行する毎日のルーチンを設定させることができます。

Dr Eggbot 大好き

それが実行されている間に、スキルが何をするのか、そしてどのようにしてあなたのために高品質な検証スキルを作成するのかを見ていきましょう。

私は、Grok @Bot と Cursor を構築するために使用しているすべての検証スキルを、一種のメタスキルとしてこのスキルに凝縮しました。これは、あなた自身のアプリ用に高品質な検証スキルを作成する方法をエージェントに教えます。

ここで、テクノロジースタックの選択が重要になります。例えば、Electron や Web 向けのアプリを構築している場合、JS エコシステムで利用可能な豊富なデバッグツールを活用できます。例えば、Chrome DevTools Protocol (CDP) を使用すると、ブラウザの開発者ツールで利用可能なものと同じツールを使用できます。また、iOS アプリを構築している場合は、シミュレーターを活用できます。

理想的には、アプリと対話し、デバッグし、パフォーマンストレースを取得し、手動でアプリを開発する場合に通常使用するであろうその他のデバッグおよび開発ツールを使用できることが望ましいです。もし利用可能なリッチなランタイムがない場合は、エージェントにツールを作成するよう依頼するか（例：lldb の使用、開発環境でサイドカーとして実行されるカスタムパッケージ）、または利用可能なものを活用する必要があるかもしれません。

私は、エージェントによる検証は非常に重要であると感じているため、ソフトウェア構築において不公平なアドバンテージと極度の生産性を得るために、独自のリッチなデバッグツールを構築したり、場合によっては異なるテクノロジースタックを選択したりすることを、皮肉ではなく真剣に提案します。先ほど述べたように、エージェントに自身の作業を検証する能力を与えることで、組織内の全員が貢献し、自分の変更が実際に機能することを検証できるようになります。テクノロジースタックのデバッグと制御が難しいほど、エージェントを生産的に使用することが難しくなります。

再現可能にする

pstack には、"Build the Lever" という原則があります。スキルを作成するという文脈では、これは、エージェントにはマークダウンだけでなくツールを与えることを好むという意味です。検証スキルの場合、これは、アプリとの対話とデバッグをスクリプト化する小さな CLI を、エージェントフレンドリーな小さなユーティリティとして作成することを意味します。つまり、エージェントはタスクを実行するために消費するトークンが少なくなり（何かをクリックするためだけに使い捨てのスクリプトを書く代わりに CLI コマンドを実行する）、検証スキルをより再現可能でテスト可能なものにします。

以下は、エージェントが Electron アプリ用に作成する可能性のある CLI の仮想的な例です。

bash

1# health
2node .cursor/skills/verify-atlas/control-atlas.mjs doctor
3
4# open a blank thread and send
5node .cursor/skills/verify-atlas/control-atlas.mjs new-session
6node .cursor/skills/verify-atlas/control-atlas.mjs send "list open tasks in this project"
7
8# keyboard path
9node .cursor/skills/verify-atlas/control-atlas.mjs press "Meta+KeyN"
10
11# accessibility snapshot of the live UI
12node .cursor/skills/verify-atlas/control-atlas.mjs snapshot
13
14# screenshot for evidence
15node .cursor/skills/verify-atlas/control-atlas.mjs screenshot /tmp/atlas-proof.png
16
17# wait for streaming / layout to settle
18node .cursor/skills/verify-atlas/control-atlas.mjs wait-settle
19
20# flip a feature flag for the session
21node .cursor/skills/verify-atlas/control-atlas.mjs feature-flag rooms_v2 on

これで、すべてのエージェントがこの CLI を使用して、アプリをすばやくナビゲートし、デバッグできるようになります。また、アプリを構築する際の開発者体験についても考え始める必要があります。

開発データベースのシード
認証、テストユーザー、テスト/ステージング環境に対する API 呼び出しの処理方法
開発環境を一貫した方法でインストールし、起動する方法

これらはすべて、自分でコードを書いていたときにもおそらく考える必要があったことです。これを、エージェントがアプリ上で開発作業を行うための主要なユーティリティと考えてください。しっかりとメンテナンスし、テストしてください！

検討すべきその他のコマンド例をいくつか示します。

markdown

1- **検査:** `info`, `snapshot`, `screenshot`, `components`
2- **ナビゲーション:** `home`, `new-session`, `select-project`, `select-runtime`, `scroll`
3- **操作:** `send`, `click`, `click-xy`, `aria-click`, `type`, `press`, `eval`, `upload-image`, `add-context`, `feature-flag`
4- **パフォーマンス:** `trace`, `profile`, `record`, `perf-metrics`, `wait-settle`
5- **ストリーミング:** `console`, `network-log`, `network-summary`
6- **ヘルス & クリーンアップ:** `doctor`, `cleanup`, `watch --restart`

この基本的なセットアップが完了すれば、エージェントのパフォーマンスに大きな改善が見られるはずです。エージェントはアプリ内を簡単に移動し、デバッグできるようになるはずです。

より高度なことを行う前に、ここで時間をかけてこの CLI を優れたものにし、エラーのないものにすることをお勧めします。また、エージェントフレンドリーな CLI を設計することについても考える（またはエージェントに依頼する）必要があります。オンラインにはエージェントに指示できるリソースが多数ありますが、私が好む重要な特性は次のとおりです。

API が構成しやすいこと（John Ousterhout の深いモジュールの哲学を参照）
破壊的な副作用の可能性があるコマンドには --dry-run オプションが必要
サブコマンドを使用して、機能を一度にすべて公開するのではなく、段階的に公開する
エラーメッセージは非常に説明的で、代わりに何をすべきかをエージェントに伝える必要がある
豊富な --help テキスト
機械可読な形式（例：JSON）で出力を返す

ワークツリーではなく Cloud Agents で並列処理を高速化

検証スキルを実行していくつかの PR をマージすることに成功したら、さらに並列化できないかと考え始めるかもしれません。例えば、エージェントがあなたのプロンプトを受け取り、それをマージ可能な状態にほぼ導いてくれるのであれば、あなたはより多くのエージェントを実行できるようになるのではないでしょうか？

最初に思いつくのはワークツリーのサポートを追加することです。つまり、エージェントが git を使用してリポジトリの追跡コピーを作成し、メインのチェックアウトから分離して変更を加えられるようにすることです。理論的には、これにより、変更が互いに上書きされることなく、複数のエージェントを同時に実行できます。

私はこれには反対します。第一に、マシンのストレージ容量とリソースを大量に消費します。リポジトリのサイズとマシンの性能によっては、ワークツリーを使用して最大 10 個のエージェントを並列実行できるかもしれません。しかし、はるかに優れた方法があります！

Cursor の cloud agents は、Cursor のインフラストラクチャ上、クラウドで実行されるエージェントです。これらのエージェントは実際のコンピュータにアクセスできるため、依存関係のインストール、アプリの実行、ビデオやスクリーンショットの撮影、実際のユーザーのようにアプリとの対話を行うことができます。前のステップで開発者体験の向上に十分に投資していれば、クラウドエージェントをセットアップするのはそれほど大きな負担にはならないはずです。クラウド環境を初めてセットアップするときは、エージェントがセットアップと正しい実行を支援します。最初のビルド後、スナップショットが作成されるため、その後のクラウドエージェントの実行は常に迅速に開始されます。

クラウドエージェントのセットアップに時間をかけることを強くお勧めします。これにより、並列処理における生産性が大幅に向上します。後の投稿では、クラウドで数百のサブエージェントを並列実行する方法を紹介します！しかし今は、環境をセットアップし、すべてのエージェントをクラウドで実行することに自信が持てる状態にしましょう。

フィーチャーマップでエージェントをスマートに保つ

アプリが複雑になるにつれて、エージェントは機能を見つけて操作するためにより多くのガイダンスを必要とします。これを行うために、私はフィーチャーマップと呼ぶものを考案しました。名前が示すように、これはアプリで利用可能なすべての機能、その機能の説明、およびユーザーの視点からそこに到達する方法を、検索しやすいようにマッピングしたものです。

以下は、Atlas という架空のアプリ用に私が用意したフィーチャーマップの例です。これは、検証スキルの SKILL.md で言及されているいくつかのマークダウンファイルです。

このファイルはどこにでも配置できますが、/create-verification-skill では、README.md とともに references/features ディレクトリが自動的に作成されます。README 自体がマップであり、利用可能なすべての主要機能の概要を、特定の詳細へのリンクとともに示します。機能の例は次のようになります。

markdown

1# Preferences
2
3フルスクリーンの設定オーバーレイとそのタブセット。
4
5## サブ機能
6
7- settings-overlay: 歯車アイコンまたは Cmd/Ctrl+, から開くフルスクリーンオーバーレイ
8- settings-nav: タブの左ナビゲーション（General, Appearance, Models, Plan & Usage, ...）
9- settings-search: オーバーレイ内検索（設定が開いている状態で Cmd/Ctrl+K）
10- theme-picker: Appearance タブ内のクイックテーマコントロール
11
12## アクセス方法（ユーザー視点）
13
14アカウントアバターの横にある歯車をクリックするか、Cmd/Ctrl+, を押します。左ナビゲーションからタブを選択します。設定の検索ボックスに入力してジャンプします。Esc キーまたは閉じるコントロールで閉じます。
15
16## control-atlas での操作
17
18bash
19node .cursor/skills/verify-atlas/control-atlas.mjs press "Meta+Comma"
20node .cursor/skills/verify-atlas/control-atlas.mjs snapshot
21node .cursor/skills/verify-atlas/control-atlas.mjs press "Escape"
22
23- オーバーレイルート: a11y ツリーで Preferences という名前のダイアログ/リージョンを探します。
24- タブ: 表示名をクリックします。Plan & Usage は一部のアカウント状態では表示されない場合があります。
25- 設定が開いている間、Cmd/Ctrl+K はグローバルパレットではなく設定検索になります（`multi-surface-journeys.md` を参照）。
26
27## 注意点
28
29- スイートの途中で設定を閉じると、フォーカスが役に立たない場所に残ることがあります。`new-session` または `home` で回復します。
30- 一部のタブは権限によって制限されています。明示的なアカウント理由を付けてスキップします。

これらを自分で書くことを心配する必要はありません！/create-verification-skill を実行すると、エージェントが自動的にアプリをくまなく調べ、すべてをカタログ化し、これらのリファレンスを作成します。

フィーチャーマップは、CLI と組み合わせることで、pstack の検証スキルが非常に優れている主な理由の 1 つです。エージェントはすべての機能とそのアクセス方法に関するコンテキストを持つようになり、コンテキストウィンドウ内の貴重なトークンを節約し、その機能が何のためにあり、どのようにそこに到達するかを正確に教えます。

フィーチャーマップは、「具体化されたメモリ」の一種と考えることができます。しばらくエージェントを使用しているなら、おそらくメモリの概念に精通しているでしょう。通常、これらは単純なマークダウンファイル（例：Obsidian vault）として保存されるか、あるいはベクターデータベースのようなより複雑なものとして保存される場合もあります。個人的には、コードベースこそが究極のメモリの形だと思います。コードは、あなたとあなたのチームが行った意思決定の投影であり、何が起こったか、そして物事が実際にどのように機能するかについての真実の情報源を表します。フィーチャーマップは、トークンを節約するために設計された、そのよりコンパクトな形式にすぎません。そして、それはスキル内の単なるマークダウンであるため、コードベースに貢献するすべての人がこの共有メモリの恩恵を受けることができます。

つまり、検証スキルを維持することは非常に重要です。エージェントが常にアプリ制御に関する最新の詳細情報を入手できるように、/maintain-verification-skill を少なくとも 1 日 1 回実行することをお勧めします。また、検証スキルをより頻繁に使用するにつれて、エージェントがアプリ上で作業する際に自動的にそれらを更新することに気付くかもしれません。/maintain-verification-skill は、見逃されたものをキャッチします。

検証スキルの使用方法

参考までに、架空のアプリ用に作成された検証スキルの例を次に示します: https://github.com/poteto/verification-skill-example。念のため、/create-verification-skill を実行すると、基本的な CLI とフィーチャーマップを含むスキルが作成されます。

以下は、pstack での私の典型的な使用方法です。

まず、もちろん、プロンプトを /poteto-mode で開始します。Cursor を通じて pstack を使用している場合、/poteto-mode をオートコンプリートするときに、Enter キーではなく Opt + Enter キーを押すこともできます。これにより、スキルが Custom Mode として追加され、スキルが固定されるため、新しいターンごとにエージェントがスキルを使用するように促されます。

/poteto-mode と入力し、Opt + Enter を押して Custom Mode として固定します

Grok @Bot で、プラグインをインストールし、/poteto-mode と入力します。

Grok Bot でも pstack を使用できます！

例: 新機能の構築

新機能を構築する場合、私は通常、検証スキルを /poteto-mode と組み合わせて使用し、エージェントに作業を検証させます。例えば、次のようなプロンプトを入力します。

/poteto-mode build <機能の説明、関連するコンテキスト>. /control-app を使用して変更を検証し、証拠としてビデオとスクリーンショットを見せてください

ここで、/control-app は /create-verification-skill の結果です。Grok @Bot では、次のようなプロンプトを入力します。

spawn a cloud agent to use /poteto-mode to build <機能の説明、関連するコンテキスト>. /control-app を使用して変更を検証し、証拠としてビデオとスクリーンショットを見せてください

ここでの小さな違いは、Grok @Bot では、ボットに作業自体を実行させる代わりに、クラウドエージェントを起動するように指示することです。私がこれを好む主な理由は、ボットを他のタスクに解放し、コンテキストウィンドウをクリーンに保つことができるからです。その意味で、私は自分のボットを、クラウドエージェントを管理および監督するコーディネーターのように考えています。また、クラウドエージェントを使用すると、Cursor で利用可能なモデルの全配列を活用できます。これらのモデルはそれぞれ独立したマシンを持つため、ボットのコンピューターは他のタスクのために空いたままになります。

例: パフォーマンス作業

spawn a cloud agent to use /poteto-mode to improve the initial loading time of our app. first use /control-app to take a trace of the status quo, and identify opportunities for improvement. then do a targeted fix and use /control-app + a
/swarm to confirm the win

/swarm は、検証スキルと組み合わせるのに最適なスキルの 1 つです。任意の数のクラウドエージェントをファンアウトして検証スキルを実行させるため、十分なサンプルサイズでパフォーマンスの向上を確認したり、アプリをファジングして何も壊したり退行させたりしていないことを確認したりできます。

例: ユーザーレポートの自動再現

検証スキルに満足したら、それを Grok @Bot のルーチンや Cursor Automations 内に配置できます。ルーチンとオートメーションを使用すると、スケジュールに従ってタスクを実行したり、イベントが発生するたびにトリガーしたりできます。

例えば、ユーザーフィードバックを Slack にパイプし、独自の内部フィードバックチャネルがある場合、ボットにすべてのレポートをリッスンさせ、クラウドエージェントで自動的に再現を試みさせることができます。検証スキルとフィーチャーマップが十分に優れていれば、問題を自動修正することも検討できるかもしれません。

検証がツールボックスの中で最も重要なスキルの 1 つであると私が先に述べたのには理由があります。検証は、その上に新しいスキルやルーチンを構築するための基盤を提供します。そして最も重要なことは、チームの全員がその恩恵を受けることです。

検証スキルに投資する

検証スキルを作成したら、/maintain-verification-skill でそれを常に最新の状態に保ってください。CLI を継続的に改善し、重要なインフラストラクチャと同様にスキルに投資してください。オンコールローテーションを設定することも検討してもよいでしょう。それほど、チームの生産性を 100 倍から 1000 倍に引き上げるために重要なのです。

このスキルは、pstack ガイドで取り上げる他の多くのスキルの基盤であり、それらすべてと美しく連携します。