superpowers 実践編 — スキル深掘り・カスタム開発・品質ガバナンスの全貌

はじめに

本記事は superpowers シリーズの第3回（実践・カスタマイズ編）だ。入門編では superpowers の14スキルの概要、2時間以上の自律作業を実現する仕組み、6ツール向けのインストール手順を取り上げた。第2回の設計パターン編では、スキル横断で使われる設計パターン（Iron Law、合理化防止テーブル、Red Flags、CSO、XML タグ等）を解説した。

本記事では個別スキルの内部設計に踏み込み、「各スキルは内部でどう動いているのか」「自分のプロジェクト固有のルールをスキルとして組み込めないか」「このリポジトリはなぜ94%のPRを却下するのか」といった疑問に答える。

対象読者は入門編を読み終えた人だ。14スキルの名称や役割、基本的なインストール方法については入門編を参照してほしい。

注記: 本記事の情報は2026年4月時点のものであり、各リポジトリの機能・数値は変動する可能性がある。最新の情報は各リポジトリの README を参照してほしい。

1. systematic-debugging を深掘りする

入門編では「4段階フロー（Root Cause Investigation → Pattern Analysis → Hypothesis and Testing → Implementation）」と「場当たり的な修正を防止する」という概要レベルの説明にとどめた。実際のスキル実装はより精緻な設計になっている。

1-1. フロー詳細と「根本原因なき修正禁止」原則

スキルの最も重要な制約は、証拠収集なしに修正を試みてはならないという強制だ。原文では次のように定義されている。

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

デバッグを「早く終わらせたい」という圧力下では、エージェントは症状が現れている箇所に直接パッチを当てようとする。systematic-debugging はこの衝動を構造的にブロックする。特筆すべきは「時間的プレッシャー下でこそ体系的手順を守れ」という明示的な警告が含まれている点だ。直感に反するが、焦っているときほど場当たり的な修正が連鎖して時間を浪費する。

1-2. 「3回失敗したら止まれ」アーキテクチャルーブレーカー

フローに組み込まれた重要なエスカレーションルールがある。同じ問題に対して3回以上の修正が失敗した場合、それはバグではなくアーキテクチャ上の問題を示しているとみなし、作業を中断してパートナー（ユーザー）に状況を報告させる。

これは現実的な知見だ。3回連続で修正が失敗する状況は、根本的な設計の問題や誤った前提に基づいたアプローチであることが多い。無限ループに陥る前にエスカレーションを強制することで、エージェントが何時間も無意味な試行を繰り返す事態を防ぐ。

1-3. 補助ドキュメント群の役割

systematic-debugging スキルには、SKILL.md 本体に加えて独立した補助ドキュメントが付属する。

root-cause-tracing.md — コールチェーンを遡る

症状が現れた箇所を修正するのではなく、コールチェーンを上流に向かって遡り、問題の発生源を特定するガイドラインだ。5ステップで構成されている。

1. 症状を観察する — エラーが現れている箇所を特定
2. 直接的な原因を特定 — その箇所を担当するコードを特定
3. 呼び出し元を追う — コールチェーンを上流に辿る
4. 遡り続ける — 問題のある値がどこから来たかを追跡
5. 発生源を特定 — 無効なデータが生まれた本当の起点を見つける

手動トレースが難しい場合は、危険な操作の直前に計装コードを追加することを推奨している。ログ出力には console.log ではなく console.error() を使う（テスト実行時にロガーが出力を抑制する可能性があるため）。

defense-in-depth.md — 4層バリデーションで構造的にバグを不可能にする

根本原因を修正した後、同じ問題が再発しないよう多層防御を実装するガイドだ。

第1層: エントリーポイント検証
  → API境界で明らかに無効な入力を拒否（ディレクトリ存在確認、空文字チェック）

第2層: ビジネスロジック検証
  → 操作の文脈でデータが意味をなしているか確認

