Claude CodeやCursorなどの自律型AIコーディングエージェントに機能実装やバグ修正を直接指示すると、設計やテストを省略して場当たり的なコード変更を繰り返し、既存コードのデグレを引き起こすケースが頻発します。
この課題を解決するのが、エージェントにスキル定義とTDD（テスト駆動開発）のワークフローを強制する拡張フレームワーク「superpowers」です。要件定義・テスト作成・実装の順序を厳格に統制することで、AIによる当てずっぽうなコード変更を防ぎ、堅牢な開発プロセスを維持できます。
本記事では、superpowersのインストール手順からCLAUDE.mdおよび.cursorrulesの設定方法、TDDを強制するコマンド実行フロー、さらにトークン消費を抑える運用ノウハウまで詳しく解説します。
superpowersとは？AIコーディングの「丸投げ暴走」を終わらせる開発方法論
結論から言えば、superpowersとは「AIコーディングエージェントに人間のシニアエンジニアのような堅牢な開発プロセスを強制する、行動規範（スキル）のフレームワーク」です。
単なる便利プロンプト集ではなく、「設計合意前のコーディング禁止」「テストのない本番コード作成の禁止」「根本原因調査なしのバグ修正禁止」といった厳格な規律（The Iron Law）をAIに課す点が、従来のAI活用法と根本的に一線を画しています。
単なるプロンプト集ではない「規律を強制するフレームワーク」
superpowersの最大の特徴は、AIエージェントの行動パターンを「場当たり的な実装者」から「規律あるチーム開発者」へと構造的に変革する点にあります。
通常、CursorやClaude Codeに「〇〇の機能を作って」と指示すると、AIは即座にソースコードの編集を開始します。しかしsuperpowersを導入した環境では、AIは勝手にコードを書き始めることができません。まず「Brainstorming」スキルが自動発動し、要件の深掘りと設計案の提示を行い、人間との合意を形成します。
設計が承認されて初めて、2〜5分単位の極小タスクに分割された「Writing Plans」が作成され、厳格なテスト駆動開発（TDD）のサイクルに従って1ステップずつ着実に実装が進められます。
従来のAIコーディング vs superpowers導入後の決定的な違い
従来のAIコーディングと、superpowersによって規律が組み込まれたAIエージェントの振る舞いを比較すると、その差は一目瞭然です。
| 比較項目 | 従来のAIコーディング（素の状態） | superpowers導入後のAIエージェント |
|---|---|---|
| 開発アプローチ | 指示直後にいきなりコードを書き始める（場当たり的） | 要件定義・設計書を提示し、合意形成してから着手 |
| テストの扱い | 指示されない限り後回し、または省略する | 「失敗するテスト（RED）」を最初に書くことを絶対強制 |
| バグ調査・修正 | 直感や当てずっぽうでコードを修正し、再エラーを招く | 仮説検証とログ収集を行い、根本原因を特定してから着手 |
| 作業の粒度 | 数十〜数百行を一度に書き換えて破綻しやすい | 2〜5分単位のマイクロタスクに分割して逐次検証 |
| エンジニアの役割 | AIが生成した怪しいコードの火消し・デバッグ係 | アーキテクチャの承認者・プロジェクトディレクター |
以前書いたGitHub Copilot活用術でも解説した通り、AIコーディングの成否は「モデル自体の賢さ」以上に「AIをどういうプロセス枠組みで駆動するか」にかかっています。superpowersはその枠組みを標準化してくれる強力な武器と言えます。
💡 あわせて読みたい
【完全手順】Cursor / Claude Codeへの導入とファイル配置
ここからは、実際に手元の開発環境にsuperpowersを組み込む具体的な手順を解説します。「リポジトリをクローンしてコピペ」という曖昧な説明ではなく、読者がそのまま自分のプロジェクトで再現できるよう、フォルダツリーと設定コードを完全公開します。
Cursor環境での推奨フォルダ配置と.cursorrules設定
Cursorでsuperpowersの規律を適用する場合、プロジェクトのルートディレクトリに .cursorrules を配置するか、最新の推奨仕様である .cursor/rules/ ディレクトリにルールを分割配置します。
まずは、最もシンプルかつ確実に機能するプロジェクトルート直下のファイル配置ツリーを確認しましょう。
your-project/
├── .cursorrules # superpowersの核となる規律ルールを記述
├── .cursor/
│ └── rules/ # 個別スキルを分割管理する場合（任意）
│ ├── tdd.mdc
│ └── systematic-debug.mdc
├── src/ # 実装コード
├── tests/ # テストコード
└── package.json (または requirements.txt / pyproject.toml)以下は、superpowersの最も重要なコア原則（TDDの鉄の掟、バグ調査プロセス、設計計画の義務化）を抽出し、Cursor Agent向けに最適化した .cursorrules の実践コードです。このままコピーしてプロジェクトルートに配置してください。
# ==============================================================================
# superpowers Development Discipline Rules for Cursor
# ==============================================================================
# [Rule 1: The Iron Law of TDD]
# 新機能の追加、バグ修正、リファクタリングにおいて、
# 「失敗するテスト」を事前に作成して実行確認するまで、本番コードの記述を一切禁止する。
tdd_discipline:
iron_law: "NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST"
cycle:
- step: "1. RED"
action: "要件を満たす最小限のテストを先に作成する（モックではなく実際の振る舞いを検証）。"
- step: "2. VERIFY_RED"
action: "テストコマンドを実行し、意図通りの理由でテストが失敗することを必ず確認する。"
- step: "3. GREEN"
action: "テストをパスさせるための最小限の実装コードのみを記述する。"
- step: "4. VERIFY_GREEN"
action: "テストを再実行し、すべてのテストが通過することを確認する。"
- step: "5. REFACTOR"
action: "テストが通った状態を維持しながら、コードの可読性や重複を整理する。"
# [Rule 2: Systematic Debugging]
# エラーやバグが発生した際、根本原因を特定する前の当てずっぽうなコード修正を禁止する。
debugging_discipline:
iron_law: "NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST"
procedure:
- "エラーログ・スタックトレースを精読し、エラー発生行と入力を特定する"
- "再現可能な最小テストケースを作成してバグを100%再現させる"
- "仮説を立て、必要に応じて調査ログを追加して原因箇所を絞り込む"
- "根本原因を特定した証拠が得られてから、初めて修正コードを適用する"
# [Rule 3: Plan Before Implementation]
# 3ステップ以上の変更を伴うタスクでは、いきなりコードを書かず、
# 必ず2〜5分単位のマイクロタスクに分割した実装計画をユーザーに提示し合意を取ること。Claude Code環境でのプラグイン導入とCLAUDE.md設定
CLI上で自律動作する Claude Code を使用している場合、superpowersは公式のプラグインマーケットプレイスを通じて極めてスムーズにインストールできます。
ターミナルで Claude Code を起動し、以下のスラッシュコマンドを実行してください。
# 公式マーケットプレイスから直接インストールする場合
/plugin install superpowers@claude-plugins-official
# または obra氏の専用マーケットプレイスを登録してインストールする場合
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace
# インストール完了後に設定を再読み込み
/reloadインストールが完了すると、セッション開始時にバックグラウンドで自動的にフックが登録されます。しかし、「プラグインを入れたのに素のAIと同じように勝手にコードを書き換えてしまう」というトラブルが現場で頻発しています。
これを防ぎ、AIエージェントに100%規律を強制するには、プロジェクトルートの CLAUDE.md にsuperpowersのワークフローを明示的に宣言しておくことが必須となります。
【コピペ推奨】CLAUDE.md に記述する最小推奨テンプレート
以下は、Claude Codeがプロジェクトを読み込んだ瞬間に「TDD優先・設計先行」を自覚させるための最小設定テンプレートです。そのままプロジェクトルートの CLAUDE.md にコピーしてご活用ください。
# Project Development Guidelines with superpowers
## Core Rules for AI Assistant
You MUST strictly follow the superpowers discipline framework:
1. Test-Driven Development (TDD) First:
- NEVER write implementation code without a failing test (RED).
- Verify test failure by running the test runner before writing code.
- Write the minimal code to pass the test (GREEN), then refactor.
2. Systematic Debugging:
- When an error occurs, do NOT guess fixes.
- Investigate stack traces, reproduce with minimal test case, and identify root cause first.
3. Task Planning:
- For changes requiring 3+ steps, create a numbered task plan and get user approval before writing code.
## Verification Commands
- Test Command: `npm test` (or `pytest`, `go test ./...`)
- Lint Command: `npm run lint` (or `ruff check .`)superpowersの日常開発コマンドとTDD実行フロー
セットアップ完了後、Claude Code上でsuperpowersを使いこなすための主要コマンドと実践的なプロンプト投入フローは以下の通りです。
| コマンド・指示内容 | 実行タイミング | AIエージェントの振る舞い |
|---|---|---|
/plugin list |
セットアップ直後 | superpowersプラグインが有効（Enabled）になっているか確認 |
「◯◯機能を追加してください」 |
新機能の開発時 | いきなり実装せず、まず要件の確認とタスク分割計画を提示する |
「計画に合意しました。TDDで進めて」 |
計画承認時 | まず失敗するテスト（RED）を作成・実行し、失敗を確認してから実装に入る |
「このエラーの原因を特定して」 |
バグ調査時 | 当てずっぽうの修正をせず、ログ収集と最小再現コード作成を先行する |
このように、「プラグイン導入」と「CLAUDE.mdへの宣言」をセットで行うことで、Claude Codeは単なるチャットボットから「頼れるシニアエンジニアのペアプロ相手」へと劇的に進化します。
【実践ログ検証】superpowersでTDDを回す！具体プロンプトと実行結果
では、実際にsuperpowersの規律を適用した環境でAIエージェントに機能追加を指示すると、どのような思考ログを出力し、どのようにテストと実装を進めるのでしょうか？実際の動作検証ログを通じて確認してみましょう。
検証シナリオ：ユーザー登録のバリデーション機能追加
今回は、Webアプリケーションの認証基盤において、以下の要件を満たす新機能の実装をAIエージェントに指示しました。
- ユーザー登録時に、入力されたメールアドレスのドメイン形式をチェックする
- 既に登録済みのメールアドレスが渡された場合は、例外を送出して登録を弾く
【投入したプロンプト】
ユーザー登録サービスにメールアドレスの重複チェック機能を追加してください。
既存ユーザー一覧に同一のメールアドレスが存在する場合はエラーを送出するようにしてください。【通常のAI（素の状態）の挙動】
素のAIにこの指示を出すと、いきなりサービス層のソースファイルを書き換え始め、既存のDB問い合わせメソッドを適当に変更して「修正が完了しました！」と報告してきます。テストコードは一切作成されず、本当に重複が弾けるかの検証も行われません。
REDフェーズ：失敗するテストの作成と実行ログ
一方、superpowersが適用されたエージェントは、「The Iron Law: NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST」に従い、まずテストファイルのみを作成しました。
# tests/test_user_service.py
import pytest
from src.user_service import UserService, UserRepository
def test_should_reject_registration_when_email_already_registered():
repo = UserRepository()
repo.add_user("test@example.com", "User1")
service = UserService(user_repo=repo)
# 重複メールアドレスの登録時に TypeError が送出されることを検証
with pytest.raises(TypeError, match="Email already in use"):
service.register_user("test@example.com", "User2")テストコードを作成した後、エージェントは自らターミナルでテストコマンドを実行し、「テストが意図通りに失敗すること（RED）」を確認しました。その際の実際のターミナル実行ログが以下です。
=== STEP 1: VERIFY RED (Failure Check) ===
$ pytest tests/test_user_service.py -v
collected 1 item
tests/test_user_service.py::test_should_reject_registration_when_email_already_registered FAILED
=================================== FAILURES ===================================
________________ test_should_reject_registration_when_email_already_registered ________________
def test_should_reject_registration_when_email_already_registered():
> with pytest.raises(TypeError, match="Email already in use"):
E Failed: DID NOT RAISE <class 'TypeError'>
tests/test_user_service.py:11: Failed
============================== 1 failed in 0.08s ===============================
[Agent Log]: テストが正しく「未実装による理由（DID NOT RAISE）」で失敗したことを確認しました。
これより GREEN フェーズに移行し、テストをパスさせる最小限の実装を行います。GREEN & REFACTORフェーズ：最小限の実装と全テスト通過ログ
失敗を確認したエージェントは、初めて本番コード src/user_service.py に手を加え、重複チェックロジックを追加しました。
# src/user_service.py
class UserService:
def __init__(self, user_repo):
self.user_repo = user_repo
def register_user(self, email: str, name: str):
# 重複チェックロジックの最小実装
existing_user = self.user_repo.find_by_email(email)
if existing_user is not None:
raise TypeError("Email already in use")
return self.user_repo.add_user(email, name)実装完了直後、エージェントは再度テストを自動実行し、テストの通過（GREEN）と既存テストを含めた全体テストの整合性を検証しました。
=== STEP 2: VERIFY GREEN (Success Check) ===
$ pytest tests/ -v
collected 4 items
tests/test_user_service.py::test_user_registration_success PASSED [ 25%]
tests/test_user_service.py::test_should_reject_registration_when_email_already_registered PASSED [ 50%]
tests/test_auth.py::test_login_flow PASSED [ 75%]
tests/test_auth.py::test_token_verification PASSED [100%]
============================== 4 passed in 0.12s ===============================
[Agent Log]: 全テストが GREEN になりました。
既存機能への悪影響（リグレッション）がないことを確認済みです。このように、指示を与えただけで「テスト作成 → 失敗の確認 → 最小実装 → 全テスト通過の確認」というプロのエンジニアが行うべき一連のサイクルを完全に自動で完遂してくれます。これこそがsuperpowersを導入する最大の恩恵です。
現場で直面する落とし穴とアンチパターン（向かないケース）
極めて強力なsuperpowersですが、銀の弾丸ではありません。現場で実際に運用してみて分かったリアルなトレードオフと注意点についても客観的にお伝えします。
トークン消費量と実行時間のトレードオフ
superpowersの最大の実務的コストは、「API利用トークン消費量の増加と実行時間の長期化」です。
タスク着手前のBrainstorming、設計ドキュメントの生成、実装計画書の作成、テストコードの事前記述、ターミナルでのテスト実行とログ解析など、AIエージェントが経由するステップが通常の2〜3倍になります。その結果、消費されるトークン量も単純なプロンプト指示に比べて約2倍〜4倍程度に膨らみます。
そのため、「ボタンの色をちょっと変更したい」「READMEのタイポを直したい」といった数行で終わる軽微な修正タスクに対してsuperpowersのフルワークフローを回すのは、時間的にもコスト的にも明らかなオーバースペック（アンチパターン）です。
トークン消費を抑えつつ開発効率を最大化するアプローチについては、以前書いたLLMのトークン節約術でも解説していますので、併せてご覧ください。
「モックだらけの偽装テスト」を防ぐプロンプトガード
もう一つの落とし穴は、AIエージェントが「テストを通すこと」を優先するあまり、本番の振る舞いを一切検証しない無意味なモックテストを量産してしまう現象です。
たとえば外部APIやDBを過剰にモック化し、「モックが正しく呼び出されたか」だけをテストして本質的なビジネスロジックの欠陥を見逃すケースがあります。これを防ぐため、superpowersのTDDスキルには以下の防壁プロンプトが組み込まれています。
- 「モックではなく実際の振る舞いをアサートすること」: 単なる呼び出し回数（toHaveBeenCalled）の検証だけで終わらせない。
- 「テスト名に ‘and’ が含まれる場合はテストを分割すること」: 1つのテストケースで検証する関心事を厳格に1つに限定する。
導入すべきプロジェクト vs 見送るべきプロジェクトの選定基準
プロジェクトの性質に合わせてsuperpowersを使い分けるための判断基準をまとめました。
| 向いているケース（即導入を推奨） | 向いていないケース（適用を見送るべき） |
|---|---|
| 中〜大規模で長期保守が必要な本番プロダクト | 半日〜数日で捨てる使い捨てのプロトタイプ作成 |
| 決済・認証・データ永続化などのコアロジック開発 | HTML/CSSのスタイリング微調整や静的テキスト修正 |
| 既存のテストスイートが既に整備されているリポジトリ | テスト環境（jestやpytest等）が一切存在しない案件 |
| AIに数時間自律稼働させて大きな機能を任せたい場合 | 人間が横で1行ずつペアプログラミングしたい場合 |
よくある質問（FAQ）
Q1: Cursorの既存のルールファイルやプロジェクト設定と競合しませんか？
A: 基本的な設定であれば競合しません。
既存の .cursorrules に言語固有のスタイル規約（TypeScriptの型定義やディレクトリ命名規則など）が書かれている場合、その末尾にsuperpowersの「TDD Iron Law」セクションを追記する形で共存可能です。ただし、「テストを省略して高速にコードを出力せよ」といった相反する指示が存在する場合は挙動が不安定になるため、行動規律の部分はsuperpowers側に統一することをお勧めします。
Q2: Claude CodeやCursor以外のAIエージェントでも使えますか？
A: はい、Gemini CLI、GitHub Copilot CLI、Devin、Antigravityなど主要なエージェントに対応しています。
superpowersの実態はMarkdownベースの「スキル指示書」であるため、プロンプトやシステム指示を読み込めるツールであればどの環境でも動作します。リポジトリ内には各ツール向けの設定フックやインストール手順が用意されています。
Q3: トークンコストを節約しながらTDDの恩恵だけを得る方法はありますか？
A: 必要なスキル（TDDとデバッグ）だけを厳選してルールに含める方法が効果的です。
すべてのワークフロー（ブレインストーミングや作業ツリー作成）を常時有効化するのではなく、.cursorrules に「TDDの鉄の掟（失敗テストの先行作成）」と「デバッグ時の根本原因追究」の2点のみを記述しておくことで、余分な計画フェーズをスキップしつつ堅牢なコーディング規律を維持できます。
まとめ：superpowersでAIを「真のシニアエンジニア」に育てる
本記事では、AIコーディングエージェントに開発規律を強制するオープンソースフレームワーク「superpowers」の仕組みと実践的な導入法について解説しました。
- AIの「場当たり的な丸投げコーディング」を終わらせ、設計→計画→TDDの堅牢なサイクルを強制できる
- Cursorでは
.cursorrules、Claude Codeでは公式マーケットプレイスコマンドで簡単に導入可能 - 「失敗するテストの確認なしに本番コードを書かない（The Iron Law）」により、バグやデグレを激減させられる
- 小規模な修正ではトークン消費が増えるトレードオフがあるため、用途とプロジェクト規模に応じた使い分けが肝要
AIモデルの知能が急速に向上する中、エンジニアに求められる役割は「自らコードを書く作業者」から「AIに適切な規律を与え、品質を保証するディレクター」へと確実にシフトしています。superpowersはその第一歩を踏み出すための最も実践的かつ強力なアプローチです。ぜひあなたの開発環境にも導入して、AIが自律的かつ堅牢にコードを紡ぎ出す心地よさを体感してみてください！
💡 あわせて読みたい
【脱・毎回指示】GitHub Copilot Custom Instructionsで自分専用のAIアシスタントを育てる設定手順
