pstack の 51 個の skill：poteto の Cursor エンジニアリングワークフローの使い方

作成日 2026年10月8日 ソース: https://github.com/cursor/plugins/tree/main/pstack
タグ: #ai-agents #agent-harness #ai-coding #code-review #Cursor

pstack は Lauren Tan（@poteto）が作った Cursor / Grok Bot 向けプラグインで、入れると 51 個の skill が使えるようになる。中身は、彼女自身が毎日コードを書くときに使っているエンジニアリングのやり方だ。agent でコードを書いてはいるが、まだ任せきりにする勇気はない、という人向けだと思う。彼女は講演で「信頼が先、並列はその後」と話し、修正をどの層に置くべきかを整理していた。その内容はこちらにまとめてある：信頼が先、並列はその後。pstack は、その考え方を skill の形に落としたものとして読める。講演では、このプラグインについてはその日は深入りしないと本人が断っていたので、このノートで補う。

まず範囲をはっきりさせておく。以下の細部は公開リポジトリ cursor/plugins の pstack ディレクトリ に基づく。確認時点のプラグインのバージョンは 0.15.15、ライセンスは MIT。リポジトリの更新は頻繁なので、デフォルトのモデルや playbook の数といった細部は今後変わりうる。

何を解決しようとしているか

README の冒頭は “if you want to go fast, go deep first” だ。速くしたいなら、まず一つのことを深くやれ、という意味になる。彼女の見立てでは、いまの agent は数合わせのコードを書きすぎていて、スループットはあっても品質がない。それは望まない、という。pstack の目標はコード行数を増やすことではなく、むしろ逆で、書く量を減らして品質を上げることだ。

二つ目の主張は講演と同じ線上にある。一つの agent を深く使い込み、検証可能なコードを出してくると信頼できてはじめて、安心して複数を同時に走らせられる。彼女はこれを「恐れのない並列」と呼んでいる。

三つ目はモデルだ。pstack は特定のモデルに縛られず、しかも多くの skill はもともとマルチモデル前提で作られている。同じ仕事を異なる系統のモデルにやらせたりレビューさせたりして、それぞれの得意分野を活かす。

もう一つ、別に取り上げておきたい立場がある。pstack には「計画を書く」系の skill がない。README で彼女は、自分は先に計画を書くやり方を信じていないと書き、“the best spec is code”、つまり最良の仕様はコードだ、と言っている。どうしても計画が欲しければ /poteto-mode に対応する playbook はあるが、デフォルトの手順ではない。

利用量については、2026 年 5 月にオープンソース化したその週に、エンジニアリングチームがこれらの skill を約 1 万回使ったと、本人が投稿で述べている。これは彼女自身の説明で、独立した集計ではない。

インストールと 2 つの入口コマンド

Cursor のチャットでプラグインを入れる：

/add-plugin pstack

入れたあとに覚えるコマンドは 2 つだけだ。

1 つ目は /setup-pstack。まずアカウントで実際に呼べるモデルを検出し、推論予算の大きさを尋ね（unlimited、large、medium、small の 4 段階。デフォルトは large 相当で、xhigh）、各ロールにどのモデルを使うかを一覧にして確認を求める。ロールはコードを書く役、判断と文章の役、いくつかのレビューパネルなどに分かれる。確定すると always-applied ルール（毎回のセッションに自動で読み込まれるルール）を ~/.cursor/rules/pstack-models.mdc に書き出し、すべての skill がそれを読む。記述のないロールは skill 側のデフォルトに戻る。ロールを auto か inherit-parent にすると、そのサブエージェントはいま使っているチャットのモデルをそのまま使う。現在の README によると、デフォルトではコードの仕事は Grok に、いちばん難しい変更と文章と判断は Opus 5.5 に回り、レビューパネルはデフォルトでこの 2 系統から 1 つずつ出す。

setup の最後には、プロジェクトにアプリの振る舞いを証明する手段があるかも確認する。なければ、/create-verification-skill で生成するかを一度だけ聞いてくる。ガイドは、初めての人は素直に受け入れるよう勧めている。この一手がいちばん効くからで、詳しくは後で触れる。

2 つ目は /poteto-mode で、タスクの最初に使う。普通に Enter を押すと、そのメッセージ 1 件にだけ効く。スラッシュメニューで選ぶときに Option+Enter（Mac）か Alt+Enter（Windows）を押すと custom mode（カスタムモード）になり、抜けるまで毎ターンコンテキストに残る。このモードは現在、Cursor の agents ウィンドウと CLI で使える。

