Superpowers Skill設計哲学 — LLMを従わせる技術¶

この記事のスコープ¶

第1回でSkillは「行動制御コード」だと書いた。この記事では、その具体的な設計パターンを掘り下げる。

Superpowersの14個のSkillは、大きく2つのカテゴリに分かれる。

この記事では、特に設計が高度な規律型Skillのパターンを中心に解説する。

パターン1: Iron Law — 絶対的なルール¶

すべての規律型Skillには、冒頭にIron Lawが宣言されている。

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

共通する設計原則：

• 全大文字で視覚的に目立たせる
• 否定形（NO ... WITHOUT）で「やってはいけないこと」を先に示す
• 例外なし。条件分岐なし。曖昧さなし

なぜ否定形なのか。「テストを先に書いてください」は提案に聞こえる。「テストなしのコードは許可しない」は禁止に聞こえる。LLMは禁止に対してより強く反応する。

パターン2: 合理化テーブル — 言い訳を事前に潰す¶

エージェントは「今回だけは例外」と自分を説得する能力が極めて高い。Iron Lawだけでは、この合理化を防げない。

SuperpowersはRationalization Tableでこれに対処する。TDD Skillの例：

このテーブルの各行は推測ではなく実験結果だ。Skillなしでエージェントを走らせ、実際に言った合理化を一語一句記録し、それに対する反論を書いている。

パターン3: Red Flags — 自己チェックリスト¶

合理化テーブルは「言い訳に対する反論」だ。Red Flagsは、その一歩手前——「自分が今まさに合理化しようとしている」ことに気づかせる仕組みだ。

TDD Skillの例：

## 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.**

最後の一行が重要だ。「該当したらどうするか」を曖昧にしない。全部同じ対応：コードを消して最初からやり直せ。

パターン4: 「精神 vs 文字」を先に潰す¶

エージェントが最もよく使う高度な合理化パターンがある。

「ルールの文字通りには従っていないが、精神には従っている」

これは強力な論法だ。一見合理的に聞こえるし、多くの場面で実際に正しい。だからこそ危険だ。

Superpowersは、規律型Skillの冒頭にこの論法を先に無効化する一文を置く。

**Violating the letter of the rules is violating the spirit of the rules.**

この一文で「精神に従っている」という合理化の経路全体が塞がれる。TDD、debugging、verificationの3つの規律型Skillすべてにこの一文がある。

パターン5: descriptionのトリガー条件設計¶

第1回で触れたが、ここでより詳しく解説する。

発見の経緯¶

subagent-driven-developmentのdescriptionを以下のように書いていた。

description: Use when executing plans - dispatches subagent per task 
  with code review between tasks

テストの結果、Claudeは「code review between tasks」を読み、各タスクの間に1回だけレビューを行った。しかし、Skill本文のフローチャートは明確に2段階レビュー（spec compliance → code quality）を定義していた。

descriptionを以下に変更したところ、Claudeは正しくSkill本文を読み、2段階レビューを実行した。

description: Use when executing implementation plans with independent 
  tasks in the current session

設計ルール¶

この発見から導かれるルールは明確だ。

# ❌ フローを書いている — Claudeがdescriptionだけで行動する
description: Use for TDD - write test first, watch it fail, 
  write minimal code, refactor

# ✅ トリガー条件のみ — Claudeは本文を読むしかない
description: Use when implementing any feature or bugfix, 
  before writing implementation code

LLMはショートカットを見つけたら必ず使う。 descriptionにフローを書くことは、本文を読み飛ばすショートカットを提供することと同じだ。

パターン6: フローチャートによる決定制御¶

SuperpowersはGraphviz dot記法でフローチャートを埋め込んでいる。ただし、すべてにフローチャートを使うわけではない。

使う場面¶

• 非自明な分岐がある時（A or B の判断が必要）
• 見落としやすいループがある時（早すぎる終了を防ぐ）
• 「いつAを使い、いつBを使うか」の判断

使わない場面¶

• 参照情報 → テーブル
• コード例 → マークダウン
• 線形の手順 → 番号付きリスト

brainstormingのフローチャートの例：

digraph brainstorming {
    "Explore project context" -> "Visual questions ahead?";
    "Visual questions ahead?" -> "Offer Visual Companion" [label="yes"];
    "Visual questions ahead?" -> "Ask clarifying questions" [label="no"];
    ...
    "User approves design?" -> "Present design sections" [label="no, revise"];
    "User approves design?" -> "Write design doc" [label="yes"];
    ...
    "User reviews spec?" -> "Invoke writing-plans skill" [label="approved"];
}

重要なのは終端ノードだ。brainstormingの終端は"Invoke writing-plans skill"であり、本文にもこう書かれている。

The terminal state is invoking writing-plans. Do NOT invoke frontend-design, mcp-builder, or any other implementation skill.

フローチャートと文章の両方で「次のSkillはこれだけ」を強制している。

パターン7: Skill間の強制チェーン¶

各Skillの末尾に「次に呼び出すSkill」が指定されている。これは設定ファイルではなく、Skill本文の自然言語で書かれている。

「何を呼ぶか」だけでなく「何を呼ぶな」も指定するのがポイントだ。brainstormingは「writing-plansだけ」と言うだけでなく、「frontend-design、mcp-builderなど他は呼ぶな」と明示的に禁止している。

Anthropic公式ガイドとの比較¶

Superpowersのリポジトリには、Anthropic公式のSkill設計ガイド（anthropic-best-practices.md）が含まれている。両者の設計思想を比較する。

一致する点¶

明確に異なる点¶

1. Claudeの能力への前提

2. descriptionの書き方

3. 語気

4. テスト方法

なぜ異なるのか¶

公式ガイドは汎用的なSkill（APIドキュメント、ツールリファレンス）を想定している。「PDFからテキストを抽出する方法」を教えるSkillに、合理化防止は不要だ。

Superpowersは規律型Skillという、より困難な問題に取り組んでいる。「テストを先に書け」「根本原因を調べてから直せ」といったルールは、エージェントにとってコストが高い。コストが高いルールほど、合理化される。

CLAUDE.mdにもこう書かれている。

Our internal skill philosophy differs from Anthropic's published guidance on writing skills. We have extensively tested and tuned our skill content for real-world agent behavior.

まとめ：設計パターン一覧¶

次回は、これらのパターンを実際に使うSubagentアーキテクチャを解説する。