⚡
★ 86.6k

チャプター10：よくある質問

一般

Superpowersはどのプラットフォームで動作しますか？

プラットフォームステータス
Claude Code完全サポート
Cursor完全サポート（v4.3.1以降）
Gemini CLI完全サポート（v5.0.1以降）
Codex実験的サポート（v3.3.0以降）
OpenCode完全サポート（v3.5.0以降）

通常のAIエージェントとどう違いますか？

通常のAIエージェントはプロンプトに従います。SuperpowersはAIエージェントに強制されるプロセスです。

違いは構造にあります。Superpowersなしでは、AIがコードを書き、あなたがレビューし、問題を見つけ、修正を依頼します。Superpowersを有効にすると、AIは自分でテストを書き、自分でテストを実行し、自分で検証し、失敗すると自分でデバッグします。あなたは結果を確認します。

実際的な違いは、Superpowersはより多くの機能をより少ない手直しで実現することです。AIが検証しないときにあなたが発見していたバグが、今ではAIのプロセスの一部として発見されます。

チームでSuperpowersを設定するにはどうすればいいですか？

チームセットアップには標準インストールとは別のものは何も必要ありません。各開発者が自分の環境にスキルをインストールします。スキルはロールアウトする構成ではありません—それらはAIの動作を定義するファイルです。

一貫性のために：

  1. スキルのバージョンをCLAUDE.mdに記録してください
  2. スキルのアップデートに関するレビュープロセスを確立してください
  3. チームメンバーがスキルに違反している場合（例：TDDをスキップしている場合）、それを通常のコードレビューフィードバックとして扱ってください

TDDと品質

TDDは本当に交渉の余地がありませんか？すべてのコードにテストが必要ですか？

はい。TDDは交渉の余地のない鉄の法則です—オプションのベストプラクティスではありません。

テストが難しいコードに対してよく聞かれる質問です。難しいのは本物です。しかし、Superpowersはそれを理由に例外を作りません。テストが難しい場合、それはほぼ常にコードの設計に問題があることを示しています—過度な結合、隠れた依存関係、または壊れた単一責任の原則。正しい対応はテストを書けないから免除することではなく、テストしやすくするためにコードを修正することです。

唯一の正当な例外は、テスト可能なコードがまだ存在しない場合の探索的コードです。しかし探索的コードはプロダクションコードになってはいけません。探索するなら削除するか、テストからやり直してください。

どのモデルを使うべきですか？

タスク推奨モデル
主要な実装Claude Sonnet 4.5以上
ルーティングと軽量タスクClaude Haiku 3.5
代替プラットフォームGemini 2.0 Flash、GPT-4o
コスト最適化Haiku 3.5でサブエージェント、Sonnetでオーケストレーター

重要なのは特定のモデルではなく、ツール呼び出しをサポートし、スキルの実行に必要なコンテキストウィンドウを持っていることです。

インストールとアップデート

Superpowersをどのようにアップデートしますか？

標準のアップデートプロセス：

# 現在のスキルworktreeがある場所に移動
cd ~/path/to/superpowers-skills

# リモートから最新の変更を取得
git pull origin main

# アップデートがインストールを完了するか確認
# （スキルはすでにClaude Codeのスキルシステムに直接リンクされているため、
# 追加の手順は必要ありません）

アップデート後、新しいスキルを使い始めるには新しいセッションを開始してください。実行中のセッションは更新されたスキルを自動的に取得しません。

新しいスキルを追加するにはどうすればいいですか？

新しいスキルの追加は5つのステップです：

  1. .claude/skills/にスキルファイルを作成する（例：my-skill.md）
  2. スキル名、説明、および使用タイミングのメタデータヘッダーを含める
  3. 失敗するテストを書く（スキルはコードです—鉄の法則4が適用されます）
  4. テストが通過するようにスキルを実装する
  5. CLAUDE.mdにスキルを文書化する

スキルはMarkdownファイルです。Claude Codeに指示を与えるMarkdownを書けるなら、スキルを書けます。