どの skill を使えばいいか迷ったら /poteto-help に聞く。質問に答え、そのまま送れる prompt を 1 つ渡し、答えの出典ファイルを示してくれる。ただし代わりに作業を始めることはしない。pstack を一回走らせるとそれなりに token を使うからだ。

入口と設定（4 個）

skillひとことで
poteto-mode総合入口。playbook を選び、タスク表を作り、必要に応じて他の skill を呼び、証拠が揃うまで完了と言わない
poteto-help「どれを使えばいい？」を聞く場所。答えと送れる prompt を返すだけで、作業は始めない
setup-pstack使えるモデルを検出し、ロールごとにモデルと推論予算を決めて 1 本のグローバルルールに書く
automate-me最近のチャット履歴から作業の癖を抽出し、自分専用の -mode skill を作る

automate-me はもう少し説明しておく価値がある。poteto-mode は彼女一人のスタイルで、あなたに合うとは限らない。/automate-me は現在のワークスペースでの最近の会話を読み、繰り返し出てくる好み（返答の書き方、仕事の振り方、検証の仕方、コードと文章への要求）を拾い出し、どれが本当に自分のものかを確認したうえで、Cursor 組み込みの create-skill を使って <あなたの名前>-mode を起草する。それを unslop に通し、最後に worktree から PR を開いてレビューに回す。下ではそのまま pstack の仕組みが動いている。

1 つのタスクの流れ

/poteto-mode がやっていることは、次のステップに分けられる：

  1. 依頼を読み、まず原則のインデックスを読み、23 個の playbook から合うものを 1 つ選ぶ。playbook は書き起こされた決まった手順のことで、bug fix、perf、feature、refactoring、prototype、babysit（PR をマージ可能になるまで見張る）、shipping、夜通し走らせる autonomous run などがある。
  2. タスク表を開き、その先頭に playbook の手順をそのまま写し込む。ある手順を飛ばすと決めても、その手順は消えない。表に残り、skip: 理由 と 1 行付く。何をやらなかったかが見える。
  3. 手順の中で何かが必要になったら、対応する skill を呼ぶ。how、architect、interrogate、unslop などだ。
  4. 返答では、どの原則を適用したか、その原則がどの判断を変えたかを明示しなければならない。判断の裏付けがない原則の引用について、ガイドははっきりと「名前を出しただけ」だと書いている。
  5. 完了を報告する前に証拠を出す。それぞれの主張に、測ったのか、推測したのか、当て推量なのかのラベルを付ける。
  6. コードを変える playbook は、どれも最後に「PR を開く」ステップにつながる。worktree から始め、小さく順序立った commit に整え、diff を掃除し、説明文から AI っぽさを抜く。

デフォルトの振る舞いをいくつか補足する。元に戻せる作業は「やっていいですか」と聞かずに進める。元に戻せない操作は必ず止まって待つ。共有ブランチへの force-push、デプロイ、データ削除、顧客へのメッセージなどだ。サブエージェントを立てるときはデフォルトで新しいものを起こし、最初の依頼と後から出た指示をまとめて渡す。古いセッションを再開しないのは、再開すると指示が抜け落ちやすいからだ。

prompt の書き方について、ガイドは 5 つの要素を挙げている。目標、成否が判定できる完了条件、見たい証拠、すでに分かっている手がかり、本当の制約（「まず再現」「まだコードを変えない」「振る舞いは一切変えない」など）。逆に書かないほうがいいものが 2 つある。具体的なやり方と、原因についての自分の推測だ。少なくとも最初は推測を言わない。言うと agent はあなたが指した場所しか探さなくなる。いちばんよくある失敗は、prompt に skill の順番を並べることだ。「まず /how、次に /architect、それから /arena」というように。順番は playbook がすでに決めていて、手で並べた順番はたいてい手順を落とすか入れ替えてしまう。skill の名前を出すのは、特定のデフォルトを上書きしたいときだけでいい。

手を動かす、並列で回す

このグループは、実装の前と最中に仕事をどう分けるかを扱う。

architect はコードを書く前に骨組みを描く。呼び出し側がどう使うか、型、関数シグネチャ、モジュールの境界を決め、関数の中身は空のままにしておく。まず how（必要なら why も）で変更対象のコードを把握し、次に arena で複数のモデルにそれぞれ草案を出させ、それを統合してから実装に入る。デフォルトでは統合した設計からそのまま実装に進む。先に設計を見たければ「チェックポイント付きで、実装前に止まって」と言えばいい。実装中に同じパッチがあちこちで必要になったり、型が any や強制キャストなしでは通らなかったりしたら、それを設計が間違っている証拠とみなし、継ぎはぎを続けずに作り直す。