第3層: 環境ガード
  → テスト環境等、特定の文脈で危険な操作を防ぐ

第4層: デバッグ計測
  → 問題発生時の調査用コンテキストをログに記録

「なぜ単一の修正ではなく4層が必要か」についても明確に回答されている。異なるコードパスが第1層を回避したり、モックが第2層を迂回したりするため、層ごとに相互補完の関係が必要になる。

1-4. condition-based-waiting — 非同期テストの不安定さを解消する

systematic-debugging には、テストの不安定性（flaky test）に対処するための専用テクニックが付属する。condition-based-waiting.md で解説されている手法で、核心は「任意の待機時間ではなく、実際の条件成立を待つ」という原則だ。

// BAD: 任意の待機時間を推測する（マシン負荷で結果が変わる）
await new Promise(r => setTimeout(r, 50));
const result = getResult();
expect(result).toBeDefined();

// GOOD: 条件が成立するまでポーリングする
await waitFor(() => getResult() !== undefined);
const result = getResult();
expect(result).toBeDefined();

汎用的なポーリング関数 waitFor と、それを拡張したドメイン固有ヘルパー（waitForEvent、waitForEventCount、waitForEventMatch）の実装例が TypeScript で提供されている。ポーリング間隔は 10ms、タイムアウト付きで無限ループを防止する設計だ。

このテクニックを適用した実績として、「15件の flaky テストを修正し、パス率 60% → 100%、実行時間 40% 短縮」という結果がスキル付属ドキュメント（condition-based-waiting.md）に記録されている。ただし任意のタイムアウトが正当な場面（デバウンスやスロットル間隔のテストなど）もあり、その場合は「なぜその待機時間なのか」をコメントで説明することが求められている。

1-5. find-polluter.sh — テスト汚染の犯人を特定する

もう一つの補助ツールとして find-polluter.sh がある。これは「単独では通るが、他のテストと一緒に実行すると失敗する」テスト汚染問題を特定するための bash スクリプトだ。

# 使い方: どのテストが .git を不正に生成しているかを特定する
./find-polluter.sh '.git' 'src/**/*.test.ts'

動作原理はシンプルだ。テストファイルを1つずつ順番に実行し、各テストの実行後に指定されたファイルやディレクトリが出現したかをチェックする。汚染源を検出した時点で、対象のテストファイル名と調査用コマンドを出力して終了する。二分探索ではなくリニアサーチだが、問題の特定には十分実用的な設計になっている。

2. subagent-driven-development の設計思想

入門編では「サブエージェントによる2段階レビュー」という概要を説明した。このスキルの核心は、バイアスを構造で排除する設計にある。

2-1. 3つのプロンプトテンプレートの役割分担

スキルには3つの専用プロンプトファイルが付属する。それぞれが異なる「疑いの視点」を担う。

implementer-prompt.md — 実装エージェントへの作業指示

タスクを受け取って実装する主体エージェント向けの指示だ。6ステップのワークフローが定義されている。

1. 実装実行 — 仕様に沿ってコードを書く
2. テスト作成 — TDD 適用時はその手順を遵守
3. テスト検証 — 実装が動作することを確認する
4. コミット — 変更を確定する
5. 自己レビュー — 4分野（完全性・品質・規律・テスト）でチェック
6. 報告 — 結果をステータスと共に報告する

注目すべきは「報告前の自己レビューチェック」（ステップ5）が組み込まれている点だ。完全性（要件漏れ・未対応エッジケースの確認）、品質（命名の明確さ・保守性）、規律（YAGNI原則の遵守・過剰実装の排除）、テスト（動作検証の有効性・網羅性）の4分野を検査してから報告させる。

また、作業を中断してエスカレーションすべき5つの条件も定義されている。「複数の有効なアプローチが存在するアーキテクチャ的決定が必要な場合」「提供されたコンテキスト外のコード理解が必要な場合」「アプローチの正しさに確信が持てない場合」などがこれにあたる。エージェントが「なんとかやってみる」のではなく、不確実な状況では人間に判断を委ねる行動を強制している。

