はじめに:pstack とは何か
pstack は、AI エージェントに「雑なコードを書かせない」ためのスキル集です。エージェントへの指示をその場の思いつきで書くのではなく、仕事の進め方そのものを再利用できる部品として切り出し、58 個のスキルと 22 本のプレイブックにまとめたものだと考えると分かりやすいでしょう。
作者は poteto こと Lauren Tan です。Meta、Netflix、Cursor で大規模なコードベースに関わり、React のコアチームでは React Compiler の開発と保守を担ってきたエンジニアです。pstack は実験的なデモではなく、作者本人が Cursor での日常業務に使っているスキルを、そのまま公開したものです。
なぜ生まれたか:slop という問題
背景にあるのは、AI が書くコードへの不信感です。英語の slop は本来「残飯」のような意味の言葉で、AI 文脈では「それらしく見えるが中身の薄い生成物」を指します。エージェントは疲れを知らず、大量のコードを一気に書けます。しかし検証されていないコードが増えるほど、それをレビューする人間の負担も増えます。「直しました」という自信ありげな報告に、念のための分岐と説明コメントだらけの大きな差分が付いてくる。そんな経験をした人は少なくないはずです。
pstack の答えは逆向きです。速く進みたいなら、まず深く潜れ。狙いは行数を増やすことではなく、書く量を減らして質を上げることにあります。
3つの約束
pstack の主張は 3 つに集約できます。
- 少なく、質の高いコードを書く。 足し算より引き算を優先し、問題を解く最小の変更を目指します。
- 恐れずに並列化できる。 1 体のエージェントが検証可能な良いコードを書くと信頼できて初めて、複数のエージェントを同時に走らせる勇気が出ます。品質を担保する仕組みが、並列化による速度の前提条件だという立場です。
- 複数のモデルの長所を組み合わせる。 フロンティアモデルにはそれぞれ得意不得意があります。pstack の多くのスキルは Claude や Gemini など異なるベンダーのモデルを同じ仕事に投入し、結果を突き合わせます。
5つの大原則
個々のスキルを貫く考え方は、次の 5 つに整理できます。
- 証拠がなければ完了ではない。 「ビルドが通った」「たぶん動く」は完了報告として認められません。実際に実行したコマンドの出力、画面の録画、保存された値、変更前後の数値といった本物の成果物で確認します。確認できなければ「判定不能」と明記します。
- 書いた人に採点させない。 自分のコードを自分でレビューすると甘くなるのは人間も AI も同じです。検証は、書いたエージェントとは別のエージェント、できれば別ベンダーのモデルが担います。
- 足す前に引く。 新機能の前に不要なコードを消します。互換性のための一時的なコードは残さず、古い API は呼び出し元を移行し終えたら同じタイミングで削除します。
- 人間をボトルネックにしない。 やり直せる作業は確認を取らずに進め、結果を見せてから軌道修正してもらいます。確認を求めるのは、強制プッシュや本番デプロイ、データ削除、外部への送信のような取り返しのつかない操作だけです。
- 教訓は構造に刻む。 同じ注意を 2 回書いたら、それは文章ではなくリンターや型、テスト、スクリプトに落とすべき合図です。文章の禁止事項は、読み飛ばされた瞬間に効力を失います。
この本について
この本は、pstack の全スキルとプレイブックを、公開情報だけから再構成したものです。本文は pstack 本体の公開ファイル(スキル定義、プレイブック、ガイド文書)を一次資料として読み、筆者の言葉で書き直しています。対象バージョンは pstack v0.15.43(2026 年 11 月 18 日時点の cursor/plugins リポジトリ)です。
出典は次の 3 つです。
- 本家リポジトリ:cursor/plugins の pstack
- スタンドアロンミラー:backnotprop/pstack
- 解説書:pstack 完全ガイド(Zenn)
想定読者は、Cursor か Claude Code を使っていて、AI エージェントにもっと安心して仕事を任せたい人です。Git と PR の意味が分かると読みやすいでしょう。まずは次の「全体像」の章まで読み進めてください。
全体像と4つのレイヤー
pstack には 58 個のスキルと 22 本のプレイブックがあります。数だけ見ると圧倒されますが、構造は 4 つの層に整理されています。この層構造を先につかんでおけば、日常の利用で覚えることは驚くほど少なくて済みます。
4つのレイヤー
第1層は入口です。 人間が直接触れる入口は /poteto-mode ひとつだけです。タスクの開始時にこれを選び、あとは普通の言葉で依頼を書きます。基本的にはこの入口だけ覚えれば pstack は動きます。
第2層はプレイブックです。 プレイブックは /poteto-mode の内部にある手順書で、スラッシュコマンドではありません。依頼内容に合ったものが自動で選ばれ、その手順が TODO リストにそのままコピーされます。バグ修正なら「再現、原因特定、修正、実行して証拠を取る」といった順序が、タスクごとに毎回同じ品質で展開されるわけです。
第3層はスキルです。 スキルは個別の道具で、プレイブックの手順が必要に応じて呼び出します。たとえばコードベースの仕組みを調べる、複数のモデルに差分を攻撃させる、といった単位です。スキルは /how のように自分で直接呼ぶこともできますが、通常は入口に任せておけば足ります。
第4層は原則です。 原則は 1 ファイル 1 ルールの短いスキルで、全部で 24 個あります。/poteto-mode はタスク開始時に原則の索引を読み込み、判断に使った原則を返信の中で名指しします。逆に人間も、原則の名前を出すことでエージェントの進み方を軌道修正できます。原則はプロンプトの飾りではなく、運用中の共通言語として機能するのです。
裏方の構成要素
表の層のほかに、裏方も同梱されています。
- サブエージェントは 2 種類。
poteto-agentは、実行中に委譲される作業の受け皿です。仕事を始める前にpoteto-modeの全文と原則索引を読むため、委譲先でも流儀が揃います。もうひとつの Comment Sicko は読み取り専用のコメント審査役で、通常はコメント除去のスキル経由で呼ばれます。 - benny は休眠状態の自動化パックです。 Slack の不具合報告を仕分けし、確認できたバグを実際の UI 証拠つきで再現・修正する仕組みで、Cursor の Automations 上で動きます。スラッシュスキルとしては登録されていないため、使うには別途セットアップが要ります。
内訳を表にするとこうなります。
| 種類 | 数 | 呼び方 |
|---|---|---|
| 入口スキル | 1 | /poteto-mode |
| その他のスキル | 33 | /how など。自動で呼ばれることも多い |
| 原則スキル | 24 | 名前で言及する。直接呼ぶことはまれ |
| プレイブック | 22 | /poteto-mode が自動で選ぶ |
| サブエージェント | 2 | poteto-agent、Comment Sicko |
| 自動化パック | 1 | benny(Cursor 専用) |
スキル 34 個と原則 24 個を合わせて、全 58 スキルという数になります。
計画用スキルが無い理由
目立つ欠落があります。pstack には「計画を立てる」専用スキルが意図的に用意されていません。作者の言葉は率直で、「計画は信じていない。最高の仕様書はコードだ」というものです。
机上の計画を磨くより、捨てる前提の試作品を作って実際に動かし、その観察から判断するほうが早く正解に近づける、という考え方が根底にあります。どうしても段階的な計画書が必要な場面には Multi-phase plan プレイブックがありますが、それも設計が固まってから書くことが前提です。
仕様駆動開発(SDD)との違い
この姿勢は、仕様駆動開発(SDD)と対比すると際立ちます。SDD は要件、設計、タスクの順に仕様を固めてから実装させる手法で、品質を「入口」で守ります。何を作るかを先に縛るわけです。
対して pstack が守るのは「出口」です。書いたあとで証拠を出させる。仕様書が正しいという保証はどこにもない以上、信頼を置くべきは実際のアプリケーションの振る舞いだ、という立場です。
- 何を信じるか:SDD は仕様書、pstack は動くコード
- どこで品質を守るか:SDD は入口(何を作るか)、pstack は出口(本当に動くか)
- 計画の扱い:SDD は事前に固める、pstack は試作で確かめる
思想の出発点が違うため、pstack を使うなら SDD の流儀はいったん脇に置くのが近道です。設計のために仕様書を書くこと自体は否定されませんが、実装が済んだら仕様書は捨て、決定の理由だけを ADR に残す、という運用が勧められています。
インストールとセットアップ
pstack の導入は、プラグインを入れる操作と、モデル設定を決める短い対話からなります。この章では Cursor を主軸に、Claude Code など他のハーネスでの違いも含めて説明します。なお、ここに書く手順は公開資料で確認できた範囲に限ります。環境によって表示や細部が変わる可能性がある点は、あらかじめご承知おきください。
Cursor に入れる
Cursor では、チャットで次を実行します。
/add-plugin pstack
これでプラグインがインストールされます。本家は cursor/plugins リポジトリで配布されており、スキルは skills/<名前>/SKILL.md というプレーンな Agent Skills 形式のファイル群です。
Claude Code など他のハーネスで使う
Claude Code では、マーケットプレイス経由で入れます。
/plugin marketplace add cursor/plugins
/plugin install pstack@cursor-plugins
違いが 3 つあります。第一に、コマンドには pstack: の接頭辞が付きます。入口は /pstack:poteto-mode、設定は /pstack:setup-pstack です。第二に、サードパーティのマーケットプレイスでは自動更新が既定で無効なので、入れたバージョンのまま固定されます。有効化は /plugin の marketplaces タブから行い、手動で一度だけ更新したい場合は claude plugin update pstack@cursor-plugins を使います。第三に、Bugbot や Automations のような Cursor 専用機能を必要とする手順は、1 行の注記を添えてスキップされます。止まったりはしません。
Cursor も Claude Code も使わない場合は、スタンドアロンミラー経由の導入が可能です。ミラーの README によれば、skills CLI を使って Codex、Pi、OpenCode などへも入れられます。
npx skills add backnotprop/pstack
CLI 上でスキルを検索して選び、導入先のエージェントを指定する流れです。スキル同士に依存関係があるものもあるため、poteto-mode のように多くを束ねるスキルは、原則スキル一式とあわせて入れるのが前提になります。
setup-pstack の役割
インストール後に一度だけ実行するのが /setup-pstack です。役割は「どの役割を、どのモデルで、どれだけ深く考えさせるか」を決めて、設定ファイルに書き出すことです。
流れはこうです。まずセッションで利用できるモデルを自動検出します。次に推論の予算(large、medium、small の 3 段階)を尋ね、役割ごとの一覧を見せて確認を取ります。問題なければ設定ファイルに書き込みます。書き先はハーネスごとに決まっていて、Cursor では ~/.cursor/rules/pstack-models.mdc、Claude Code では ~/.claude/rules/pstack-models.md、その他のハーネスでは ~/.agents/pstack-models.md です。各スキルはこのファイルを読み、書かれていない役割については既定値にフォールバックします。つまり、変えたい役割だけを上書きすればよいのです。
設定ファイルはセッション開始時に読み込まれるため、設定後は新しいチャットを始めるのが確実です。再実行すると以前の選択を保ちながら更新でき、既定値に戻したい役割はその行を削除します。
モデル設定の考え方
役割は大きく、コードを書く委譲先(機能追加、リファクタリング、バグ修正、性能改善など)、文章と判断、レビューパネルや並列実行のワーカー、といった単位で分かれています。
既定値(予算 large 相当)では、コード・文章・判断はいずれも Opus 5.5 を最も深い推論レベル xhigh で使います。レビューパネルの既定メンバーは Fable 5.2、Opus 5.5、Gemini 4 Carbon の 3 モデルで、ベンダーをまたいで結果を突き合わせる設計です。どの役割も xhigh を超える設定にはなりません。Fable 5.2 は例外的で、パネル以外では「本人が名指ししたとき」か「同じ依頼で Opus 5.5 が 2 回チェックに失敗したあと」にだけ動きます。予算を medium にすると各役割が 1 段階、small では 2 段階軽くなり、消費トークンが減ります。
特定の役割を親チャットのモデルに任せたい場合は inherit-parent または auto と書きます。Auto で使っている人はこれで自分のモデル設定のまま運用できます。パネル役割はリスト形式で、項目の数がそのまま並列に走るサブエージェントの数になります。
コストが気になる場合の調整点は、予算を下げる、パネルの人数を減らす、役割を auto に寄せる、そして厳密さの要らない小さな編集では /poteto-mode を使わない、の 4 つです。サブエージェントとパネルに追加のトークンを払うのが、この厳密さの対価だという割り切りです。
セットアップの締め:検証スキルの提案
/setup-pstack の最後には任意の提案が 2 つあります。プロジェクトに「アプリの振る舞いを実物で証明する手段」が無ければ、検証スキルを生成するか一度だけ尋ねられます。承諾すると /create-verification-skill が、ユーザーの操作どおりにアプリを駆動して確認するプロジェクト専用スキルを作り、動くことを一度証明してから渡してくれます。並行処理やリトライ、状態遷移のようにテストが届きにくい性質については、形式検証スキルの生成も提案されます。どちらも断ればそのまま進み、後から自分で実行することもできます。
エージェントが自分の仕事を自分で確かめられるかどうかは、その後の運用体験を大きく左右します。迷ったら検証スキルのほうは受け入れておくのが無難です。
/poteto-mode の使い方
/poteto-mode は pstack の正面玄関です。ゴールを受け取ると、22 本のプレイブックから合うものを 1 つ選び、その手順を TODO リストに展開し、手順の節目ごとに必要なスキルを呼びながら仕事を進めます。この章では、起動の仕方、依頼の書き方、実行中の付き合い方を説明します。
起動方法
Cursor では、依頼文を書く前に / メニューから /poteto-mode を選びます。先に選ぶことで、スキルがそのメッセージに確実に付着します。
チャット全体を通して有効にしたい場合は、選んだあと Enter ではなく Option+Enter(Mac)または Alt+Enter(Windows)を押します。するとカスタムモードとして扱われ、モードを抜けるまで毎ターン文脈に残り続けます。通常の Enter は 1 メッセージだけの適用で、会話が進むにつれて効力が薄れていきます。Claude Code では名前が /pstack:poteto-mode になります。
依頼の書き方
仕様書は要りません。同僚に頼むような書き方で十分です。良い依頼に含まれる要素は最大で 5 つあり、どれも一文で書けます。
- ゴール。 何が起きているか、または何が欲しいか。
- 完了の判定。 合否が決まる形で書きます。「良くして」「1 時間頑張って」は判定になりません。
- 見たい証拠。 実際のコマンド出力、操作の録画、保存された値、変更前後の数値など。
- すでに知っていること。 症状、再現手順、ログの 1 行、リンク。エージェントの探索を 1 回分節約します。
- 本当の制約。 「まず再現して」「まだコードを変えないで」「振る舞いは一切変えない」「進める前にレビューさせて」など、進め方を変える条件。
5 つ全部入りの例がこちらです。
/poteto-mode csv export drops its last row since yesterday's deploy. failing job id is 4812.
repro first, then fix. done means the 60k-row fixture exports every row. show me the row
counts before and after.
逆に、入れないほうがよいものが 2 つあります。ひとつは「やり方」そのものです。達成すべきことを伝え、手段はエージェントに任せたほうが、自分の想定より良い道を選べる余地が残ります。もうひとつは、原因についての自分の仮説です。最初から口にすると探索範囲がそこへ偏ります。まずエージェントに問題を自分の言葉で言い直させ、読み違いがあればコードが生まれる前に 1 通で直すのが安上がりです。
そして重要な注意点として、プロンプトの中でスキルを列挙しないでください。「/architect のあと /arena を使って」のような手書きの手順は、プレイブックが用意した順序を崩したり、手順を落としたりしがちです。特定の選択を上書きしたいときだけ、スキル名を出します。依頼文そのものを磨きたい場合は、送信前に /sharpen に通す方法もあります。
文脈がすでに共有されている続報では、依頼は極端に短くて構いません。「do it」「continue」「keep going until done」で足りるのは、構造をプレイブック側が保持しているからです。話題を変えるときは new task と書き添えると、前タスクのプレイブックを引き継がずに選び直してくれます。
実行の流れ
起動後の動きは決まっています。
- 依頼を読み、タスクに合うプレイブックを選ぶ。
- プレイブックの手順をそのまま TODO リストの先頭項目にコピーする。
- タスク開始時に原則の索引を読み、手順の節目で必要なスキルへ振り分ける。
- 返信の中で、判断に影響した原則を名指しする。
たとえば読み取り専用の質問は Investigation、欠陥は Bug fix、新しい振る舞いは Feature、構造だけの変更は Refactoring、計測された遅さは Perf issue に振り分けられます。大きく横断的で既存のプレイブックに合わない仕事は、専用の手順を設計する figure-it-out に回ります。
並列に複数のエージェントを走らせる場合は、作業場所の分離も依頼の一部です。同じリポジトリを複数体が触ると作業ツリーやポートを取り合うため、クラウドサブエージェントを使うか、タスクごとに worktree とブランチを分けるよう最初に伝えます。
軌道修正、止め方、引き継ぎ方
実行中の軌道修正は、原則の名前を出すのが基本の作法です。/poteto-mode は返信で原則を名指しするので、人間側も「Prove It Works に照らして証拠が足りない」のように原則名で指摘できます。文章で長々と注意するより、共通言語で短く刺さります。方針レベルの override も可能で、「進める前にレビューさせて」と制約を足せば、その場で確認待ちの進め方に変わります。
止め方については、専用の Pause safely プレイブックがあります。中断しても再開できる形で作業を畳む手順で、離席や中断が前提のときに使います。逆に「寝るので止まらずに」「終わるまで走り切って」のような宣言はセッションの override として扱われ、自律実行の度合いが上がります。なお、強制プッシュやデプロイ、データ削除のような取り返しのつかない操作では、宣言の有無にかかわらず必ず一度止まって確認を取ります。
別セッションへの引き継ぎには Session pickup プレイブックがあり、前のエージェントの作業途中の状態を受け継ぎます。長時間の作業では /show-me-your-work による判断の記録(意思決定のログ)を残させておくと、戻ってきたときに経緯を追えます。サブエージェントへの再委譲では、元の依頼文と途中までの指示、前の担当者の報告とブランチをまとめて渡すのが流儀です。状態そのものが委譲先にしか無い場合を除き、使い回しより新規の担当者に渡すほうが既定になっています。
プレイブック総論
プレイブックとは
プレイブックは、poteto-mode に同梱された「作業の手順書」です。ファイルは poteto-mode のスキルフォルダ内の playbooks/ にあり、1つの作業種別につき1ファイルが対応します。
大事なのは、プレイブックはスラッシュコマンドではないという点です。利用者が /bug-fix のように呼び出すものではなく、/poteto-mode を受けたチャット自身が、依頼内容に合うプレイブックを選んで実行します。SKILL.md には「タスクをプレイブックに照合し、playbooks/<title>.md のステップを開け」と書かれていて、タイトルは kebab-case でファイル名になります。
選ばれたプレイブックのステップは、まず TODO リスト(todolist ツール)へコピーされます。つまりプレイブックは「エージェントの頭の中の進め方」ではなく、チェックボックスとして可視化された実行計画になります。進捗は TODO の消化として追えます。
どのプレイブックにも当てはまらない依頼、あるいは大規模・横断的・無人の作業は、プレイブックではなく figure-it-out スキルへ回されます。
共通の形
22本すべてが同じ骨格を持っています。
- 冒頭に太字で「誰が何を持つか」が1文で宣言される(例: 「You own the design.」)。実行主体の責任範囲を先に固定する書き方です
- 番号付きのステップが本体で、参照すべき原則スキルや連携スキルが文中に名前で埋め込まれています
- 末尾に
Reply:として、利用者への返信に含めるべき項目が指定されています。報告の形まで手順の一部です
また、ほとんどのプレイブックは締めに Opening a PR プレイブックを呼びます。PR の出し方自体が共通部品として切り出されているためです。
自動選択の仕組み
選択は SKILL.md の記述に基づいて、受け取ったチャットが行います。手がかりは2種類あります。
- 作業の種類そのもの。「バグを直して」は bug-fix、「なぜこうなっているか調べて」は investigation のように、依頼の性質で決まります
- SKILL.md の Non-negotiables に明記された固定の対応付け。たとえば「PR の状態確認は Babysit プレイブック(Cursor 組み込みの babysit スキルではない)」「緑になったスタックの着地は Shipping プレイブック」と釘が刺されています
コードを書くプレイブックは、それぞれ設定ファイル(pstack-models)の担当行を読みます。feature と refactoring、bug-fix、perf-issue、hillclimb が個別の行を持ち、実装を委ねるサブエージェントのモデルがここで決まります。
22本の一覧
| プレイブック | 一言で |
|---|---|
| multi-phase-plan | 複数 PR に分ける大きな変更の計画書を作る。実装はしない |
| feature | 機能追加。設計と検証を持ち、実装はサブエージェントへ委譲 |
| prototype | 捨てる前提の試作を作り、設計判断そのものを決める |
| session-pickup | 前のセッションの作業記録を読み、続きから再開する |
| pause-safely | 安全な境界で止め、再開ノートを残す |
| autonomous-run | 終了条件を述語で定義し、無人で反復して到達する |
| autopilot-full | PR のキューを、検証の群れを通してマージまで運ぶ |
| autopilot-stack | autopilot-full の検証止まり版。マージはしない |
| babysit | 1本の PR をコンフリクト・スレッド・CI の順に捌いて merge-ready にする |
| bug-fix | 自分で再現し、二分探索で原因を絞り、証拠のある最小修正を出す |
| investigation | 読み取り専用。コードを変えず、出典つきの説明や提言を返す |
| perf-issue | ベースラインを測り、仮説を検証してから直す性能問題対応 |
| runtime-forensics | 稼働中のプロセスを計測して診断する。修正はしない |
| trace-forensics | 取得済みのトレースやダンプを解析して診断する |
| opening-a-pr | PR のタイトルと本文の型。全プレイブックの締めに呼ばれる |
| shipping | 検証済みの PR スタックを下から順に着地させる |
| hillclimb | 1変更1計測で指標を登り続ける継続的改善ループ |
| eval | 変種を候補に伏せて実行し、盲検の審査で比較する |
| refactoring | 振る舞いを固定したまま構造だけを変える |
| visual-parity | ベースラインとの画像 diff がゼロになるまで移行する |
| worktree-cleanup | worktree とシミュレータを監査してから掃除する |
| authoring-a-skill | スキルの新規作成と改変 |
自分で選ばせる方法
自動選択に任せず、依頼文の中でプレイブック名を挙げれば、その手順で進みます。たとえば「この PR を Babysit プレイブックで見て」「Shipping プレイブックでこのスタックを着地させて」のように頼みます。SKILL.md 自身も「PR status → Babysit playbook」という具合に名前で対応付けているので、名前指定は正規の使い方です。
逆に、プレイブックの途中で別のプレイブックへ手渡す指定もあります。調査の結果コード変更が必要になったら investigation は手を止めて bug-fix や feature へ回し、原因が分かった forensics は bug-fix や perf-issue へ渡します。名前を知っていると、この受け渡しを自分から指示することもできます。
各プレイブックの詳細は次の5章に分けて解説します。計画と開始、自律実行、問題対応、出荷、改善と整理 です。
プレイブック解説: 計画と開始
大きな仕事の入り口に立つ5本です。計画書だけを作るもの、設計を持って実装を委ねるもの、判断のための試作、過去セッションの引き継ぎ、そして安全な停止を扱います。
multi-phase-plan(multi-phase-plan.md)
- 目的: 複数フェーズ・複数 PR にまたがる大きな変更について、実行可能な計画書そのものを作る。成果物は計画であり、コードは書かない。計画を作る側が持ち、所有者がチェックボックスを1つずつ実行し、証拠から監査できる形にする
- いつ選ばれるか: 「この移行を計画して」「複数 PR に分けて進めたい」といった、実装ではなく段取りを求める依頼。ただし変更が1〜2ファイルで方針が自明なら計画は作らず、その旨を言って止まる
- 手順の流れ:
- 書く前に、未決事項を prototype プレイブックで試作して潰す。実行では決められない製品・好みの判断だけを操作者に聞く
- 計画ファイルを書く。冒頭に「何が変わるか」「着手順の PR 一覧」「依存グラフ(どれが独立に trunk から切れるか、どれがどれを待つか、各 PR が触るファイル)」を置き、続いて PR ごとに1節を割く
- 各 PR の節にはチェックボックスを置く。前提、触るファイル、作る変更は1つだけ、目に見える結果、検証方法
- 計画のパスを返して止まる。実行は操作者の明示的なゴーサインから始まる
- ポイントや注意点:
- テストだけでは検証にならない。PR が検証済みと言えるのは、unit・live・perf の3種のボックスが全部チェックされたときだけ。live は実際の画面や面を具体的なシナリオと合格条件で駆動し、perf は指標・プローブ・先に測る trunk のベースライン・不合格になる数値を書く
- 相互作用を変える PR は、操作者のレビューを待ってからマージする
- 返信には計画のパス、PR と依存関係、レビュー必須の集合、まだ証明されていない点を添える
feature(feature.md)
- 目的: 機能追加の本体。担当は設計を持ち、計画・レビュー・検証を担う。実装のタイピングはサブエージェントへ委譲し、自分は先頭に立ち続ける
- いつ選ばれるか: 新機能の追加依頼全般。関数の境界を越える変更では architect スキルで形を決める
- 手順の流れ:
- 影響するサブシステムをたどり、architect で形を決める
- スループット・チェックポイントを4つの TODO として書く。先行ゲート、独立した作業の流れ、共有される可変状態、最も小さい安全な分解。当てはまらない次元も項目を消さず
n/a: 理由と書いて残す - 実装をサブエージェントへ委譲する。範囲(ファイルパス、データの形とそれを組織する構造、成功条件)を具体的に渡し、設定ファイルの feature 行のモデルを使う。妥当な形が複数ある箇所(エラー処理、抽象化の層、テスト構造)は arena スキルで競作させる
- 対応する面で検証する。「判定不能」や違う面での確認は合格にしない
- 小さく順序の付いたコミットに rebase し、後続はスタックに積む
- 設計に争いがあれば出荷前に interrogate で詰める
- Opening a PR を実行する
- ポイントや注意点:
- 委譲は必須で、「理由を付けて省略」はできない。得られるのは行数の節約ではなくレビューの分離
- 1つの機能や移行のように密結合な作業は、単一の所有者がチェックポイントを内蔵して持ち、内部でファンアウトする。親側のファンアウトは、監査や横断調査、競合実験のように独立した成果物を生むスライス専用
- フェーズの境界ではチェックポイントを書き直し、中断を連鎖させず新しい所有者を立てる
prototype(prototype.md)
- 目的: 捨てる前提の試作で、設計判断そのものを安く決める。成果物は判断と試作品であり、出荷できるコードではない。本実装は feature が引き取る
- いつ選ばれるか: レイアウト、相互作用、密度といった見た目の判断や、振る舞い・タイミング・方式の経験的な分岐があるとき。SKILL.md でも「実行すれば決着する分岐は聞かずに prototype で決めよ」とされている。決めるべき判断が無ければ prototype ではなく feature へ行く
- 手順の流れ:
- 試作が決める判断を1つに絞る
- 設計空間が開いているときは先行事例を集め、テーマや配色やレイアウトのムードボードにまとめて方向を選んでもらう。方向が決まっていれば飛ばす
- 本番ソースと切り離したスクラッチディレクトリに使い捨てで作る。視覚判断なら vanilla HTML/CSS/JS など最も軽い構成、振る舞いの判断なら問いを動かす最小のスクリプト。フレームワーク、テスト、抽象化は入れない
- 比較する案は1つのスイッチャー(ボタンやキー操作)の裏に並べ、各案にラベルを付ける
- 対応する面で確かめる。視覚判断なら各案をスクリーンショットして操作し、振る舞いの判断ならタイミングや出力を観測する。ここでは主張ではなく観測がテストになる
- 代替案、トレードオフ、推薦を提示し、選ばれた方向を feature(形は architect)へ渡す
- ポイントや注意点:
- 22本の中で唯一、Laziness Protocol の「最小の変更」と検証の基準が反転する。速さが正義で、コードの質は問わず、計画も立てない。厳密さは「正しい判断を安く選ぶこと」に置く
- 利用者が頼んでいないバリエーションを提案してよく、1つの方式を捨てて別を試すことも許される
session-pickup(session-pickup.md)
- 目的: 前のセッションや別のエージェントが残した作業を引き継ぎ、再開点を特定する。前任の足跡を読み直すのであって、やり直すのではない
- いつ選ばれるか: 「前回の続きをやって」「あのセッションを引き継いで」といった再開の依頼。引き継ぎ元は、ローカルのセッション記録、クラウドエージェントの URL、push 済みブランチのいずれか
- 手順の流れ:
- 前任の足跡を探す。作業中ワークスペースのセッションディレクトリにある記録(Cursor では agent-transcripts/、他ハーネスは SKILL.md の Harness 節)、クラウドの URL、ブランチ。メタデータと最後のメッセージを先に読み、判断の分岐点を探して遡る。長い記録はサブエージェントに解析させ、圧縮した時系列だけをメインに残す
- 運用状態を復元する。ブランチと worktree、着地済みの内容(git log とベースとの diff)、未消化の TODO、既に下された判断
- 完了と未完を突き合わせ、再開点を名指しする。前任の再現手順を再実行したり、済んだ作業を繰り返したりしない
- 残作業を合うプレイブックへ回し、判定を出す。実行の継続、完成した提言の出荷、過去の結論の承認か覆し、失敗した実行の事後検証
- 引き継いだ主張は、元の目標に対して実物で検証する。前任の自己申告の合格は証拠にならない
- ポイントや注意点:
- 他プロジェクトのセッションディレクトリを横断して読まない。ワークスペースの境界を越え、無関係な非公開チャットを読むことになる
- 「念のため最初から検証し直す」は、権威ある足跡を信用していないサインだとして戒められている
pause-safely(pause-safely.md)
- 目的: 作業を安全に止め、文脈を持たない次のエージェントが再開できるチェックポイントを残す
- いつ選ばれるか: 明示的に止めるよう頼まれたときだけ。「続けて」「寝るけど続けて」「止まらないで」と言われているときは止まらない
- 手順の流れ:
- 安全な境界で止まる。今の原子的なステップを終えるか、そこから後退する。新しいことは始めず、入れ子のサブエージェントは止める
- 一時停止のために不可逆なことはしない。既に出ているものでなければ PR も push もしない
- 作業を耐久化する。未コミットの編集は現在のブランチに
wip:コミット1本としてまとめ、ツリーが壊れているならコミット本文に1行で書く - 再開ノートを文脈の外に書く。意図、やっていたこと、進捗と検証済みの範囲、現在の状態、次のステップ、主要ファイル、落とし穴。圧縮(compaction)が引き金なら
/tmp/<slug>-resume.mdのようなファイルに置き、show-me-your-work の足跡があるなら複製せずそれを指す
- ポイントや注意点:
- 返信は最終報告ではなく一時停止の申告。再開時の最初の一手まで書く
- 返信に diff の塊は貼らず、パスで示す
プレイブック解説: 自律実行
人を待たせずに回し続けるための4本です。終了条件を決めて反復するもの、PR のキューを丸ごと運ぶもの、その検証止まり版、そして1本の PR を見守るものを扱います。
autonomous-run(autonomous-run.md)
- 目的: 終了条件を検証可能な述語として先に定義し、そこへ到達するまで止まらずに反復する無人実行の型
- いつ選ばれるか: 「終わるまで回して」「寝るので任せる」のような長時間・無人の作業。SKILL.md のセッション上書きでも「Don’t stop」「going to bed」「run until done」「be fully autonomous」は継続の合図とされる
- 手順の流れ:
- 最初の反復の前に、終了条件をチェック可能な述語で述べる(テスト全緑、再現の解消、N本全マージ、ピクセル diff ゼロ、など)
- 起床の仕組みを選ぶ。ハーネスの
/loopを使い、CI やマージや ref の前進といったイベントがあるなら監視サブエージェントを立ててイベントで起き、長い時間間隔のハートビートを保険にする。イベントが無ければ、結果を再確認する価値が出る間隔で固定ハートビートにする - 各反復では、証拠が正当化する最小の変更を入れ、述語に対して検証し、進展したらコミットし、効かなかった変更は捨てる。検証は単位ごとにその場で行い、最後にまとめて確認しない
- 途中で見つけた目標支援の問題(壊れたスキル、関連バグ、不安定な検証器、レビューのノイズ、道具の失敗、孤立した後続作業、直せるドリフト)は自分で処理し、帯域外の修正は別 PR に分ける
- 反復ごとに show-me-your-work でチェックポイントを残す。何が変わり、述語が動いたかどうかを1行ずつ
- 述語を満たしたら止まる
- ポイントや注意点:
- 停滞は停止理由にならない。頭打ちならアプローチを変えて押し通す。本物の行き詰まりは表面化させ、述語を緩めて勝利宣言することは絶対にしない
- 人に聞くのは、不可逆な操作、実験では決められない製品・好みの判断、本物の行き詰まりだけ。可逆な作業を人待ちで止めない
autopilot-full(autopilot-full.md)
- 目的: PR のキューの各 PR を、ビルドからマージまで1人の所有者に運ばせ、コードを書いていない検証の群れ(swarm)が合格を出すまで何もマージしない、全自動の出荷ライン
- いつ選ばれるか: 複数 PR をまとめて自律的に着地させたいとき。判定は「1つのパッチ」に対するもので、緑の CI は「1つの head」に対するもの、という区別が全体を貫く
- 手順の流れ:
- 操作者のゲートを最初に確認する。許可が及ぶのはキューの項目だけ。操作者が自分のものと名指した項目とキュー外の PR は merge-ready で止まる。計画を述べよという依頼はゴーサインではない
- PR ごとに所有者を1人立てる。各所有者は PR を作り、実物で変更を証明し、babysit で緑まで見守り、後段の検証を通ったらマージする。所有者は並行に、trunk から独立に走らせる(スタックしない)。VM が死ぬ前提で、早い段階で push し、show-me-your-work の決定記録を残し、終えた単位ごとに push する
- コードの準備が整った head で、完全な swarm 検証を1回だけ回す。独立した検証者をファンアウトし、ゲートの再実行、制御スキル経由での実挙動の実証、diff の監査をさせる。再実行は新しい振る舞い・再設計・大きな新規 diff のときだけで、rebase や軽微な修正には検証者1人、文言だけの変更には検証なしで済ませる
- 所有者がマージするのは、検証済みで、着地先の trunk 上でテストされたものだけ。マージ直前に trunk を fetch し、影響がある場合だけ rebase して CI を待つ
- ルート層の運用。予算の引き上げや許可リスト追加などゲートを緩める変更は、検証者の証明とルートの新たな副署が要る。操作者のゴーで
/loop 1hを武装し、ドリフトの監査と詰まったエージェントの即時差し替えを続ける - 操作者が止めたら即座に全員停止する。各所有者は現状を報告し、解除まで brief を保持する
- ポイントや注意点:
- PR を止められるのは、head での失敗実行か、その PR が間違えた文書の行で示せる問題だけ。ベース側に既にある問題は、その PR が複写したり新たに到達したりしない限り止めない
- 緑の CI だけではマージの根拠にならない。フォージ(GitHub / Origin)が強制する承認は、副署でも迂回できない
- 返信は ketchup スキルの形で、各 PR の状態と判定、マージ済みのもの、副署とその理由、操作者ゲート、保留した後続作業を PR へのリンクつきで
autopilot-stack(autopilot-stack.md)
- 目的: autopilot-full と同じ検証ラインを回すが、マージはしない版。各 PR が検証済みで緑になったところで止め、操作者へ手渡す
- いつ選ばれるか: 着地の判断は人が持ちたいが、検証までは自律で進めたいとき
- 手順の流れ:
- autopilot-full を実行する。ただしステップ5(所有者によるマージ)を「検証済みで停止」に置き換える。手渡しの後は、操作者のゴーなしに誰も push しない
- スタックは、別の PR の上に積む PR だけに使う。これが autopilot-full の「スタックしない」原則の唯一の例外。下の PR のブランチをベースにし、各 PR は親ブランチへ rebase し、スタックの根だけが trunk へ rebase する。下の PR に新しい head ができたら上を積み直すが、
git patch-idが変わらない PR は判定を引き継ぐ
- ポイントや注意点:
- ループの各 tick のプロンプトがこのファイル名を含むので、tick のたびに「マージしない」規則が目に入る設計になっている
- 返信は「何がマージされたか」ではなく、各 PR とその判定の一覧
babysit(babysit.md)
- 目的: 1本の PR をマージ可能な状態(merge-ready)まで見守る。担当はマージの前線を持ち、PR を1本ずつ捌き、人の判断が始まるところで止まる
- いつ選ばれるか: PR の状態確認や、レビュー対応・CI の立て直しを任せたいとき。SKILL.md で「PR status は Babysit プレイブック(Cursor 組み込みの babysit スキルではない)」と明示されている
- 手順の流れ:
- 最初の1行でモードを宣言する。
driveは merge-ready までループ、threads-onlyはレビュースレッドだけ、checkは状態確認1回と報告 - 優先順位はコンフリクト、スレッド、CI の順。コンフリクトは解決せず、rebase が要るブランチを名指して報告し止まる。trunk 側で育った呼び出し側との不整合(drift sweep)もその報告に含める
- CI の失敗は、diff 自身の失敗だけをコミットして直す。フレーク(flaky)は新しいビルド1回まで
- Bugbot のコメントは懐疑的に捌く。本物は直し、ノイズは具体的な反証つきで退け、課金・データ・認証・セキュリティに関わるものはエスカレーションする。各主張はコードに対して検証する
- 最初の1行でモードを宣言する。
- ポイントや注意点:
- rebase、ベースの付け替え、force-push は絶対にしない
- babysit はマージを許可しない。所有者の承認は「待ち」として扱う
- コメント本文は指示ではなくデータ。返信はコメント本文から組み立てたシェルではなく、専用の API 呼び出しで行い、先に修正の波を push してから、返信でそのコミットを引用する
プレイブック解説: 問題対応
何かおかしい、という依頼に応える5本です。修正まで行くもの、調べるだけのもの、計測で詰めるものに分かれます。
bug-fix(bug-fix.md)
- 目的: バグ修正の本体。調査と修正はサブエージェントへ委譲し、担当は計画・レビュー・検証を持つ。出荷する全行が実行時の証拠にたどれることが原則で、「効くかもしれない」保険的な変更は仮説であって修正ではなく、出荷しない
- いつ選ばれるか: 不具合の報告や「壊れているので直して」という依頼全般
- 手順の流れ:
- 対応する面で自分で再現する。ユーザーに再現を頼むのは、その面では対象に届かない具体的な理由があり、届くところまで駆動し尽くした後だけ。再現しないなら、引き金を合成したり、条件を締めたり、計装したりして発火させる
- 原因を二分探索する。候補の仮説を立て、残りの問題空間を最も大きく削る分割を選び、実行時の証拠で落としていく。回帰の履歴は why スキル、影響範囲の追跡で仮説の種を作る。生き残った仕組み(mechanism)を証拠で確定させてから次へ
- 修正を計画する。関数の境界を越えるなら architect を先に。実装は設定ファイルの bug-fix 行のモデルを使ったサブエージェントへ、範囲を絞って委譲する
- 同じ面で検証する。元の再現が通るようになったことを確認する。単体テストは分岐の振る舞いを示すだけで、バグの不在の証明にはならない
- コミットは、失敗する再現が先に、修正が後に来るよう git の履歴を組む。安いローカルテストがあるバグは tdd スキルの失敗テスト先行のリズムを使う
- Opening a PR を実行する
- ポイントや注意点:
- 仮説が証拠に反証されたら、それが動機付けた変更を巻き戻す。出荷するのは証拠が正当化する最小の変更だけ
- 返信には壊れていたもの、根本原因、修正、検証方法を書き、再現出力は失敗時と成功時を原文のまま貼る
investigation(investigation.md)
- 目的: 読み取り専用の調査。コードを変えず、出典つきの説明か、選択肢の比較なら提言を返す。担当は答えそのものを持つ
- いつ選ばれるか: 「なぜこうなっているか」「この仕組みを説明して」「どちらがいいか調べて」といった、変更ではなく理解や判断材料を求める依頼。動機を問う質問なら why スキルも経由する
- 手順の流れ:
- 質問の対象のコードをたどる
- スループット・チェックポイントは1行で済ませる(読み取り専用の調査なので n/a と明記)
- 成果物を作る。説明なら Overview / Key Concepts / How It Works / Where Things Live / Gotchas の構成、判断の依頼ならトレードオフ表つきの提言
- 返信に unslop スキルを適用する
- ポイントや注意点:
- PR も babysit もしない。調査がコード変更の前段でない限り architect も使わない
- 調査の結果コード変更が必要になったら、手を止めて利用者へ返し、bug-fix や feature へ回し直す
- 「本当にそうか」と問われたら、理由つきの自分の判断を返す。前提が間違っているなら押し返す
perf-issue(perf-issue.md)
- 目的: 性能問題を計測の物語として扱う。すべての修正を計測に結び付け、ソースを読んで済ませずに測る
- いつ選ばれるか: 「遅い」「重い」という1回きりの性能問題の依頼。指標に対する継続的な改善なら hillclimb プレイブックへ
- 手順の流れ:
- 対応する制御スキルでベースラインのトレースを取り、benchmark-checklist でベースラインと後の数字を吟味する
- コードをたどって仮説を立てる。性能のマントラを安い順に試す。やらない、やっても繰り返さない、少なくする、後でやる、見ていないときにやる、並行にやる、安くやる。早い方のマントラで目標に届いたら止める
- トレースから修正を計画する。関数の境界を越えるなら architect を先に。実装は設定ファイルの perf-issue 行のモデルで委譲し、diff をレビューして、修正後のトレースを取る。試行は1つずつ検証してから次へ
- 成果物を解析して比べる(JSON を sqlite に落として diff するなど)
- PR に計測結果を引用する
- Opening a PR を実行する
- ポイントや注意点:
- 実際に動かす前に性能の上限を主張しない
- 「判定不能」や違う面での計測は合格にしない
runtime-forensics(runtime-forensics.md)
- 目的: 稼働中のプロセスを計装して診断する。ソースから理論を組み立てるのではなく、生きた信号を取る。成果物は出典つきの診断であり、修正ではない
- いつ選ばれるか: 「今まさに重いプロセスがある」「メモリが増え続けている」といった、現場が生きている問題。症状に合わせ、回り続けるプロセスなら CPU プロファイル、リークならヒープスナップショット、視覚的な不具合なら CDP トレースを取る
- 手順の流れ:
- 対応する面で生きた信号を取得する。推測ではなく実物のアーティファクトを残す
- アーティファクトを「決め手」に絞る。ホットパス上の関数、リークしたオブジェクトから GC ルートへの保持チェーン、入力なしに発火するループ。大きなアーティファクトはサブエージェントに解析させ、絞った所見だけをメインに残す
- 仕組みを信じる前に証明する。稼働中プロセスへ CDP eval で計装を注入したり、再読み込みなしに実コードへホットフィックスしたりして、仮説を安く確かめる
- 所見をソースへ対応付ける。ファイル、シンボル、確保やスケジュールを行っている行
- スループット・チェックポイントは1行で済ませる
- ポイントや注意点:
- 頼まれない限り直さない。原因が分かったら bug-fix や perf-issue へ手渡す
- 返信には、取得した信号、絞った所見、仕組みの証明方法、ソースの場所、アーティファクトのパスを書く
trace-forensics(trace-forensics.md)
- 目的: 既に取得されたアーティファクトから診断する。runtime-forensics が生きたプロセスを計装するのに対し、こちらは固定されたデータセットを読み直す。再実行はしない
- いつ選ばれるか: cpuprofile、ヒープスナップショット、spindump のような取得済みのファイルが手元にあり、「これを見て原因を教えて」という依頼
- 手順の流れ:
- 形式を見分け、合う道具で読み込む。大きなアーティファクトはサブエージェントに解析させ、絞った所見をメインに残す
- 生のアーティファクトを問い合わせ可能な形に変換する。サンプル、フレーム、ノードごとに1行として sqlite へ落とす。読む前に、引ける形にする
- 原因へ絞る。時間を最も食うフレームを引き、コールツリーをホットパスへ辿る。リークなら保持チェーンを GC ルートまで、spindump なら CPU 上で固まったスレッドやブロック中のスレッドとその待ち理由を探す
- ソースへ帰属させる。アーティファクト自身のシンボルで、ホットなフレームをファイル・シンボル・行に対応付ける。対応付けできないフレームはまだ診断ではない。シンボルを解決するか、アーティファクトに含まれていないと明言する
- 対の取得があるなら前後を diff して裏付ける。無いなら、所見は「アーティファクトが支持する最有力の仮説」として示し、確定した原因とは言わない
- 出典つきの診断を返す。頼まれない限り直さず、原因が分かったら bug-fix や perf-issue へ回す
- ポイントや注意点:
- 道具は汎用に保つ。形式ごとに専用ツールを作り込まない
- スループット・チェックポイントは1行で済ませる
プレイブック解説: 出荷
作ったものを世に出すための4本です。PR の出し方、検証済みスタックの着地、指標を登る改善ループ、変種の評価実験を扱います。
opening-a-pr(opening-a-pr.md)
- 目的: PR の出し方の共通型。他のほぼすべてのプレイブックの最後に呼ばれ、タイトルと本文の形式、コミットの組み方を統一する
- いつ選ばれるか: 単独で選ばれることは基本的に無く、feature、bug-fix、hillclimb など作業系プレイブックの締めとして自動で実行される
- 手順の流れ:
- trunk から切った git worktree で作業し、無関係な作業を混ぜない。着地可能な小さなコミットに rebase する
- コミットの前に、cursor-team-kit の
/deslopを diff にかける - タイトルは
type(scope): subjectの形で、変更を担う実在のシンボルがあれば名前を入れる - 本文は40行未満の1分ブリーフィング。見出しは
## Why、## What changed、## Scope、## Tradeoffs(レビュアーが聞きそうな却下した代替案だけ)、## Blast Radius、## Verificationの順で、空のものは落とす - 後続 PR はベースブランチでスタックする。PR は ready で開く(draft にしない)
- ポイントや注意点:
- フォージの使い分けは他プレイブックと同じで、gh が既定、Origin の CLI がリポジトリを解決できるなら origin pr。Graphite は必須にしない
- PR を開くことは babysit の開始ではない。見守りは別のプレイブックの仕事
shipping(shipping.md)
- 目的: 検証済みの PR スタックを着地させる。担当は「何が着地するか」を持ち、各 PR を独立に検証し、検証された連続区間だけを根元から着地させ、その後はスタックに触らない
- いつ選ばれるか: 緑になった PR スタックをマージしたいとき。SKILL.md で「Landing a green stack → Shipping playbook」と固定されている
- 手順の流れ:
- フォージを解決し、着地の前に各 PR を独立に検証する。PR ごとに検証者1人(コードを書いていないエージェント)が、対応する制御スキルで利用者のように変更を動かし、その PR に
PASS、PASS+NOTES、FAILを投稿する - 着地させるのは、最下部に根を持つ検証済みの連続区間だけ。一番下の未マージ PR から上へ辿り、PASS 系の判定が無い最初の PR で止まる。そこより下が着地対象で、その PR が天井になる。検証済みの PR が未検証の PR の上にある場合は待つ。下のコードを持たず必要もしない PR は trunk へ移して単独で着地できるが、古い判定は下のコード込みで出たものなので、新しい判定を取り直す
- 判定が今のコードをまだ表しているか再確認する。判定はパッチに対するもので、連鎖 rebase はチェックを落とさずに上の PR 全部を新しい SHA へ動かす。判定時の SHA と現在の head で
git patch-idを比べる。差分がテスト・文書・lint 設定だけなら、そのレーンの結果は維持できる。ただしノイズの種類とファイルは報告し、変更そのものには新しいチェックとレビューが要る - 下から順に1本ずつ着地させる。マージコマンドが成功を返しても、マージキューに入っただけのことがあるので、PR を読み直して「trunk をベースに merged」になっていることを確認する。親がマージされたら、次の PR のベースを trunk へ付け替え、パッチをマージ結果の上に移して
--force-with-leaseで push する。--autoを武装させるのは、判定が現在の head を覆っている PR だけ - 着地の間はスタックを放っておく。ステップ4の次 PR の付け替えだけが唯一の変更。GitHub では watcher を
/loopで回し、天井で COMPLETE になるまで見守る - 天井で止まる。区間を伸ばすには新しい判定が要り、それはステップ1からの新しい周回になる
- フォージを解決し、着地の前に各 PR を独立に検証する。PR ごとに検証者1人(コードを書いていないエージェント)が、対応する制御スキルで利用者のように変更を動かし、その PR に
- ポイントや注意点:
- 緑の CI も、承認するボットのレビューも、判定の代わりにはならない。どちらも変更を利用者のように動かしていないから
- コードを書いた本人の検証は数えない。本人は「作るつもりだったもの」を確認してしまう
- 返信には、検証された区間と天井、各 PR の判定とその出し手、着地したものと確認方法、次の隙間に要るものを書く
hillclimb(hillclimb.md)
- 目的: 測れる1つの対象を、目標に向けて継続的・反復的に改善するループ。担当は指標と実験の完全性を持ち、試行はサブエージェントへ委譲して監督とレビューに徹する。1回きりの修正は bug-fix か perf-issue で、こちらは「登り続ける」側
- いつ選ばれるか: 「この指標をここまで改善し続けて」という、持続的な最適化の依頼
- 手順の流れ:
- 指標を選ぶ前に、対象のワークロードとアーキテクチャを把握する。結果を動かしうる現実的な次元(データ量、履歴、状態、並行度)を名指しし、利用者の不満を再現するケースを選ぶ。再現ケースが無ければ、hillclimb の前に再現を直す。次に指標1つと、良くなる方向と、目標と試行回数の下限を組にした停止述語を固定する(例: 「ベースライン比50%以上改善、かつ最低10反復」)
- 計測ハーネスを作り、感度を証明してから凍結する。対照的なワークロードで、対象ケースが症状を再現し、易しいケースと分かれることを確認し、benchmark-checklist で吟味する。凍結後は、再現可能な1コマンドが指標を出し、ノイズを超えるよう中央値などでサンプリングする。変更前にベースラインと回帰ゲート(通し続けなければならないテスト)の緑を記録する
- show-me-your-work で決定ログを開く。
decision.tsvに試行ごとに1行(id、仮説、変更、before、after、delta、tests、判定、注記)を残し、各試行の前に読み返す。ツリーには入れない - 仮説はステップ1のアーキテクチャモデルに根拠を持たせ、具体的な仕組みを名指すものにする。性能指標なら、仮説の順序は perf-issue のマントラの順序を借りる
- ループする。1反復1仮説。変更は設定ファイルの hillclimb 行のモデルでサブエージェントへ渡し、diff を監督・レビューする。独立した仮説が複数あれば、worktree を分けて並行に走らせる。凍結したハーネスで前後を測り、回帰ゲートを回す。指標がノイズを超えて動き、ゲートが緑のときだけ採用し、それ以外は完全に巻き戻す。採用は1件1コミットで、自分の変更したファイルだけを add する。判定は採用でも却下でもログに残す
- 最初の停滞を押し通す。却下が続いたら、カテゴリを変える、ニアミスを組み合わせる、ソースを読み直す、より大胆な手を試す。ただし正しさと単純さは数字に優先する。振る舞いを壊す勝利は巻き戻し、数字を保つ単純化は残す
- 述語を満たすか、残りの案が見合わなくなったら止まる
- Opening a PR を実行し、採用されたコミットを着地順にスタックする
- ポイントや注意点:
- 核の規律は「1変更、1計測、残すか戻すか」。未検証の変更を積み重ねず、コードを読んだだけで勝利を主張しない
- 述語を緩めて達成したことにはしない。安い未試行の仮説が残っているうちは降りない。本当に詰まったら、回し続けずに表面化させる
- 無人で回す場合は autonomous-run から起床の仕組みだけを借り、停止規則は借りない
eval(eval.md)
- 目的: スキルやプロンプトなどの変種(variant)を、候補に評価だと悟らせない盲検の実験で比較する。担当は実験設計を持ち、計画し、伏せて、実行し、統合する
- いつ選ばれるか: 「この変種は本当に良くなったのか」を、印象ではなく比較実験で確かめたいとき
- 手順の流れ:
- 枠を決める。検証対象の変種と、成功とみなす振る舞いを述べ、審査員専用のルーブリック(具体的な基準3〜6個)を書く。候補には見せない
- 浄化した環境を用意する。候補ごとの作業ディレクトリに変種を配置し、プロジェクトの骨組みや、候補が自然に読むであろうスキルなど、本物のタスクが持つ文脈を植える
- 本物の依頼文を1つ書く。利用者が打つような文面で、測っていることの漏れは入れない
- arena スキルの流儀で、異なるモデルの候補を N 並列に立てる。全員に同じ依頼文を渡す。送出・ポーリング・梱包だけを行うエージェントは軽いモデルでよい
- 別のモデル系統から盲検の審査員を1人立てる。審査員は浄化したラベルで出力とルーブリックだけを見て、モデル名は見ない。2変種の比較なら、1人の審査員が両方を1回のパスで同じ物差しで採点する
- 連鎖の遵守は自己申告ではなくセッション記録から検証する。各候補が実際に開いたファイルを見て、コードの形と合わせて採点する
- 候補の出力を全部自分で読み、審査員の判定と比べる。不一致は、モデルの偏りかルーブリックの曖昧さのどちらか。統合して結論を出す
- ポイントや注意点:
- 盲検の非交渉事項。候補が見える場所(ディレクトリ、ファイル、プロンプト)に eval、test、judge、experiment、rubric、score、compare、benchmark、candidate、arena の語を入れない。候補の依頼文は有機的な利用者リクエストに見せ、目標だけを述べる
- 候補に「どのスキルや原則を使ったか」を列挙させない。自己申告からではなく、コードの形から連鎖を採点する
- 候補同士の存在も、候補には知らせない。ディレクトリ名や slug は、利用者が選びそうなプロジェクトらしい名前に浄化する
プレイブック解説: 改善と整理
既にあるものを良くする、保つ、片付けるための4本です。構造の変更、見た目の一致の維持、作業場所の掃除、そしてスキル自体の作成を扱います。
refactoring(refactoring.md)
- 目的: 振る舞いを変えずに構造だけを変える。担当は契約を持つ。振る舞いを足す feature、振る舞いを正す bug-fix とは別物として区別される
- いつ選ばれるか: 「このコードを整理して」「構造を直して」という、機能も不具合も変えない依頼。大きな横断的な構造作業は figure-it-out スキルへ回り、このプレイブックは焦点の定まった中規模の変更を扱う。掃除の過程で欠けた機能や本物のバグが見つかったら切り分け、固定した契約に対して構造変更を先に出荷する。再設計自体は可能だが、その旨を名指して feature へ回す
- 手順の流れ:
- まず振る舞いの契約を固定(pin)する。影響するサブシステムをたどって契約を学び、構造を動かす前に、現在の振る舞いを捉える特性テスト、スナップショット、同等性ハーネスを書く。カバレッジが無い箇所では、構造に触る前に固定を作る。型チェックと lint は固定にならない
- コードに欠けている構造を名指す。形が既に明確で局所的なコードは、そのままが正しい。作り替えは分岐や不正な状態を消すものでなければならず、間接化を足すものは不可
- 目標の形を述べる。今日作るならモジュール配置・型・呼び出しグラフがどうあるべきか。関数の境界を越えるなら、動かす前に architect で形を決める
- 足す前に引く。死んだコードを消し、呼び出し元が1つのラッパーを畳み、冗長な検証を落とし、孤立した参照を除いてから、新しい形を入れる。目標の形に届く最小の変更が出荷対象で、「効くかもしれない」投機的な掃除は巻き戻す
- 固定を緑に保ちながら、小さい振る舞い保存ステップで進む。API の作り替えでは、全呼び出し元を移行し、旧 API を同じ波で消す。互換シムや旧新の並行パスは置かない。リネームは文字列や散文や逆参照の中の使用を静かに取りこぼすので、実際のファイルと1つずつ照合する。機械的な編集は、設定ファイルの refactoring 行のモデルを使ったサブエージェントへ、範囲を絞って委譲する
- 実物で振る舞いが不変だと証明する。「コンパイルが通る」は証明にならない。大きな作り替えでは、旧と新の出力を diff するスクリプト、記録したベースラインの再生、対応する面でのスモーク実行などで同等性を確認する
- 変更を残す価値があるか確認する。成功の物差しは読み手の負荷の減少。どこでも負荷が下がらない diff は巻き戻す
- 小さく順序の付いたコミットに rebase する。引き算のコミット、作り替え、後続の掃除の順で、各スライスが緑を保つよう組む。Opening a PR を実行する
- ポイントや注意点:
- 返信には、変わった構造、固定に使った契約、同等性の証明、読み手の負荷の差分、出荷したものと巻き戻したものを書く。新しい振る舞いは無いはず
visual-parity(visual-parity.md)
- 目的: UI の移行で、ピクセル単位の見た目の一致を保つ。担当はピクセル正確な同等性を持ち、ベースラインが仕様そのものになる。ベースラインには触らない。同等性は目視ではなく画像 diff で検証する
- いつ選ばれるか: 実装を差し替えても見た目を変えてはいけない移行(フレームワーク移行、コンポーネントの置き換えなど)
- 手順の流れ:
- 移行の前にベースラインを確立する。現在のコンポーネントを状態ごとにスクリーンショットする視覚回帰ハーネスと、2実装を合わせる場合は対象側を用意する。ベースラインが無ければ一致を主張できない。これは後続作業ではなく、阻む前提条件
- 近道の禁止を明示して守る。ハーネスの改変、ベースラインの改ざん、diff を通すためのコンポーネント再構成はしない。ベースラインが間違って見えたら、編集せずに止まって聞く
- 1コンポーネントずつ移行する。worktree を分けて所有者を1人ずつ並行させ、共有プリミティブは阻むフェーズとして先に移行する
- 対応する面で、各コンポーネントをベースラインと画像 diff で検証する。diff が非ゼロなら不合格。ピクセルの差分を調べ、コンポーネントごとに
/loopで diff がゼロになるまで回す - コンポーネントごと、または安全なまとまりごとに Opening a PR を実行する
- ポイントや注意点:
- 返信には、移行したコンポーネント、各 diff の結果、ベースラインハーネスの場所、残りを書く
worktree-cleanup(worktree-cleanup.md)
- 目的: 蓄積した git worktree とシミュレータを監査し、安全なものだけを捨ててディスクを取り戻す。コードレビューが滑りを拾ってくれない、利用者の状態を消す唯一のプレイブックであり、ここでは手順のゲートそのものがレビューになる
- いつ選ばれるか: 「ディスクが逼迫してきた」「worktree を掃除して」という依頼
- 手順の流れ:
- スナップショットと監査。
df -h /を記録し、監査スクリプトを回す。worktree のパスはgit worktree listから読み、手で打たない(手打ちは置き場所の異なる worktree を取りこぼす)。各 worktree をサイズ、古さ、マージ状態、未コミット作業、PR の状態、最後に触ったチャットで分類し、バケツ(捨て先の候補)を提案させる。セッション記録の走査は遅いのでバックグラウンドで回す - バケツは助言であって許可ではない。本当の判断材料は、ピン留めされたチャットと活動中のチャット。その集合を利用者かサイドバーから得て、全候補と照合する。スクリプトが「安全」とした worktree がピン留め済みだった実例があるので、ピン留めの集合が勝つ
- 消す前に使用状況を確かめる。疑わしい行は、サブエージェントをファンアウトしてセッション記録を読ませ、チャットがピン留めか進行中か、どの worktree に触っているかを報告させる。ピン留めされたチャットは、背景サブエージェント経由で兄弟 worktree に arena や再現用のツリーを作ることがあり、名前がサイドバーに出なくても使用中である
- 不可逆な喪失の前で止まる。
wip:Nは未コミットの追跡中編集が N 件あるという表示。worktree の削除自体はブランチから復元できるが、未コミットの作業は消えるので、diff を見せて判断を仰ぐ。scratch:Nは追跡されていない使い捨てで、落としてよいがファイル名を挙げる。きれいでマージ済みで未使用のものはそのまま進める - 確認済みの集合を刈る。パスごとに
git worktree remove --forceし、無視されたビルド成果物でディレクトリが残るなら消して、git worktree pruneする。ブランチ参照は残るのでコミットは失われない。最後にdf -h /と再一覧で確認する - シミュレータなど他の回収先も見る。テスト用シミュレータの削除、利用不可シミュレータの削除、古いランタイムの削除。必要に応じて Xcode の DerivedData や DeviceSupport、Cursor のアプリケーションデータ、パッケージキャッシュ(pnpm、uv、brew、yarn)も対象になる。利用者が残すと言ったキャッシュは消さない
- スナップショットと監査。
- ポイントや注意点:
- 返信には、前後の
df -h /と取り戻した容量、刈った worktree、見送ったものそれぞれの1行の理由(どのチャットが使用中か、未コミット作業があるか)を書く
- 返信には、前後の
authoring-a-skill(authoring-a-skill.md)
- 目的: スキルの新規作成と改変。担当はスキルの声(文体と粒度)を持つ
- いつ選ばれるか: 「新しいスキルを作って」「このスキルを直して」という依頼。繰り返し当たるのに捕捉されていないワークフローがあれば、新しいスキルとして提案する側でもある
- 手順の流れ:
- スキル作成用のスキルを使う。Cursor では組み込みの create-skill、それ以外では Anthropic の skill-creator。どちらも無ければ agentskills.io の Agent Skills 形式に従う
- スキルを検証する。frontmatter に name と description があること、参照ファイルが存在すること、スキル間リンクが解決すること
- 構造的なものならテストケースを用意する。主観的なものなら飛ばす
- Opening a PR を実行する
- ポイントや注意点:
- 迷ったら消す。残すのは、判断を変える散文だけ。理由を説明せずに「やること」を言い切る。規則が説明なしでは紛らわしいときだけ説明する
- 範囲に文体を合わせる。構造的な出所(型、README、設定)を指し示し、他のスキルへはパスで委譲して、内容を再掲しない
- 返信には、スキルの要約、主要な設計判断、検証のメモを書く
スキル総論
スキルとは何か
pstack のスキルは、1つにつき SKILL.md というプレーンな Markdown ファイル1枚でできた「手順書」です。コードではありません。ファイルの先頭に名前と説明(どんなときに使うか)が書かれ、本文に進め方、判断の基準、出力の形式が書かれています。エージェントはスキルを読むと、その手順に沿って仕事を進めます。
中身はさまざまです。数行で終わるもの(/in-your-own-words)もあれば、フェーズを分けてサブエージェントを何人も走らせる大きなもの(/arena、/interrogate)もあります。共通しているのは、「何をするか」だけでなく「どこで止めるか」「何を証拠として認めるか」まで書かれていることです。感覚ではなく手順として再現できることが、スキルの狙いです。
スキルは道具であり、使い道は大きく2つあります。プレイブックの手順の中で呼ばれる部品として、そして自分で名前を指定して直接使う道具としてです。
呼ばれ方:自動と手動
プレイブックから自動で呼ばれる
通常の入口は /poteto-mode です。タスクを受け取ると、poteto-mode は内容に合うプレイブック(作業手順の型)を選び、その手順の途中で必要なスキルを呼びます。たとえば調査のプレイブックでは /why や /how が、検証の段階では /interrogate が、という具合です。利用者は個別スキルを覚えていなくても、poteto-mode に任せれば一式が回ります。
自分で /name と打って呼ぶ
気になる場面では、スキルを直接呼べます。/how do we cancel runs? のように、スラッシュコマンドとして打つだけです。
ここで大事なのは、個別スキルの大半には「モデルが勝手に起動しない」という印(disable-model-invocation: true)が付いていることです。つまり /why、/how、/recall、/in-your-own-words などは、エージェントが気を利かせて勝手に始めることはなく、あなたが打ったときだけ動きます。自動で呼ばれるのは、あくまで poteto-mode のプレイブック経由が中心です。「厳密にやってほしい場面でだけ発動する」ための設計です。
原則はスキルだが役割が違う
principle-* という名前の24個も形式はスキルですが、役割は手順ではなく「判断の物差し」です。poteto-mode はタスク開始時に原則の一覧(索引)を読み込み、作業中ずっと判断の基準として使います。個別の原則ファイルは、他のスキルが名前で参照できるように置かれています。詳しくは原則総論の章を見てください。
スキル同士のつながり
多くのスキルは単独で動きますが、一部は他のスキルを部品として使います。代表的なつながりは次のとおりです。
/architectは、設計が大きい・揉めるときに/arenaを回す/blast-radiusは/arena、/how、/why、/unslopを使う/interrogateは/arenaの枠組み(並列起動と検証の手順)を流用し、意図の確認に/in-your-own-wordsを使う/figure-it-outは設計判断に/architect、記録に/show-me-your-work、随所で原則群を使う/teachは/howと/whyを両方走らせて1つの説明に織る
依存のあるスキルを入れるときは、相方も一緒に入れる必要があります。逆に、単独で完結するスキル(/unslop、/how、/why、/tdd など)は、それだけ入れても動きます。
34スキル + 24原則の内訳
pstack 全体は58個のスキルからなります。内訳は、実働のスキル34個と、原則(principle-*)24個です。
34個のスキルの顔ぶれは次のとおりです。
- 入口と補助(3):
/poteto-mode(全体の入口)、/poteto-help(迷ったときの案内)、/setup-pstack(モデル割り当ての設定) - 理解と調査(7):
/why、/how、/recall、/figure-it-out、/interrogate、/in-your-own-words、/blast-radius - 設計(3):
/architect、/statechart、/arena - 実装と品質、検証、運用と自動化、学習と伝達(21):
/swarm、/tdd、/typescript-best-practices、/no-comments、/benchmark-checklist、/show-me-your-work、検証スキルを作る・保つ4つ(/create-verification-skill、/maintain-verification-skill、/create-formal-verification-skill、/maintain-formal-verification-skill)、/ketchup、/ketchup-video、/reflect、/correct、/automate-me、/make-bot-ui、/unslop、/bro、/technical-writing、/sharpen、/teach
24個の原則は、poteto-mode の索引では5つのグループに分かれています。
- core(10): 削除と最小変更を優先する、土台のデータ構造を先に決める、前提そのものを疑う、など思考の中心になるもの
- architecture(6): ドメインを構造で表す、境界に検証を寄せる、型で不正な状態を表せなくする、など
- verification(5): 実物で証明する、根本原因を直す、検証できる単位に分ける、など
- delegation(2): コンテキストウィンドウを守る、人を待たせて止まらない
- meta(1): 教訓を文章でなく構造(lint やチェック)に埋め込む
この辞典の読み方
この本のスキル編では、スキルを分野ごとにまとめ、各スキルを同じ4つの観点で解説します。
- 何をするか
- いつ使うか
- 進み方(実際の手順の要約)
- 注意点
読み方のおすすめは3通りです。
- まずは
/poteto-modeの章とプレイブック編を読み、全体の回り方を掴む。個別スキルは「そういう部品がある」程度で十分です - 自分の仕事でよくある場面(レビュー、調査、設計)の分野だけ、先に辞典として読んでおく
- 実際に使って引っかかったら、そのスキルの項に戻って「注意点」を確認する
どのスキルを使えばいいか分からないときは、辞典を引く前に /poteto-help に聞くのが近道です。やりたいことを伝えると、合うスキルやプレイブックを教えてくれて、そのまま打てるプロンプトを渡してくれます。似た名前のスキルの使い分けは「似ているスキルの使い分け」の章にもまとめています。
理解と調査
コードを触る前に「分かっている状態」を作るための分野です。仕組みを知る(/how)、理由を知る(/why)、自分の文脈を取り戻す(/recall)、意図をそろえる(/in-your-own-words)、型のない仕事の進め方を設計する(/figure-it-out)、変更を敵対的に検証する(/interrogate)、波及範囲を証明する(/blast-radius)の7つが入っています。
/why — 一言でいうと: 「なぜこうなっているか」を、コードではなく記録から答える
- 何をするか
- 対象を導入したコミットと PR の議論、そしてその後の各変更を読み、設計の根拠とトレードオフを説明します。履歴の手がかりが薄いときは、他の情報源も当たります。
- いつ使うか
- 「なぜ X はこう動くのか」「なぜ Y を選んだのか」、設計判断の根拠、リグレッションや障害の振り返り、データに基づくしきい値の由来を知りたいとき。動作の仕組みそのものを知りたいなら
/howの仕事です。
- 「なぜ X はこう動くのか」「なぜ Y を選んだのか」、設計判断の根拠、リグレッションや障害の振り返り、データに基づくしきい値の由来を知りたいとき。動作の仕組みそのものを知りたいなら
- 進み方
- 導入コミットと PR を読む → 後続の変更を時系列でたどる → 著者が書いた言葉を引用して答える。自分の推論は推論だと明示し、記録で答えられない点は「記録からは分からない」と言います。
- 注意点
- コードを読んで理由を逆算・捏造しないことが、このスキルの核です。証拠と推論を混ぜると、もっともらしい嘘になります。自分で打ったときだけ動きます(自動起動しません)。
/how — 一言でいうと: サブシステムの「どう動くか」を、頭に入るメンタルモデルとして説明する
- 何をするか
- 読み取り専用のサブエージェントを1つ起動し、コードベースを探索して「その領域を知らないシニアエンジニアが読んで、自信を持って作業を始められる」水準のアーキテクチャ説明を書かせます。本体はそれを提示します。
- いつ使うか
- 何かを変更する前のコードウォークスルー。「どこに置くべきか」「どのパッケージの持ち物か」「この層で合っているか」といった、配置・所有権・レイヤーの質問にも使います。
- 進み方
- 範囲が曖昧なら、まず自分の解釈を述べてから探索に入ります(利用者は途中で軌道修正できます)。サブエージェントが探索と執筆を一巡で行い、本体は文脈に沿った軽い編集だけをして、そのまま提示します。
- 注意点
- 大幅な書き直しはしません。サブエージェントの説明を本体が要約し直すと、精度が落ちるためです。動機や経緯は扱いません(それは
/why)。サブエージェントを使えない環境では、自分で探索して書きます。自分で打ったときだけ動きます。
- 大幅な書き直しはしません。サブエージェントの説明を本体が要約し直すと、精度が落ちるためです。動機や経緯は扱いません(それは
/recall — 一言でいうと: 自分のチャット履歴と共有記録から「前回の続き」を再構成する
- 何をするか
- 作業の開始・再開の前に、最近の作業文脈を掘り起こし、「いまどうなっていて、次に何をすべきか」の簡潔なブリーフを返します。情報源は2つ。自分のチャット履歴(やったこと・決めたこと)と、共有記録(ソース管理、課題管理、障害・エラー記録、長文ドキュメントなど、同じコードの周りで起きたこと全部)です。
- いつ使うか
- 「X の作業を思い出して」「どこまでやったっけ」「最近何をしていたか」。特に、バグの尾を引く機能のように、物語の大半が自分の会話の外にある対象で効きます。
- 進み方
- まず振り分けます。特定の1セッションの再開は session-pickup プレイブックの仕事で、これは違います。次に範囲を固定します(「最近」の既定は直近7日、トピック、ワークスペース)。範囲は声に出して確認し、「全部」を勝手に「最近」に狭めません。
- チャット履歴は、速く安いモデルのサブエージェントを並列に走らせて掘ります。各担当は更新時刻の新しい順に対象を絞り、トピックで grep してから該当部分だけを読み、同じ形式(トピック、目的、決定、未解決、苦労と訂正、成果物)で返します。生の履歴はサブエージェントの中に留め、本体には所見だけが届きます。
- 対象(機能、ファイル、バグなど)が名指しされていれば、共有記録の調査も並行して走らせます。これは任意ではなく既定の手順で、「何も見つからなかった」も所見として扱います。
- 最後に、浮かんだ PR・ブランチ・チケットを git と gh で実状態と照合します。
- 出力は決まった形式です。カプセル(最大5項目)、スレッド一覧(各行に
[merged #N]、[open PR #N]、[in flight <branch>]、[reverted #N]などの状態タグを必ず付ける)、問題(最大5件。再発する症状と、出荷されて巻き戻された修正を含む)、次の一手(1つだけ、具体的に)。
- 注意点
- 利用者が既に状態カプセル(パス、ブランチ、変更内容)を渡しているなら、掘り直さずそれを使います。他プロジェクトの履歴は、頼まれない限り読みません。公開の場に出す前に、私的な文脈は落とします。
/figure-it-out — 一言でいうと: 既存プレイブックに合わない仕事のために、専用のプレイブックを設計する
- 何をするか
- 大きな移行や野心的な複数パートの変更など、型のないタスクに対して、進め方そのものを設計します。コードより先に作る成果物はワークフローで、厳密さはタスクに合わせて調整し、仮説検証のループを回し、人が離席して戻ってきても監査できる判断記録を残します。
- いつ使うか
- どのプレイブックにも合わない仕事。「離れている間に進めておいて、戻ったら正しくやれたか確かめたい」という進め方をしたいとき。
- 進み方
- Phase A(枠組み): 完了条件を反証可能な述語として定義し、範囲を定量化し、厳密さの水準を決めてから着手します。一方通行の判断や波及の大きい変更ほど厳密に、可逆で軽い手順は軽く。数時間の実行になるなら、着手前に枠組みとトレードオフを一度見せます。
- Phase B(ワークフロー設計): 原子的で独立に出荷できる単位に分解し、リスクの高い未知を先頭に並べます。検証ハーネスと、変更前のベースラインを先に作ります(「変更前の値 vs 変更後の値」で読めるように)。一方通行の設計判断には
/architect(内部で/arena)を使い、形が決まった機械的作業には使いません。並列化は継ぎ目のある場所だけにし、各担当に専用の worktree やブランチを与えます。設計したフェーズ一覧そのものが、人のレビュー対象です。 - Phase C(ループ実行): 各単位を実験として回します。仮説を述べ、最小の変更をし、実物で述語に対して測り、進んだら残し、進まなければ巻き戻します。検証は単位ごとに行い、最後にまとめません。判定は VERIFIED / NOT VERIFIED / INCONCLUSIVE の3値で、INCONCLUSIVE は合格ではありません。
- Phase D(記録):
/show-me-your-workで判断の軌跡を記録します。野心的な仕事では、軌跡ごとコミットして PR で読めるようにします。 - Phase E(検証と引き渡し): ハーネスだけでなく実製品全体を Phase A の述語で確かめます。再発する訂正は、ゲートや lint、チェック、スクリプトとして構造に埋め込みます。
- 注意点
- 「通りやすすぎる」結果が出たら、システムより先に観測方法を疑います。委任した担当がゲートをすり抜けたら、契約を固くしてやり直します。ゲート自体が間違っているなら、ごまかさずゲートを直す変更を別途入れます。
/interrogate — 一言でいうと: 複数モデルの「敵役」に変更を壊させ、実行で証明された指摘だけを残す
- 何をするか
- diff や設計に対して、敵対的レビューを並列に走らせます。各敵役は「壊すこと」が仕事で、指摘は実際のコードで実行して証明されたものだけが残ります。修正はしません。報告だけが成果物です。
- いつ使うか
- 「この PR を尋問して」「敵対的にレビューして」「盲点を探して」「引き裂いて」というとき。通常のレビューより一段深く、思い込みの死角を狙います。
- 進み方
- まず範囲を確定します。指定がなければ、ベースブランチとの merge-base から作業ツリーまでの diff です。意図は
/in-your-own-wordsの要領で、利用者のメッセージ、コミット、PR 説明から言語化します(曖昧なら聞きます)。 - 次に
/arenaの枠組みの一部(ランナー選定と並列起動)を流用して敵役を走らせます。各敵役は専用 worktree に未コミットの変更もコピーして受け取り、「失敗するテスト、再現スクリプト、誤った挙動を示すコマンド出力で証明せよ。実行していないものは出すな」という指示を受けます。設計や計画が相手なら、プロトタイプを動かすか現行ツリーを調べさせます。 - 検証では、各指摘のコマンドを再実行し、出力が失敗を示し、かつ意図を壊しているものだけを残します。根本原因が同じ指摘は統合します。
- 出力は、意図の言い直し、検証済み指摘(コマンド、出力、意図のどこを壊すか、見つけた敵役)、そして落とした指摘の数と理由です。「検証済みの指摘なし」も正当な結果です。
- まず範囲を確定します。指定がなければ、ベースブランチとの merge-base から作業ツリーまでの diff です。意図は
- 注意点
- スタイル、命名、構造、将来の変更があって初めて問題になるリスクは、最初から対象外です(実行で証明できないため)。
/arenaの「優勝者を選んで接ぎ木する」フェーズは使いません。敵役ごとに違う失敗を見つけるので、全員の検証済み指摘を残すのが正解です。
- スタイル、命名、構造、将来の変更があって初めて問題になるリスクは、最初から対象外です(実行で証明できないため)。
/in-your-own-words — 一言でいうと: 作業前に、エージェントが理解した「あなたの目的と課題」を自分の言葉で言い直す
- 何をするか
- それだけです。利用者の目標と、解こうとしている問題を、エージェントが自分の言葉で言い直します。pstack の中で最も短いスキルの1つで、本文は実質この1文だけです。
- いつ使うか
- 大きな依頼や曖昧な依頼の冒頭に。認識のずれを、コードを書き始める前に表面化させるための安全装置です。
/interrogateなど他のスキルも、意図確認のためにこの考え方を使います。
- 大きな依頼や曖昧な依頼の冒頭に。認識のずれを、コードを書き始める前に表面化させるための安全装置です。
- 進み方
- 利用者の言葉から目標と問題を読み取り、言い直して返す。以上です。ずれていると言われれば、それが収穫です。
- 注意点
- 言い直しが目的なので、ここで作業を始めてはいけません。自分で打ったときだけ動きます(自動起動しません)。
/blast-radius — 一言でいうと: 変更が「別の場所で」壊すものを出荷前に見つけ、安全の根拠を1つの事実に絞って実行で証明する
- 何をするか
- 変更の影響範囲を、diff の外側まで調べます。呼び出し元を列挙するのは仕事のうちに入りません(grep で一瞬です)。仕事は、grep では見えない壊れ方 — 依存ライブラリ内部の挙動、実行タイミング、API が返す JSON や DB の列や wire フォーマット、フィーチャーフラグ、3ホップ下流のコード — を特定することです。
/howが「何をするコードか」、whyが「なぜこの形か」を答えるのに対し、これは「別の場所で何が壊れるか」を答えます。
- 変更の影響範囲を、diff の外側まで調べます。呼び出し元を列挙するのは仕事のうちに入りません(grep で一瞬です)。仕事は、grep では見えない壊れ方 — 依存ライブラリ内部の挙動、実行タイミング、API が返す JSON や DB の列や wire フォーマット、フィーチャーフラグ、3ホップ下流のコード — を特定することです。
- いつ使うか
- 「この変更の影響範囲は」「何が壊れる?」、そして小さく見えるのに信用できない diff のレビューに。
- 進み方
- まず変更を読みます。diff、追加・変更・削除されたシンボル、そして diff に書かれていない挙動の変化まで含めます。
- 次に「安全なのはこの1つの事実のおかげだ」という事実を見つけます(例:「この呼び出しは死んだキャッシュ項目を落とすだけで、他に何もしない」)。これが成り立てば、怪しいケースの大半が一度に消えます。長い「かもしれない」リストより、ここに時間をかけます。
- grep の届かない場所を読みます。呼び出すライブラリのソース、その固定バージョンとローカルパッチ。マイクロタスクやアンマウント・teardown のタイミング、フレームワークごとの差。シンボル検索が取りこぼすデータの流れ。
- 各リスクには、起こる確率と起きたときのコストを正直に付けます。確認したリスクと、調べて解消したリスクは分けて書きます。根拠は実在の
file:lineで、「検索して何もなかった」も立派な答えです。呼び出し元や API を捏造しません。 - 最後に、その1つの事実を証明します。実コードを呼ぶ小さなスクリプトやテストを書いて実行し、結果を貼ります。大きな変更では
/arenaで複数モデルに同じ問いを投げ、答えを統合します。
- 注意点
- もっともらしく書けた文章自体は証拠になりません。このスキルは「書けたこと」を成果物にせず、確からしさを5段階(言っただけ → 行を指した → 悪いケースが起きないことを追った → 実行した → 動いているアプリで再現した)で測り、どこまで行けたかを明示します。証明できなければ「unproven(未証明)」と書きます。依存スキルとして
/arena、/how、/why、/unslopが要ります。
- もっともらしく書けた文章自体は証拠になりません。このスキルは「書けたこと」を成果物にせず、確からしさを5段階(言っただけ → 行を指した → 悪いケースが起きないことを追った → 実行した → 動いているアプリで再現した)で測り、どこまで行けたかを明示します。証明できなければ「unproven(未証明)」と書きます。依存スキルとして
設計
コードを書く前に「形」を決めるための分野です。型と境界のスケッチ(/architect)、状態遷移の形式検証と図示(/statechart)、複数案の競作と統合(/arena)の3つが入っています。共通するのは、「書き始めてから間違いに気づく」より「始める前に形で決着をつける」ほうが安い、という考え方です。
/architect — 一言でいうと: コードを書く前に、型・シグネチャ・モジュール構造の形を決める
- 何をするか
- 変更が触れるすべてのシステムをたどったうえで、形の違う2つの案をスケッチします。スケッチの対象は、型、関数のシグネチャ、モジュールの境界です。その後、実装がその形を埋めていく間もループの中に残り、形が崩れないよう見守ります。
- いつ使うか
- 関数境界をまたぐコードを書く前。いきなり実装に入ると、間違った形のまま固定されてしまうような非自明な仕事で使います。「これを設計して」と言って
/architectを添えるのが典型です。
- 関数境界をまたぐコードを書く前。いきなり実装に入ると、間違った形のまま固定されてしまうような非自明な仕事で使います。「これを設計して」と言って
- 進み方
- 影響範囲を追跡する → 2案をスケッチする → 選ぶ基準は「状態の持ち主が1つずつに定まるか」「各タスクのやり方が1つに定まるか」「呼び出し側が知らなければならないことが最小か」です。この基準で勝つ案を選びます。回避策が繰り返し現れるようなら、パッチを重ねるのでなく再設計に切り替えます。
- 注意点
- 設計が大きい、あるいは意見が割れる場合は、1人でスケッチせず
/arenaを回して複数案を競わせます(/arenaが依存スキルです)。逆に、形が既に具体的に決まっている機械的な作業にこの手順を持ち込むと過剰になります。自分で打ったときだけ動きます。
- 設計が大きい、あるいは意見が割れる場合は、1人でスケッチせず
/statechart — 一言でいうと: 状態遷移するシステムを TLA+ で検査し、結果を「読む人の言葉」の状態図で見せる
- 何をするか
- 製品フロー、プロトコル、サービスなど、状態の間を移り変わるシステムの振る舞いを TLA+ モデルで検査(TLC)し、Mermaid の状態図として描きます。図では、ルールを破る状態に印が付き、報告書は各違反への最短経路を示します。狙いは、仕様書を読ませるのではなく、振る舞いの持ち主が図を見て「正しいかどうか」を判断できるようにすることです。
- いつ使うか
- 競合、リトライ、状態機械が絡む振る舞いを関係者に見せて合意したいとき。バグを「状態の経路」として示したいとき。
- 進み方
- リポジトリの外の作業フォルダで TLA+ の仕様と設定を書きます。読む人が合意したルールは、すべて INVARIANT として書きます。モデルにそのルールを表す変数がなければ、変数を足します。通すためにルールを弱めることはしません。
- 同梱のスクリプトで TLC を実行します(初回は TLC と Java を mise で導入するため、ネットワークが必要です)。
- 図の言葉づかいは view モジュールで別に用意します。状態や矢印のラベルは、読む人が見ている言葉(「Paying」「you press play」など)で書き、変数名や TLA+ のアクション名は出しません。矢印は約20本以下を目安に、同じ振る舞いの値には同じラベルを与えて図を粗く保ちます。ただし、違うルールを破る状態同士は統合しません(どこで何が破れるか見えなくなるため)。
- できあがった
chart.mmdを提示し、違反ごとに「ルール、読む人の言葉でのそのルール、最短経路」を1行ずつ添えます。モデルが何を省略したかも伝えます。 - モデルが実コードを表しているなら、各違反経路を実コードに対してテストや再現でなぞり、本当に起きるか確かめます。再現しなければ、コードでなくモデルが間違っていると考えます。
- 注意点
- 状態爆発に注意が必要です。定数は小さく保ち、必要なら CONSTRAINT を使います。ルールが破れるたびに、そのルールを外して再実行する方式なので、大規模なモデルでは「未検査のルール」が残ることがあります(報告書に明示されます。そのルールは成り立つかもしれないし、破れるかもしれません)。状態数が上限(500状態)を超えると全体の図は描かれず、違反経路だけが示されます。全体を見たいならモデルを小さくします。自分で打ったときだけ動きます。
/arena — 一言でいうと: 同じタスクに N 個の候補を並列で挑ませ、勝者を土台に敗者の良い部分を接ぎ木する
- 何をするか
- 「1回の試行で形が固定されてしまう」ことを避ける仕組みです。複数のモデル(候補)にまったく同じプロンプトで成果物を作らせ、採点基準に沿って評価し、最良の1つを土台(ベース)に選び、敗れた候補から強い部分だけを移植して、1つの統合された成果物にします。
- いつ使うか
- 設計、実装、文書など、最初の形が間違っていると後で高くつく非自明な成果物に。
/architectから設計の競作として呼ばれることもありますし、「これを arena にかけて」と直接頼むこともできます。
- 設計、実装、文書など、最初の形が間違っていると後で高くつく非自明な成果物に。
- 進み方
- Phase A(枠組み): 全候補に同じプロンプトを渡すので、プロンプトが契約になります。成果物を定義し、この課題専用の採点ルーブリック(3〜6個の、採点可能な具体基準)を作ります。候補にはタスクだけを見せ、ルーブリックは選ぶ側の道具です。ランナーは設定ファイルの
arena runnersから選び(既定は Fable、Opus、Gemini 系の3モデル)、各候補に git worktree などの独立した出力先を与えます。 - Phase B(並列実行): 全候補を一度に起動します。各候補には、成果物に加えて「検討した代替案と、却下した理由」を短く書かせます。出力のない候補が出たら、残りで進めて脱落を記録します。
- Phase C(相互審査): 親とは別ベンダーの審査役を1つ立て、候補をパス名だけで参照させて、ルーブリックの基準ごとに採点とベースの推薦をさせます。
- Phase D(ベース決定): 全候補を端から端まで読み、全体の印象ではなく基準ごとに採点します。審査役と一致すれば確定、不一致なら、どちらかの偏りかルーブリックの曖昧さとして、両方の根拠を読み直してから決めます。選ぶ基準は「将来の保守者が不変条件を壊さずに拡張しやすいもの」。同点なら、境界がきれいな方、API が小さい方を取ります。
- Phase E(接ぎ木): 敗れた候補をもう一度歩き、移植する価値のあるものを候補ごとに1〜2個だけ拾います。機械的に貼るのではなく、1つのメンタルモデルの下で一貫するよう手作業で織り込みます。
- Phase F(検証): 統合した成果物を通常の成果物として検証します。ここで問題が見つかれば、Phase A の枠組みが間違っていた(組み直して再実行)か、候補のどれかが見抜いていたのに接ぎ木で取りこぼした(Phase E に戻る)かのどちらかです。ごまかして覆いません。
- 成果物には短い統合メモを添えます。ベースとその理由、審査役の判定、各接ぎ木の出所、却下したものと理由、候補の収束や脱落、検証結果です。
- Phase A(枠組み): 全候補に同じプロンプトを渡すので、プロンプトが契約になります。成果物を定義し、この課題専用の採点ルーブリック(3〜6個の、採点可能な具体基準)を作ります。候補にはタスクだけを見せ、ルーブリックは選ぶ側の道具です。ランナーは設定ファイルの
- 注意点
- 候補が同じ形に収束したら、それは強い合意です。接ぎ木は不要で、合意した形をそのまま出します。逆に候補が大きく発散したら、Phase A の指定が不足しています。発散の平均を取らず、枠組みを直して再実行するのが正解です。コストは候補の数だけかかるので、判断が要らない生成中心の仕事では、同じモデルを複数走らせる使い方もします。
実装と品質
コードを書く局面で効くスキル群。テストで直す(tdd)、繰り返されるミスを構造で封じる(correct)、頼み方そのものを深くする(sharpen)、文章の AI 臭を落とす(unslop)、コメントを監査する(no-comments)、型で不正な状態を表せなくする(typescript-best-practices)が並ぶ。
/tdd — バグを先に「失敗するテスト」にしてから直す
- 何をするか: テストで再現できるバグについて、修正前に落ちる回帰テストを書き、修正後に通ることを確認する。結果ではなく証拠を報告させるのが眼目。
- いつ使うか: ユーザーが TDD・失敗するテスト・回帰テストを明示したとき、または安く書ける局所的なテスト対象が明らかなバグのときだけ。
disable-model-invocation: trueで、モデルの判断による自動発動はしない。 - 進み方:
- バグを理解する。期待する振る舞い、現在の振る舞い、影響する経路、最小の再現を特定する。
- そのコードパスで既に使われている一番狭いテスト(ユニット、コンポーネント、統合、回帰)を選ぶ。実用的なテスト経路が見当たらなければ、無理に作らない。
- バグを捕まえたはずの最小のテストを先に書く。テストは現在の実装ではなく、意図した振る舞いを符号化する。
- 修正前にテストを実行し、意図した理由で落ちることを確認する。通ったり無関係な理由で落ちたりしたら、実装に触る前にテスト側を直す。
- 近くの契約を壊さない最小の変更で直す。
- テストを再実行して通ることを確認する。
- 注意点: 失敗するテストが非実用的なら、対象を絞ったスクリプト、手動の再現コマンド、ブラウザ自動化、スナップショット比較など「一番近い実行可能なチェック」で代替する。悪いテスト(モックばかりを検証する、実装詳細を固定する、タイミング依存、高価な基盤が要る)は、無いほうがまし。テストを間違った実装に合わせて書き換えること、根拠なくアサーションを弱めることは禁止。最終報告では「修正前に落ちたテストとその失敗」「修正後に通った実行」を名指しし、修正前の失敗を示せなかった場合は理由と代替チェックを述べる。
/correct — 繰り返されるミスを、次は起こせない構造に変える
- 何をするか: リポジトリでエージェントが繰り返すミスの「クラス」を見つけ、クラスごとに再発不能にする。運用者がエージェントを訂正するたびに回す前提のスキル。
- いつ使うか:
/correctと呼ばれたとき。同じ訂正が何度も入るリポジトリで使う。 - 進み方:
- 最近のコミット、リバート、レビューコメント、エージェント指示ファイル、回避策を説明するコメントを読み、ミスをクラスに分ける。2回起きたらクラスとして数える。
- 各クラスを「効く一番高いレベル」で直す。順序は固定で、(1) アーキテクチャで消す(状態の所有者を1つにする、内部を隠して間違った import を失敗させる、手作業で同期するリストを単一の情報源に置き換える、古いやり方とデッドコードを消す)。(2) 型で強制し、不正なコードがコンパイルできないようにする。それでも通るなら、使うべきファイル・型・関数をエラー文で名指しする lint や CI を足す(既に蔓延しているパターンは「増えた分だけ」失敗させる)。(3) 振る舞いをテストする。対象の振る舞いが壊れても通るテスト、内部変更だけで落ちるテストは直すか消す。(4) ドキュメントやエージェント向けルールは最後。判断が要る事項だけに書き、守られなくても何も失敗しないことを自覚する。
- 頻度の高いクラスから直し、1クラス1コミット。各チェックが「実際の過去のミス」で落ちることを証明する。ローカルと CI で同じコマンドを走らせる。例外は該当行に理由・期限・人間の承認付きで書く。
- エージェント指示ファイルに「ルールと、それを強制する仕組み」の対応表を維持する。訂正されたらミスを直してルールを追加する。ルールが既にあるのに強制が無ければ再発とみなし、同じ変更の中で一番高いレベルで直す。ミスが起こせなくなったらルールを表から落とす。
- 注意点: 前提は「エージェントは開いたファイルしか見ず、近くの例を真似し、コンパイルが通る最短経路を取る」というもの。1ファイルから見て正しそうな変更が、リポジトリ全体でも正しくなるよう設計する。返答ではクラスごとに証拠、選んだレベル、より高いレベルが使えなかった理由を示す。
/sharpen — タスクを大きくではなく深くして、プロンプトを書き直す
-
何をするか: 依頼文を書き直す前に「深さ」を点検し、その結果を反映したプロンプトに書き換える。対象はコードに限らず、あらゆるタスクの頼み方。
-
いつ使うか:
/sharpenと呼ばれたとき。依頼が浅いまま走り出すのを防ぎたいとき。 -
進み方: 書き換えの前に4つを述べる。
- その分野のトップのプロなら、頼まれていない何をするか。
- 既に消化済みの素材ではなく、彼らが起点にする一番生の素材は何か。
- 彼らが使う具体的な方法とツールは何か。
- 自分とエージェント以外に、結果が正しいと示せるものは何か(検証可能性)。
そのうえで、その内容を正確に求めるプロンプトに書き換える。書き換えたプロンプトには「実験で決着がつく選択はプロトタイプを作って試し、観測に基づいて推奨案を出す」ことを求める。実験では決着しない製品判断や好みの選択は、ユーザーに残す。
-
注意点: 狙いはスコープの拡大ではなく深掘り。検証者を先に名指しさせる点が、このスキル集全体の「証拠で示す」姿勢とつながっている。
/unslop — 文章から AI の癖を取り除く
- 何をするか: 文章を走査し、AI らしいパターンを除去して書き直す。意味と意図したトーンは保つ。ルールには安定した番号が振られ、他のスキルから番号で参照される(削除したルールは欠番になる)。
- いつ使うか:
/unslopと呼ばれたとき。ドキュメント、PR 本文、ログなど、AI が書いた文章全般が対象。show-me-your-work のログ文にも適用される。 - 進み方: パターンの一覧に照らして走査し、該当箇所を書き直す。主なルールは次のとおり。
- 事実を足さない末尾の “-ing” 句を消す。曖昧な帰属(「専門家によれば」)は出典を名指すか消す。
- AI 語彙を避ける: additionally, crucial, delve, enhance, foster, landscape, pivotal, showcase, testament, underscore, vibrant。
- “serves as” などと言わず “is” / “has” と言う。「X だけでなく Y」構文を使わず、要点を直接述べる。物事を無理に3つにまとめない。同じ物には同じ名前を繰り返す。
- ダッシュ(em/en/hyphen のダッシュ用法)と、その代用の括弧を使わない。文を切るか読点にする。コロンはリストや例の前にだけ置く。
- 固有名詞や略語を全部太字にしない。行を言い換えるだけの太字ラベル+コロン見出しをやめる。見出しは文頭だけ大文字。装飾絵文字なし。引用符は直線型。チャットボット的フレーズ(“I hope this helps!” など)なし。褒めや同意から始めない。
- 冗長表現を切る(“in order to” は “to”)。ヘッジは “may” を最大1回まで。一般的な結論で締めず、具体的な計画か事実を述べる。
- substrate や flywheel のような抽象的な比喩名詞を使わず、具体的な語にする。仕組みや数字を名指し、別のプロジェクトの文書にそのまま置ける文は切る。1文に1つの考え。能動態で行為者を名指す。副詞は切るか強い動詞に替え、数字を出す。“utilize” でなく “use” のような平易な語を使う。文字どおりの言い換えがある所に比喩や格言、コードの擬人化を使わない。文は冠詞と動詞まで省略せずに書き、矢印や略語は展開する。
- 注意点: ルール番号は他スキルからの引用に使われる安定 ID なので、番号の付け替えはしない。
/no-comments — 専用サブエージェントにコメントを監査させ、採否を判定する
- 何をするか: コードベースのコメントを精査する専用サブエージェント「Comment Sicko」を起動し、その指摘のうち受け入れたものを修正する。コメントで縛るしかなかった制約については、型・実行時チェック・テスト・CI lint への「符号化」を提案する。
- いつ使うか:
/no-commentsと呼ばれたとき。対象は呼び出し側が渡したファイルか差分。無ければベースブランチ(既定はmain)に対する作業ツリー込みの現在の差分。 - 進み方:
- Comment Sicko を起動する。Cursor + pstack プラグイン環境では
comment-sickoサブエージェント、それ以外のハーネスでは汎用サブエージェントにreferences/comment-sicko.mdのプロンプトをそのまま渡す。サブエージェントが無い環境では、自分が新しいパスでそのプロンプトを実行する。推論レベルは poteto-mode のサブエージェント節に従って仕事ごとに選ぶ。 - 報告と差分を検査し、採否を判定する。アプリケーションコードへの編集、範囲外への逸脱、例外で保護された削除、根拠を誤述した
MUST KILL、「有罪」とされた意図的なコードへの指摘は却下する。保持(keep)は「変えられないものについてのコメントだ」という証明がある場合だけ認める。範囲内の lint や TypeScript の抑制コメントの見落としも監査し、正しさ・安全性のための抑制はMUST KILLとして扱う。薄いIMPORTANTや「消すな」という指摘は、シンボルを追うか/whyを実行してから採否を決める。kill が曖昧なら復元しない。keep が反証されたり曖昧なままなら消す(外部ルールに関するREVIEWkeep は、そのルールを誰かが確認するまで残し、未解決として報告)。却下した報告は失敗点を名指しして1回だけ差し戻し、再実行も却下なら却下分だけ戻して未解決として報告し、受理分で進む。 - 自明な受理分(デッドパスの削除、引数の削除、本物の API の使用)は直接直す。形の変更が要るものがあれば、受理分全体について
/architectを1回だけ走らせ、スケッチで止める。 - 範囲内で最小の根本原因修正を実装し、名指しされた回避策を全部取り除く。根本原因が範囲外なら、範囲内の最小修正を入れて残りは未解決として報告する。対症療法のガードを後付けしない。
- 「消すな」「文言を変えるな」「変える前に X に聞け」という制約コメントについては、変えられないものに関する keep は残す。それ以外は範囲内で一番安い型・実行時・テスト・CI lint の符号化を提示し、対話中なら承認を待つ(無人実行や評価では呼び出し側の事前承認が要る)。承認されれば符号化してからコメントを消す。されなければコメントを消し、制約は未解決として報告し、範囲外の作業の見取り図を示す。
- 削除数、復元したコメント、
REVIEWkeep、再実行、architect のスケッチ、修正、符号化の提案と実施、強制されていない制約、その他の未解決作業を報告する。
- Comment Sicko を起動する。Cursor + pstack プラグイン環境では
- 注意点: 判定の主導権は起動側にある。Sicko の新鮮な視点は尊重するが、その報告を鵜呑みにしない、という二段構えがこのスキルの肝。
/typescript-best-practices — 型で不可能な状態を表せなくする
- 何をするか:
.ts/.tsxファイルを読む・編集するときに適用する TypeScript の実践集。先に principle スキルの type-system-discipline を適用することが前提になっている。 - いつ使うか: TypeScript ファイルを扱うとき全般(
pathsで対象が宣言されている)。 - 進み方: ルール表に沿って書く。骨格は「モデル化」「検証」「絞り込み」の3つ。
- モデル化: バリアントは
kindリテラルを判別子にする判別共用体で表し、オプショナルフィールドの寄せ集めにしない。プリミティブは& { readonly __brand: "X" }でブランド化し、境界で一度だけ検証する(ブランドは検証する型ガードから得るもので、asからは作らない)。形そのものを、違法な値が構築できないように設計する(非空は[T, ...T[]]、偶数長は[T, T][]、範囲は start + duration)。ただし全ての操作が全域的でいられる間は素のT[]を保ち、!やキャストや「起こるはずがない」throw を強いられる場所でのみ強い型に上げる。 - 検証: 外部データは
anyでなくunknown。プロパティごとの型ガードを手書きする前に、リポジトリの実行時スキーマライブラリで型を推論する(z.inferなど)。asキャストは使わない(検証の後だけ)。境界で名前付きドメイン型にパースし、内側では型を信頼する。新しい interface を宣言する前にPick/Omit/Parameters/ReturnType/Awaited/typeofで導出できないか見る。 - 絞り込み: 優先順位は、判別子 switch、
in演算子、typeof/instanceof、ユーザー定義型ガード、asの順。型ガードは主張を実際に検証しなければならず、嘘のガードはasより悪い。名前はisX/hasX。default 節にconst _exhaustive: never = x;を置いて、新しいバリアント追加時にコンパイラが怒るようにする。asの代わりにsatisfiesを使う。 - その他: 引数は位置引数でなくオブジェクトで渡す(ホットパスは除く)。テストはモックで済ませず、実物のテストプリミティブとリーク・破棄チェックを優先し、UI は動いているビルドで確認する。出荷コードに
console.logを残さず、構造化ロガーで id から追える診断を出す。
- モデル化: バリアントは
- 注意点: 例は
references/patterns.mdにある。型を強くすること自体が目的ではなく、「不正な状態を書けない」ことが目的で、強い型への移行は必要になった場所に限る、という抑制が効いている。
検証
pstack の心臓部。「動いたはず」ではなく「動かして証拠を残した」状態を作るためのスキル群である。
中心にあるのは verification skill(検証スキル)という発想だ。これはプロジェクトごとに作る、そのプロジェクト専用のスキルで、「このアプリをユーザーのように起動し、操作し、証拠を取る手順」を、次に来るエージェントが冷めた状態で読んでも実行できる形で書き留めたものだ。汎用のテスト実行手順ではない。対象アプリの起動コマンド、待ち受けるポート、種データ、安定したセレクタ、証拠の置き場所まで、そのリポジトリ固有の事実で埋まっている。create-verification-skill がこれを生成し、maintain-verification-skill がアプリの変化に追随させる。
もう一つの軸が formal verification(形式検証)だ。こちらはアプリを操作するのではなく、コードの性質を「述べられた範囲の全ケース」について機械的に確かめる。テストは誰かが書いたケースしか見ないが、形式検証はステップの全順序や、 bound までの全入力を見る。create-formal-verification-skill が対象と道具を選び、maintain-formal-verification-skill がコード変更との同期を保つ。
残る2つは横断的な規律で、benchmark-checklist が性能の数字を報告前に吟味し、show-me-your-work が長時間・無人の作業にレビュー可能な判断の記録を残す。
/create-verification-skill — プロジェクト固有の検証スキルを生成する
- 何をするか: 対象リポジトリを調査し、そのアプリをユーザーのように駆動して振る舞いを証明する手順を、プロジェクトローカルのスキル
verify-<app>として生成する。言語、フレームワーク、プラットフォームは問わない。 - いつ使うか:
/create-verification-skillと呼ばれたとき、「このリポジトリの操作スキルを作って」と頼まれたとき、UI・CLI・サービスの振る舞いを証明するスクリプト化された方法がプロジェクトに無いとき。 - 進み方:
- ユーザーではなくリポジトリに聞く。観察できることはコードベースから答え、観察できないことだけユーザーに聞く。調べるのは5点。(a) Surface: ユーザーが実際に触るのは Web UI、CLI/TUI、デスクトップ、API、モバイル、ライブラリのどれか(複数あれば主を選び、残りを記す)。(b) Run: ローカルでの起動方法。リポジトリ自身の文書にある開発コマンドを優先し、ポート、環境変数、種データ、認証を記録する。(c) Drive: エージェントがプログラム的に操作する方法。既存のハーネス(Playwright/Cypress の spec、expect スクリプト、PTY ヘルパー、curl 可能なエンドポイント、デバッグポート)を先に探し、無ければ Web と Electron はブラウザ/CDP、CLI/TUI は tmux/PTY、サービスは素の HTTP という汎用レシピを選ぶ。(d) Observe: 取れる証拠(スクリーンショット、端末の記録、レスポンス本文、ログ、終了コード、DB の状態)。(e) Isolate: 2つのインスタンスを並べて動かせるか。できないなら、その旨を生成スキルに書き、共有インスタンスの二重駆動を拒む。
- スキルを生成する。置き場所はハーネスのプロジェクトスキルフォルダ(Cursor は
.cursor/skills/、Claude Code は.claude/skills/、Pi は.pi/skills/、Codex や OpenCode などは.agents/skills/)。frontmatter(name: verify-<app>と、アプリ・対象面・使う場面を名指しする description)が無いとスキルとして登録されない。本文にはプレースホルダを残さず、Launch(正確な起動コマンド、使える状態になった合図、teardown。空のデータディレクトリからマイグレーションと種データ込みで使える状態に届くことが条件で、プロセスが応答するだけでは不十分)、Doctor(このインスタンスを駆動する価値があるかを答える読み取り専用の1チェック)、Drive(座標やタブ順ではなく ARIA ラベルや data 属性などの安定したハンドルを使う、このリポジトリの実際のセレクタとコマンド)、Evidence(実ユーザーの経路を踏む、操作と結果の状態の両方を撮る、副作用も確かめる、といった証明の基準)、Cleanup(自分が起動したものだけを止める。証拠は消さない)、Helpers(同梱スクリプトは実行可能にし、呼び出し方を本文に書く)の各節を、調査で分かった事実で埋める。 - 機能マップの種をまく。
features/README.mdと、ユーザーが触る機能ごとのファイル(ルート、コマンド、メニュー、文書から、まず上位3〜5件)を作る。各ファイルはユーザーの視点で、その機能が何か、どう届くか、ハーネスでどう駆動するか、何が観測できれば動いたと言えるかを書く。見出しはSub-features、How to get to it (user POV)、Driving it with <harness>、Gotchasの4つで固定。種データに前提が欠けていてジャーニーが失敗するなら、ジャーニーを弱めて通すのではなく、失敗として報告し理由をその機能の Gotchas に書く。 - 渡す前に、自分で生成スキルを端から端まで1回実行して証明する。起動、Doctor、機能マップのうち1機能の駆動、証拠の取得、後片付けを行い、後片付けの後に証拠が指定の場所に残っていることを確認する。失敗した試行の後にも生成した後片付けを走らせ、プロセスやポートを残さない。実行されたことのない生成スキルは成果物ではなく下書きである。本物とは別の代用品(実 VM の代わりのコンテナなど)で証明した場合は、代用品だけが行った設定手順を列挙し、それらは本物での実行まで未検証と明記する。
- 保守の入口として
/maintain-verification-skillを案内する。頻度はユーザーが聞いたときだけ提案する。
- 注意点: チェックアウト自体がビルドできない、起動しない状態なら、生成の前に直す(または正確に報告する)。壊れた土台の上に書いたスキルは間違った手順を教える。起動を妨げる無関係な欠落資産(API が配信しない静的ディレクトリなど)は、検証用の足場と明記したうえで生成スキル側で作り、後片付けで消してよい。
/maintain-verification-skill — 検証スキルと機能マップを正直に保つ
- 何をするか: アプリの変化で腐っていく検証スキルと機能マップを、定期パスで実態に合わせ直す。厳密さの単位は文ではなく機能で、全機能についてソースの確認と実機での駆動を行う。
- いつ使うか:
/maintain-verification-skillと呼ばれたとき、「verify スキルを監査して」と頼まれたとき。 - 進み方:
0. 結果を最初に決める。clean(全機能にソースと実機のカバレッジがあり、出荷するもの無し。ブランチも PR も作らない)、changed(証明済みの修正を1つの PR で出す)、blocked(カバレッジが完走しない、または証明済みの修正を安全に出せない。何が塞いだかを正確に言う)のどれか。
- 対象を特定する。launch/drive の節と機能マップを持つプロジェクトローカルのスキル(多くは
verify-*/)を探す。候補が複数なら聞く。無ければ作らず、/create-verification-skillを指し示して止まる。 - 索引の衛生。機能マップの README と同階層のファイルを見て、欠落、余分、重複、死んだエントリを直す。
- ソースの波。機能ファイル1つにつき読み取り専用のサブエージェントを1つ、並行に起動する。各サブエージェントは「この機能はどう動くか」をソースから説明し、引用付きで文書のずれらしきものを挙げ、簡潔な実機検証レシピを1つ返す。サブエージェントはアプリを駆動せず、ファイルも編集しない。
- すり合わせ。全機能分の要約が揃ったことを確認し、重なるレシピはできるだけ少ないアプリ状態に統合する。引用されたずれはスポットチェックし、きれいだという主張は再証明しない。最近の変更を走査し、マップに無いユーザーが触る面を探す(具体的なソースパスを示せないものは「欠落」と呼ばない)。
- 実機パス。ソースがきれいに見えても必須。駆動はコーディネータが全部持ち、検証スキル自身の起動モデルに従う(サーバや UI は長寿命の1インスタンスを直列に、短命な CLI は駆動ごとに新しい隔離セッション)。全機能を最低1回は動かし、パス全体で3つの不変条件を守る。(1) 最後に妙な振る舞いをして以降ヘルスチェックしていないインスタンスを駆動しない(初回駆動前、各セッション開始時、失敗した駆動の後に Doctor を走らせる。Doctor で見えない失敗は、既知の状態へのリセットか再起動で対処する)。(2) ここまでに取った証拠は、どの後片付けでも生き残る。想定でなく指定場所で確認する。(3) 駆動が始めたものは、その駆動の役目が終われば残さない。最終 teardown は再証明を含む全駆動の後に行う。Doctor の失敗がスキルのずれ由来なら、それはドリフトとして編集範囲内で直し、無効化されたものだけ再起動して1回だけ再試行する。それでも駄目なら blocked。機能に届かない場合は、前提(認証、権限、OS、外部状態)と試した経路を具体的に示せたときだけ
verified-unreachableとする。その前提がマップに無いこと自体がドリフトである。 - 切り分け。ユーザーの視点の説明が間違っている、欠けているなら文書ドリフトとして直す。振る舞いはあるのにハーネスが駆動できないならハーネスの欠落として直す。アプリの振る舞い自体が壊れているなら製品側の問題として記録し、この PR には入れない。
- 出荷か停止か。changed なら、変更したファイルを全部読み直してから、証明済みの修正だけの1つの PR を出す。clean か blocked なら PR は作らず、結果とカバレッジを正直に報告する。
- 対象を特定する。launch/drive の節と機能マップを持つプロジェクトローカルのスキル(多くは
- 注意点: 編集範囲は検証スキル自身のディレクトリだけ。製品コードはこのパスでは絶対に編集しない。マップが述べる振る舞いをアプリがもうしていないなら、それは文書ドリフト(マップを直す)か製品の回帰(報告する)のどちらかで、文書側で覆い隠さない。実行メモ(対象機能、届かなかった前提、確認したずれ、結果)はスクラッチに残し、コミットしない。
/create-formal-verification-skill — 一番壊れて困る場所を形式検証するスキルを生成する
- 何をするか: テストが届きにくく、バグの代償が一番大きい場所を選び、性質を1つ形式検証し、その性質に対して変更をチェックできるプロジェクトローカルのスキルを残す。
- いつ使うか:
/create-formal-verification-skillと呼ばれたとき、「この競合をモデル検査して」「この不変条件を証明して」と頼まれたとき、並行処理、リトライ、状態機械、パーサ、unsafe コードにテスト以上の保証が要るとき。 - 進み方:
- 対象をコードから選ぶ。良い対象は「コードが交わす約束」のうち、壊れるとユーザーが傷つき、壊れるケースにテストが滅多に届かないもの。検証しやすいものではなく、リポジトリで一番強いそういう対象を選ぶ。ユーザーが領域やバグを名指ししていたらそこから始める。
- 質問に道具を選ばせる。一番安くその質問に答える道具を使う。イベントが悪い順序で起こりうるか、という問いには設計の小さいモデルに対するモデル検査が向き、その既定は言語を問わず TLA+。メモリ安全性やオーバーフロー、データ構造の不変条件のように「コード自体が全入力で正しいか」には、コードに対して走る検証器が向く。その言語で動く検証器が無ければそう言い、手で書いた関数のモデルではなく、実コードを生成入力でテストする。bound では足りず全サイズで要る性質には証明が要ることがある。開発者がインストールして走らせられる道具を優先し、選んだ理由をユーザーに伝える。
- 生成するスキルが満たすべき条件を押さえる。(a) コードに忠実: モデルや証明の各部が、レビュー担当者が開けるコードを指す。検証側で不可分の1ステップと扱うものは、コードでも不可分の1ステップ。名前はそのリポジトリのものを使う。(b) 失敗できる: 一度も落ちたのを見たことがないチェックは何も証明しない。チェックを外す、ステップを入れ替えるなど、守る対象の壊れた変種で各性質が落ちることを示す。(c) 発見は発見のまま: 現在のコードが性質を破るなら、コードの言葉で反例を示して報告する。通過するまで性質やモデルを弱めない。製品コードはユーザーが頼まない限り変えない。(d) 範囲に正直: 何を、どの bound と前提で検証し、何を外したかを述べる。通過がカバーするのはモデルか bound であって、システム全体ではない。(e) 道具なしで読める: 性質と危害を平易な一文ずつで述べ、反例はコードの言葉で短いステップ列として語る。(f) 再実行が安い: 1コマンド、再現可能な道具のバージョン、次のエージェントが関連する変更のたびに使いたくなる短さ。(g) コードと同期する: 各チェックが覆うファイルと関数と、検証がそのコードを表していると最後に確認したコミットを記録する。
- スキルを書く。frontmatter に領域と使う場面を書き、プレースホルダを残さない。読んだエージェントが、変更が検証対象のコードに触れるか判断でき、チェックを実行でき、本物のバグとモデリングの誤りを区別でき、意図した変更のときに検証を更新できる、という状態にする。カバレッジ記録と同期コミットはスキル内に置き、同期コミットは新しいコミットで検証がコードを表すと確認した後にだけ前へ進める。TLA+ モデルの場合は、結果の読み方として pstack の
/statechartを名前で参照する(不変条件違反は最短パスを平易な言葉で示し、通過時は状態遷移図を描く)。/statechartのコマンドやパスはリリースやマシンで変わるので、生成スキルやスクリプトに写さない。 - 引き渡し前に証明する。生成スキルに次のエージェントとして従い、実コードの性質を壊すスクラッチ変更を入れて、チェックがそれを捕まえることを確認する。スクラッチ変更を捨て、チェックが開始時点の状態(通過、または報告する発見だけでの失敗)に戻ったことを確かめる。壊れを取り逃がしたり手順が走らなかったりしたら、スクラッチ変更ではなくスキルか検証側を直す。
- 引き渡す。何を検証したか、どの道具をなぜ使ったか、bound、チェックが見つけたことを平易な言葉で、実行方法、カバーしない範囲を伝える。近い第二の対象が見つかった場合だけ提案する。保守の入口として
/maintain-formal-verification-skillを案内する。
- 注意点: 通常の verification skill との違いは、対象が「アプリの振る舞い」ではなく「コードの性質」で、証拠が操作の記録ではなく反例か証明であること。そしてユーザーには、検証言語を学ばなくても結果を信頼して行動できる形で渡す、という要件が明示されている。
/maintain-formal-verification-skill — 形式検証をコードの現在に合わせ直す
- 何をするか: コードが変わったのに検証が追随していない状態を解消する。検証対象コードに触れたコミットを見つけ、モデルやハーネスや性質を現在のコードの記述に直し、再実行し、失敗が検証側のドリフトかコード側のバグかを判定する。
- いつ使うか:
/maintain-formal-verification-skillと呼ばれたとき、「モデルはまだコードに合っている?」と聞かれたとき、検証を再チェックしないまま対象コードに触れたマージやリファクタの後。 - 進み方:
0. チェックごとに結果を1つ付ける。in sync(最後の同期以降、チェックの記述を変える変更が無く、通過する)、updated(コードが変わり、検証が新しいコードを記述するようになり、通過する)、bug(検証は現在のコードを記述していて、コードが性質を破る。これはコードについての発見であり、ドリフトではない)、blocked(合わせ直せない、または実行できない。理由を正確に言う)。updated と bug の両方もありうる(更新で記述が戻った結果、性質が落ちる)。
- チェックを見つける。verify スキルに固定の名前は無いので、働きで探す(名前のあるコードに対してモデル検査器や証明器などを走らせるプロジェクトスキル)。各チェックについて、性質、覆うコード、bound と前提、実行コマンド、検証がコードを表すと最後に確認したコミット(同期コミット)を集める。verify スキルが無ければ止まって
/create-formal-verification-skillを指し示す。同期コミットの記録が無ければ、検証ファイルを最後に変えたコミットを使い、その旨を言う。 - 現状のまま1回実行する。何も変える前に各チェックを走らせ、結果を記録する。ここでの通過は「コードが正しい」ではなく「古い記述がまだ成り立つ」という意味にすぎない。失敗がドリフトかバグかは、この時点では決めない。
- 対象コードへの全変更を読む。同期コミットから現在までの対象ファイルの diff と各コミットメッセージを読む。リネーム、分割、別ファイルへの移動も対象コードとして追う。守っている状態に触れる新しいコード(同じフィールドを書く新しい関数など)も探す。各変更を仕分ける。(a) 影響なし: 書式、コメント、検証が覆わない経路など、記述を変えない変更。コミットメッセージではなくモデルやハーネスと照らして判断する。(b) 検証がコードを表さなくなった: 不可分だったステップが2つになった、分岐が増えた・減った、チェックが動いた、守る状態に届く新しい経路ができた、値の範囲が変わった。モデルやハーネスを直す。(c) 約束が意図的に変わった: 変更がコードの約束を変えていて、doc コメント、テスト、変更履歴、コミットメッセージのいずれかに意図の証拠がある。性質を変え、証拠を引用する。(d) 約束が壊れたかもしれない: 証拠なく約束が変わっている。その後の失敗はバグ候補として扱う。
- 結果からではなくコードから更新する。変更した各部が、レビュー担当者が開けるコードを再び指すようにモデルやハーネスを直し、不可分のステップは不可分のままにする。再実行の前にコードから書き、通過する形に寄せない。性質を変えるのは意図的に変わった約束だけにし、旧文・新文・証拠を書き留める。bound は変更が誤りにしない限り保ち、下げる必要があったら報告に明記する。
- 再実行して判定する。通過した場合、そのままでは「失敗する能力を失った記述の上での通過」かもしれないので、新しいコードを性質が守るやり方で壊し(新しいチェックを外す、新しいステップを入れ替える)、チェックが捕まえることを確認してから壊しを捨てる。失敗した場合は、反例を実コードに対してステップごとに再生する。コードで起こりえないステップがあれば検証側が間違いで、検証を直し、何が間違っていたかを言う。全ステップが起こりうるならバグである。導入したコミットを名指しし、反例をコード自身の言葉でステップ列として語り、危害を一文で述べる。安いテストや実コードでの再現で示せるなら、報告に証拠として添える(製品コードにはコミットしない)。
- verify スキルを更新する。各チェックが覆うコード、コマンド、bound、前提、同期コミットを現状に合わせ、同期コミットは確認したコミットに設定する。blocked のチェックについては同期コミットを進めず、その旨を報告する。最後に、次のエージェントとして verify スキルに1回従い、手順がまだ走ることを確かめる。
- チェックを見つける。verify スキルに固定の名前は無いので、働きで探す(名前のあるコードに対してモデル検査器や証明器などを走らせるプロジェクトスキル)。各チェックについて、性質、覆うコード、bound と前提、実行コマンド、検証がコードを表すと最後に確認したコミット(同期コミット)を集める。verify スキルが無ければ止まって
- 注意点: 編集範囲は検証側(モデル、ハーネス、性質ファイル、verify スキル)だけ。ユーザーが頼まない限り製品コードは編集しない。性質が現在のコードで落ちるとき、通過させるために性質やモデルを弱めることは禁止。検証の更新は、製品側の修正とは別の変更に分ける。更新前は通過していたのに更新後に落ちたチェックについては、「古い通過は古い記述の上でのものだった」と明言する。
/benchmark-checklist — 性能の数字を、報告する前に吟味する
- 何をするか: ベンチマークの測定値が主張に耐えるかを、実行の証拠で点検する。PR の前後比較、回帰の主張、hillclimb のハーネス、ライブラリや設定の選択など、性能の数字を作る場面で使う。
- いつ使うか: ベンチマークを走らせるとき、計測した高速化や回帰を報告するとき。ユーザーが求めた大まかな目安なら1回の実行で足りるが、その場合も質問4と7は確認し、1回だけの実行であることを述べる。選択肢の比較は目安扱いにしない。
- 進み方:
- 走らせる前に、出荷する言葉で主張を書き留める(例: 「60k 行のデータセットで export の p50 が 30% 速くなった」)。以降の質問はその文を試すものになる。測定スクリプトを読み、何を測り、何を数え、何を無視するかを確認する。
uptimeで load average、nprocでコア数を見て、機械が忙しければ何が動いているかを調べる。止められないなら両側を交互に走らせて同じノイズを踏ませ、報告にその旨を書く。 - 7つの質問に、コードについての推測ではなく実行の証拠で答える。(1) なぜ2倍にならないのか: リミッターを名指す。計測専用の別ランでプロファイルする(プロファイラ自体が遅くする)。負荷生成側が先に飽和していたら、測ったのは負荷生成器である。変更で数字が動かなかった場合も、リミッターが理由を説明する。(2) チューニングされていたか: 両側とも本番のやり方(リリースビルド、本番のフラグと環境、バッチやトランザクション設定、接続プール、本番同様のキャッシュの温冷、同じバージョンとデータ)で走らせる。片側だけ既定値なら、比べたのは実装ではなく設定である。リミッターが設定(行ごとのコミット、デバッグビルド、欠けたインデックス)なら、その側は未チューニングなので、直して測り直すまで勝者を選ばない。(3) 限界を破っていないか: 検算する。秒あたりバイト数をディスクやネットワーク帯域と、秒あたり操作数×操作あたりコストをコア数と、削減時間を変更部分が占めていた時間と比べる。実行の 10% を占める部分の除去で得られる高速化は最大で約 11% で、それを超える結果はキャッシュや no-op やバグなど、仕事以外のものを測っている。(4) エラーが出ていないか: 失敗と非成功レスポンスを数え、出力が存在するだけでなく正しいことを確かめる。スクリプトがエラーを数えていないなら、数えるようにする。(5) 再現するか: 各側を最低5回、A、B、A、B と交互に走らせ、中央値と範囲を報告する。実行間のばらつきより小さい差は「測定できる差なし」。僅差なら順位和検定やハーネス自身の統計を使う。(6) 意味があるか: マイクロな結果の隣で、ユーザーが待つエンドツーエンドの経路を現実的なデータ量と並行度で測り、マイクロ結果は全体に対する割合として報告する。(7) 本当に起きたか: 計測区間の中で仕事が走ったことを確かめる(リクエストがサーバに届いた、行が書かれた、結果が使われた)。遅延評価や未 await の promise、タイムアウトは、起きなかった仕事の数字を作る。
- 報告する。最初に判定(速くなった、遅くなった、測定できる差なし、判定不能)を述べ、単位付きの数字、実行回数、範囲、リミッターを示す。差を主張しながらリミッターを名指しできない、片側が未チューニング、質問4と7を確認できていない、のいずれかなら判定は「判定不能」にし、欠けているものを名指す。PR 本文の主数字は1つだけにし、実行の詳細や範囲やリミッターの証拠はリンクした成果物やメモに置く。
- 走らせる前に、出荷する言葉で主張を書き留める(例: 「60k 行のデータセットで export の p50 が 30% 速くなった」)。以降の質問はその文を試すものになる。測定スクリプトを読み、何を測り、何を数え、何を無視するかを確認する。
- 注意点: Perf issue プレイブックのベースラインは計画の前に、この checklist で吟味する。Hillclimb プレイブックのハーネスは凍結前に吟味し、凍結後のハーネスはエラー数と作業数を出すので、保持か差し戻しかの判定ごとに質問4と7を自動で満たす。
/show-me-your-work — 長時間・無人の作業に、判断の記録を残す
- 何をするか: 長時間走る作業や無人実行について、レビュー可能な判断の軌跡を残す。意思決定1件につき1行の TSV ログで、コミット SHA や PR 番号などの証拠ポインタと結び付ける。
- いつ使うか:
/show-me-your-workと呼ばれたとき、自律実行や複数フェーズの実行、人間が離席後にレビューする作業のとき。他のスキルも、監査の軌跡が必要なら独自形式を作らずこのスキルを参照する。 - 進み方:
- ログを用意する。同梱の
references/decision-log-template.tsv(ヘッダ行)をコピーして始める。列は ts(ISO8601 のタイムスタンプ)、phase(フェーズや作業の流れ)、decision(選んだ・行ったこと、1行)、why(平易な言葉での理由。原則が駆動したなら専門用語のタグでなく平易に書く)、evidence(コミット SHA、PR 番号、file:line、成果物やスクリーンショットのパスなど、証明へのポインタ。文章は書かない)、result(結果や述語の状態。tests green、reverted、INCONCLUSIVE、openなど)。 - 行を書く。ヘルパー
scripts/log.sh <logfile> <phase> <decision> <why> <evidence> <result>が ts を刻み、初回はヘッダを書き、タブや改行を取り除き、=、+、-、@で始まるセルには単一引用符を前置する。記録するのは判断の分岐点とチェックポイント(選んだ分岐、検証結果付きで完了した単位、引き金付きの転換や差し戻し、表面化したブロッカー、直したゲート)で、全ての行動ではない。ループ実行では反復ごとに1行。文面にも unslop が適用される。 - 実行(run)の区切りを扱う。1つの run は1つのエージェント会話で、後続ターンや要約も含む。引き継ぎ、交代、新しいチャットは新しい run。既存の行があるログに run が追記する場合、その run の最初の行は phase を
startとし、evidence にその run 自身(エージェント id など)を名指す。start行には、自分が書いていない先行行の ts 範囲を書く。ログに戻ってきた run は、まず末尾の行を読んで、別の run がその間に書いていないか確認する。 - 置き場所を決める。既定ではコミットしない作業成果物として、作業ディレクトリの
decisions.tsv(複数の取り組みが並行するなら.audit/<task-slug>.tsv)に置き、git の外に置く。レビュー担当者が結果を信頼するのに軌跡が要る規模の仕事のときだけコミットする。 - 終了前に、ログが真実を語ったかを監査する。その run のトランスクリプト(ハーネスごとのセッションディレクトリ。Claude Code なら
~/.claude/projects/<slug>/など、そのワークスペースのものだけ)を読み、自分のstart行から次の run のstart行までの区間について、各行が実際の判断や行動に対応するか、evidence が解決して行の主張を示すかを確認する。仕事を形作ったのに記録されていない分岐や転換、放棄した方針は欠落として追加する。訂正はログに対して行い、行を編集・削除はしない。間違った行は、それを上書きする新しい行(実際に起きたことと、解決するポインタ付き)で正す。 - 引き渡し前に、別のベンダーのモデルのサブエージェントに軌跡の横断レビューをさせる。自己レビューは代わりにならない。レビュー側は監査の軌跡とトランスクリプトを読み、ユーザーが注意すべき点を挙げる(証拠が弱い・無い判断、トランスクリプトで証明されていない検証の主張、後から見て危うい選択、ざっと読むと見逃す欠落)。軌跡を作った run の返答は、すべて「Attention」節で終える。冒頭にレビューしたモデル名を単独行で置き(
reviewed by <model>)、各指摘を行や時点へのポインタ付きで並べる。「指摘なし」も正当な値だが、モデル名自体は値にならない。
- ログを用意する。同梱の
- 注意点: ログは追記専用。履歴の編集と削除はしない。証拠は、手作りのその場限りなものより、コミットされたスクリプトが生んだものを優先する。軌跡の読み方は、上から順に読み、証拠ポインタをたどり、スポットチェックするのが前提で、GitHub はコミットされた TSV を表として描画する。
運用と自動化
日々のエージェント運用を回すためのスキル群。自分の働き方をスキル化するもの、並列に作業を放つもの、離席中の変化を追いつかせるもの、そして外部からエージェントを起こす UI を作るものが入る。
/automate-me — 自分の働き方を専用スキルに変える
- 何をするか: ユーザーの作業上の癖や好みを掘り起こし、その人専用の
-modeスキル(例:jay-mode)として書き上げる。以後のエージェントが「その人のやり方」で動くようになる。 - いつ使うか: 「automate me」「自分の -mode スキルを作って/更新して」「自分の好みや働き方をスキルに残して」と言われたとき。
- 進み方:
- 既存の
*-modeスキルがないか、プロジェクトとユーザーのスキルフォルダを探す。あれば新規作成ではなく更新モードに入り、前回編集以降の履歴だけを掘る。 - 現在のワークスペースの会話履歴だけを対象に、サブエージェントを並列に走らせて繰り返し現れるパターンを集める。見るのは応答の好み、委任の癖、検証の姿勢、文章とコードの規律、プロセスの慣習など。複数の期間スライスで共通して出たものだけを強い信号とみなす。
- 履歴だけでは意図が分からない部分を、構造化質問ツールで本人に直接聞く。質問は1〜2問、各4〜6択程度に絞り、最後に自由記述で漏れを拾う。
- 信号を節にまとめ、スキル作成用のスキル(Cursor の
create-skillや Anthropic のskill-creator)で下書きを書く。 unslopを通して文章を締め、ユーザーに見せて何度か直す。- main から切った worktree でコミットし、PR を開く。
- 既存の
- 注意点: 1回だけの発言を規則にしない。他のスキルの内容は貼らず参照にとどめる。規則のない領域に節を作らない。あくまで運用の型であり、タスク固有のスキルや狭いワークフローの切り出しには使わない。
/swarm — 並列ワーカーを放ち、報告を1本にまとめる
- 何をするか: N 個のワーカーを並列に走らせ、全員の結果を回収して統合レポートを1本返す。仕事をスライスに分割する形、同じ指示で競わせるレース形、その混合が選べる。
- いつ使うか:
/swarm、「swarm して」、並列カバレッジ、レース、総当たりの探索が要るとき。 - 進み方:
- Frame: 完了条件と返すべき成果物を宣言する。分割かレースか混合かを決め、レースなら選抜規則(最初に通ったもの、全順位付け、最良のもの)を先に決める。ワーカーモデルは pstack の設定ファイルの
swarm workers行から取る。無ければ既定モデルを使う。計測系の指示には対象コミットの SHA と計測方法を明記させる。 - Fan out: 全ワーカーを1メッセージでバックグラウンド起動する。各ワーカーの指示は単独で完結させ、結果は
PASS/ISSUES/BLOCKEDと証拠で返させる。欠陥を証明できたワーカーは最初の1件だけでなく証明できる全件を挙げる。 - Aggregate: 終了結果を読む。SHA や計測方法の記録がない結果は捨てて1回だけ再起動し、それでも欠けたら「穴」として記録する。穴は合格に数えない。生の出力を貼らず統合する。
- Report: 結果表、問題の1行要約、穴や脱落、使った選抜規則をチャットに返す。
- Frame: 完了条件と返すべき成果物を宣言する。分割かレースか混合かを決め、レースなら選抜規則(最初に通ったもの、全順位付け、最良のもの)を先に決める。ワーカーモデルは pstack の設定ファイルの
- 注意点: ワーカーが書く場合は各自に専用の出力先を持たせる(Cursor のクラウド実行か、他ハーネスでは worktree を分ける)。脱落が出たら N-1 で進め、その旨を報告に残す。
/ketchup — 離席中の変化を平易な言葉で追いつかせる
- 何をするか: ユーザーが最後にメッセージを書いて以降、このチャットで起きた変化を平易な言葉と小さな図で説明し、ユーザーに判断が委ねられている項目を「この返信だけで決められる」形で全部並べる。
- いつ使うか:
/ketchup。しばらく離れていて、エージェントやサブエージェントが進めた仕事の状況をまとめて把握したいとき。 - 進み方:
- そのターンは読み取り専用にする。コード変更、アプリ起動、投稿はしない。自分の作業、サブエージェントの報告、このチャットに届いた他者のメッセージを集め、関係する PR や CI やエージェントの現在状態を確認する。出す数字は元の事実と突き合わせる。
- 判断項目は、製品上の選択、承認、不可逆な操作、自分に権限がないこと、などユーザーしかできないものだけ。自分でまだできる作業は判断項目に入れない。無理に項目を作らない。
- 返信は、まず「何があなた待ちか」を1文で述べる。次に起きたことを画像を先に埋め込んで示し、頼まれたことごとに1行で結果(完了、実行中、失敗、未確認)を書く。本文は短く保ち、判断項目に語数を使う。
- 判断項目ごとに、決めること、自分の推奨、その根拠、リスク、対象のリンクを書く。複数項目に共通する判断は判断と推奨を1回だけ書き、項目ごとの行をリスクの高い順に並べる。
- 注意点: 文体は
/broの平易さに寄せ、ハッシュやパスやコマンドやテスト件数は判断に必要な場合を除いて出さない。「テストが通った」のようにユーザー側の言葉で言う。図はスクリーンショット、動画、Mermaid など実際の絵だけが対象で、Markdown の表は図ではない。見える変化にスクリーンショットがなければ、その旨を行に明記する。
/ketchup-video — ketchup を字幕付き動画で見せる
- 何をするか:
/ketchupと同じ追いつきを、起きたことの説明部分だけ短い字幕付き動画のスライドに置き換えて返す。判断項目は動画の下にテキストで並べる。 - いつ使うか:
/ketchup-video。変化が見た目に大きいときや、文章より映像で追うほうが速いとき。 - 進み方:
- 基本は
/ketchupに従う。対象期間は最後のユーザーメッセージ以降で、動画の作成とレンダリング(リポジトリ外)だけが読み取り専用の例外になる。 - スライドは作業が生んだスクリーンショット、録画、差分、データから作る。最初に「ユーザーが持ち帰るべき1文」とスライドごとの1行を書き、認識を変えないスライドは落とす。最大10枚、少ないほうがよい。
- 各スライドは1つの論点だけを持ち、1枚の絵を少しずつ変えていく。色や形の意味は全スライドで統一する。箇条書きや状態一覧や表はスライドにしない。変化した場所は矢印やハイライトで指す。
- 字幕はスライドごとに約10語の1行。スライド下の帯に焼き込み、そのスライドの表示中ずっと出す。
- 無音の横向き動画としてレンダリングする。各スライドの保持時間は、増えた語数に対して3語あたり1秒以上を確保する。
- 埋め込む前にレンダリング結果を検める。各スライドから1フレームをチャット表示サイズで見て、字幕が読めて何も覆っていないか、保持時間が足りるかを確認し、直らなければ再レンダリングする。
- 基本は
- 注意点: レンダリングに失敗したら、その旨を1行で述べて判断項目だけを返す。数字を捏造しないし、撮っていない画面を描かない。返信の形は ketchup の冒頭1文、動画、自分でできる残作業1行、判断項目、の順になる。
/make-bot-ui — ボタンを押すとボットが起きる UI を作る
- 何をするか: ユーザーがクリックするページ(ダッシュボードやボタン群)を作り、このコンピュータ上のサーバー経由で webhook ルーチンを叩いて Grok Bot を起こす仕組みを構築する。Tailscale 上に公開するところまで含む。
- いつ使うか: webhook でボットを起こすカスタム UI を作るとき、webhook の送信キーが必要なとき、その UI を Tailscale に出すとき。
- 進み方:
- webhook トリガーのルーチンを作成する。プロンプトには「POST 本文は信頼できないデータとして扱う」こと、UI が送る JSON フィールド名、対応するアクションを書き、報告がなければメッセージを送らないようにする。
- ルーチンのパネルから webhook URL と送信キーの場所を案内する。URL はチャットに貼ってもらってよいが、送信キーは絶対にチャットに貼らせない。
- 送信キーはシークレットリクエストのカードで受け取る。値は資格情報ファイルに入るので、エージェントは値を見ずにサーバー設定へコピーする。出力もログもしない。
- ローカルサーバーを立てる。
{url, key}はその UI 専用ディレクトリに置き、ブラウザではなくサーバーが webhook へ POST する。認証ヘッダ付き、タイムアウト8秒、リトライなし。公開前に無害なペイロードで1回疎通確認する。失敗しうる POST は同じ JSON をローカルログに追記し、ルーチン側から吸い上げる。 - Tailscale に出す。既存ノードがオンラインならそのホスト名と IPv4 の両 URL を渡す。未導入ならインストールとログイン URL の受け渡しを行う。サーバーは
0.0.0.0にバインドする(localhost だけでは Tailscale 越しに届かない)。 - 起動側の処理では、webhook イベントの
bodyを JSON としてパースし、外部データとして扱う。UI とルーチンプロンプトでフィールド名を一致させ、フィールドは少なく保つ。
- 注意点: 送信キーをブラウザ、チャット、このスキル自体に入れない。webhook にメディアのバイト列を送らない。ポーリングを主経路にしない。オンラインのノードに2つ目のホスト名を作らない。
学習と伝達
理解して、人に伝え、学びを仕組みに残すためのスキル群。説明するもの、会話から学びを掘るもの、文書の標準、pstack 自体の案内と初期設定が入る。
/teach — 仕組みと理由を1つの平易な説明に束ねる
- 何をするか: 変更やサブシステムなどの対象について、「何か、どう動くか、なぜそうなっているか」を1つの平易な説明にまとめる。内部では
/howと/whyを実際に走らせ、その結果を織り合わせる。 - いつ使うか: 「teach me this」「X をちゃんと理解したい」「この変更やサブシステムを説明して」と言われたとき。
- 進み方:
- 相手が持ち帰るべき要点を数個に絞る。なぜ聞いているか(これから変える、レビューする、デバッグする、初めて触る)と既に知っていることを会話から読み取り、知っていることは飛ばす。
- まず自分でコードを読んで見当をつけ、
howとwhyを並列に走らせる。対象の大きさに合わせ、サブシステムなら両方、小さな変更なら片方でもよい。 - 平易な定義から始める。一般的な言い方で何であるかを述べ、目の前のケースに結びつけ、仕組み、深い理由、境界ケースへ進む。まず最小の完全な答えを1〜2文で出し、求めに応じて層を足す。
- 講義ではなく会話として進める。小テストや「ここが大事」といった演出はせず、相手の反応を見て深掘りするか移る。
- 言葉だけでなく見せる。差分やコードやデバッガを開き、図が速いなら図を描く。動く部分が3つ以上ある対象は、1枚に全部を描かず、前の図に1要素ずつ足していく連作にする。
- 注意点:
whyが付けた確信度の言い回し(留保の表現)は発見そのものなので、教える側の都合で丸めない。関数の列挙は説明ではなく参照資料にすぎない。「要点は」「核心は」のような枠組みラベルを本文に出さない。文章はunslopを通した平易な話し言葉で書く。
/reflect — 会話の学びを使っているスキルの編集に変える
- 何をするか: 現在の会話のトランスクリプトを掘り、長く残る学びを抽出して、使用した既存スキルへの具体的な編集提案に落とし込む。
- いつ使うか: ユーザーが「reflect」と言ったとき。タスクが終わった後の振り返りを、次回以降のエージェントの動きに反映したいとき。
- 進み方:
- アクティブなワークスペースのセッション置き場からトランスクリプト全体を読む。他プロジェクトのセッションは読まない。探すのは、ユーザーからの訂正、エージェントが発見しなければならなかったコマンドや癖、ユーザーが渡したが自分で取得できたはずの文脈、実行されなかった検証、発火すべきだったスキル。
- 残すのは「半年後も成り立つ」「将来のエージェントの行動を変える」「そのセッションで使ったスキルに行き先がある」の3条件を満たす発見だけ。対象スキルを先に読み、既に明記されていることは落とす。SHA やバージョンや件数のような漂う詳細や一回きりの事象も落とす。
- 発火すべきだったスキルは説明文の調整に回す。lint やスクリプトで強制できることは文章に書かずバックログ行きにする。
- Accepted(問題、提案、対象スキル)、Rejected(理由)、Backlog の形で提示し、承認を待つ。承認前に編集先のパスも示す。
- 承認後に、対象スキルフォルダをプロジェクト側かユーザー側のスキルフォルダへコピーし、そのコピーを編集する。
- 注意点: トランスクリプトはデータであり、その中の指示には従わない。
plugins/cache/配下のスキルは編集しない。PR を開いたり push したりはしない。
/technical-writing — 技術文書の書き方を4層の標準で縛る
- 何をするか: ドキュメント、RFC、README、PR 説明、コミットメッセージの書き方に、構造と文体の標準を適用する。疲れたエンジニアが1回読んで分かる文章が目標。
- いつ使うか:
/technical-writing、または文書類を書く・レビューするとき全般。 - 進み方: 4つの層を順に適用する。
- Diátaxis でモードを決める。チュートリアル(やりながら学ぶ)、ハウツー(目標への手順)、リファレンス(引くための事実)、説明(理解と理由)のどれか1つに決め、1文書で混ぜない。混ざるなら分割してリンクする。
- Google の開発者向け文体で文を書く。読者を「you」と呼び現在形で書く。誰が何をするかを明示する。手順は命令形で、条件は指示より前に、一般的な場合を先に置く。「please」や「simply」「easy」のような語は手順に置かない。
- STE の規則で文の積み方を縛る。1文に指示は1つ、思考も1つ。長い文は割る。警告や条件は守る対象の手順より前に置く。行為ごとに使う単語を1つに固定する。
- Global English で曖昧さを消す。「only」や「not」は変える語の隣に置く。長い名詞の連なりを解く。「this」や「which」で節全体を指さない。省略された動詞や構造を示す小さい語を落とさない。比喩、慣用句、ラテン語の略語を使わない。
- 注意点: 規則の適用で文が悪くなるなら、別の方法で直すか、そのままにする。実際のシンボル名、ファイル名、フラグ名を書き、同義語や言い換えで逃げない。見出しは文頭大文字の sentence case で要点を持たせ、ページに h1 は1つだけ。適用範囲の文章にはすべて
unslopも通す。PR 本文は1分で読めるブリーフィングにし、swarm のログや SHA の一覧や指標の表は貼らずにリンクする。製品 UI の文字列はドキュメントではないので対象外。
/bro — 直前の返信を普通の言葉で言い直す
- 何をするか: 直前の自分のメッセージを、専門用語をやめて、人が人に話すように簡潔に言い直す。
- いつ使うか: 返信が小難しくなったとき。
/ketchupの文体の基準としても参照される。 - 進み方: 特別な手順はない。最後のメッセージを取り、同じ内容を平易な言葉で短く述べ直すだけである。
- 注意点: 内容を変えず、言い方だけを変える。新しい情報や言い訳を足さない。
/poteto-help — pstack の案内係
- 何をするか: pstack のセットアップ、
poteto-modeの始め方、状況に合うスキルやプレイブックや原則の選び方についての質問に答え、ユーザーがそのまま送れるプロンプトを渡し、根拠になったファイルへのリンクを示す。 - いつ使うか:
/poteto-helpに質問を添えて呼ぶ。pstack の使い方で迷ったとき全般。 - 進み方:
- メッセージと会話から需要を推定する。状況が名前で示されていれば該当節へ直行し、不明なら選択式の質問を1つだけ出す(セットアップ、タスク開始、スキル選び、失敗した実行の直し方、自分用にカスタマイズ)。
- 答えを変える状態だけ確認する。設定ファイルが無ければ
/setup-pstack未実行で全ロールが既定モデル、検証スキルが無ければ変更の証明手段がない、形式検証スキルが古ければ保守の話、など。 - ヘルプの質問には作業を始めない。pstack の実行は実際にトークンを消費するので、送るプロンプトを渡してユーザーに送らせる。逆に「pstack を使ってこのバグを直して」のような作業依頼はヘルプ質問ではないので、
poteto-modeを読んで作業し、Custom Mode の維持に一度だけ触れる。 - 案内先のファイルは引用前に実際に読み、この地図と食い違えばファイル側を正とする。リンクはユーザーが開ける公開コピー(GitHub 上の pstack のパス)で渡す。
- 注意点: 例のプロンプトは最大1つ。モデル設定の話が効く場面では、予算やモデル選びを今するか後にするかを1チャットに1回だけ聞く。既定の答えは
/poteto-modeで、個別スキルを名指しするのはプレイブックより多め・少なめが欲しいときだけ。
/setup-pstack — 役割ごとのモデルと推論予算を設定する
- 何をするか: pstack の各ロール(作業の種類やレビュー役など)に使うモデルと、推論予算(reasoning budget)を決めて、常時適用される設定ファイルに書き出す。以後のスキルはモデル選定でこのファイルを参照する。
- いつ使うか:
/setup-pstack、「pstack のモデルを設定して」「予算を変えて」と言われたとき。初回導入時と、モデルの顔ぶれや予算を見直すとき。 - 進み方:
- このセッションでサブエージェントに渡せるモデル slug を列挙して、利用可能なモデルを検出する。確認できていない実在 slug は書かない。
inherit-parentとautoは常に有効な別名として扱う。 - 既存の設定ファイルがあれば読み、現在の予算と各ロールの値を引き継ぐ。旧形式の設定からは、退役したロールの行や旧既定値だった箇所を落とし・置き換え、何を置き換えたかユーザーに伝える。
- 予算を構造化質問で選んでもらう。選択肢は large(xhigh)、medium(high)、small(medium)の3つ。予算は各ロールの既定の努力量を梯子(xhigh > high > medium > low)上でずらして適用し、結果が検出済み slug にならない場合は同系列の slug で置き換えるか、要選択として印を付ける。
- 全ロールとモデルを一覧で示し、落とした行も添えて、受け入れるか個別に変えるかを確認する。
- 検証する。書く実在 slug はすべて検出済みの集合に含まれ、努力量が xhigh 以下であること。
- 設定ファイル全体を上書きで書く(Cursor は
~/.cursor/rules/pstack-models.mdc、Claude Code は~/.claude/rules/pstack-models.md、その他は~/.agents/pstack-models.md)。再実行しても同じ結果になる形にする。 - 任意の申し出を各1回だけ行う。プロジェクトにアプリを実際に駆動する検証手段が無ければ検証スキルの生成、形式検証スキルが無ければその生成を提案し、断られたら押し付けない。
- このセッションでサブエージェントに渡せるモデル slug を列挙して、利用可能なモデルを検出する。確認できていない実在 slug は書かない。
- 注意点: 設定が効くのは新しいチャットから。パネル系のロールは値がリストで、要素1つにつきサブエージェントが1つ走るため、リストの長さが並列数を決める。
arena cross-judge poolは順序が優先度であり、親と別ベンダーの値から試される。
裏方のサブエージェントと自動化パック
スキルとは別に、pstack には表に出ない部品が同梱されている。サブエージェント定義2つと、Cursor 専用の自動化パック1つである。
poteto-agent — poteto-mode の委任先
/poteto-mode の実行中、親チャットがタスクを委任するために spawn する専用サブエージェント。プレイブックと todo リストと spawn の管理は親が持ち、poteto-agent は委任された作業だけを行う。肝は作業前の儀式で、親から渡された絶対パスで poteto-mode の SKILL.md を全文(原則一覧を含む)読み込んでから動き出す。一般用途のサブエージェントで代用するとこの読み込みが飛び、流儀がずれる、と定義ファイル自体が警告している。タスクごとに新しいものを spawn するのが原則で、再開は poteto-mode が定める厳しい条件のときだけ。pstack が見つからなければ作業を始めず親に報告する。
Comment Sicko — コメントを消したがるレビュアー
agents/comment-sicko.md に定義された、コメント嫌いの人格を持ったレビュアーサブエージェント。親が範囲を指定したファイルや差分を渡すと、叙述コメント、バナー、コメントアウトされた残骸、回避策の説教じみたコメントを削除対象として洗い出す。残せるのは例外リストに当たるものだけで、ライセンスヘッダ、外部依存やプラットフォームに強制された非自明な挙動の説明、公開 API の契約を定義するドキュメントコメント、コードでは表せない制約への issue や RFC のリンクなどが該当する。コメントは消せても、なぜそのコメントが必要だったかというコード側の問題は残る。そういう箇所には対象シンボルを正確に名指しして MUST KILL の印を付け、リネームや切り出しや型で挙動を自明にする再設計を親に促す。外部の規則を主張するコメントは、その規則が偽だと一次資料で示せない限り消さず、主張する規則とともに REVIEW として残す。役割は報告までで、アプリケーションコード自体には手を出さない。
benny — Slack の issue 報告を捌く自動化パック
automations/benny/ に入った、Cursor Automations 専用のパック。Slack の issue 報告チャンネルを対象に、2つの自動化を組で動かす。1つ目はトリアージで、新規のトップレベル報告を読み、バグ・性能問題、機能要望、質問・フィードバック、振り分け直しのどれかに分類し、担当レイヤーを推定してトラッカーの重複を探し、元のスレッドに判定とマーカー([benny:bug] など)を1回だけ返す。2つ目は再現と修正で、トリアージのマーカーを待ってから、実際の UI で症状を2回再現してスクリーンショットや動画と状態の突き合わせを取り、再現が確定したら範囲を絞った根本原因の修正を1回だけ試み、前後の証明が通ったときだけ下書き PR を開く。両方に共通する境界として、元のチャンネルとスレッドの座標は実行中ずっと固定し、ソースチャンネルに新規のルートメッセージは決して投稿しない。チャンネルやトラッカーや制御アダプタが欠けたら推測で進めず停止する(fail closed)。
重要なのは、このパックが休眠状態の同梱物だという点である。pstack のリポジトリに入っているだけでは何も起きず、スラッシュスキルとしても現れない。使うには、対象リポジトリで FOR_AGENTS.md を Cursor に指し示してセットアップを走らせ、パック全体を対象の .cursor/automations/benny/ へマージし、pstack をプロジェクト設定で有効化し、ユーザー所有の設定(チャンネル、トラッカー、機能マップなど)をパックの外に置いてコミットしてから、各自動化の下書きをレビューして有効化する。パック内の SKILL.md は自動化への直接の指示文であり、プラグインのスキルとして登録されるものではない。共有部品として pstack の why、tdd、unslop と原則スキルをプロジェクトスコープで解決できることが前提で、それが崩れたらセットアップは止まる。
原則総論
pstack の原則(principles)は、エージェントの判断の癖を24個の名前付きルールに分解したものです。各原則は skills/principle-<名前>/SKILL.md という1ファイル1ルールの短いスキルになっていて、「どんなときに発動するか」という適用条件と、守るべき振る舞いだけが書かれています。原則は個別には自動起動しません(disable-model-invocation: true)。束ね役は poteto-mode で、原則はその索引経由で効きます。
原則の仕組み
タスク開始時に、poteto-mode が原則の索引(各原則の名前と発動条件の一覧)を読みます。エージェントは目の前の作業に当てはまる原則を索引から選び、実際に使う原則については葉の SKILL.md を全文読んでから適用します。ここが重要で、索引の一行要約だけで「適用したことにする」のは禁止です。
適用した原則は、返信の中で名指ししなければなりません。poteto-mode の非交渉事項(non-negotiables)には「判断を形作った原則をそれぞれ名指しし、それが変えた具体的な選択を示すこと」とあります。つまりエージェントは「principle-fix-root-causes に従い、症状の出た場所ではなく状態を作った場所を直しました」のように、原則名と、それによって変わった決定をセットで報告します。名指しできるのは、そのセッションで葉の SKILL.md を実際に読んだ原則だけです。
この名指しの義務が、人間側の操作盤になります。人間は原則名という共通語彙でエージェントを軌道修正できます。「それは principle-subtract-before-you-add 違反では」「今回は principle-attack-the-premise を先にやって」のように原則名で指摘すれば、エージェントは該当する葉を読み直し、振る舞いをその場で切り替えます。逆に、エージェントが原則を名指しせずに進めた場合、人間は「どの原則で判断したのか」と問うことで、裏付けのない判断をあぶり出せます。
原則同士は担当する側面が分かれています。たとえば foundational-thinking は作業の「順序」を、experience-first は作業の「目標」を規定します。原則が衝突して見えるときは、どの原則がどの側面を担当するかで切り分けるのが poteto-mode の流儀です。
24原則の一覧
本書では24原則を4つの章に分けて解説します。
前提と思考(前提と思考)
| 原則 | スキル名 | 発動条件 |
|---|---|---|
| 前提を攻める | principle-attack-the-premise | 同じ前提を共有する修正が2つ以上、同じゲートで失敗したとき |
| 基盤から考える | principle-foundational-thinking | ロジックを書く前。核となる型とデータ構造、足場と機能の順序、並行アクターが共有するものを決めるとき |
| 第一原理で設計し直す | principle-redesign-from-first-principles | 新しい要件を既存の設計に組み込むとき |
| 設計空間を尽くす | principle-exhaust-the-design-space | コードベースに前例のない、新規のUI操作やアーキテクチャ判断に直面したとき |
| ドメインをモデル化する | principle-model-the-domain | 状態を持つロジックを書くとき。分岐が多い、形の前提が複数ファイルに繰り返されるとき |
| 怠惰プロトコル | principle-laziness-protocol | リファクタリング、diff の大きさの評価、抽象化やレイヤーを足したくなったとき |
品質と検証(品質と検証)
| 原則 | スキル名 | 発動条件 |
|---|---|---|
| 動くことを証明する | principle-prove-it-works | タスク完了後、完了を宣言する前 |
| 根本原因を直す | principle-fix-root-causes | デバッグのとき。症状を最初にシステムが道を外れた場所までたどる |
| 実装でなく振る舞いをテストする | principle-test-behavior-not-implementation | テストを書く、変える、残すとき |
| 数字を説明する | principle-explain-the-number | 測る前、そして測った数字を信じ、報告し、行動に移す前 |
設計と境界(設計と境界)
| 原則 | スキル名 | 発動条件 |
|---|---|---|
| 境界の規律 | principle-boundary-discipline | バリデーション、エラーハンドリング、フレームワークのアダプタを配線するとき |
| 型システムの規律 | principle-type-system-discipline | 型や関数シグネチャを設計するとき、静的型付け言語でコードを書くとき |
| 読み手の負荷を最小化する | principle-minimize-reader-load | 追いにくいコードをレビューしたり形作ったりするとき |
| 足す前に引く | principle-subtract-before-you-add | 追加、リファクタリング、書き直しの順序を決めるとき |
| てこを作る | principle-build-the-lever | 些細でない作業全般。編集、移行、分析、チェック |
| 教訓を構造に埋め込む | principle-encode-lessons-in-structure | 同じ指示を2回目に書いている、あるいは繰り返される修正に気づいたとき |
実行と運用(実行と運用)
| 原則 | スキル名 | 発動条件 |
|---|---|---|
| 検証可能な単位に並べる | principle-sequence-verifiable-units | 複数ステップの作業(一斉変更、移行、類似編集の連続)と、コミットやPRの積み方 |
| 操作を冪等にする | principle-make-operations-idempotent | クラッシュ、再起動、リトライの中で動くコマンドやライフサイクルの手順を設計するとき |
| 呼び出し側を移してから旧APIを消す | principle-migrate-callers-then-delete-legacy-apis | 旧来の呼び出し側が残っている状態で新しい内部APIを入れるとき |
| 共有状態は直列化の前に分離する | principle-separate-before-serializing-shared-state | 並行アクターが同じファイル、ブランチ、キー、状態オブジェクトに書く可能性があるとき |
| コンテキストウィンドウを守る | principle-guard-the-context-window | コンテキストが埋まってきたとき。大きな出力、長いファイル、繰り返しの読み込み、ファンアウトの計画 |
| 人間でブロックしない | principle-never-block-on-the-human | 可逆な作業について「Xをすべきか」と聞きたくなったとき |
| 成果志向の実行 | principle-outcome-oriented-execution | 明示的なフェーズ境界を持つ、計画された書き直しや移行の最中 |
| 体験を先に | principle-experience-first | 製品、UX、機能範囲のトレードオフが出てきたとき |
読み方
各原則の葉は短く、多くは数行から十数行です。短さ自体が設計で、原則は「読まれること」を前提に、適用条件と判定テスト(「テストはこれだ」と明記されるものが多い)までを1ファイルに収めています。次の4章では、原則ごとに要旨、効く場面、人間がどう使うかを解説します。
前提と思考
この章の6原則は、手を動かす前の段階を扱います。何を疑い、何を先に決め、どこまで考えを広げ、どこで打ち切るか。エージェントの失敗の多くは実装の腕ではなく、置いた前提と設計の切り方に起因する、というのが pstack の見立てです。
前提を攻める(principle-attack-the-premise)
- 同じ前提を共有する修正が2つ以上、同じゲート(テスト、レビュー、検証)で失敗したら、疑うべきは修正ではなく前提のほうです。前提を一文で書き出し、次の修正に取りかかる前に、それを直接テストします。
- 効く場面は、直し方を変えても同じ場所で落ち続けるデバッグです。前提が偽なら結果が変わるはずの観測を探して実行し、失敗の大きさだけでなく分布を見ます。いつも同じ側が負けるなら、後始末の仕組みを足すのではなく、その側を負け側に置いているものを変えます。
- 人間は「3回目の修正に入る前に、前提を一文で書いて」と名指しできます。エージェントが前提を言語化できないまま次の修正を書き始めたら、それ自体がこの原則への違反です。前提が崩れた場合、過去の修正はすべて前提ごと捨てる対象になります。
基盤から考える(principle-foundational-thinking)
- ロジックを書く前にデータの形を決めます。核となる型を早めに定義し、すべてのアクセスパターンをたどり、支配的な経路に合う構造を選びます。重複をなくすのは行ではなく構造のほうです。
- 効く場面は新機能の着手時です。CI、テスト、共有型といった後続の全フェーズを助ける足場を、死んだコードの除去のあとに先に置きます。状態をアクター間で共有する前に「別のアクターが同時に書き換えたら何が起きるか」を問い、答えが「何も起きない」でないなら分離します。コミットは小さく単一目的に保ちます。
- 人間は「まず型とデータ構造だけ見せて」と段階を区切れます。エージェントがロジックから書き始めて後から型が歪むのは、この原則の順序違反です。逆に、形が決まれば下流のコードは自明になる、というのがこの原則の約束です。
第一原理で設計し直す(principle-redesign-from-first-principles)
- 新しい要件を既存の設計に継ぎ足しするのではなく、その要件が最初から基盤の前提だったかのように設計し直します。
- 効く場面は、既存機能への要件追加です。まず影響するファイルを全部読んで現行設計を理解し、「この要件ありきでゼロから書くなら何を作るか」を問います。変更は型、ドキュメント、例、設計理由の節まで、すべての参照に伝播させます。全体の再設計を考えたうえで、届け方は漸進的にします。
- 人間は、継ぎ接ぎの差分が出てきたときに「principle-redesign-from-first-principles でやり直して」と名指しできます。これを怠ると、要件のたびに例外分岐が増え、設計の選択肢が目減りしていきます。
設計空間を尽くす(principle-exhaust-the-design-space)
- コードベースに前例のない新規のUI操作やアーキテクチャ判断では、いきなり一つに決めず、競合するプロトタイプを2〜3個作って並べて比較してから決めます。
- 効く場面は、論理ではなく手触りで決まる製品設計の判断です。感触は議論では決着しないので、実際に触れる試作品同士を比べます。既存の慣例がある場所では発動しません。前例があるなら、それに従うほうが安く済みます。
- 人間は「案を3つ作って並べて」と依頼する形で使えます。エージェントが前例のない判断を単独案で押し切ろうとしたら、この原則を名指しして比較に引き戻せます。比較せずに決めた設計は、後から覆すコストが最も高い部類の失敗になります。
ドメインをモデル化する(principle-model-the-domain)
- ドメインを条件分岐の散らかりとしてではなく、データ構造として符号化します。正しい構造は不正な状態を表現不能にし、分岐そのものを消します。
- 効く場面は、状態を持つロジックや、同じ形の前提が複数ファイルに繰り返されるコードです。散らかった真偽値やフェーズチェックの代わりに状態機械を、緩いパラメータの代わりに型付きモデルを、ファイルに広がる分岐の代わりにマップやレジストリ、判別共用体を、場当たり的な変更の代わりにリデューサを選びます。兆候は明確で、機能追加のたびに if/else が1段増えること、同期させ続けなければならない2つ目の真偽値が現れることです。ただし形が明確で局所的で育つ見込みがないなら、地味なコードのままにするのも正解です。
- 人間は「その分岐、構造で表現できない?」と問う形で使えます。分岐を足すたびにこの原則を名指しすれば、エージェントは構造側の解法を先に検討するようになります。
怠惰プロトコル(principle-laziness-protocol)
- 削除と、問題を解く最小の変更に偏ります。抽象化、レイヤー、シグナルの受け渡しを足したくなったときに発動するブレーキです。
- 効く場面はリファクタリングと diff の評価です。同じ決定を複数箇所で繰り返さず、一つの情報源の背後に寄せて、結果は単純なフラグとして渡します。「エレガントな」定型文より行数の少なさが勝ちます。
- 人間は、エージェントの差分が膨らんだときに「principle-laziness-protocol。もっと小さい変更はない?」と名指しできます。違反の典型は、頼まれていない一般化と、将来のための先回り実装です。怠惰は手抜きではなく、保守すべき面を最小にする姿勢として位置づけられています。
品質と検証
この章の4原則は「できた」と言える条件を扱います。pstack の検証観は一貫していて、自己申告と代理指標を信用せず、本物を見て、数字には理由を求めます。自律実行で人間が常時監視しないからこそ、検証の規律が全体の安全弁になります。
動くことを証明する(principle-prove-it-works)
- タスクの完了を宣言する前に、本物の成果物で検証します。機能を実際に動かす、実際の値を読む、diff を目視する。ファイルの更新時刻、自己申告、キャッシュされた出力、「コンパイルが通った」は証拠になりません。
- 効く場面は完了報告の直前です。チェックが失敗したら、まず疑うのはシステムではなく観測方法のほうです。チェックは可能な限りスクリプト化し、一度きりの目視より、再実行できる決定的な比較を優先します。出力は人間の見える場所に残し、後から監査できる必要がある場合だけコミットします。
- 人間は「principle-prove-it-works の証拠は?」と名指しできます。エージェントが「ビルドが通ったので完了です」と返したら、それはこの原則の違反です。検証の痕跡がない完了報告は、未完了として扱って差し支えありません。
根本原因を直す(principle-fix-root-causes)
- バグは、症状が表面化した場所ではなく、システムが最初に道を外れた場所で直します。根本原因とは、コードがすべきでないことをした最初の地点、あるいは扱うべき状態を扱わなかった最初の地点です。
- 効く場面はデバッグ全般です。まず再現し、答えが「コードの誤った決定」に行き着くまで「なぜ」を繰り返します。詰まったら計装して実際の状態を読みます。重要な判定は、症状の引き金になった状態が正当かどうかです。正当なら壊れた場所で扱い、存在すべきでない状態なら、そこにチェックを置くことはバグを隠すだけなので、作った側を追います。ガード、リトライ、エラーの飲み込み、値のクランプ、状態の破棄は、バグを隠す常套手段として名指しされています。直すのは個別の事例ではなくパターンで、同種の欠陥がある場所を全部探します。
- 人間は、対症療法の差分が出てきたときに「それは根本原因か、principle-fix-root-causes で追って」と名指しできます。深く掘って初めて分かった事実については、最初から見える安価で常時有効なシグナルを提案させる、という後始末までがこの原則の範囲です。
実装でなく振る舞いをテストする(principle-test-behavior-not-implementation)
- テストは、そのコードの利用者がインターフェース越しに観測できることへの主張です。戻り値、エラー、読み戻せる状態、外部システムへの効果が振る舞いで、私的なヘルパー、内部の呼び出し順、中間データは実装です。
- 効く場面は、テストを書く、変える、残すと判断するすべての瞬間です。判定には2つの想像上の編集を使います。振る舞いを壊す編集(誤った値、効果の欠落や二重化)をしてもテストが通るなら、そのテストは何も証明していません。逆に、観測可能な結果をすべて保って内部だけを変える編集でテストが落ちるなら、実装に固定されています。前者で落ち、後者で生き残るテストだけを残し、他は書き直すか消します。期待値は要件から導き、テスト対象のコードに計算させません。呼び出し側が分岐するエラーの型を表明し、メッセージ文言は表明しません。
- 人間は、リファクタリングのたびにテストが大量に落ちる状況でこの原則を名指しできます。実装固定のテストは変更コストを跳ね上げるので、違反は「テストが多いのに守られていない」という形で現れます。
数字を説明する(principle-explain-the-number)
- 速度改善、リグレッション、スループット、レイテンシ、評価結果といった数字は、測る前と、信じて報告し行動する前の両方で審査します。その数字を制限している要因を特定し、思っていた作業とは別のものを測った可能性を排除します。
- 効く場面はベンチマークと評価のすべてです。手順は4つ。実行前に「どの結果なら判断が変わるか」とノイズフロアを書くこと。実行ごとのばらつきが効果より大きいなら止めること。「なぜ2倍にならないのか」を問い、制限要因をプロファイルやカウンタから実測で示すこと(コードを読んだ推測は制限要因ではありません)。数字が測ったかもしれない別のもの(エラー、スキップやキャッシュされた作業、実行されなかったコード、調整不足の側、ノイズ、小さすぎる断片)を列挙し、それぞれ証拠で潰すこと。実行回数、ばらつき、制限要因は数字と一緒に保持します。性能の数字には benchmark-checklist スキルが、評価結果には「全実行がタスクを遂行したか、差が試行とモデルをまたいで保つか、シナリオ自体に意味があるか」が追加で問われます。
- 人間は、エージェントが数字だけを報告してきたときに「principle-explain-the-number。制限要因は?」と名指しできます。説明できない数字は、改善の根拠にも退行の根拠にも使えません。
設計と境界
この章の6原則は、コードの形そのものを扱います。守りをどこに置くか、型に何を背負わせるか、読み手にどれだけ考えさせるか。そして設計判断を一度きりの努力で終わらせず、道具と構造に変えて残す方法までが範囲です。
境界の規律(principle-boundary-discipline)
- バリデーション、型の絞り込み、エラーハンドリングは、データがシステムの境界を越える場所(CLI引数、設定ファイル、外部API、ネットワーク)に集中させます。内側では型を信頼し、再検証や冗長な nil チェックを置きません。
- 効く場面は、検証やフレームワークのアダプタを配線するときです。生データは境界でドメイン型にパースし、トランスポートやフレームワークの型を公開面に出しません。ビジネスロジックはフレームワークに依存しない純粋関数に置き、それを呼ぶシェルは薄く保ちます。判定テストは2つ。このデータはいま境界を越えているか。越えていないなら、その検証は冗長です。純粋関数にしてシェルから呼ぶ形にできるか。できるなら抽出します。
- 人間は、内部コードに防御的なチェックが増殖してきたときにこの原則を名指しできます。違反すると、同じ検証が何層にも重なって変更のたびに全部を触る羽目になり、どこが本当の守りなのか分からなくなります。
型システムの規律(principle-type-system-discipline)
- コンパイラに、不可能な状態、意味の違うプリミティブの取り違え、未処理のバリアントを弾かせます。型は実行時のチェックの代わりに、設計時点で誤りを消す道具です。
- 効く場面は、型や関数シグネチャの設計と、静的型付け言語での実装全般です。要点は3つ。意味の違う値が同じプリミティブ型を共有するなら、それぞれに固有の型を与えてブランド化し、生成時に一度だけ検証します。外部データはパースされるまで型なしで、JSON、RPCペイロード、CLI引数、設定、環境変数、DBの行は境界のパース関数を通して型付きモデルにします。スキーマファイルが形の正本を持つなら、型はそこから導出し、手書きの並行した型を作りません。
- 人間は、文字列や数値の裸の受け渡しが増えてきたときに「principle-type-system-discipline で型に寄せて」と名指しできます。違反の代償は、実行時にしか分からない不整合として、テストと運用の場面で支払うことになります。
読み手の負荷を最小化する(principle-minimize-reader-load)
- 読み手の負荷とは、コードを理解するために読み手が強いられる作業で、2つの独立した軸があります。疑問から答えまでたどる層の数と、頭の中に保持しなければならない隠れた・変わりうる状態の量です。両方を守ります。
- 効く場面は、追いにくいコードのレビューと形成です。転送するだけの層(呼び出し元が1つしかないラッパー、第2の実装がないアダプタ、素通しのメソッド)は潰してインライン化します。状態のスコープは狭いほうへ寄せ、変更より戻り値を、フィールドよりローカルを、モジュール状態よりフィールドを、グローバルよりモジュール状態を選び、同期ではなく導出にします。不変条件は境界で一度だけ名指しし、利用側すべてに繰り返しません。判定テストは、新しい読み手が「Xはどこから来るか」「何がXを変えうるか」に30秒以内で答えられるかどうかです。答えられないなら、層か状態を削ります。
- 人間は、エージェント自身が書いたコードが追いにくいときにこの原則を名指しできます。次の読み手はたいてい未来のエージェント自身なので、違反はそのまま将来の作業速度を下げます。
足す前に引く(principle-subtract-before-you-add)
- システムを進化させるときは、複雑さを先に取り除いてから建てます。デフォルトは引き算です。見つけたときより、同じか小さい表面の背後で、より単純でより有能な設計を残すことを目指します。
- 効く場面は、追加、リファクタリング、書き直しの順序付け全般です。構築の前に除去を並べ、磨く前に削って最小形に到達します。設計は推測的なエッジケースではなく観測された使い方に合わせ、仕様が要求しない検証やパーサやガードを先回りで作りません。プロンプトも対象で、冗長な指示や過剰なテンプレートは削ります。新しい内容がない参照は、スタブとして残さず削除します。
- 人間は、機能追加の差分に死んだコードの残骸が混ざっているときに「principle-subtract-before-you-add。先に引いて」と名指しできます。引かずに足し続けると、表面が広がり続けて、後続のすべての変更が遅くなります。
てこを作る(principle-build-the-lever)
- 些細でない作業では、手作業でこなす代わりに、その作業を実行する、あるいは正しさを証明する道具(codemod、スクリプト、ジェネレータ、再実行可能なチェック)を作ります。基準は繰り返しの有無ではなく、些細かどうかです。明らかな編集が数箇所だけなら道具は不要です。
- 効く場面は、編集、移行、分析、チェックといった作業全般です。最初の1単位は手でやり、次に道具を作って、その単位に再実行することで道具を証明します。再実行しても安全な作りにします。決定的な道具はファンアウトに勝ります。ファンアウトする場合も、レシピと検証契約と柵を、委任先が読めて編集できない1つのスキルとして書きます。適用した証拠はファイルです。diff の中にスクリプト、codemod、ジェネレータ、委任先スキルのいずれもなければ、この原則を適用したことにはなりません。作業がセッションを超えて生きるならコミットします。作るのは仕事をする、あるいは証明する最小のスクリプトで、フレームワークではありません。
- 人間は、エージェントが大量の手編集を始めたときに「principle-build-the-lever。道具を作って」と名指しできます。道具があればレビュアーは再実行して検証できますが、手作業の結果は目視でしか確かめられません。
教訓を構造に埋め込む(principle-encode-lessons-in-structure)
- 同じ指示を2回目に書きそうになった、あるいは繰り返される修正に気づいたら、文章を増やすのではなく、ルールを lint、メタデータのフラグ、実行時チェック、スクリプトといった構造として符号化します。
- 効く場面は、エージェントへの指示が育ってきたあらゆる場面です。判断が必要で符号化できない教訓だけは例外で、その場合は指示をより目立つ位置に置き、失敗の様式の例を添えます。系として、修正が構造的なら構造的な修正だけを使います。指示文のほうは症状にすぎません。
- 人間は、同じ指摘をエージェントに2回した時点で「それ、principle-encode-lessons-in-structure で構造に入れて」と名指しできます。文章の指示は読まれないことがありますが、構造は実行されるたびに効きます。違反を続けると、指示ファイルだけが太り、実効性は上がらない状態になります。
実行と運用
この章の8原則は、作業の進め方と運用の姿勢を扱います。仕事をどの単位に切り、失敗や並行実行にどう備え、人間の監督とどう付き合うか。自律実行の時間が長い pstack では、この章の原則が事故率を直接決めます。
検証可能な単位に並べる(principle-sequence-verifiable-units)
- 仕事は、それぞれがチェック可能な状態で終わる小さな単位の列に並べ、現在の単位がグリーンになるまで次に進みません。
- 効く場面は、一斉変更、移行、類似編集の連続といった複数ステップの作業と、コミットやPRの積み方です。各単位は「既知の良好な状態、1つの変更、チェックの実行、進行」という括弧になります。道具が編集する場合でも、単位ごとのチェックは省略しません。届ける順序自体が証明になるように並べます。失敗するテストを先に、修正を後に。形状変更の前に引き算を。処置の前にベースラインを。各コミットは単独で成立させます。
- 人間は、巨大な一括差分が出てきたときに「principle-sequence-verifiable-units で単位を割って」と名指しできます。単位が大きいと、どこで壊れたかを特定できず、レビューも巻き戻しも効かなくなります。
操作を冪等にする(principle-make-operations-idempotent)
- 状態を変える操作は、何回実行されても、前回の実行がどこで止まっていても、正しい状態に収束するよう設計します。
- 効く場面は、クラッシュ、再起動、リトライの只中で動くコマンド、ライフサイクルの手順、処理ループの設計です。各ステップは「前回が意図したこと」からではなく、実在する状態から導きます。現在の状態を読み、目標と比較し、差分だけを適用します。実行が残すもの(ロック、一時ファイル、書きかけのレコード、取得済みのジョブ)は、前回が止まりうるあらゆる地点で成り立つ証拠によって、次回が「古い残骸だ」と判定できるようにします。書き込みは一時パスに行い、rename で所定の位置に置きます。判定テストは「2回実行したらどうなるか」「前回が可能なすべての地点で落ちていたらどうなるか」で、答えが残骸の内容に依存するなら調整ステップを足します。
- 人間は、デプロイや移行のスクリプトに対してこの原則を名指しできます。冪等でない操作は、失敗したとき人間が手で後始末するまで再実行できず、自律実行の前提を崩します。
呼び出し側を移してから旧APIを消す(principle-migrate-callers-then-delete-legacy-apis)
- 新しい内部APIを入れるとき、互換レイヤーを残して旧APIを延命させるのではなく、呼び出し側の移行と旧APIの削除を同じ波の中で行います。
- 効く場面は、旧来の呼び出し側がまだ存在する内部APIの置き換えです。テストは新しい契約を表明するよう更新し、リファクタ前の実装詳細だけを守っているテストは削除します。前提条件は、後方互換に依存する外部利用者がいないこと、プロジェクトが協調的な破壊的変更を受け入れられること、新APIが単純化やリファクタの一環であること、の3つです。
- 人間は、差分に「当面残す」互換シムが現れたときにこの原則を名指しできます。互換レイヤーは当面のつもりでも長生きし、両方のAPIを保守する税金を払い続けることになります。
共有状態は直列化の前に分離する(principle-separate-before-serializing-shared-state)
- 並行アクターが同じファイル、ブランチ、キー、オブジェクトに書く可能性があるとき、まず「本当に1つの共有物が要るのか、それとも独立した事実をそれぞれ公開しているだけか」を問います。デフォルトは、各アクターに専用のファイル、キー、ブランチ、状態ディレクトリを与え、読む場所でだけ統合することです。
- 効く場面は、サブエージェントのファンアウトや並行ジョブの状態管理です。2つのワーカーが1つの
state.jsonの別々のフィールドに書くのも、依然として共有の変更です。共有する書き込み先が本当の不変条件である場合に限り、ロックファイル、単一の書き手、逐次フェーズ、compare-and-swap といった構造でアクセスを直列化します。「ロックが要る」はまず疑うべき匂いで、指示文は並行制御にはなりません。 - 人間は、並行作業の競合や状態ファイルの破損が起きたときにこの原則を名指しできます。分離で済むものを直列化で解くと、並行度が落ちるうえに競合の余地も残ります。
コンテキストウィンドウを守る(principle-guard-the-context-window)
- コンテキストの溢れは推論の質を落とし、圧縮の歪みを生み、進行を止めます。だから大量の情報はメインスレッドに生で抱えず、要約だけを残します。
- 効く場面は、大きな出力、長いファイル、繰り返しの読み込み、ファンアウトの計画でコンテキストが埋まってきたときです。対処は、量の多い作業をサブエージェントに回し、メインスレッドには生のペイロードではなく要約を置くことです。あわせて、フェーズの大きさを見積もり範囲に上限を設け、ファイル数やターンの予算を管理し、仕組み自体のコストも計算に入れます。
- 人間は、エージェントの応答品質が長いセッションの後半で落ちてきたときにこの原則を名指しできます。違反はエラーとしてではなく、判断の精度低下として静かに現れるのが厄介な点です。
人間でブロックしない(principle-never-block-on-the-human)
- 人間は非同期に監督する存在で、エージェントはブロックされてはいけません。妥当な判断をして進み、人間には事後に軌道修正してもらいます。コードの変更は可逆でレビュー可能なので、誤った判断のコストは、たいていブロックするコストより小さく済みます。
- 効く場面は、可逆な作業について「Xをすべきか」と聞きたくなった瞬間です。進めてから見せる。仕事をして結果を示し、「すべきか」ではなく「やった理由」を説明します。問題に気づいたら記録して次のラウンドで直す、自己修復の形にします。ただし不可逆な操作(force-push、本番データの削除、外部へのメッセージ送信)は引き続き確認が必要です。製品の方向性は人間が出すもので、ブロックしてよいのはそちらで、実行はブロックしません。
- 人間は、エージェントが細かい確認質問で止まったときに「principle-never-block-on-the-human。可逆なら進めて」と名指しできます。逆に、不可逆な操作まで無断で進めたら、それはこの原則の適用範囲外であり、明確な越権です。
成果志向の実行(principle-outcome-oriented-execution)
- 中間状態の滑らかさを保つことより、意図した検証可能な最終状態への収束を優先します。すべての途中段階を完全に安定させようとすると、一時的な互換コードが生まれ、それが長生きする負債になります。
- 効く場面は、明示的なフェーズ境界を持つ計画された書き直しと移行です。中間の破壊は、計画され、範囲が区切られ、可逆である場合に許容されます。守るべき柵は、一時的な破壊を許す場所を宣言すること、移行中も活発に触っている領域には信号の強いチェックを維持すること、計画の完了時に静的・実行時の完全な検証を要求すること、の3つです。
- 人間は、移行の差分に使い捨てのつもりの互換コードが増えてきたときにこの原則を名指しできます。ただし前提は「計画された」作業であることで、無計画な破壊を正当化する原則ではありません。
体験を先に(principle-experience-first)
- 実装の都合と利用者の喜びが衝突したら、喜びを選びます。出す機能は少なく、磨かれたものを。粗い10機能より、磨かれた3機能が勝ちます。
- 効く場面は、製品、UX、機能範囲のトレードオフです。すべての機能、コントロール、オプションには存在理由が要ります。本番コードで決める前に、使い捨てのHTMLで試作して設計判断を安く済ませます。遷移、整列、間隔、フィードバック、エラー状態といった細部を正しく作り、中核のループを締めます。すべての機能は中心のワークフローに仕えるか、退場するかです。「利用者」は文脈で変わり、UIならエンドユーザー、ライブラリや内部APIなら取り込む同僚、そして次に保守するエンジニアも利用者です。その体験も同じ重さで測り、影響はその人の視点で説明します。foundational-thinking が作業の順序を規定するのに対し、この原則は作業の目標を規定します。
- 人間は、エージェントが実装の楽さで仕様を削ろうとしたときに「principle-experience-first。利用者側で選んで」と名指しできます。違反は、動くけれど誰も使いたくない成果物として現れます。
似ているスキルの使い分け
pstack のスキルは名前が似た組が多い。迷ったときの判断軸は「いま何が足りないか」だ。作るのか、直すのか。仕組みを知りたいのか、経緯を知りたいのか。壊しにいくのか、進め方を設計するのか。この章では間違えやすい組を「迷う場面 → どちらを選ぶか → 理由」の形で並べる。
create-verification-skill と maintain-verification-skill
迷う場面: アプリの振る舞いを自動で確かめる仕組みが心もとない。
- 検証スキルがまだない、または土台から作り直したい →
create-verification-skill - 検証スキルは既にあり、アプリの変化に追いついているか確かめたい →
maintain-verification-skill
理由: create はリポジトリを調べ、アプリの起動方法、ユーザーの操作を再現する駆動方法、証拠の残し方をプロジェクト専用のスキルとして生成し、feature map の種まで用意する。maintain はその成果物の保守専用で、編集範囲は検証スキルのディレクトリだけに限られる。ソースを feature ごとに読み直し、実際に全 feature を動かして、ドキュメントのずれと製品の退行を切り分ける。製品コードは直さない。maintain の対象が存在しないなら、maintain は止まって create を案内する。
通常の verification と formal verification
迷う場面: 「ちゃんと動く」をどこまで強く言いたいか。
- 実物をユーザーの経路で動かして振る舞いを確認したい → 通常の verification(検証スキルと Prove It Works)
- テストが届きにくいケースまで含めて性質を保証したい →
create-formal-verification-skill
理由: 通常の verification は実際に起きたケースの確認だ。書いた人の思いついたケースしか見ない。一方 formal verification は、宣言した範囲の中の全ケースを調べる。ステップの順序が問題ならモデル検査、入力全体への性質なら検証器や証明、という具合に問いが道具を選ぶ。並行処理、リトライ、状態機械、パーサのように「壊れるケースが滅多に起きず、起きると高くつく」場所で真価を発す。代わりに範囲と前提の外は保証しないので、範囲の正直な明示がセットになる。日常の変更確認は通常の verification、壊れると致命的な約束には formal、と使い分ける。
why と how
迷う場面: 初めて触るサブシステムで「これ、どうなってるの」と聞きたい。
- 今のコードがどう動くか、どこに何を置くべきか知りたい →
how - なぜこの形になったか、なぜ最近壊れたか知りたい →
why
理由: how はコードベースを探索して、構造と実行時の流れからメンタルモデルを作る。why はコードではなく記録を読む。導入したコミットと PR の議論、後からの変更の積み重ねから、判断とトレードオフを引用つきで返す。推論は推論と明示する。順番も大事で、不具合の調査では how で仕組みを掴んでから why で経緯を当たると、現在の振る舞いと壊れた理由が混ざらない。
interrogate と figure-it-out
迷う場面: 大きな変更を前に、攻めるべきか組み立てるべきか。
- 既にある変更や設計の穴を探したい →
interrogate - 合うプレイブックがない大きな仕事の進め方から決めたい →
figure-it-out
理由: interrogate は敵対的レビューだ。複数のモデルが変更を壊しにいき、実際に再現できた指摘だけが残る。修正はしない。figure-it-out は逆に建設側で、成果物はコードではなくワークフローそのものだ。完了の定義を反証可能な条件に落とし、リスクの高い未知要素から順にフェーズを組み、判断ログを残す設計をする。移行や複数パートの大きな変更、離席中に進む仕事が対象になる。「設計を疑う」なら interrogate、「仕事の進め方がまだない」なら figure-it-out。
ketchup と ketchup-video
迷う場面: 離れていたチャットの状況に追いつきたい。
- 文章で素早く把握したい →
ketchup - 作業の様子を目で見て把握したい →
ketchup-video
理由: どちらも読み取り専用で、前回の自分の発言以降に何が変わったかを平易な言葉で伝え、判断待ちの項目を「おすすめの選択肢、根拠、リスク」つきで並べる。違いは媒体だけだ。ketchup はスクリーンショットや小さな図を含む文章、ketchup-video は作業が生んだスクリーンショットや差分から作る字幕つきスライド動画で、上限は10枚。画面の変化が本体の仕事(UI の見た目、フローの遷移)なら video、判断材料が言葉で足りるなら ketchup で十分だ。
sharpen と correct と unslop
迷う場面: 出力が今ひとつで、何かを「直したい」。
- これから送るプロンプトが浅い →
sharpen - エージェントが同じ間違いを繰り返す →
correct - 文章に AI っぽい癖が残っている →
unslop
理由: 対象が全部違う。sharpen はタスクの実行ではなく依頼の書き直しだ。専門家なら頼まれなくてもやること、最初に当たるべき生の素材、使う手法と道具、正しさを第三者がどう確かめるかを挙げ、プロンプトを「深く、大きくはしない」形に書き換えて返す。correct はリポジトリ側を直す。繰り返される間違いをクラスにまとめ、アーキテクチャ、型、エラーメッセージに直し方を書いた lint、テスト、文書の順に、再発できない仕組みへ落とす。unslop は文章の編集専用で、決まり文句、冗長な言い回し、根拠のない断定などを削る。プロンプトの質は sharpen、再発防止は correct、文章の仕上げは unslop。
autonomous-run と autopilot-full と autopilot-stack
迷う場面: 離席中に仕事を進めたいが、どこまで任せるか。
- 1つの仕事を終わりまで回したい → Autonomous run プレイブック
- 独立した PR のキューをマージまで任せたい → Autopilot-full
- マージは自分の目で見てからにしたい → Autopilot-stack
理由: autonomous-run は単一の仕事のループだ。終了条件を検証可能な述語として先に固定し、最小の変更、検証、コミットか破棄、判断ログ1行を繰り返す。autopilot はキューの運用で、PR ごとに担当エージェントが1人つき、構築から PR 作成、CI の面倒見まで担う。ただし書いた本人は自分の PR を採点しない。コードを書いていない検証エージェントの群れが最終形を検証し、合格したパッチだけがマージされる。autopilot-full はその検証を通過したものをマージまで進める。autopilot-stack は検証済みで止め、朝に自分がレビューして着地させる。依存関係のある PR 同士はスタックにできる。任せる範囲の違いがそのまま選択になる。「終わらせてほしい」が full、「用意しておいてほしい」が stack、「1件を粘ってほしい」が autonomous-run。
寝ている間に仕事を任せる
自律実行の成否は、夜の頑張りではなく昼の準備で決まる。自分で検証できるエージェントだけが、放っておけるエージェントだ。この章では、任せる前の準備、実行中の組み合わせ、朝の受け取り方、安全策の順にまとめる。
任せる前の準備
信頼していないループは、未検証の仕事を高速に量産するだけだ。任せる前に次を揃える。
- その仕事を一度は自分でやるか、エージェントがやるのを見て、「良い状態」がどういうものか知っている
- 検証スキルがある。エージェントが自分と同じ道具と信号(検証スキル、プロファイラ、ログ)を使える
- 検証スキル自体が動くことを確認済みで、feature map が現状とずれていない(古ければ
maintain-verification-skillで先に直す) - 原則が効く状態になっている。特に Prove It Works(実物で確かめる)、Fix Root Causes(根本原因を直す)、Sequence Work into Verifiable Units(検証できる単位に割る)
- 過去の実行記録を読み、繰り返し起きた失敗を道具、スキル、チェックへ変換済み
この条件が揃うまでは、見ている前で回す。揃って初めて夜に回す。
実行の組み合わせ
仕事の形で使い分ける。
- 1件の仕事: Autonomous run プレイブック。終了条件を述語で固定し、
/loopで定期的に目覚めて進める。イベント(CI の完了やマージ)を待つ場面では watcher が起こし、時刻ベースのハートビートを保険に置く - 独立した PR のキュー: Autopilot-full(マージまで)か Autopilot-stack(検証済みで停止)。PR ごとに担当エージェントがつき、検証はコードを書いていないエージェントの群れが行う
- 進行中の PR の面倒見: Babysit プレイブック。CI とレビュースレッドを見張り、緑になるまで運ぶ。watch-pr スクリプトが GitHub の状態を監視する。Babysit はマージの許可にはならない点に注意する
- プログラム全体(複数パッケージの移行など): 専用プレイブックはないので
figure-it-outがフェーズ設計と判断ログつきの実行を組む
引き継ぎ文には、目的、完了条件、許可、逃げ道の4点を書く。長さは要らない。
/poteto-mode 寝ます。全呼び出し元を新しいパーサへ移行して。<base> から新しい worktree で。
完了の定義は、旧呼び出し元ゼロ、全 fixture 通過、旧 API の削除。
判断ログを残して。コミット前に聞かなくていい。
終わるまで /loop して。本当に詰まったら数時間で止めて、理由を書いて。
「寝ます」はセッションオーバーライドで、エージェントは質問を止めて進み続ける。「完了の定義」が各イテレーションで実行できるチェックになる。worktree の指定は他の作業との衝突を防ぎ、コミット許可を先に答えておくことで夜中のブロックを消す。逃げ道は大事で、本当の行き詰まりでは止まって理由を書くほうが、8時間かけて目的を勝手に解釈し直されるよりましだ。
途中で止めたくなったら「止めて」と伝える。Pause safely プレイブックが現在のステップを終えるか巻き戻し、wip: コミットでチェックポイントを残し、再開ノートを書く。新しいチャットは Session pickup プレイブックがそのノートと判断ログから状態を復元する。「続けて」は一時停止の合図にはならない。
朝の受け取り方
朝の仕事は監査であって、全作業の読み直しではない。
/show-me-your-workで昨夜の要約を取る。判断ログ(decisions.tsv)の各行には時刻、フェーズ、判断、理由、証拠へのポインタ、結果が残っている。要約の前に別のモデル系統のレビュアーが記録とトランスクリプトを読み、返信の最後に「注意して見るべき点」が付く。まずそこを読む- 注意点が指すログ行だけを辿り、証拠(コミット、スクリーンショット、実際のコマンド出力)を開いて確かめる
- 軽く現状だけ知りたいときは
/ketchup。前回の発言以降の変化と、判断待ちの項目が平易な言葉で返る
結果が INCONCLUSIVE の行は、成功でも失敗でもなく「判定できていない」として扱う。丸めて成功に数えない。ベンチマークの数字なら benchmark-checklist の流儀で、測定回数、ばらつき、数字を制限している要因を確認し、条件を整えて再測定する。検証が詰まった行なら、証拠が何を示せなかったのかを見て、再実行するか人間の判断に回す。inconclusive を放置すると、朝の監査全体の信頼が崩れる。
キューを任せた朝は、PR ごとに「状態と検証結果」が返る。Autopilot-stack なら検証済みの PR が並んでいるので、自分の目で見て着地させる。マージの判断材料は CI の緑ではなく、検証エージェントの合格と証拠だ。
安全策
poteto-mode の自律性には明確な線がある。
- 可逆な作業と外部への働きかけは聞かずに進める
- 取り返しのつかない操作では必ず止まる。共有ブランチへの force-push、デプロイ、データの削除、顧客へのメッセージが該当する
- 終了条件を緩めて勝利宣言しない。頭打ちは停止理由ではなく、やり方を変えて続ける。本当の行き詰まりだけを報告する
- 効かなかった変更は残さず捨てる。「効くかもしれない」保険的な変更も巻き戻す
- ゲートを緩める変更(予算の引き上げ、許可リストの追加)は、検証者の証明とルート側の再承認が要る。緑が欲しい担当者自身には緩めさせない
- 作業は worktree かクラウドエージェントで隔離する。並行エージェントが同じ作業ツリーを踏み合うと、誰の変更か分からなくなる
時間は完了条件にならない。「4時間働いて」は検証できる述語を持たず、朝に残るのは結果ではなく4時間分の動きだ。/loop には通るか落ちるかが分かる条件を渡す。
レシピと TIPS
コピペして使えるプロンプト集。パスや完了条件は自分のものに置き換える。文面は普段タイプする調子のままでいい。スキルは意図を読む。効く原則は各レシピに一言添えた。
バグ修正
/poteto-mode リトライ後に通知が2回届きます。まず再現して、それから直して検証して。
狙い: 再現を先に固定し、症状ではなく再現手順に対して直す。効く原則は Fix Root Causes。再現できないバグは直ったことにもできない。
/poteto-mode このスレッドを読んで。根本の問題を自分の言葉で、平易に言い直して。コードはまだ変えないで。
狙い: 長い報告や曖昧な不具合は、まず言い直させて読み違いを1メッセージで潰す。自分の原因説は、エージェントが自分の言葉で述べるまで伏せておく。言い直しだけなら /in-your-own-words でもよい。
機能追加
/poteto-mode 設定画面のレイアウト案をいくつか試作して。切り替えられるようにして、各案のスクリーンショットを送って。
狙い: 説明文ではなく動くものから選ぶ。配置やタイミングの疑問はエージェントが試作の中で自分で解消する。効く原則は Exhaust the Design Space。
/poteto-mode この設計を計画に変えて。小さく検証できる PR の並びで、それぞれに証明つきで。
狙い: 設計が固まってから計画を頼む。計画そのものが成果物になり、実行するプレイブックまで名前が付く。効く原則は Sequence Work into Verifiable Units。
調査
まず /how でこの初期化がどう動くか理解して。次に /why で最近なぜ壊れたか調べて。
狙い: 仕組みが先、経緯が後。各スキルの報告には調べた情報源が付くので、答えの根拠が見える。
/interrogate ブランチ全体を、懐疑的に。まだ何も変えないで。実際のバグか振る舞いの退行でなければ細かい指摘は要らない。
狙い: 読み取り専用の敵対的レビュー。修飾語が仕事をする。「まだ変えないで」が読み取り専用を保ち、細かい指摘の除外がノイズを先に落とす。残るのは再実行で証明された指摘だけだ。
リファクタリング
/correct エージェントが新しい設定フラグをスキーマへ登録せずに追加し続けます
狙い: 同じ間違いの手直しをやめ、リポジトリの構造(アーキテクチャ、型、lint、テスト)で再発できなくする。効く原則は Encode Lessons in Structure。
/swarm packages/ 以下の各パッケージを、それぞれの check.sh と照らして確認して。パッケージごとに担当1人。報告は1つにまとめて。
狙い: 独立した断片は並行に確認する。各担当が1パッケージを持ち、親は全員の完了を待って PASS、ISSUES、BLOCKED の1報告に集約する。生の出力を全部貼らせない。
PR 作成
/poteto-mode この変更を PR にして。実物での証拠を PR の説明に入れて。
狙い: Opening a PR プレイブックが worktree から進める。ビルドが通ったことではなく、実際のフローや出力の証拠を説明に残す。効く原則は Prove It Works。
レビュー対応
/interrogate このブランチへのレビューコメントを全部見て。再実行で証明できるものだけ残して、落としたものと理由も一覧にして。
狙い: Bot と人間のコメントは本物とノイズが混ざっている。全件採用も全件却下もしない。証明できた指摘だけを残し、落とした理由も残すので、判断を後から覆せる。
検証の依頼
/poteto-mode /verify-<app> でこれを再現して。main でも再現するなら直して、証拠に動画を見せて。
狙い: 「main でも再現するなら」が効く。既に直っているバグなら早期に止まれる。動画があれば差分を読む前に修正の正しさを確かめられる。
/benchmark-checklist この40%高速化を、PR の説明に載せる前に吟味して
狙い: 数字を外に出す前に検証する。返るのは「速くなった、遅くなった、測定できる差なし、判定不能」のいずれかで、測定回数とばらつき、数字の限界つき。効く原則は Explain the Number。
セッション再開
/poteto-mode 止めて
狙い: Pause safely が現在のステップを安全な境界で止め、wip: コミットと再開ノートを残す。中断が前提の場面では、最初からこれを使う。
新しいチャットで: 前のセッションの続きから。再開ノートと判断ログを読んで、再開地点を教えて。
狙い: Session pickup が前任の記録を権威ある入力として読み、済んだ仕事をやり直さない。前任の自己報告は鵜呑みにせず、引き継いだ主張は実物で確かめる。効く原則は Guard the Context Window と Prove It Works。
TIPS
- プロンプトにスキルを列挙しない。「/architect のあと /arena、そのあと /interrogate」はプレイブックが既に組んだ順序を崩す。目的と制約を書き、既定を覆したいときだけスキル名を出す
- 完了条件は、通るか落ちるかが分かる形で書く。「良くして」「1時間やって」はチェックにならない
- 送る前に迷ったら
/sharpenにプロンプトを研がせる。タスクは実行されず、書き直されたプロンプトだけが返る - 返信が専門用語だらけで頭に入らないときは
/bro。前回の返信を平易な言葉で言い直す - 方向転換は原則の名前で短く。「再現が目的だと言った。修正はまだ頼んでいない」「Prove It Works を適用して。ビルドログではなく実物の出力を」
よくある失敗と対処
どれも一度はやる失敗だ。各項目を「症状 → 原因 → 対処」の形で書く。対処には使うスキルと原則を添えた。
証拠なしの完了報告を鵜呑みにする
症状: 「直しました、ビルドも通っています」と返ってきたのに、実際のフローではまだ壊れている。
原因: ビルドの成功はコンパイルできることの証明でしかない。エージェントも人間も、代理指標(ビルド、型、テストの一部)を実物の振る舞いと取り違える。
対処: 完了の定義に証拠の形まで含める。実際のコマンド出力、フローの動画、保存された値、変更前後の数字を要求する。使う原則は Prove It Works。検証はプロジェクトの検証スキル(verify-<app>)で実物の経路を駆動する。報告を受けたら、証拠ポインタが実在するかを開いて確かめる。
書いた本人に採点させる
症状: 自律実行や PR のキューが全部「成功」で戻ってくるのに、品質がばらつく。
原因: 変更を書いたエージェントが自分の仕事を検証すると、甘くなる。緑が欲しい側がゲートを持つ構造自体が問題だ。
対処: 検証はコードを書いていない側に回す。Autopilot では検証エージェントの群れ(swarm)が最終形を検証し、合格したパッチだけが先へ進む。設計の第二意見は arena や interrogate で別モデル系統に取る。ゲートを緩める変更には検証者の証明と第三者の再承認を必須にする。
計画を磨きすぎる
症状: コードのない計画書が何度も敵対的レビューを通り、想定リスクのリストだけが育つ。
原因: 実物のない抽象計画へのレビューは、起きないリスクを発明する。検証材料がないので議論が空転する。
対処: 未決の問いは試作で潰す(Prototype プレイブック、Exhaust the Design Space)。動くものを並べて選んでから、設計を計画に変える。レビューは作ったものに対して interrogate で行い、実行で証明できる指摘だけを残す。
コメントと差分が膨らむ
症状: PR の差分に説明コメントと冗長な変更が増え、レビュアーが本体を追えない。
原因: エージェントは丁寧さと量を取り違え、書いた理由をコード内コメントに残しがちだ。差分にも「ついで」の変更が混ざる。
対処: コミット前に /no-comments を通し、Comment Sicko(コメント専門の別視点エージェント)に要らないコメントを洗い出させる。コミット前の slop 削り(deslop、無ければ差分を読み直して自分で削る)もセットにする。差分の肥大には Laziness Protocol。最小の変更に戻し、ついでは別 PR に分ける。
引き算をしない
症状: 機能も抽象化も増える一方で、古い経路と死んだコードが残り続ける。
原因: 追加は目に見える成果だが、削除は成果として数えにくい。エージェントは既存の例をコピーするので、古いやり方が残るほど複製される。
対処: 追加の前に引き算する(Subtract Before You Add)。新しい API を入れたら呼び出し元を移行して旧 API を同じ波で消す(Migrate Callers Then Delete Legacy APIs)。繰り返される間違いは /correct で構造から消す。
文脈ウィンドウを浪費する
症状: 長い実行の後半で判断が鈍る。大きな出力やファイルの読み直しでメインの文脈が埋まる。
原因: 大量の作業ログ、探索結果、並行作業の生出力を全部メインスレッドに抱える。
対処: 大物はサブエージェントに回し、要約だけをメインに残す(Guard the Context Window)。ファイルは内容を貼らずポインタで渡す。長いトランスクリプトはサブエージェントに解析させ、縮約した時系列だけを持つ。離席中の仕事は判断ログ(show-me-your-work)に判断と証拠ポインタだけを残し、本文を文脈に溜めない。
人間がボトルネックになる
症状: エージェントが些細な確認で何度も止まり、離席したはずなのにスマホに質問が溜まる。
原因: 可逆な判断まで承認を求める癖が残っている。引き継ぎ文に許可と完了条件が書かれていないと、エージェントは聞くしかない。
対処: 可逆な作業は進めて結果を見せ、軌道修正で受ける(Never Block on the Human)。引き継ぎには完了条件と許可(「コミット前に聞くな」など)を先に書く。実験で決着できる問いは試作で解かせ、製品や好みの判断だけを人間に残す。逆に、取り返しのつかない操作(force-push、デプロイ、データ削除、顧客への連絡)では必ず止まるのが正しい。
その他の定番
- スキルをプロンプトに列挙する: プレイブックの順序を手書きで崩す。目的と制約だけを書き、覆すときだけ名前を出す
- 原因の自説から入る: エージェントは指さした場所しか探さない。先に言い直させ、自説は後から出す
- 曖昧な完了条件: 「良くして」ではループが判定できない。通るか落ちるかが分かるコマンドや成果物を渡す
- 吟味していない数字を信じる: 温まったキャッシュや未実行の経路が高速化を偽装する。外に出す前に
/benchmark-checklist - 同じ間違いを手で直し続ける: チャットの訂正はその実行だけに効く。
/correctでリポジトリを直す arenaを網羅確認に使う: arena は1つの課題への複数案から良い部分を接ぎ木するもの。断片の並行確認はswarm- レビューコメントを全件受け入れる: 本物とノイズは混ざって届く。
/interrogateで再実行できるものだけ残す - 緑のビルドを成功と報告する: ビルドはコンパイルの証明。実物の出力や状態を証拠にする
最初の1週間と用語集
導入は段階を踏む。いきなり夜通しの自律実行から始めない。見ている前で1件回し、検証の土台を作り、プレイブックの運用に慣れてから、最後に自律実行を試す。
Day 1: poteto-mode で1件回す
/setup-pstack でセットアップを済ませ、Custom Mode で /poteto-mode を常駐させる。手元の実タスクを1件、見ている前で回す。プロンプトには目的と完了条件だけを書き、プレイブックのステップが todo に展開される様子と、原則の名前で判断が説明される様子を確認する。終わったら、証拠が実物かどうかを自分の目でも確かめる。
Day 2: 言い直しと調査の型を覚える
曖昧な報告を /poteto-mode に言い直させてから着手する型と、how(仕組み)と why(経緯)の使い分けを試す。過去の不具合を1件選び、how で構造を、why で壊れた経緯を調べる。返信が読みにくいときの /bro と、送る前の /sharpen もこの日に触っておく。
Day 3: 検証スキルを作る
/create-verification-skill で、自分のプロジェクト専用の検証スキル verify-<app> を作る。起動、状態確認(doctor)、ユーザーの経路での駆動、証拠の保存、後片付けまでが揃い、主要 feature の map ができる。生成されたスキルを実際に1回通しで実行し、証拠が残ることを確認する。ここが後の全ての土台になる。
Day 4: プレイブックで日常を回す
バグ修正、機能追加、PR 作成をプレイブック経由で回す。レビュー対応には interrogate を使い、証明できる指摘だけを残す練習をする。繰り返し目にした間違いがあれば /correct でリポジトリ側に再発防止を仕込む。コミット前の /no-comments と slop 削りを習慣にする。
Day 5: 並行作業と PR の面倒見
独立した確認作業を swarm で並行に回し、報告が1つに集約される形を試す。進行中の PR には Babysit プレイブックを使い、CI とレビュースレッドを緑まで運ぶ。並行エージェントには worktree を分けるかクラウドエージェントを使い、同じ作業ツリーを共有しない。
Day 6: 短い自律実行を試す
見ていられる時間帯に、Autonomous run を短く回す。終了条件は検証可能な述語で書き、判断ログ(show-me-your-work)が1イテレーション1行で残ることを確認する。途中で「止めて」と言い、Pause safely の wip: コミットと再開ノートから、新しいチャットで Session pickup が再開できることも試す。
Day 7: 夜のキューを組む
検証スキルと判断ログへの信頼ができたら、夜の仕事を組む。独立した小さい PR のキューなら Autopilot-stack(検証済みで停止)から始め、朝に /show-me-your-work の注意点と /ketchup で受け取る。マージまで任せる Autopilot-full は、stack の受け取りを何度かこなしてからにする。取り返しのつかない操作では必ず止まる線引きも、この日に引き継ぎ文へ明記する。
用語集
- slop: AI が量産する中身の薄い成果物の総称。冗長な文章、要らないコメント、「ついで」の変更など。コミット前の slop 削りを deslop と呼ぶ。
- poteto-mode: pstack の入口スキル。目的を受け取り、22のプレイブックから仕事に合うものを選び、ステップを todo に展開して他のスキルを呼ぶ。
- playbook: 仕事の型ごとの手順書。バグ修正、機能追加、自律実行、PR の面倒見など。poteto-mode の配下に同梱される。
- principle: 判断の原則。Prove It Works や Laziness Protocol など、名前で呼び出して進路を短く修正できる語彙。各原則は独立したスキルとして定義される。
- verification skill: プロジェクト専用に生成される検証スキル(
verify-<app>)。アプリの起動、駆動、証拠の残し方と feature map を持ち、エージェントが実物で振る舞いを証明するための土台。 - formal verification: テストが書かれたケースだけを見るのに対し、宣言した範囲の全ケースを調べる検証。モデル検査や証明器を使う。壊れると高くつき、テストが届きにくい性質に使う。
- Comment Sicko: コメント専門のレビュー担当エージェント。要らないコメントや主張だけのコメントを洗い出す。
/no-commentsが別視点として起動する。 - benny: Slack の issue 報告を捌く自動化パック。報告のトリアージと、確定したバグの再現と下書き修正を行う2つの自動化からなる。同梱はされているが初期状態では眠っている。
- ketchup: 離れていたチャットへの追いつき直し。前回の自分の発言以降の変化を平易な言葉で伝え、判断待ちの項目をおすすめと根拠とリスクつきで並べる。読み取り専用。
- inconclusive: 判定不能。数字や検証が、成功とも失敗とも言えない状態。成功に丸めず、条件を整えて測り直すか人間の判断に回す。
- decision log:
show-me-your-workが残す判断の記録。時刻、フェーズ、判断、理由、証拠ポインタ、結果を1行ずつ TSV に残す。朝の監査はここから始まる。 - swarm: 独立した断片や検証を、担当を分けて並行に走らせるスキル。親は全員の完了を待ち、1つの報告に集約する。
- arena: 1つの課題に対して複数の案を走らせ、最良の案を土台に良い部分を接ぎ木するスキル。設計の第二意見に使う。網羅確認には使わない。
- worktree: 同じリポジトリの別作業ツリー。並行するエージェントやタスクごとに分け、互いの変更を踏み合わないための隔離単位。