arena と swarm はどちらも並列だが用途が違い、ガイドはこれを混同するのをよくある誤用として挙げている。arena では同じ依頼を N 個のサブエージェントがそれぞれ一通りやる。読み取り専用の審査役（設定が許せば別系統のモデル）が採点基準に沿って点を付け、リードの agent が最良の 1 つを土台に選び、他の案の長所を接ぎ木して、結果を検証する。swarm では仕事を互いに独立した断片に切るか、いくつかのルートを競走させる。各ワーカーは自分の担当分だけを持ち、PASS、ISSUES、BLOCKED のどれかを返し、最後に 1 本のレポートにまとまる。土台選びや接ぎ木はしない。設計を比べたいなら arena、網羅したいなら swarm だ。

figure-it-out は合う playbook がないときの受け皿で、まず監査可能な playbook を設計し、それに沿って実行する。大規模な移行、複数の部分にまたがる変更、席を外したあとで戻ってレビューする仕事は、feature playbook が当てはまる場合でも poteto-mode がここに回す。最初に「完了」を反証可能な条件として書くことを求め、show-me-your-work をつないで判断ログを残す。

show-me-your-work がその判断ログだ。1 つの TSV ファイルに 1 行 1 判断で、列は時刻、フェーズ、何をしたか、なぜか、証拠（commit、PR 番号、ファイルと行、スクリーンショットのパスといったポインタで、段落は書かない）、結果。デフォルトではローカルに置くだけで、仕事が大きく、レビューする人がこの記録を頼りに結果を信頼する必要があるときに commit する。

skillひとことで
architect呼び出し側の使い方、型、シグネチャ、モジュール構成を先に決めてから実装し、設計が誤りと分かれば作り直す
figure-it-out既存の playbook がないとき、監査可能な手順をまず設計してから実行する
arena同じ依頼で N 個の候補を並列に作り、1 つを土台にして他の長所を接ぎ木する
swarm仕事を分割するか競走させ、N 個のワーカーを並列に走らせて 1 本の集約レポートを返す
tdd明示的に頼んだとき、またはバグに安いローカルのテスト経路があるときだけ、失敗するテストを先に書いてから直す
show-me-your-work長時間・無人の作業で TSV の判断ログを残す。1 行 1 判断
make-bot-uiボタンで webhook 経由で Grok Bot を起こす小さなページを作る。鍵はローカルのサーバー側に置く

検証と修正：講演の五層との対応

ここが pstack でいちばん見どころのある部分だ。講演の五層の修正と同じ線上にあるからだ。まず五層を強い順に振り返る。第一層はコードベースとアーキテクチャで、悪い書き方をカテゴリとして書けなくする。第二層は静的解析で、lint、コンパイラ、CI。第三層はルール、Bugbot、skill で、ここから強制ではなく誘導になる。第四層はスタイルガイドと人のレビュー。第五層は検証 skill で、機能ができているかどうかは証明できるが、性能やコード品質は証明しない。

次の対応表は、このノートが skill の役割から並べたもので、彼女が公表した表ではない：

講演の層対応する pstack の skill
第一層：アーキテクチャcorrect の第一選択。no-comments がコメントで主張された制約をコード上の制約に書き換える
第二層：静的解析correct が一段下げて型、lint、CI を使う。原則 encode-lessons-in-structure
第三層：ルールと skillreflect が 1 回のセッションの教訓を skill の修正に落とす。pstack 全体もこの層にある
第四層：人のレビューinterrogate が複数モデルで敵対的レビューをする。no-comments の Comment Sicko もレビュアーの一人
第五層：検証create-verification-skill、maintain-verification-skill、原則 prove-it-works

correct：繰り返す修正を prompt からリポジトリへ移す

/correct は、講演のあの順序をほぼそのまま skill にしたものだ。まず最近の commit、リバート、レビューコメント、agent 向けの説明ファイル、回避策を説明しているコメントを読み、ミスを種類ごとにまとめる。同じ種類が 2 回起きてはじめて 1 つの種類として数える。そのうえで、種類ごとに「効く範囲でいちばん高い層」で直す。まずアーキテクチャを試す。状態ごとに持ち主を 1 つにし、仕事ごとにサポートするやり方を 1 つにし、内部を隠して間違った import がそのまま失敗するようにし、agent が真似しそうな古い書き方を消す。それで駄目なら型を使う。悪いコードがまだコンパイルできるなら、lint か CI のチェックを足し、そのエラーメッセージで代わりにどのファイル、型、関数を使うべきかを直接示す。それも駄目ならテストを書く。ドキュメントと agent 向けルールは最後で、判断が要ることだけに使う。agent がルールを読み飛ばしても何も失敗しないからだ。