spec-reviewer-prompt.md — 懐疑的仕様適合検証

実装者とは別の独立したエージェントが、実装が仕様を満たしているかを検証する。このプロンプトの出発点となる前提が興味深い。

「実装者はあまりにも早く完了した。報告内容は不完全か、不正確か、楽観的すぎる可能性がある。」

実装者の完了報告を信用しない、という強制的な懐疑姿勢がデフォルトとして組み込まれている。検証作業は報告書を読むのではなく、実際のソースコードを直接読み、仕様要件と実装を行単位で比較する。主張されているが実装されていない機能と、要求されていないのに追加された機能（過剰実装）の両方を検出する。

code-quality-reviewer-prompt.md — 5軸コード品質検査

仕様適合が確認された後に実行されるコード品質レビューだ。5つの検査軸が定義されている。

1. コード品質の基本 — クリーン・テスト済み・保守可能な実装
2. 単一責任原則   — 各ファイルが明確な1つの責務と定義されたインターフェースを持つか
3. 独立した分解   — ユニットが独立して理解・テストできる単位に分解されているか
4. 構造的整合性   — 実装が計画のファイル構造に従っているか
5. 変更影響評価   — 新規ファイルが既に大きすぎないか、既存ファイルを大幅に肥大化させていないか

このレビューは「仕様適合レビューが合格した後にのみ実行される」という順序が設計上の意図だ。仕様を満たしていないコードの品質を評価しても意味がないため、品質レビューへのショートカットを防いでいる。

2-2. 「自分が書いたコードを自分でレビューするバイアス」への構造解

subagent-driven-development が解く問題は、エージェントが自分の実装を自分でレビューする際に生じる確証バイアスだ。人間でも同じ問題が起きるが、エージェントは特に顕著だ。

解法はシンプルで、実装エージェントとレビューエージェントを完全に別のコンテキストで実行する。レビューエージェントは実装の過程を知らず、完成品だけを見て独立した判断を下す。この分離が「気持ちよく通過するセルフレビュー」を構造的に不可能にする。

3. カスタムスキルの作り方

superpowers の組み込みスキルは汎用的なプロセスを定義している。しかし、実際のプロジェクトにはプロジェクト固有のルールがある。writing-skills スキルがその作成方法を体系化している。

3-1. スキルファイルの仕様

スキルは YAML フロントマターを持つ Markdown ファイルだ。agentskills.io 仕様に準拠しており、フロントマターには name と description の2つの必須フィールドがある。

---
name: my-custom-skill      # 小文字・数字・ハイフンのみ、特殊文字不可
description: |             # 最大1024文字、第三人称で記述
  Use when the engineer needs to...
---

description の設計には重要なルールがある。スキルの動作を説明するのではなく、使用する場面だけを記述する。エージェントが「今このスキルを呼び出すべき状況か」を判断するためのシグナルとして機能するためだ。"Use when..." で始め、具体的な症状や文脈を含めることが推奨されている。

3-2. 推奨ファイル構成

スキルの複雑さに応じて3つのパターンが用意されている。

パターン1: 自己完結型
  skills/my-skill/SKILL.md のみ

パターン2: ツール付き
  skills/my-skill/SKILL.md
  skills/my-skill/helper-script.sh  ← 再利用可能なコード

パターン3: リファレンス型
  skills/my-skill/SKILL.md
  skills/my-skill/detail-doc.md     ← 600行超の参照ドキュメント

トークン効率の観点から、SKILL.md 本体は頻繁に参照されるため200語以内を目標とし、詳細は別ファイルに分離して必要なときだけ参照させる設計（プログレッシブディスクロージャ）が推奨されている。コンテキストウィンドウは「公共財」であり、必要以上のトークンを消費するスキルは他の処理のリソースを奪う、という思想だ。