互換性

WindowsでSuperpowersは動作しますか？

Superpowersは主にmacOSとLinuxで開発され、テストされています。Windowsは動作しますが、いくつかの考慮事項があります：

パスセパレーター： スキルとCLAUDE.mdのパスはフォワードスラッシュ（/）を使用します。WindowsはClaude Code内でも通常これを扱えますが、スクリプトやbashコマンドを書くときに問題が発生する場合があります。

行末： .gitattributesにLF行末の正規化が設定されていることを確認してください。CRLFの行末はスキルのパースに問題を引き起こす可能性があります。

WSL2の推奨： Windowsで重大な問題に遭遇した場合、WSL2（Windows Subsystem for Linux 2）の使用を強くお勧めします。Superpowersの機能は完全なLinux環境でより確実に動作します。

Worktreeパス： Windowsでgit worktreeを使用する場合、ドライブレターを含むパス（例：C:\projects\myapp--feature-auth）はClaude Code端末でそのまま動作するはずです。

Claude Code以外のプラットフォームではスキルはどのように動作しますか？

各プラットフォームにはスキルをロードするための独自のメカニズムがあります：

  • Cursor： スキルはCursorのルールシステムを通じて動作します。.cursor/rules/ディレクトリにスキルコンテンツを配置するか、プロジェクト設定にインポートしてください
  • Gemini CLI： activate_skillツールを通じてスキルが動作します。インストール手順はGemini CLIドキュメントを参照してください
  • Codex： サポートは実験的です。ツール呼び出しの制限により、一部のスキルは期待通りに機能しない場合があります
  • OpenCode： Claude Codeと同様に動作します

Claude Code以外のプラットフォームでは、スキルのツール名はClaude Codeの名前とは異なる場合があります。プラットフォームの同等ツールへのマッピングについては、references/codex-tools.mdを参照してください。

トラブルシューティング

スキルが起動しません。何が問題ですか？

スキルが期待通りに起動しない場合、このチェックリストを使用してください：

  1. スキルはインストールされていますか？ .claude/skills/ディレクトリにスキルファイルが存在することを確認してください
  2. スキルはCLAUDE.mdに文書化されていますか？ AIはCLAUDE.mdからスキルを学習します。スキルが記載されていない場合、AIはそれを認識しません
  3. コンテキストウィンドウはどのくらい埋まっていますか？ コンテキストウィンドウが高い使用率（>80%）の場合、新しいセッションを開始してください
  4. スキルを明示的に呼び出しましたか？ 一部のスキルはスラッシュコマンドで明示的な呼び出しが必要です。/skill-nameを使用して呼び出してください
  5. スキルのフォーマットは正しいですか？ スキルファイルに適切なメタデータヘッダーがあることを確認してください

問題が続く場合は、/using-superpowersを使用してスキルシステム自体をリロードしてください。

テストがローカルでは通過するのにCIで失敗します

これは環境の違いの問題です。チャプター6のフェーズ1デバッグプロトコルを使用してください：

根本原因調査：

  1. CI環境とローカル環境の正確な違いをリストしてください（Nodeバージョン、環境変数、依存関係バージョン）
  2. CIのエラー出力の完全なスタックトレースを確認してください—切り捨てないでください
  3. 同じエラーをローカルで再現してみてください（CI環境変数を使用し、--ciフラグを付けてテストを実行する）

一般的な原因：

  • 環境変数がCIに設定されていない
  • ファイルシステムの大文字小文字の区別（macOSは大文字小文字を区別しないが、Linuxは区別する）
  • タイミングに依存するテスト（CIはローカルより遅い場合がある）
  • ロックファイルのコミット忘れ（package-lock.jsonまたはyarn.lock）

根本原因を特定せずに修正を試みないでください。原因がわからない場合は調査を続けてください。

他に質問がある場合は、GitHubのissueとして提出するか、Superpowersコミュニティフォーラムで質問してください。