さらに、新しいチェックはそれぞれ過去の実際のミスで本当にエラーになることを証明しなければならない。agent 向けの説明ファイルには表を持ち、各ルールとそれを強制しているものを対にしておく。何にも強制されていないルールでまた同じミスが起きたら再発とみなし、同じ変更の中でより高い層で直す。ガイドにはもう一文ある。人のレビューはこのリストに入っていない。PR のたびに人が同じミスを拾わなければならないこと自体が、これが解決しようとしている問題だからだ。

no-comments：コメントは書いていない人にレビューさせる

/no-comments は Comment Sicko という読み取り専用のサブエージェントを立て、コメントだけをレビューさせる。理由は単純で、コメントを書いた agent は自分のコメントをかばうからだ。Comment Sicko が残すのはごくわずかな種類だけだ。ライセンスヘッダー、公開 API のドキュメントコメント、コードでは説明しきれないことを説明するリンク、自分では変えられない外部依存によって強いられた振る舞い。それ以外は消す。自分のコード内の妙な箇所を説明しているコメントなら、「ここはリファクタリングすべき」というサインとして扱われ、/no-comments はコメントをきれいに書き直すのではなく根本から直す。「消さないで」「変える前に誰々に相談」といった制約が書かれたコメントには、型、ランタイムチェック、テスト、lint のどれかに置き換えることを提案する。同意すれば、先に制約をコード化してからコメントを消す。

これは講演でコメントについて話していた部分と同じ懸念だ。agent はコメントを本当の問題を直さない口実にするし、リポジトリにある書き方は次の agent に真似される。講演で彼女が話していたのは、自分のチームのフレームワーク Dune がコメントを全面禁止しているという話だった。Dune は社内のフレームワークで、pstack の一部ではない。pstack でそれに当たるのがこの skill だ。

検証 skill：create と maintain

/create-verification-skill は、プロジェクト専用の検証 skill を .cursor/skills/verify-<app>/ に生成する。まず「あなたではなくリポジトリに聞く」。ユーザーが実際に触るのは何か（Web UI、CLI、デスクトップアプリ、API）、ローカルでどう起動するか、何で操作するか（まずリポジトリに既にあるテスト用ハーネス、なければブラウザと CDP、PTY、素の HTTP）、どんな証拠が残せるか、2 つのインスタンスを並べて動かせるか。コードから答えが出ないことだけをあなたに聞く。

生成される skill には決まった節がある。起動、診断（このインスタンスは操作する価値があるかを見る読み取り専用のチェック）、操作、証拠、後片付け。それに加えて feature map（機能マップ）があり、ユーザー向けの機能ごとに 1 ファイルで、どうたどり着くか、どう操作するか、どういう結果が見えればできたと言えるかを書く。引き渡す前に、生成した skill を一度最初から最後まで走らせる。起動、診断、機能を 1 つ操作、証拠を取る、後片付け。しかも後片付けのあとも証拠が残っていなければならない。それが通らなかった出力は使わないこと。

/maintain-verification-skill は定期的な手入れだ。ガイドは少なくとも 1 日 1 回、できれば定期実行の自動化に載せて走らせるよう勧めている。機能ごとに読み取り専用のサブエージェントを 1 つ送ってソースを読ませ、ドキュメントのずれを調べ、そのあと 1 つのライブセッションがマップ上のすべての機能を実際に操作する。結果は 3 通りしかない。clean（全部カバーした、変更なし）、changed（PR 1 本、検証 skill 自身のディレクトリだけを変更）、blocked（何で詰まったかを明示）。製品コードは決して触らない。ライブで走らせて製品側の退行を見つけたら、ドキュメントを直して覆い隠すのではなく、退行として報告する。

講演の記事を読んだ人なら、構造が彼女の話していた社内の検証 skill に似ていることに気づくはずだ。再現可能な操作手段と、ディスクに書かれた機能マップ。ただし彼女が話していた Control Glass は社内のもので、公開されておらず、pstack にも入っていない。pstack が提供するのは、その種の skill を生成する道具のほうだ。

数字と影響範囲：benchmark-checklist と blast-radius