3-3. TDD によるスキル開発

スキル自体も RED-GREEN-REFACTOR サイクルで開発する。

RED フェーズ — 失敗シナリオを記録する

まず、スキルなしの状態でエージェントが失敗するパターンを特定・記録する。「エージェントは〇〇という状況で△△という誤りを犯す」という具体的な失敗例の収集だ。

GREEN フェーズ — 最小限のスキルを書く

特定した失敗パターンに対処する最小限の指示をスキルに書く。サブエージェントを使って検証し、失敗が解消されることを確認する。

REFACTOR フェーズ — 新たな言い訳を封じる

エージェントがスキルの指示を迂回しようとする新たなパターンを特定し、対策を追加して再検証する。このサイクルを繰り返すことで、スキルが徐々に「抜け穴のない指示書」に成長する。

3-4. 説得原理の応用

writing-skills スキルには、Cialdini の説得原理への明示的な言及があり、これをスキル設計に適用するガイドとして記述されている。エージェントの「言い訳」を事前に封じるための手法として機能する。

実用的な観点では、次のような応用が示されている。

• 権威性（Authority）: 「これは業界標準であり、〇〇研究によって実証されている」という形で指示を裏付ける
• 一貫性（Commitment）: 「前のステップでこの原則を遵守することに合意した」と冒頭でコミットメントを取る
• 希少性（Scarcity）: 「このチェックポイントをスキップする例外はない」と明記して逃げ道を閉じる
• 社会的証明（Social Proof）: 「この手順を守ることでPRが却下されずに済んだ実績がある」という実績の提示

これは単なる技術仕様ではなく、エージェントの行動心理を理解した上でのプロンプト設計だ。指示が「なぜ従うべきか」を説明できているほど、エージェントはその指示を遵守する傾向がある。

4. 品質ガバナンス：94% PR却下率の設計

superpowers のリポジトリには、CLAUDE.md に記述された厳格な品質ガバナンスがある。リポジトリの CLAUDE.md によると PR 却下率は 94% であり、メンテナーは低品質なPRを数時間以内にクローズする。コメントとして "This pull request is slop that's made of lies" が付くこともある。

この苛烈なガバナンスは、リポジトリの設計思想と一致している。スキルはコードであり散文ではない。意図して検証された振る舞いが定義されており、証拠なしに変更することは検証済みの内容を壊すことを意味する。

4-1. AI エージェントが満たすべき5つの提出前チェック

PRを開く前に、AI エージェントはすべての条件を満たす必要がある。

1. PR テンプレートへの完全記入
   → プレースホルダーではなく、具体的な内容で埋めること

2. 既存 PR の検索
   → オープン・クローズ済みの両方を確認し、重複を避けること

3. 実在する問題の確認
   → 推測や理論的な問題ではなく、実際に経験した障害に基づくこと

4. コア機能への適合判断
   → ドメイン固有の機能はプラグインとして実装すべきか判断すること

5. 人間によるレビューの取得
   → 完全な差分を人間がレビューし、承認を得てから提出すること

1つでも満たせない場合、PRを開いてはならない、と明示されている。

4-2. 却下される6つのパターン

却下理由はカテゴリとして文書化されている。

4-3. スキル変更に証拠が必要な理由

スキルを変更する際は、以下が必須とされている。

• 複数セッションにわたる対比テストの実施
• 修正前後の評価結果の提示

これは「スキルはコードであり散文ではない」という設計思想の現れだ。スキルの言葉一つひとつが、数百のセッションを経て検証されたチューニング済みコンテンツだ。「なんとなく読みやすくなった」「より明確に書き直した」という主観的な判断で変更することは、検証済みの振る舞いを壊すリスクがある。

この考え方は自分のカスタムスキル開発にも適用できる。スキルを変更する際は、変更前後でエージェントの振る舞いが実際にどう変わったかを記録し、改善が確認されたものだけを取り込む習慣が品質の維持につながる。

