superpowers入門 — コーディングエージェントに規律ある開発プロセスを強制するフレームワーク

はじめに

Claude Code や Codex CLI を日常的に使っていると、ある問題に気づく。エージェントの自由度が高すぎるのだ。

同じプロンプトを投げても、テストを先に書くこともあれば書かないこともある。デバッグ時に場当たり的な修正で済ませることもある。計画なしにいきなり実装を始め、途中で方針がブレることもある。結果として、成果物の品質にバラつきが生まれる。

この問題に対する1つの回答が、プロセスの強制というアプローチだ。エージェントに「何を作るか」だけでなく「どう作るか」を厳密に指示するフレームワーク、superpowers を紹介する。GitHub で ~148k stars（2026年4月時点）を獲得しており、この領域で広く注目を集めているプロジェクトの1つだ。

本記事は superpowers を3回に分けて解説するシリーズの第1回（入門編）だ。フレームワークの全体像と「何ができるのか」を把握することを目的とする。設計パターンの詳細は第2回（設計パターン編）、実践的なカスタマイズは第3回（実践・カスタマイズ編）で扱う。

superpowers とは

superpowers は、コーディングエージェント向けの完全なソフトウェア開発ワークフローを提供するフレームワークだ。CLAUDE.md や同等の設定ファイルにスキルセットと初期指示を注入し、エージェントが段階的に計画・実装・検証を進めるよう強制する。

核となる設計思想は明確で、エージェントを「優秀だが経験の浅いジュニアエンジニア」と見なし、詳細な作業手順書に従わせるというものだ。これにより、エージェントの出力が属人的なプロンプトの巧拙に依存しなくなる。

対応するツールは Claude Code、Cursor、Codex CLI、OpenCode、GitHub Copilot CLI、Gemini CLI と幅広く、特定の CLI にロックインされない汎用性も特徴だ。

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

開発ワークフローの全体像

superpowers の最大の特徴は、個々のスキルが独立したツールではなく、一貫した開発ワークフローの各ステージとして連携する点にある。以下がフレームワークが想定する基本的な開発フローだ。

brainstorming → using-git-worktrees → writing-plans → subagent-driven-development / executing-plans → finishing-a-development-branch

1. brainstorming（要件定義）

エージェントがいきなり実装に入るのを防ぐ。ソクラテス式の1問1答で要件を掘り下げ、2〜3のアプローチを提案し、ユーザーの設計承認を得てから次に進む。設計ドキュメントとして成果を保存する。

2. using-git-worktrees（環境構築）

Git worktree を使い、ブランチ単位で隔離された開発環境を作成する。メインの作業を汚さずに実験的な変更を試せる。テストのベースラインも確認する。

3. writing-plans（計画策定）

タスクを 2〜5分単位の粒度に分解し、各タスクにファイルパス・完全なコード例・検証コマンドを含める計画書を作成する。「No Placeholders」ルールにより TBD や TODO は禁止される。

4. subagent-driven-development / executing-plans（実装）

計画に基づいて実装を進める。サブエージェントが使える環境では subagent-driven-development でタスクごとにサブエージェントをディスパッチし、2段階レビュー（仕様準拠 → コード品質）を自動化する。サブエージェントが使えない環境では executing-plans でバッチ実行する。

5. finishing-a-development-branch（完了処理）

テスト確認後、ローカルマージ・PR作成・ブランチ保持・作業破棄の4択を提示し、ユーザーの選択に従ってクリーンアップまで実行する。

このように、「何を作るか」の合意形成から「どう完了させるか」まで、開発プロセス全体がスキルチェーンとして定義されている。エージェントが各ステージをスキップすることは構造的に困難になっている。

全14スキル一覧

superpowers は v5.0.7 時点で14のスキルを提供している。以下にカテゴリ別の全体像を示す。

Testing

test-driven-development

TDD の RED-GREEN-REFACTOR サイクルをエージェントに強制する。「テストなしでプロダクションコードを書くことは絶対禁止」（Iron Law）が定義されており、テスト前にコードを書いた場合は削除して最初からやり直すことが要求される。各ステップの完了を検証コマンドで確認してから次に進む。

Debugging

systematic-debugging

バグ報告に対して、4段階の根本原因分析プロセス（Root Cause Investigation → Pattern Analysis → Hypothesis and Testing → Implementation）を適用する。場当たり的な修正を禁じ、「修正を3回失敗したらアーキテクチャを見直す」ルールを組み込んでいる。