講演では、検証 skill が証明するのはできたかどうかであって、速いかどうかではないと言っていた。pstack はそこを benchmark-checklist と原則 explain-the-number で補う。性能の数字を報告する前に、実際に走らせた証拠で 7 つの質問に答えることを求める。何がこの数字を制限しているのか、なぜ 2 倍ではないのか。どちらの側も本番と同じように調整されていたか（release ビルド、本番の設定、キャッシュの温まり具合）。結果がディスク帯域やコア数のような物理的な上限を超えていないか。エラーや誤った出力はなかったか。交互に何度か走らせて再現するか、中央値と範囲はどうか。ユーザーが実際に待つ経路にとって意味があるか。計測区間の中で、仕事は本当に行われていたか。判定は 4 通りだけだ。速くなった、遅くなった、測れる差はない、判断できない。制限要因を言えない、あるいは片方が未調整なら、判定は「判断できない」になる。

blast-radius は別の問いを扱う。小さく見えるがどうも信用できない diff が、diff の外のどこを壊しうるか。要点は、自分で書いたもっともらしい分析を信じないことだ。その変更が安全だと言える根拠になっている 1〜2 個の事実を見つけ、論証を書くのではなく、小さなスクリプトやテストを書いて実際に走らせて証明する。

interrogate と reflect

/interrogate は同じ diff、意図、採点基準を異なる系統のモデルに渡し、それぞれ独立に問題を探させる。肝心なのはモデルの多様性で、役割を割り振ることではない。2 つのモデルが独立に指摘した問題がいちばん信頼できる。リードの agent は実務的なシニアエンジニアとしてふるまい、結果を「対応する」「検討する」「記録のみ」「却下」の 4 つに分け、却下には理由を付ける。コードを自動で変えることはしない。ガイドは、却下されたものにも目を通すよう念を押している。リードは神託ではないからだ。それから、コードの裏付けがない抽象的な計画にこれを向けないこと。レビュアーが起こりもしないリスクを山ほど作り出す。

/reflect はタスクを終えたあとに使う。3 つのレビュー用サブエージェントを並列に立てて現在の会話を読ませ、判断、ツール、発散という 3 つの観点から教訓を引き出し、まとめ役がそれを採用、却下、バックログに分ける。lint、スクリプト、メタデータで強制できる項目はバックログに回され、より高い層で直す対象になる。採用分は、あなたが承認するまで skill を変更しない。skill を変えると以後のすべての agent に影響するからだ。ガイドは役割分担をはっきり書いている。/reflect は 1 回のセッションから skill を改善し、/correct はリポジトリを変えて、ある種類のミスが二度と起きないようにする。

skillひとことで
create-verification-skillユーザーと同じようにアプリを操作するプロジェクト専用の検証 skill を生成。feature map 付きで、引き渡し前に自己テストする
maintain-verification-skill定期的に機能ごとにソースを読み、実際に操作し直して、検証 skill と機能マップを古びさせない
benchmark-checklist性能の数字を報告・利用する前に、7 つの質問で本物かどうか確かめる
blast-radius変更が diff の外のどこを壊しうるかを探し、安全の根拠となる事実を実コードを走らせて証明する
correctこのリポジトリで agent が繰り返すミスを、アーキテクチャ、型と lint、テスト、ドキュメントの順で潰す
no-commentsComment Sicko にコメントをレビューさせ、消すべきものを消し、主張された制約をコードの制約に変える
interrogate異なる系統の複数モデルが diff を敵対的にレビューし、リードが分類して結論を出す。自動では変更しない
reflect3 つのサブエージェントが現在の会話から教訓を引き出し、承認後に既存 skill の修正にする

コードを理解する：how、why、teach、recall、bro

このグループはすべて読み取り専用で、手を入れる前に使う。ガイドによると、agent が失敗する理由はたいてい 2 つだ。何を求められているかを取り違えるか、正しくやるための文脈が足りないか。このグループは後者を扱い、同時に agent に自分の理解をあなたが確かめられる言葉で説明させる。

/how は「X はどう動いているか」、それに「これはどこに置くべきか、どのパッケージの持ち物か、この層で合っているか」といった問いに答える。シニアエンジニアが新しく入った人にサブシステムを案内するように説明するのが目標で、メンタルモデルが作れる程度で十分であり、1 行ずつ注釈を付けたソースコードのようにはしない。問いが狭ければそのまま読んで説明する。サブシステムが大きければ、まず読み取り専用の探索役を何体か並列に走らせ、それを 1 体の説明役に渡す。

/why は「なぜこうなっているのか」に答える。設計の理由、なぜ Y を選んだか、退行、事後振り返り、ある閾値にデータの裏付けがあるか。まずバージョン管理から調べ、次にどの MCP がつながっているかを見て、issue トラッカー、長文のドキュメント、チャット、監視、エラー追跡、データウェアハウスに並列で問い合わせる。レポートは出典を示し、直接の証拠と推論を分ける。何も見つからなければそのまま報告する。「誰も理由を書き残していない」こと自体が答えだからだ。

