はじめに
本記事は「superpowers入門 — コーディングエージェントに規律ある開発プロセスを強制するフレームワーク」の続編だ。入門編では superpowers の14スキルの概要と、エージェントが数時間にわたり自律的に作業を継続するための仕組みを紹介した。
しかし、入門編では触れなかった根本的な疑問がある。なぜ Markdown で書かれたスキルが、エージェントの行動を実際に制御できるのか？
通常、プロンプトに「テストを先に書いてください」と書いても、エージェントは状況に応じてその指示を無視する。「今回は簡単だから」「後でテストを追加するから」と自己合理化し、指示を迂回するのだ。superpowers のスキルが他のプロンプトと異なるのは、エージェントが陥りやすい自己合理化のパターンを想定し、その回避経路をあらかじめ塞いでいる点にある。
本記事では、superpowers のスキルファイルを精読し、そこに埋め込まれた6つの設計パターンを体系化する。これらのパターンは、superpowers に限らず、エージェント向けのプロンプト設計全般に応用可能な技法だ。
注記: 本記事の情報は2026年4月時点のものであり、各リポジトリの機能・数値は変動する可能性がある。最新の情報は各リポジトリの README を参照してほしい。
1. 共通設計パターンの全体像
superpowers のスキル（v5.0.7 時点の14スキル）を精読すると、スキル間で共通して使われる6つの設計パターンが浮かび上がる。
| パターン | 目的 | 使用スキル（例） |
|---|---|---|
| Iron Law | ゼロトレランスの絶対ルール | TDD, systematic-debugging, verification-before-completion |
| 合理化防止テーブル | エージェントの言い訳を事前に無効化 | TDD（11項目）, systematic-debugging（8項目）, using-superpowers（12項目） |
| Red Flags リスト | 行動パターンの自己チェック | TDD（13項目）, systematic-debugging（11項目）, SDD（12項目） |
| XML タグ強調 | プロンプト内の優先度階層 | brainstorming, using-superpowers |
| Graphviz DOT フローチャート | エージェントが解析可能な構造化フロー | TDD, systematic-debugging, brainstorming, SDD |
| 「human partner」用語 | 関係性のフレーミング | TDD, systematic-debugging, verification 等の主要スキル |
これらのパターンは独立して機能するのではなく、相互に補強し合う多層防御として設計されている。Iron Law が絶対ルールを宣言し、合理化防止テーブルがルールの回避パターンを無効化し、Red Flags リストがエージェントの自己監視を促す。以降のセクションで、各パターンの実装を具体的に見ていく。
2. Iron Law パターン
superpowers の複数のスキルに共通する、最もシンプルかつ強力なパターンが Iron Law だ。
構造
Iron Law は以下の形式で定義される。
NO [禁止される行動] WITHOUT [前提条件] FIRST
実際のスキルから引用する。
test-driven-development スキル:
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
systematic-debugging スキル:
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
verification-before-completion スキル:
NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
なぜ機能するか
Iron Law の設計上の特徴は、バイナリ（二値）判定にある。「テストを書くことが望ましい」のような段階的なガイドラインでは、エージェントは「今回は状況が特殊だから」と判断の余地を見出す。一方、Iron Law は「テストなしのプロダクションコード = 違反」という二値判定であり、グレーゾーンが存在しない。
さらに、TDD スキルでは Iron Law の違反時の対応も明示的に定義されている。
Write code before the test? Delete it. Start over.
No exceptions:
- Don't keep it as "reference"
- Don't "adapt" it while writing tests
- Don't look at it
- Delete means delete
「参考として残す」「テストを書きながら適応させる」といった、エージェントが考えつきそうな妥協案を列挙し、すべてを否定している。これは次に紹介する「合理化防止テーブル」パターンの萌芽とも読める。
また、TDD スキルの冒頭には以下の一文がある。
Violating the letter of the rules is violating the spirit of the rules.
これは「ルールの精神は守っている」という、エージェントがよく使う「精神 vs 形式」の議論を先回りして封鎖するものだ。
3. 合理化防止テーブル（Rationalization Prevention Table）
superpowers の中で最も独創的と言えるパターンが、合理化防止テーブルだ。エージェントがルールを回避する際に使いそうな「言い訳」を事前に列挙し、各言い訳に対する反論を組み込む。
実装例：TDD スキル（11項目）
TDD スキルの合理化防止テーブルから代表的な項目を引用する。
| Excuse | Reality |
|---|---|
| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
| "I'll test after" | Tests passing immediately prove nothing. |
| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
| "Deleting X hours is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. |
| "TDD will slow me down" | TDD faster than debugging. Pragmatic = test-first. |
実装例：systematic-debugging スキル（8項目）
| "Issue is simple, don't need process" | Simple issues have root causes too.
Process is fast for simple bugs. |
| "Emergency, no time for process" | Systematic debugging is FASTER
than guess-and-check thrashing. |
| "One more fix attempt" | 3+ failures = architectural problem.
(after 2+ failures) Question pattern, don't fix again. |
設計原理
このパターンの前提は、エージェントの合理化パターンにはある程度の類型があり、事前に想定しやすいという点にある。人間のエンジニアが言い訳をするパターンと同様に、エージェントもプレッシャー下では類似の回避行動を取る傾向が観察されている。
superpowers の開発者は、writing-skills スキルでこのパターンの構築方法自体を体系化している。
Build Rationalization Table
Capture rationalizations from baseline testing. Every excuse agents
make goes in the table.
つまり、合理化防止テーブルは推測で書かれたものではない。実際にエージェントにプレッシャーをかけるテスト（「プレッシャーシナリオ」と呼ばれる）を実行し、エージェントが実際に使った言い訳を収集して構築されている。この手法は、TDD の RED フェーズ（まず失敗を観測する）と同じ発想だ。
4. Red Flags リスト
合理化防止テーブルと Red Flags リストは一見似ているが、機能するタイミングが異なる。前者はルール違反の事前防止（エージェントが言い訳を思いつく前に反論を用意する）、後者は作業中の自己検知（逸脱している自分に気づかせる）だ。
Iron Law が「やってはいけないこと」を定義し、合理化防止テーブルが「言い訳への反論」を担うのに対し、Red Flags リストはエージェントの自己監視メカニズムとして機能する。
実装例：TDD スキル（13項目）
Red Flags - STOP and Start Over
- Code before test
- Test after implementation
- Test passes immediately
- Can't explain why test failed
- Tests added "later"
- Rationalizing "just this once"
- "I already manually tested it"
- "Tests after achieve the same purpose"
- "It's about spirit not ritual"
- "Keep as reference" or "adapt existing code"
- "Already spent X hours, deleting is wasteful"
- "TDD is dogmatic, I'm being pragmatic"
- "This is different because..."
All of these mean: Delete code. Start over with TDD.
Iron Law との違い
Iron Law は事前の絶対禁止であり、Red Flags リストは行動中の自己検知トリガーだ。
Iron Law は「テストなしのプロダクションコードを書くな」と宣言する。Red Flags リストは「もし自分が『今回は特別だから...』と考えていることに気づいたら、それは逸脱の兆候だ」と警告する。
この違いは実用上重要だ。Iron Law だけでは、エージェントが「自分はルールに従っている」と認識しながら実際には逸脱しているケースを防げない。Red Flags リストは、そうした無自覚な逸脱を検知するためのパターンマッチングリストとして機能する。
systematic-debugging スキルでは、Red Flags に加えて「human partner のシグナル」セクションも用意されている。
Watch for these redirections:
- "Is that not happening?" - You assumed without verifying
- "Will it show us...?" - You should have added evidence gathering
- "Stop guessing" - You're proposing fixes without understanding
ユーザーの発言パターンからも逸脱を検知する、二重のセーフティネットだ。
5. CSO（Claude Search Optimization）
superpowers の開発過程で発見された、エージェント特有の行動に関する知見が CSO（Claude Search Optimization） だ。
発見の経緯
writing-skills スキルに以下の記述がある。
Testing revealed that when a description summarizes the skill's workflow,
Claude may follow the description instead of reading the full skill content.
A description saying "code review between tasks" caused Claude to do ONE
review, even though the skill's flowchart clearly showed TWO reviews
(spec compliance then code quality).
スキルの description フィールド（スキルの概要を記述するメタデータ）に「タスク間でコードレビューを行う」と書いたところ、エージェントはスキル本文を読まずに description の要約だけを見て行動してしまった。結果、2段階レビュー（仕様準拠チェック → コード品質チェック）のうち1段階しか実行しなかったのだ。
設計ルール
この発見に基づき、superpowers では description フィールドの記述ルールが確立されている。
# BAD: ワークフローを要約 → エージェントがスキル本文をスキップする
description: Use when executing plans - dispatches subagent per task
with code review between tasks
# BAD: プロセスの詳細を含む
description: Use for TDD - write test first, watch it fail,
write minimal code, refactor
# GOOD: トリガー条件のみ → エージェントがスキル本文を読む
description: Use when executing implementation plans with independent
tasks in the current session
# GOOD: トリガー条件のみ
description: Use when implementing any feature or bugfix,
before writing implementation code
原則は「description には WHEN（いつ使うか）だけを書き、WHAT（何をするか）は書かない」だ。
SEO とのアナロジー
CSO という名称は SEO（Search Engine Optimization）のアナロジーだ。SEO が検索エンジンのクローラーの挙動を理解して最適化するように、CSO はエージェントのスキル検索・選択行動を理解して最適化する。
エージェントは人間のユーザーと異なり、「要約で十分」と判断すると本文を読み飛ばす傾向がある。これは効率化の行動だが、スキル設計者にとっては意図しない省略を引き起こすリスクとなる。CSO はこのリスクを description の設計で回避する技法だ。
この知見はより一般的に、エージェント向けメタデータには要約を含めず、トリガー条件に限定すべきという設計原則として捉えられる。要約を含むメタデータは、エージェントに本文をスキップする「ショートカット」を与えてしまう。CLAUDE.md のセクション見出しやカスタムエージェントの description など、エージェントが「読むかどうか」を判断する箇所全般に応用できる考え方だと考えられる。
6. XML タグによるプロンプト強調
superpowers では、プロンプト内の優先度階層を XML タグで表現している。
使用されるタグ
スキルファイルで確認できる主要なタグは3種類だ。
<EXTREMELY-IMPORTANT> / <EXTREMELY_IMPORTANT> — 最高優先度の強制命令。using-superpowers スキルで使用される。
<EXTREMELY-IMPORTANT>
If you think there is even a 1% chance a skill might apply to what
you are doing, you ABSOLUTELY MUST invoke the skill.
IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE.
YOU MUST USE IT.
This is not negotiable. This is not optional. You cannot rationalize
your way out of this.
</EXTREMELY-IMPORTANT>
<HARD-GATE> — 実装に進む前の必須ゲート。brainstorming スキルで使用される。
<HARD-GATE>
Do NOT invoke any implementation skill, write any code, scaffold any
project, or take any implementation action until you have presented
a design and the user has approved it. This applies to EVERY project
regardless of perceived simplicity.
</HARD-GATE>
<SUBAGENT-STOP> — サブエージェントとして呼び出された場合のスキップ指示。
<SUBAGENT-STOP>
If you were dispatched as a subagent to execute a specific task,
skip this skill.
</SUBAGENT-STOP>
設計意図：強制力の階層化
superpowers における XML タグの使い方は、プロンプト内に強制力の階層を設ける設計パターンとして捉えられる。通常の Markdown の見出しや太字と異なり、XML タグはエージェントのプロンプト解析において構造的な区切りとして認識される傾向がある。タグ名自体が意味を持つ（HARD-GATE = 通過必須のゲート、EXTREMELY-IMPORTANT = 最重要）ため、プロンプト内の優先度を明示的に差別化できる。
この階層化により、プロンプト全体がフラットな指示の羅列ではなく、通常の指示 < Iron Law < XML タグによる強制命令という重み付きの構造になる。スキル設計においては、「守れたら望ましい」ガイドラインと「絶対に逸脱させない」ルールを区別する手段として有用だと考えられる。
セッション開始フック（hooks/session-start）では、using-superpowers スキルの全文を <EXTREMELY_IMPORTANT> タグで囲んでエージェントのコンテキストに注入している。これにより、セッション開始時から「スキルの使用は任意ではなく必須である」という優先度情報がエージェントに伝達される。
7. Graphviz DOT フローチャート
superpowers の複数のスキルには、Graphviz DOT 形式のフローチャートが埋め込まれている。
実装例：TDD スキル
digraph tdd_cycle {
rankdir=LR;
red [label="RED\nWrite failing test", shape=box,
style=filled, fillcolor="#ffcccc"];
verify_red [label="Verify fails\ncorrectly", shape=diamond];
green [label="GREEN\nMinimal code", shape=box,
style=filled, fillcolor="#ccffcc"];
verify_green [label="Verify passes\nAll green", shape=diamond];
refactor [label="REFACTOR\nClean up", shape=box,
style=filled, fillcolor="#ccccff"];
next [label="Next", shape=ellipse];
red -> verify_red;
verify_red -> green [label="yes"];
verify_red -> red [label="wrong\nfailure"];
green -> verify_green;
verify_green -> refactor [label="yes"];
verify_green -> green [label="no"];
refactor -> verify_green [label="stay\ngreen"];
verify_green -> next;
next -> red;
}
なぜ DOT 形式か
文章による手順説明では、分岐やループの構造が曖昧になりやすい。「テストが失敗した場合は RED フェーズに戻る」という記述は、「どの段階から戻るのか」「戻った後どのステップを再実行するのか」が不明確だ。
DOT 形式のフローチャートでは、ノード間のエッジ（矢印）が遷移条件とともに明示されるため、分岐・ループの構造にあいまいさが残りにくい。エージェントにとっては構造化されたデータとして解析しやすく、人間にとってはレンダリングすれば視覚的に確認できるという、双方に有益な形式だと考えられる。
writing-skills スキルでは、フローチャートの使用基準も定義されている。
Use flowcharts ONLY for:
- Non-obvious decision points
- Process loops where you might stop too early
- "When to use A vs B" decisions
Never use flowcharts for:
- Reference material → Tables, lists
- Code examples → Markdown blocks
- Linear instructions → Numbered lists
フローチャートは万能ではなく、分岐やループのある非線形プロセスに限定して使うべきだという設計指針だ。この背景にある一般原則は、プロセスの構造に応じて表現形式を選ぶというものだと考えられる。線形の手順にはナンバリングリスト、参照情報にはテーブル、分岐・ループを含む非線形プロセスには構造化されたフロー記述——という使い分けが、エージェントの解釈精度を高める方向に働く。
8. 「human partner」用語の意図
superpowers の主要スキル（TDD、systematic-debugging、verification-before-completion、executing-plans、receiving-code-review、writing-skills 等）で、ユーザーを指す用語として "your human partner" が使われている。一方、brainstorming や using-superpowers など一部のスキルでは "user" が使われており、全スキルで統一されているわけではない。しかし、主要な作業スキルでの採用は偶然ではなく、意図的な設計判断だ。
superpowers の CLAUDE.md（コントリビュータガイドライン）には以下の記述がある。
"your human partner" is deliberate, not interchangeable with "the user"
この用語の選択には、エージェントとユーザーの関係性のフレーミングという設計意図がある。
「user」という用語は、エージェントをサービス提供者、ユーザーをサービス利用者として位置づける。この枠組みでは、エージェントは「ユーザーの指示に従うもの」であり、指示の範囲外のことには消極的になりやすい。
「human partner」という用語は、エージェントとユーザーを対等なパートナーとして位置づける。TDD スキルの「When Stuck」セクションには以下の記述がある。
Don't know how to test → Write wished-for API. Write assertion first.
Ask your human partner.
テスト方法がわからないときは、自分で悩み続けるのではなく「パートナーに相談する」という行動を促している。これは「ユーザーに報告する」よりも、協働関係を前提とした自然な表現だ。
systematic-debugging スキルでも、3回以上の修正に失敗した場合の対応として以下が定義されている。
Discuss with your human partner before attempting more fixes
This is NOT a failed hypothesis - this is a wrong architecture.
「human partner と議論する」という表現が、エスカレーションを「失敗の報告」ではなく「パートナーへの相談」として位置づけている。
9. マルチプラットフォームアーキテクチャ
前節までで見てきた設計パターン——Iron Law、合理化防止テーブル、Red Flags リスト等——はすべて Markdown で記述されており、特定のプラットフォームに依存しない。しかし、それらを各プラットフォームにどう届けるかは別の設計課題だ。
対応プラットフォーム
superpowers は v5.0.7 時点で6つのプラットフォームに対応している。
| プラットフォーム | プラグイン機構 | 設定ファイル |
|---|---|---|
| Claude Code | プラグインマーケットプレイス | .claude-plugin/plugin.json |
| Cursor | プラグインマーケットプレイス | .cursor-plugin/plugin.json |
| Codex CLI | git clone + symlink | .codex/INSTALL.md |
| OpenCode | JS プラグイン | .opencode/plugins/superpowers.js |
| GitHub Copilot CLI | セッションフック | hooks/session-start |
| Gemini CLI | エクステンション | gemini-extension.json |
セッション開始フックのプラットフォーム検出
セッション開始時に using-superpowers スキルの全文をエージェントに注入するフック（hooks/session-start）は、環境変数でプラットフォームを検出し、出力 JSON のフォーマットを切り替えている。
if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
# Cursor → additional_context 形式（snake_case）
printf '{ "additional_context": "%s" }' "$session_context"
elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -z "${COPILOT_CLI:-}" ]; then
# Claude Code → hookSpecificOutput.additionalContext 形式（nested）
printf '{ "hookSpecificOutput": { ... "additionalContext": "%s" } }' \
"$session_context"
else
# Copilot CLI / その他 → additionalContext 形式（SDK標準）
printf '{ "additionalContext": "%s" }' "$session_context"
fi
同じコンテンツを注入するのに、プラットフォームごとに JSON のキー名やネスト構造が異なるという、プラグインエコシステムの標準化が進んでいない現状が見て取れる。
ツールマッピング
各プラットフォームでツール名が異なるため、superpowers は references/ ディレクトリにプラットフォームごとのマッピングテーブルを用意している。
| Claude Code ツール | Codex | Copilot CLI | Gemini CLI | OpenCode |
|---|---|---|---|---|
| Task（サブエージェント） | spawn_agent | task | 非対応 | @mention |
| TodoWrite | update_plan | sql (todos) | write_todos | todowrite |
| Skill | ネイティブ | skill | activate_skill | skill |
注目すべきは、Gemini CLI ではサブエージェントが非対応という点だ。この場合、subagent-driven-development スキルは使用できず、executing-plans（シングルセッション実行）にフォールバックする設計になっている。同じスキルセットでも、プラットフォームの制約に応じて実行戦略が変わるのだ。
つまり superpowers は、スキルの内容（設計パターン）とスキルの配信（プラットフォーム適応）を分離することで、前節までに見た Iron Law や合理化防止テーブルといったパターンをプラットフォーム横断で再利用可能にしていると考えられる。プラットフォーム差異はフック・マッピング層で吸収し、スキル本文は一切変更しないという設計だ。
まとめ
superpowers の6つの設計パターンは、「プロンプトエンジニアリングをコードとして扱う」というアプローチの実践例だ。
| パターン | 核心 |
|---|---|
| Iron Law | バイナリ判定でグレーゾーンを排除する |
| 合理化防止テーブル | エージェントの逃げ道を事前に塞ぐ |
| Red Flags リスト | 行動中の自己監視を促す |
| CSO | エージェントのスキル検索行動を最適化する |
| XML タグ強調 | プロンプト内の優先度階層を構造化する |
| 「human partner」用語 | 関係性のフレーミングで行動傾向を誘導する |
これらのパターンに共通する設計思想は、エージェントの行動傾向を想定し、逸脱しにくい制御構造を設計するというものだ。単に「こうしてください」と指示するのではなく、起こりうる逸脱パターンに対して構造的な防御を組み込んでいる。
この考え方は、superpowers に固有のものではない。自分のプロジェクトで CLAUDE.md やカスタムスキルを設計する際にも、同じパターンを適用できる。
- 入門編（superpowers入門）では、14スキルの概要とワークフローの全体像を紹介している
- 第3回（実践・カスタマイズ編）では、スキルの深掘り、カスタムスキルの作り方、品質ガバナンスの詳細を扱う
参考リンク
- superpowers — コーディングエージェント向け開発ワークフローフレームワーク（公式リポジトリ）
- agentskills.io specification — スキルの front matter 仕様（superpowers が準拠）