verification-before-completion

作業完了を主張する前に、検証コマンドの実行を強制するスキル。「テストが通っているはず」「たぶん動く」といった未検証の完了報告を防ぐ。Iron Law は「検証エビデンスなしに完了を主張してはならない」であり、テスト・ビルド・リンターそれぞれについて「何を実行し、何を確認すべきか」が具体的に定義されている。

Collaboration

brainstorming

設計段階でユーザーとの対話的な仕様洗い出しを行う。要件の曖昧な部分を質問し、トレードオフを提示し、合意を得てから次のフェーズに進む。WebSocket ベースのビジュアルコンパニオン機能でモックアップを表示することも可能。

writing-plans

実装前の計画フェーズを厳格化する。タスクを2〜5分単位に分解し、各タスクに完全なコード例と検証手順を含める。「ジュニアエンジニアが迷わず実装できるレベルの詳細さ」が基準。

executing-plans

writing-plans で作成した計画書をシングルセッションで実行するスキル。計画をロードして批判的にレビューし、タスクを順次実行し、完了後は finishing-a-development-branch に引き継ぐ。サブエージェントが利用できない環境向けのフォールバックとして位置づけられている。

dispatching-parallel-agents

独立した複数のタスクをサブエージェントに並列ディスパッチするスキル。3つ以上のテストファイルが異なる原因で失敗しているようなケースで、各問題を独立したエージェントに割り振って同時に調査させる。ディスパッチ後は結果を統合し、競合がないことを確認してからフルテストスイートを実行する。

requesting-code-review

タスク間での品質チェックを組み込む。エージェントが一定の作業を完了するたびにレビューを行うプロセスを定義し、「実装して終わり」ではなく検証のチェックポイントを作業フローに埋め込む。

receiving-code-review

コードレビューのフィードバックを受け取る際の行動規範を定義するスキル。「You're absolutely right!」のようなパフォーマティブな同意を禁止し、技術的な検証を経てから実装に入ることを要求する。外部レビュアーの指摘は技術的に正しいか検証し、問題があれば技術的根拠をもって反論することを推奨する。

using-git-worktrees

Git worktree を活用して、ブランチ単位で隔離された開発環境を作成する。.worktrees/ の存在確認、.gitignore の検証、テストベースラインの確認までを一連のプロセスとして実行する。

finishing-a-development-branch

実装完了後のブランチ統合プロセスを構造化するスキル。テスト確認 → 4つの選択肢（ローカルマージ / PR作成 / ブランチ保持 / 作業破棄）の提示 → ユーザー選択の実行 → worktree のクリーンアップまでを一貫して管理する。作業破棄時には明示的な確認を要求し、誤削除を防止する。

subagent-driven-development

サブエージェントを活用した2段階レビューを実施する。タスクごとにサブエージェントをディスパッチし、仕様準拠レビュー（spec-reviewer）→ コード品質レビュー（code-quality-reviewer）の順で検証する。レビュアーは実装者の報告を信用せず独自に検証する（「CRITICAL: Do Not Trust the Report」）設計になっている。

Meta

using-superpowers

スキルシステム全体を統括するメタスキル。セッション開始時に自動注入され、「スキルが適用される可能性が1%でもあれば、必ずスキルを呼び出す」ことをエージェントに強制する。12項目の合理化防止テーブルを備え、エージェントがスキルの適用を回避する言い訳を事前に封じている。詳細は次節「スキルの自動トリガー」で解説する。

writing-skills

カスタムスキルの作成に TDD の手法を適用するメタスキル。RED（スキルなしでサブエージェントがルール違反するベースラインを記録）→ GREEN（違反を防ぐスキルを記述）→ REFACTOR（新たな合理化パターンを発見して対策を追加）のサイクルで、スキル自体の品質を保証する。CSO（Claude Search Optimization）という概念も導入しており、スキルの description フィールドにはワークフロー要約ではなくトリガー条件のみを記述する設計指針を定めている。

スキルの自動トリガー

superpowers のスキルは「使いたいときに呼び出す」ものではなく、セッション開始時に自動的にエージェントのコンテキストへ注入される。この仕組みは3層構造で実現されている。

1. セッション開始フック

hooks/hooks.json が SessionStart イベントを検知し、session-start スクリプトを実行する。

2. ブートストラップスクリプト