/teach はこの 2 つの上に乗っている。how と why を走らせ（小さな変更なら片方だけのこともある）、結果を 1 本の平易な説明に編み、図を 1 枚ずつ積み上げていく。要約では足りず、本当に理解したいときのための skill だ。agent 自身の選択を問いただすのにも使える。たとえば、なぜキューではなくこのやり方で実装したのか、何を引き換えにしたのか、と。

/recall は何かを始めるか再開する前に使う。自分のチャット履歴に共有の記録（ユーザーからの報告、過去の修正とリバート、まだ出続けているエラー）を加えて、そのテーマの近況を組み立て直し、短い現状の要約を返す。特定の古いセッションの続きをやりたいなら、それは session pickup playbook の仕事で、これではない。

/bro はいちばん単純だ。直前の返答を、専門用語なしで、より短く、平易な言葉で言い直す。技術的には丁寧なのに何を言っているのか分からない返答が来たときに使う。

skillひとことで
howX がどう動くか、変更前のコードの読み合わせ、どの層に置き誰の持ち物かを説明する
why設計の理由と経緯を掘り起こし、各種の証拠源に並列で当たり、出典を示して証拠と推論を分ける
teachhow と why を走らせ、一つの仕事を本当に分かるまで、段階的に積み上がる図付きで説明する
recall自分のチャットと共有の記録から近況を組み立て直し、現状の要約を渡す
bro直前の返答を平易な言葉で言い直す

書く：technical-writing、unslop、typescript-best-practices

unslop の説明には「常に適用すること」と書かれている。文章から AI っぽさを取り除くためのルール表で、ルールには固定の番号があり、他の skill が番号で参照する。中身のない「〜しながら」系の分詞句、「専門家によれば」のような曖昧な出典、AI が多用する語のリスト、「X だけでなく Y も」、無理に 3 つにまとめること、同義語の言い換えの繰り返し、ダッシュ、文中のコロン、太字の多用、各行の頭に太字のラベルを付けることなどだ。poteto-mode も返答でこれを守っていて、たとえば長いダッシュを使わない、1 文に 1 つのことだけを書く、といった形で表れる。

technical-writing は層になった技術文書の基準で、ドキュメント、RFC、README、PR の説明、commit メッセージに使う。4 つの層がそれぞれ 1 つの問いを立てる。これはどの種類の文書か（Diátaxis フレームワーク。文書をチュートリアル、ハウツーガイド、リファレンス、解説の 4 種に分け、1 本の文書では 1 種だけを扱う）。文は読み手にどう語りかけるか（Google 開発者ドキュメントのスタイル）。1 文にどれだけ載せるか（STE、簡略技術英語の指示文のルール）。2 通りに読める文はないか（Global English、非ネイティブの読み手を想定した構文）。目標は、疲れたエンジニアが一読で分かる文章だ。やりすぎへの注意もある。すべてのルールを守っているのに機械が書いたように読める文は、失敗とみなす。

typescript-best-practices は型の規律を TypeScript の書き方に落とし込む。バリアントは kind フィールドを持つユニオン型で表す、意味の違うプリミティブには brand を付ける、外部データはまず unknown として扱う、型ガードを手書きする前にリポジトリにあるランタイムのスキーマライブラリを使う、as を安易に使わない、など。ガイドは、これは自動では読み込まれないので、.ts / .tsx に触るタスクでは自分で /typescript-best-practices と打つよう注記している。

skillひとことで
technical-writing層構造の文章基準。まず文書の種類を決め、次に文、情報量、曖昧さを扱う
unslop文章から AI っぽさを取り除く。常時有効が前提
typescript-best-practices.ts / .tsx を読み書きするときに使い、型の規律を具体的な書き方に落とす

24 の原則

原則は 24 個のごく短い skill で、1 つにつき 1 ルールだ。poteto-mode はそのインデックスを持っていて、複数ステップのタスクの開始時に読み、発動条件に当たれば適用する。ファイルが分かれているのは、他の skill が名前で参照できるようにするためと、インデックスから完全なルールを指せるようにするためだ。

使う側にとって原則がいちばん役立つのは、軌道修正に使うときだ。呼び出す必要はなく、名前を言うだけでいい。agent が古いアダプター 3 つの上に 4 つ目を足そうとしていたら、「subtract before you add、まず古いアダプターを消して」と言う。ビルドが通ったから完了だと言ってきたら、「prove it works、本物のインポート処理を走らせて、書き込まれたレコードを見せて」と言う。それぞれの名前の裏には agent がすでに読んだ完全なルールがあるので、一言のほうが段落一つ分の指示より正確に効く。それでも agent は返答の中で、その原則がどの判断を変えたかを説明しなければならない。