5. テストスイートのアーキテクチャ

superpowers はスキルフレームワークでありながら、独自のテスト体系を持っている。tests/ ディレクトリには6つのサブディレクトリ、46以上のテストファイルが存在する（コード分析時点）。

5-1. テストの種類

5-2. 「サブエージェント行動テスト」という独自手法

superpowers のテストで注目すべきは、従来の自動テスト（入力に対して出力を assertEqual）とは根本的に異なるアプローチを取っている点だ。テストの多くは「サブエージェントにプロンプトを投げ、その振る舞いがスキルの指示に準拠しているかを検証する」形式になっている。

プロンプトベースの行動テストでは、出力の正確な文字列一致を検証できない。代わりに「スキルを呼び出したか」「指定されたワークフローを踏んだか」「禁止された行動を取らなかったか」といった行動の準拠性を確認する。これはコードのテストではなく、プロンプトのテストだ。

5-3. ローカル実行前提の設計

.github/workflows/ ディレクトリは存在せず、CI/CD ワークフローは設定されていない。テストはローカルで claude CLI を使って実行する前提だ。サブエージェントを起動するテストは API コストが発生するため、CI で自動実行するよりもローカルで意図的に実行する設計が合理的といえる。

6. バージョン履歴から読み取れる進化の方向性

最近の変更点を見ると、superpowers の開発が注力している方向性が分かる。

v5.0.7（2026年3月31日）

Copilot CLI v1.0.11 への対応と OpenCode の修正が行われた。対応ツールの拡張が継続していることを示している。

v5.0.6（2026年3月24日）

brainstorming および writing-plans の review loop が inline self-review に変更された。これによりレビューの所要時間が大幅に短縮された（CHANGELOG の記載によると 25分から30秒への高速化）。なお、subagent-driven-development など他のサブエージェントレビューループはこの変更の対象外であり、従来の独立レビュー方式が維持されている。

v5.0.6 以前は、brainstorming / writing-plans でもレビューに別の完全なサブエージェントセッションを起動していた。これは確実に独立したレビューを担保する半面、起動コストと待機時間が大きかった。v5.0.6 では inline self-review への変更により、これらのスキルで品質の担保と速度を両立させる設計にシフトしている。

v5.0.5（2026年3月17日）

Node.js 22+ との互換性修正と Windows/MSYS2 環境での PID 監視問題の修正が行われた。brainstorming スキルの Visual Companion（ブラウザ連携 brainstorming ツール）を支える WebSocket サーバーが server.js から server.cjs に改名され、Node.js 22+ での起動問題が解消された。Visual Companion はブラウザ上にオプションを表示し、ユーザーがクリックで選択するインタラクティブなツールだ。設計規約として1画面あたり2〜4つのオプションに絞ることが推奨されており、選択肢過多による判断疲れを UX レベルで防止する設計になっている。

まとめ

本記事で取り上げた内容を整理する。

本シリーズは3部構成だ。入門編で14スキルの全体像とインストール方法を、設計パターン編でスキル横断の設計パターン（Iron Law、合理化防止テーブル、Red Flags 等）を、そして本記事で個別スキルの深掘りとカスタマイズ手法を取り上げた。

特にカスタムスキルの TDD 開発手法は、組み込みスキルをそのまま使う段階を超えて「自分のチームのルールをエージェントに内面化させる」ための実践的なアプローチだ。プロジェクト固有の命名規則、レビュー基準、セキュリティポリシーをスキルとして記述し、検証を重ねることで、汎用フレームワークを超えたカスタマイズが可能になる。設計パターン編で解説した設計原則を踏まえてスキルを構築すれば、より効果的な行動制御が実現できるだろう。

参考リンク

• superpowers — コーディングエージェント向け開発ワークフローフレームワーク（公式リポジトリ）
• agentskills.io specification — スキルの front matter 仕様（superpowers が準拠）