はじめに
こんにちは！サイオステクノロジーのなーがです。前回はGoogle CloudのVertex AIをAzureから使用するための手順ということで主にインフラ関連の内容を書きましたが、今回はAIコーディングエージェントの開発プロセスを強化するフレームワーク「obra/superpowers」について書こうと思います。
AIエージェントは本当に便利なのですが、使い込んでいると「あれ、テスト書かずにいきなり実装してる…」「原因調査なしにとりあえずパッチを当てようとしてる…」という場面に気づくことがあります。エージェントは高性能ですが、プロセスを省略するクセがあるんですよね。
そんな悩みを解決してくれるのが、今回紹介する obra/superpowers です。92K以上のGitHubスターを獲得している注目のフレームワークで、AIコーディングエージェントに規律ある開発プロセスを注入してくれます。
今回は、superpowersの概要からインストール方法、実際の活用シナリオまでを詳しく紹介します。
obra/superpowers とは
obra/superpowers は、AIコーディングエージェント向けの アジャイルスキルフレームワーク です。
「スキル」と呼ばれるMarkdownベースの指示ファイルをエージェントに読み込ませることで、テスト駆動開発・体系的なデバッグ・コードレビューといった規律ある開発プロセスを強制します。
“coding agents produce better results when they follow systematic processes rather than ad-hoc approaches”
この思想が、superpowersの根幹にあります。エージェントの能力を引き出すのではなく、プロセスをガイドする というアプローチです。
誕生の背景
開発者の Jesse Vincent 氏（Prime Radiant）が、AIエージェントが以下のような「近道」を取ろうとする問題に直面したことがきっかけです。
- テストを後回しにして実装を先に書く
- 根本原因を調査せずにパッチを当てる
- 完了確認なしに「できました」と報告する
superpowers はこれらのアンチパターンを明示的にドキュメント化し、エージェントが自分でそれを認識・拒否できるように設計されています。
対応プラットフォーム
superpowers は主要なAIコーディングプラットフォームすべてに対応しています。
| プラットフォーム | 対応状況 |
|---|---|
| Claude Code | ✅ 公式マーケットプレイス対応 |
| Cursor | ✅ プラグインマーケットプレイス対応 |
| Gemini CLI | ✅ Extension対応 |
| Codex | ✅ .codex/ ディレクトリ方式 |
| OpenCode | ✅ .opencode/ ディレクトリ方式 |
スキル一覧とアーキテクチャ
14種類のスキル一覧
superpowers には14種類のスキルが含まれており、4つのカテゴリに分類されています。
| カテゴリ | スキル名 | 目的 |
|---|---|---|
| テスト・品質 | test-driven-development | テスト先行の RED-GREEN-REFACTOR サイクルを強制 |
systematic-debugging | 4フェーズの根本原因分析を強制 | |
verification-before-completion | 証拠なき完了宣言を禁止 | |
| 計画・実行 | brainstorming | 実装前の設計対話・仕様レビューを実施 |
writing-plans | 2〜5分タスク単位の実装計画を作成 | |
executing-plans | 実装計画を順序通りに実行 | |
subagent-driven-development | サブエージェント×2段階レビューで高品質実装 | |
dispatching-parallel-agents | 独立タスクを並列サブエージェントへ委譲 | |
| Git・コラボレーション | using-git-worktrees | 独立したGit worktreeで安全に並列開発 |
finishing-a-development-branch | テスト確認→マージ/PR/破棄の構造化フロー | |
requesting-code-review | 適切なタイミングでコードレビューを依頼 | |
receiving-code-review | レビューフィードバックを技術的に評価 | |
| メタ | using-superpowers | スキルの発見・呼び出しのメタプロトコル |
writing-skills | 新しいスキルをTDDで作成 |
コアスキル12種に加え、フレームワーク自体を拡張するメタスキル2種（using-superpowers・writing-skills）が含まれています。
ディレクトリ構成
リポジトリのトップレベル構成は以下の通りです。
superpowers/
├── skills/ # 14種類のスキルモジュール
├── agents/ # エージェント設定・振る舞い定義
├── commands/ # CLIコマンド実装
├── hooks/ # プラットフォーム統合フック
├── docs/ # プラットフォーム別ドキュメント
├── tests/ # テストスイート
├── .claude-plugin/ # Claude Code 統合
├── .cursor-plugin/ # Cursor 統合
├── .codex/ # Codex 統合
└── .opencode/ # OpenCode 統合
各スキルは skills/<スキル名>/ ディレクトリに格納されており、必須ファイル SKILL.md の他に必要に応じてテンプレートやスクリプトが含まれます。
アーキテクチャ図
superpowers の全体アーキテクチャを図で示します。AIコーディングプラットフォームからスキルレイヤーを通じ、フック・Git統合へと流れる構造になっています。
スキルはプロジェクトのコンテキストに応じて **自動的に発火** します。特別な構文や手動呼び出しは不要です。
次に、スキルのカテゴリ構成をマップで示します。
SKILL.md のフォーマット
各スキルは SKILL.md ファイル一枚で定義されます。構造は以下の通りです。
---
name: skill-name
description: "Use when ... (最大1024文字、トリガー条件を記述)"
---
## Overview
## When to Use
## Core Pattern
## Quick Reference
## Implementation
## Common Mistakes
フロントマターの description フィールドが特に重要で、エージェントがスキルを自動選択する際の判断基準になります。「Use when…」という形式でトリガー条件を記述することがベストプラクティスです。
Token効率も設計の考慮事項で、頻繁に読み込まれるスキルは200語以内に収めることが推奨されています。
インストール方法
Claude Code
公式マーケットプレイス経由（推奨）:
/plugin install superpowers@claude-plugins-official
カスタムマーケットプレイス経由:
# ステップ1: マーケットプレイスを追加
/plugin marketplace add obra/superpowers-marketplace
# ステップ2: インストール
/plugin install superpowers@superpowers-marketplace
インストール後、新しいセッションを開始して「この機能を計画したい」などと話しかけると、brainstorming スキルが自動的に発火します。
アップデート:
/plugin update superpowers
Cursor
Cursor のプラグインマーケットプレイスから検索してインストールするか、以下のコマンドを使用します。
/add-plugin superpowers
Gemini CLI
gemini extensions install https://github.com/obra/superpowers
参照: obra/superpowers – Installation
活用シナリオ
活用シナリオは無限に考えられますが、今回は下記の6つのシナリオを紹介します。
TDD を強制する
test-driven-development スキルを使うと、エージェントはテストなしに実装コードを一切書かなくなります。
鉄則:
“NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.”
テストより先にコードを書いた場合は、そのコードをすべて削除して最初からやり直す。
サイクルは以下の通りです。
- RED — 失敗するテストを書く
- RED確認 （必須）— テストが実際に失敗することを確認する
- GREEN — テストが通る最小限のコードを書く
- GREEN確認 （必須）— テストが通ることを確認する
- REFACTOR — コードを整理する
手動テスト済みであることを理由にテストを省略しようとすると、スキルがそのアンチパターンを認識して拒否します。
長時間の自律開発セッション
executing-plans スキルと subagent-driven-development スキルを組み合わせると、2時間以上の自律開発セッションが可能になります。
各タスクは2〜5分単位に分割され、サブエージェントが1タスクずつ実装・レビューを繰り返します。人間が介入しなくても、スキルがプロセスの品質を担保します。
複数機能の並列開発
dispatching-parallel-agents スキルを使うと、互いに独立した複数のタスクを並列で処理できます。
適用条件:
- 3つ以上の独立した失敗ファイル・サブシステムがある
- タスク間で共有状態がない
- それぞれ異なる根本原因を持つ
using-git-worktrees と組み合わせることで、各エージェントが独立したGit worktreeで安全に作業できます。
公式ドキュメントによると、6件の失敗を3つの並列エージェントで解決したケースでは、コンフリクトゼロで解決できたとのことです。
根本原因を特定してからデバッグする
systematic-debugging スキルは、エージェントが「とりあえずパッチを当てる」近道を防ぎ、4フェーズの体系的なデバッグを強制します。
4フェーズ:
- Root Cause Investigation — エラーを読み込み、再現手順を確認し、直近の変更を調査する
- Pattern Analysis — 動いている似た箇所と比較して差分を特定する
- Hypothesis and Testing — 仮説を1つ立て、最小限の変更で検証する
- Implementation — 根本原因のみを修正し、再発防止のテストを追加する
原因が特定できていない段階で修正コードを書き始めようとすると、スキルの Iron Law「NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST」に引っかかり、Phase 1 に差し戻されます。「直ったと思ったらまた壊れた」という状況を根本から防げます。
実装前に設計を固める
brainstorming スキルを使うと、エージェントはコードを書く前に設計対話フェーズを実施します。
対話の流れ:
- 要件の確認と曖昧な点の洗い出し
- 複数の実装アプローチを提示して比較
- トレードオフ（速度・保守性・複雑度）を明示
- 合意した方針をドキュメント化
このスキルは writing-plans と連携しており、対話が終わると自動的に実装計画の作成に移行します。「とりあえず実装してみて後で考える」というエージェントの傾向を、設計ファーストに切り替えます。
1問ずつ丁寧に要件を深掘りし、合意が取れた段階で設計書を作成→ writing-plans スキルへ引き渡します。
コードレビューのサイクルを回す
requesting-code-review と receiving-code-review の2スキルを使うと、エージェントがレビューの依頼から反映まで一貫して対応します。
レビュー依頼時（requesting-code-review）:
- PR の目的・変更の概要・テスト状況を整理してレビュアーに提示
- レビューしやすい粒度に変更を分割
フィードバック受け取り時（receiving-code-review）:
- 指摘内容を「必須修正」「提案」「議論」に分類
- 技術的な根拠をもとに修正の要否を判断
- 反映した変更を明示してレビュアーに返答
感情的に反応したり、すべての指摘を無条件に受け入れたりするのではなく、技術的な評価に基づいて対応します。
技術的に不要な変更はプッシュバックし、根拠のある修正のみを行います。
さいごに
今回は obra/superpowers について紹介しました。
AIエージェントは非常に高性能ですが、プロセスを省略しがちという弱点があります。superpowers はそこに「規律」を注入することで、エージェントを本来の実力で動かし続けるための仕組みです。
特に test-driven-development スキルと systematic-debugging スキルは、エージェントが近道を取ろうとする典型的な場面で真価を発揮します。まずはこの2つからインストールして試してみることをおすすめします。
興味を持った方は、ぜひ公式リポジトリや writing-skills スキルを使って、自分だけのスキルを作ってみてください！