グループ原則ひとことで
コアlaziness-protocolリファクタリングや diff の大きさを考えるときは削除と最小の変更に寄せ、抽象化の層を足さない
コアfoundational-thinkingロジックを書く前に中核の型とデータ構造を決め、並行する主体が何を共有するかを詰める
コアredesign-from-first-principles新しい要件が来たら、後付けではなく最初からの前提だったかのように設計し直す
コアattack-the-premise同じ前提に立つ修正が 2 回以上同じ関門で失敗したら、前提そのものを疑う
コアsubtract-before-you-add死んだコード、余分な検証、残った参照を先に消し、すっきりした土台の上に足す
コアminimize-reader-load問いから答えまでに何層くぐるか、読み手が頭に抱える隠れた状態はいくつかを数え、減らす
コアoutcome-oriented-execution段階的な書き直しや移行では目標のアーキテクチャへ直行し、滑らかな移行のための使い捨て互換コードを残さない
コアexperience-first製品や範囲のトレードオフでは実装の都合よりユーザー体験を優先し、数より完成度を取る
コアexhaust-the-design-space前例のない操作や設計判断では、競合するプロトタイプを 2〜3 個作って並べて比べる
コアbuild-the-lever自明でない仕事はまず道具（codemod、スクリプト、ジェネレーター）を作ってやる、または証明する。手作業でやらない
アーキテクチャmodel-the-domain状態を持つロジックや分岐の多いロジックは、散らばった条件分岐ではなく 1 つの構造にドメインのルールを込める
アーキテクチャboundary-discipline検証とエラー処理はシステムの境界に集め、内側では型を信頼し、ビジネスロジックは純粋関数に保つ
アーキテクチャtype-system-discipline不正な状態を表現できなくし、外部データは境界でパースし、コンパイラに嘘をつかない
アーキテクチャmake-operations-idempotentコマンドや処理ループは、クラッシュ、再起動、リトライのあとも同じ最終状態に収束させる
アーキテクチャmigrate-callers-then-delete-legacy-apis新しい内部 API を入れるときは、同じ波で呼び出し側を移行し古い API を消す
アーキテクチャseparate-before-serializing-shared-state複数の主体が同じファイル、ブランチ、キーに書く可能性があるなら、まず共有をなくし、直列化はその後で考える
検証prove-it-works完了を宣言する前に本物の成果物で確かめる。「コンパイルが通った」は数に入らない
検証fix-root-causesデバッグではまず再現し、なぜを繰り返して根本原因まで追ってから直す。null チェックを重ねてクラッシュを黙らせない
検証sequence-verifiable-units複数ステップの仕事や commit / PR の積み重ねを、それぞれ単独で検証できる小さな単位に分け、1 つ確かめてから次へ進む
検証test-behavior-not-implementationテストはユーザーと同じ呼び方でコードを呼び、リテラルの期待値で検証する。全関数が何も返さなくても通るテストは書き直すか消す
検証explain-the-number測った数字を信じたり報告したりする前に、何がそれを制限しているか、思っているものを本当に測ったかを説明する
委任guard-the-context-windowコンテキストが埋まりそうなら大量の読み込みはサブエージェントに任せ、メインには要約だけを残す
委任never-block-on-the-human元に戻せる仕事で「やっていいか」を聞かない。やって、結果を見せ、人にあとから直してもらう
メタencode-lessons-in-structure同じ指示を 2 回書いたら、lint、メタデータ、ランタイムチェック、スクリプトのいずれかに変える

ガイドの勧めは、この表を暗記しないことだ。一度ざっと目を通し、ある名前があれば防げたはずのことを agent がやったのを見た日に、戻ってきて引けばいい。

例示の流れ：性能の退行を直す

以下は、1 つのタスクの中で各 skill がおおよそどこに入るかを示すための例示の流れで、彼女が公表した決まった順序ではない。しかもガイドに従えば、この順番を prompt に書くべきではない。並べるのは poteto-mode に任せる。

ある一覧ページが、先週いくつか PR をマージしたあとから開くのが目に見えて遅くなったとする。送るのは 1 行だけだ：