session-start スクリプトが using-superpowers/SKILL.md の全文を読み込み、JSON エスケープして <EXTREMELY_IMPORTANT> タグで囲んだうえでエージェントのコンテキストに注入する。プラットフォームごとに出力フォーマットを切り替える（Claude Code、Cursor、Copilot CLI 等）。

3. メタスキルによる強制

注入された using-superpowers スキルが、エージェントに対して「すべてのタスクの前にスキルの適用可否をチェックせよ」と指示する。合理化防止テーブル（12項目）により、「これは単純な質問だからスキル不要」「先にコンテキストを確認したい」といった回避パターンを事前に封じている。

この3層アーキテクチャにより、ユーザーが明示的にスキルを呼び出さなくても、superpowers のワークフローが自動的に適用される。スキルは「提案」ではなく「強制」として機能する設計だ。

「数時間の自律作業」を支える仕組み

superpowers の特徴の1つに、エージェントが数時間にわたり自律的に作業を継続することも珍しくないとされている点がある。通常、長時間の自律作業ではコンテキストの喪失や方針のドリフトが発生しやすい。superpowers はこれを以下の構造で解決する。

綿密な計画（writing-plans） が全体の方針を固定する。各タスクが2〜5分単位に分解されているため、エージェントは常に「次に何をすべきか」が明確な状態で作業を続けられる。

段階的検証（TDD + verification-before-completion） が品質の劣化を防ぐ。各ステップで検証が入るため、問題が蓄積して後半で破綻するリスクを抑えられる。

「ジュニアエンジニア向けの実装計画」という形式 がコンテキスト依存を排除する。計画書自体に完全なコード例と検証手順が含まれているため、エージェントのコンテキストウィンドウが切り替わっても作業を継続できる。

この3つの組み合わせにより、「放っておいても正しく動き続ける」状態を構造的に支えている。

導入手順

対象ツールごとのインストール方法を示す。

Claude Code（Official Marketplace）

/plugin install superpowers@claude-plugins-official

公式マーケットプレイスから直接インストールする方法だ。シンプルな手順で導入できる。

Claude Code（via Plugin Marketplace）

サードパーティのマーケットプレイスを経由する場合は、まずマーケットプレイスを追加してからインストールする。

/plugin marketplace add obra/superpowers-marketplace

/plugin install superpowers@superpowers-marketplace

Cursor

/add-plugin superpowers

または、plugin marketplace で「superpowers」を検索してインストールする。

Codex

エージェントに以下の指示を与えることで、インストール手順を自動的に取得・実行させる。

Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md

OpenCode

Codex と同様に、専用のインストール手順を取得・実行させる。

Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

インストール後、エージェントに対して use superpowers や follow the superpowers workflow と指示することで、定義されたスキルセットに基づいた開発プロセスが有効化される。各ツールのインストール手順は変更される可能性があるため、最新の手順は 公式 README を参照してほしい。

他のフレームワーク・ツールとの比較

superpowers と比較されることが多いのが oh-my-claudecode だ。両者は解決する問題が異なる。

oh-my-claudecode は「誰がやるか」を最適化し、superpowers は「どうやるか」を最適化する。関心事が直交しているため、併用が可能だ。oh-my-claudecode でタスクを適切なエージェントに振り分けつつ、各エージェントの作業プロセスを superpowers で規律化するという構成が考えられる。

まとめ

superpowers が多くの開発者に支持されている理由は、「エージェントの出力品質が安定しない」という課題に、再現可能なプロセスの強制という実践的な解を示したことにある。

本記事（入門編）では、superpowers の全体像として開発ワークフローの流れ、14スキルの役割、スキルの自動トリガー機構を概観した。

• 第2回（設計パターン編） では、superpowers が採用するプロンプトエンジニアリングの技法（Iron Law、合理化防止テーブル、Red Flags リスト、CSO 等）を掘り下げる
• 第3回（実践・カスタマイズ編） では、writing-skills を使ったカスタムスキルの作成や、subagent-driven-development の実践的な活用を解説する

AIエージェントの能力が向上するほど、「何をさせるか」よりも「どうさせるか」の設計が重要になる。自分のプロジェクトでエージェントの品質バラつきに悩んでいるなら、まず superpowers の writing-plans と test-driven-development から試してみることを勧める。

参考リンク

• superpowers — コーディングエージェント向け開発ワークフローフレームワーク（公式リポジトリ）
• oh-my-claudecode — Claude Code 向けマルチエージェントオーケストレーション（公式リポジトリ）
• agentskills.io — スキル定義の仕様（superpowers のスキルが準拠）