/poteto-mode the session list got noticeably slower to open after last week's merges. capture a baseline trace, find the cause, fix it, and show me before and after.
  1. poteto-mode がこれを perf playbook に当てはめ、タスク表の先頭にその playbook の手順が並ぶ。
  2. まずベースラインの trace を取る。この手順では、対象の画面に合った control skill でアプリを操作する必要がある（この種の skill は pstack に入っていない。次の節を参照）。あるいはプロジェクトの検証 skill を使う。
  3. ベースラインの数字はまず benchmark-checklist に通す。キャッシュの温まり具合は揃っているか、debug ビルドではないか、計測区間で仕事は本当に走っていたか。以降の数字もすべて通す。
  4. how で一覧の描画とデータ読み込みの経路を説明させ、仮説を立てる根拠にする。perf playbook は、安い順にいくつかの考え方を試すことも求めている。まずその仕事をやらずに済まないか、次に 1 回だけで済まないか、減らせないか、後回しにできないか、ユーザーが見ていないときにできないか、並行にできないか、最後にもっと安くできないか。前の段階で目標に届いたらそこで止める。
  5. explain-the-number：その数字を信じる前に、なぜその値なのか、何が制限しているのかを説明する。
  6. fix-root-causes：本当の原因を突き止めてから変える。たとえば、どのコードが再計算すべきでないときに再計算しているのかを見つけ、症状が出ている層に継ぎを当てるのではなく、原因のある場所で直す。修正が関数の境界をまたぐなら、先に architect を通す。
  7. prove-it-works：修正後に本物のアプリでもう一度 trace を取り、2 つの成果物をパースして比べる。「判断できない」や、違う画面を測っていた場合は合格にならない。
  8. blast-radius：この手順は perf playbook にはなく、自分で足せるものだ。diff は小さく見えるが信用しきれないときに /blast-radius と打ち、その変更が安全である根拠の事実を見つけさせ、コードを走らせて証明させる。
  9. 最後に PR を開く。commit は小さく分け、説明にはベースライン、修正後の数字、差分、成果物のパスを書く。レビューの前に no-comments を走らせる。

できないこと

skill は誘導であって、強制ではない。 これは彼女自身の層分けだ。ルールと skill は第三層にあり、agent が読み忘れることもあれば、人が無視することもある。pstack 全体がこの層にある。poteto-mode は飛ばした手順をタスク表に残して見えるようにするが、見えることと止められることは別だ。また、setup-pstack を除くすべての skill が SKILL.md 冒頭の設定で disable-model-invocation: true を指定している。つまり、モデルが説明文だけを見て自分から読み込むことはない。自分でスラッシュコマンドを打つか、poteto-mode がフローの中で呼ぶかのどちらかだ。本当に止めなければならないミスは、correct を使ってアーキテクチャ、型、lint の層まで押し込んで直す必要がある。

マルチモデルはアカウントにあるモデル次第。 interrogate、arena、reflect の価値の一部は、異なる系統のモデルが互いに確かめ合うことから来ている。setup-pstack は使えると確認できたモデルしか書かない。1 系統のモデルしかない場合や、すべてを auto にして現在のチャットのモデルに従わせた場合でも、これらの skill は動くが、「2 つのモデルが独立に同じ問題を見つけた」というシグナルは弱くなる。

tdd はデフォルトの手順ではない。 使われるのは、TDD や失敗するテスト、回帰テストを明示的に頼んだとき、またはバグに明白で安いローカルのテスト経路があるときだけだ。テストに大がかりな準備、壊れやすいモック、重いエンドツーエンドの基盤が要るなら、そう説明して、いちばん近い実行可能なチェックに切り替える。bug fix playbook でも、安いテスト経路があるときにだけ勧めている。

参照はしているが同梱されていないものがある。 /deslop（コードから数合わせの中身を掃除する）、control-cli と control-ui（CLI、ブラウザ、Electron アプリを操作する control skill）は、別のプラグイン cursor-team-kit に入っている。/create-skill は Cursor の組み込みだ。全部揃えたいなら 2 つのプラグインを一緒に入れる。上の性能の例で trace を取る手順も、control skill か自分の検証 skill に頼っている。

token がかかる。 サブエージェントとレビューパネルはどれも追加のコストだ。ガイドが挙げる節約法は、推論予算を下げるか安いモデルに替える、コードのロールには速いモデルを使う、パネルのリストを短くする、小さくて明白な変更には poteto-mode を使わない、の 4 つ。

これは彼女のスタイルだ。 デフォルトの playbook、口調、原則は一人の人間の習慣から来ている。丸ごと受け入れたくなければ、automate-me で自分のモードを作ればいい。デフォルトのモデルは現行バージョンに基づいており、Cursor のモデルのラインナップが変われば変わる。リポジトリには、デフォルトでは無効の自動化パック benny も同梱されている。Slack に来た問題報告を仕分けし、再現して直すためのものだ。これは 51 個の skill には数えておらず、poteto-agent と Comment Sicko という 2 つのサブエージェントも数に入れていない。

リンク