SuperClaude仕組み調査

/analyze --code "コードを読んでそのようにしてClaudeCodeの能力の底上げしているか仕組みを調査して"

⏺ SuperClaude: Claude Code 能力向上の仕組み

  SuperClaudeは、Claude Codeに以下の5つの主要メカニズムを通じて能力を向上させています：

  1. モジュラー構成システム

  @include shared/superclaude-core.yml#Core_Philosophy
  - @includeディレクティブによるテンプレート参照
  - YAMLベースの構成で重複を排除
  - ~/.claude/に展開される構成ファイル群
  - CLAUDE.mdをClaude Codeが読み込み、動作を制御

  2. 19の専門コマンド

  - /analyze, /build, /test, /deployなど
  - 各コマンドは.claude/commands/にMarkdownで定義
  - 共通フラグとコマンド固有フラグを組み合わせ
  - 例：/analyze --code --think-hard --persona-architect

  3. 9つの認知ペルソナ

  --persona-architect  # システム設計思考
  --persona-security   # セキュリティ専門家視点
  --persona-frontend   # フロントエンド開発者モード
  各ペルソナが専門領域の思考パターンとツール選択を提供

  4. トークン最適化

  - UltraCompressed mode（--uc）で大幅なトークン削減
  - 記号ベースの通信：→|&|:|»
  - 構造化出力（YAML/リスト形式）を優先
  - コンテキスト使用量に応じた自動起動

  5. エビデンスベース手法

  禁止語: "最適|ベスト|高速|セキュア"
  推奨語: "可能性|測定結果|テストで確認"
  根拠のない主張を排除し、証拠に基づく開発を強制

  統合の仕組み

  1. install.shが構成ファイルを~/.claude/にインストール
  2. Claude Code起動時にCLAUDE.mdを読み込み
  3. ユーザーがコマンド実行（例：/analyze）
  4. @includeディレクティブが関連構成を動的に読み込み
  5. Claude Codeの応答が構成に従って最適化

  この仕組みにより、Claude Codeは開発ワークフロー全体で一貫性のある、専門的で効率的なアシ
  スタントとして機能します。

1. モジュラー構成システム

  仕組み

  - @includeディレクティブ: @include 
  path/to/file.yml#Section_Name形式で、YAMLファイルの特定セクションを参照
  - 階層構造:
    - グローバル設定: ~/.claude/CLAUDE.md
    - プロジェクト設定: ./CLAUDE.md
    - 共有パターン: .claude/shared/と.claude/commands/shared/

  利点

  - DRY原則: 同じ設定を複数箇所で繰り返さない
  - 保守性: 一箇所の変更が全体に反映
  - モジュール性: 機能ごとに分離された設定ファイル
  - カスタマイズ: ユーザーが独自の設定を追加可能

@includeディレクティブの機能

  @includeディレクティブは、SuperClaudeにおけるテンプレート参照システムです。実際のClaude
   Codeには、この機能は組み込まれていません。

  仕組み

  1. 形式: @include path/to/file.yml#Section_Name
    - path/to/file.yml: 参照するYAMLファイルのパス
    - #Section_Name: そのファイル内の特定セクション
  2. 実際の例:
  @include shared/superclaude-core.yml#Core_Philosophy
  2.
  これは「superclaude-core.ymlファイルのCore_Philosophyセクションを読み込め」という意味
  3. 参照先の内容:
  ## Core_Philosophy
  Philosophy: "Code>docs | Simple→complex | Security→evidence→quality"
  Communication: "Format | Symbols: →|&|:|» | Structured>prose"

  重要な点

  @includeは擬似的な機能です：
  - Claude Code自体にファイルをインクルードする機能はありません
  - CLAUDE.mdファイルに書かれた@includeは、Claude Codeへの指示として機能
  - Claude Codeは、これらの参照を見て、対応する設定内容を記憶・適用する

  なぜこの方式を使うのか

  1. メンテナンス性: 設定を一箇所で管理し、複数の場所から参照
  2. 可読性: CLAUDE.mdをコンパクトに保ちながら、詳細は別ファイルに
  3. モジュール性: 機能ごとに設定を分離
  4. バージョン管理: 各モジュールを独立して更新可能

  実際には、インストール時にこれらのYAMLファイルが~/.claude/に配置され、Claude
  CodeがCLAUDE.mdを読む際に、これらの参照を概念的に理解して動作を調整します。

4. トークン最適化の詳細

  SuperClaudeのトークン最適化は、複数の戦略を組み合わせた高度なシステムです。

  UltraCompressed Mode（--ucフラグ）

  起動方法

  1. 明示的: --ucまたは--ultracompressedフラグ
  2. 自動起動:
    - コンテキスト使用率75%超
    - 大規模プロジェクト（10k+ファイル）
    - 長時間セッション（2時間超）
  3. 自然言語: "compress", "concise", "brief"などのキーワード

  記号ベース通信システム

  論理記号

  → : "〜につながる"、"結果として"
  & : "および"、"〜と"
  | : "または"、"もしくは"
  ∵ : "なぜなら"、"〜のため"
  ∴ : "したがって"、"ゆえに"

  プロセス記号

  ▶ : 開始、初期化
  ✅ : 成功、完了
  ❌ : 失敗、エラー
  ⚡ : 高速、パフォーマンス
  🔄 : 繰り返し、ループ

  技術略語

  analyze → anlz    | build → bld      | deploy → dply
  database → db     | interface → api  | environment → env
  configuration → cfg | implementation → impl | performance → perf

  圧縮戦略（3段階）

  第1段階：構造最適化

  - 文章→YAML形式（60-80%削減）
  - 段落→箇条書き
  - 説明→表形式

  第2段階：言語圧縮

  - 削除対象:
    - 冠詞: the, a, an
    - 接続詞: however, therefore, moreover
    - 前置詞: of, in, on, at, to, for
    - フィラー: very, really, quite, that, which

  第3段階：技術圧縮

  - ドメイン固有略語の適用
  - @includeによるパターン参照
  - 記号置換の実行

  実例：Before/After

  例1：ステータスレポート

  通常出力:
  ビルドプロセスが正常に完了しました。3つのファイルが
  変更され、1つのファイルが追加され、削除されたファイル
  はありません。テストは100%のカバレッジで合格しています。

  圧縮出力:
  ✅ Build完了
  変更:3 | 追加:1 | 削除:0
  テスト: ✅ 100%カバレッジ

  例2：エラーメッセージ

  通常出力:
  デプロイメントが失敗しました。データベース接続を
  確立できませんでした。これは環境設定の誤りが原因と
  考えられます。データベースの認証情報を確認して
  再試行してください。

  圧縮出力:
  ❌ Deploy失敗 ∵ DB接続
  → env cfg確認&再試行

  例3：タスク進捗

  通常出力:
  現在、ユーザー認証機能の実装に取り組んでいます。
  5つのタスクのうち3つが完了しました。完了したタスクは
  データベーススキーマの設定、APIエンドポイントの作成、
  パスワードハッシュ化の実装です。JWTトークンの追加と
  テストの作成がまだ必要です。

  圧縮出力:
  T: ユーザー認証 | S: in_progress | P: high
  進捗: 3/5 (60%)
  ✅ DBスキーマ | APIエンドポイント | pwdハッシュ
  → JWTトークン | テスト

  トークン削減率

  | コンテンツタイプ | 削減率    |
  |----------|--------|
  | ヘッダー     | 60-80% |
  | 段落       | 70-75% |
  | リスト      | 50-60% |
  | 平均       | 約70%   |

  品質保持メカニズム

  圧縮しても以下を維持：
  - 情報密度: トークンあたりの情報量増加
  - 明確性: 圧縮されても理解可能
  - コンテキスト: 重要情報は保持
  - 可逆性: 必要時に詳細説明に展開可能

  自動最適化

  Context_Intelligence:
    高使用率: "75%超 → 自動圧縮"
    エラー継続: "修正後もエラー → introspection提案"
    大規模操作: "10k+ファイル → --uc推奨"

  この仕組みにより、APIコストを大幅に削減しながら、より多くの処理を同じトークン枠内で実行
  できます。

5. エビデンスベース手法の詳細

  SuperClaudeのエビデンスベース手法は、Claude
  Codeの回答品質を根本的に変革する仕組みです。

  禁止語と推奨語

  禁止される表現

  禁止語: "best|optimal|faster|secure|better|improved|enhanced|always|never|guaranteed"

  推奨される表現

  推奨語: "may|could|potentially|typically|often|sometimes|measured|documented"

  実例

  ❌ 通常: 「これは最適なデータベース最適化方法です」
  ✅ エビデンスベース: 「この方法は、類似シナリオで23%の改善を示した測定結果に基づいて、
  クエリ時間を削減する可能性があります（出典：PostgreSQL文書v15.2）」

  証拠要件の実施

  必須フォーマット

  証拠要件: "testing confirms|metrics show|benchmarks prove|data indicates|documentation 
  states"

  パフォーマンス主張の例

  ❌ 証拠なし: 「このリファクタリングでパフォーマンスが75%向上」
  ✅ 証拠あり: 「Chrome DevToolsで測定：遅延読み込み実装後、初期レンダリング時間が1200ms
  から900msに短縮（25%改善）」

  信頼度スコアリングシステム

  証拠源の信頼度

  公式ドキュメント: 100%
  メンテナのチュートリアル: 95%
  最近のブログ投稿: 85%
  GitHub Issue解決策: 85%
  Stack Overflow承認回答: 80%
  コミュニティチュートリアル: 75%
  証拠なし: 0%

  実装閾値

  - 実装可能: 90%以上
  - 警告付き実装: 80-90%
  - 追加調査必要: 80%未満

  測定基準の標準化

  測定フォーマット

  悪い例: "75%性能向上"
  良い例: "<測定値>%向上"
  最良例: "<基準値>→<現在値> (<差分>%)"

  実際の出力例

  ## パフォーマンス分析結果
  - バンドルサイズ: 245KB → 187KB (23.7%削減)
  - First Contentful Paint: 2.3s → 1.8s (21.7%改善)
  - Time to Interactive: 4.1s → 3.2s (22%改善)

  測定環境: Lighthouse v11.0.0, Chrome 119

  引用要件

  引用フォーマット

  // 出典: Passport.js公式ドキュメント v0.6.0 - Local Strategy
  // https://www.passportjs.org/docs/authenticate/
  passport.use(new LocalStrategy(
    function(username, password, done) {
      // 公式例に基づく実装
    }
  ));

  禁止される引用

  - // 一般的なパターン（ソースなし）
  - // 標準的なアプローチ（証拠なし）
  - // 典型的な実装（調査なし）

  品質検証パターン

  重要度レベル

  CRITICAL:
    定義: "データ損失、セキュリティ侵害、本番停止"
    対応: "即座停止、警告、ロールバック"
    例: ["本番データ削除", "秘密情報露出", "mainブランチ強制push"]

  HIGH:
    定義: "重大なバグ、パフォーマンス問題"
    対応: "警告、修正提案、代替案"

  MEDIUM:
    定義: "改善可能、技術的負債"
    対応: "助言、ベストプラクティス提案"

  調査フロー要件

  外部ライブラリ使用時の必須フロー：
  1. ライブラリ参照を検出
  2. package.json/requirements.txtを確認
  3. Context7 MCPで公式ドキュメント取得
  4. 失敗時はWebSearchでフォールバック
  5. 実装時にソース引用

  レビューコマンドでの適用例

  ## コードレビュー: auth.service.ts

  ### セキュリティ問題発見
  **重要度**: HIGH
  **問題**: パスワードが平文で保存
  **証拠**: OWASP認証チートシート セクション2.1.1
  **出典**: https://cheatsheetseries.owasp.org/
  **修正**: bcrypt実装、コストファクター12推奨（NIST SP 800-63B）

  コミュニケーション標準

  建設的フィードバック

  ❌ 曖昧: 「このコードはもっと良くできる」
  ✅ 証拠ベース:
  「React.memoの使用を検討してください。プロファイラーデータで、このコンポーネントが通常
  のユーザーフロー中に47回再レンダリングされ、340msの不要な計算が発生しています」

  エラー処理での適用

  調査失敗時の対応:
  - 明示的に記述: "[X]の公式ドキュメントが見つかりません"
  - 理由を提供: "[Y]の類似パターンを使用、理由は..."
  - 暫定マーク: "// TODO: 公式ドキュメント利用可能時に検証"

  効果

  このエビデンスベース手法により：

  1. 信頼性向上: すべての主張が検証可能
  2. 専門性: 具体的な数値とソースで裏付け
  3. 透明性: 判断根拠が明確
  4. 学習可能: ソースから詳細を確認可能
  5. 品質保証: 曖昧な推奨を排除

  結果として、Claude Codeは単なる提案者から、信頼できる技術アドバイザーへと進化します。

ユーザー視点でのSuperClaude

  コマンド使用時（推奨）

  /buildなどのコマンドを使えば、自動的に最適化が適用されます：

  # シンプルに使うだけで最適化される
  /build

  # 必要に応じてフラグを追加
  /build --watch --persona-frontend

  自動で起きること：
  - トークン効率化
  - 適切なペルソナの選択
  - エビデンスベースの応答
  - 構造化された出力

  コマンドを使用しない場合

  通常のClaude Codeとして動作しますが、SuperClaudeの設定は部分的に適用されます：

  1. 基本設定は有効
    - CLAUDE.mdの基本ルール
    - エビデンスベース手法
    - トークン意識
  2. 手動で機能を有効化可能
  「UCモードで説明して」
  「アーキテクトの視点で分析して」
  3. 自動起動トリガー
    - 大規模ファイル検出 → 圧縮モード提案
    - エラー連続 → introspectionモード提案
    - 特定ファイルタイプ → 適切なペルソナ

  最も簡単な使い方

  1. インストール後は普通に使う
  # コマンドを使うだけ
  /analyze
  /build
  /test
  2. 必要な時だけフラグ追加
  # 詳細な分析が必要な時
  /analyze --think-hard

  # 特定の専門性が必要な時
  /build --persona-frontend
  3. 自動提案に従う
    - 「大規模プロジェクトなので--ucを推奨します」
    - 「複雑なタスクなのでTodoListを作成しました」

  コマンドなしでも活用できる機能

  # これらは常に有効
  - エビデンスベースの回答
  - 構造化された出力
  - 品質基準の適用
  - セッション認識

  # キーワードで起動
  - "compress" → UCモード
  - "セキュリティ" → セキュリティペルソナ
  - "バグ" → アナライザーペルソナ

  まとめ

  - コマンド使用時: 全機能が自動的に最適化される
  - コマンドなし: 基本機能は有効、高度な機能は手動/自動トリガー
  - ユーザーは細かい設定を意識する必要なし
  - 必要に応じてシステムが提案してくれる

  つまり、SuperClaudeは「インストールして普通に使うだけで賢くなる」設計になっています。

⏺ コマンドを使用すべき時 vs 使用しなくてもいい時

  コマンドを使用すべき時 🎯

  1. 構造化されたタスク

  /build          # ビルド設定、依存関係管理
  /test           # テスト実行、カバレッジ分析
  /deploy         # デプロイメント、環境設定
  /analyze        # コード品質、アーキテクチャ分析

  2. 複雑な作業

  - 複数ステップが必要なタスク
  - 専門的な分析が必要な場合
  - 体系的なアプローチが有効な作業

  3. 特定の専門性が必要

  /scan --persona-security    # セキュリティ監査
  /design --persona-architect # システム設計
  /troubleshoot --think-hard  # 複雑な問題解決

  4. 効率を最大化したい時

  /analyze --uc              # 大規模コードベースの分析
  /review --batch            # 複数ファイルのレビュー
  /implement --no-explain    # 説明なしで実装のみ

  コマンドを使用しなくてもいい時 ✋

  1. 単純な質問・タスク

  - 「このエラーの意味は？」
  - 「変数名を変更して」
  - 「この関数の説明をして」

  2. 対話的な探索

  - コードの理解を深めたい
  - 段階的に問題を解決したい
  - 学習目的での質問

  3. クイックフィックス

  - 1行の修正
  - 簡単なバグ修正
  - タイポの訂正

  4. 一般的な相談

  - 技術選定の相談
  - ベストプラクティスの質問
  - 概念的な説明

  判断基準のまとめ

  | 状況           | コマンド使用 | 理由           |
  |--------------|--------|--------------|
  | 10個以上のファイル操作 | ✅ 推奨   | 構造化された処理が効率的 |
  | 1-2個のファイル編集  | ❌ 不要   | オーバーヘッドが大きい  |
  | セキュリティレビュー   | ✅ 推奨   | 専門ペルソナが有効    |
  | コードの意味を聞く    | ❌ 不要   | 単純な説明で十分     |
  | プロジェクト全体の分析  | ✅ 推奨   | 体系的アプローチが必要  |
  | エラーメッセージの解釈  | ❌ 不要   | 直接的な回答で十分    |
  | CI/CD設定      | ✅ 推奨   | 複雑な設定管理      |
  | README更新     | ❌ 不要   | 単純な編集作業      |

  ハイブリッドアプローチ

  # 最初は通常の質問
  「このプロジェクトの構造を理解したい」

  # 複雑になったらコマンドに切り替え
  「詳しく分析して」→ SuperClaudeが提案：
  「プロジェクトが大規模なので /analyze --arch --think を推奨します」

  経験則

  - 3ステップ以上 → コマンド使用
  - 専門知識必要 → コマンド + ペルソナ
  - 繰り返し作業 → コマンドでワークフロー化
  - 探索的作業 → 通常の対話でOK
  - 学習・理解 → 通常の対話が効果的

  基本的に、迷ったら通常の対話で始めて、SuperClaudeが必要に応じてコマンドを提案してくれま
  す。

SuperClaudeには自動提案システムがあります！

  自動提案の仕組み

  1. ファイルタイプ検出による提案

  File_Type_Detection:
    tsx_jsx: "→frontend persona"
    test: "→qa persona"
    Docker: "→devops workflows"

  例：
  - .tsxファイルを扱う時 → 「/analyze --persona-frontendを使うと効果的です」
  - test.jsを見る時 → 「/test --coverageでテスト分析ができます」

  2. キーワードによる提案

  Keyword_Triggers:
    bug_error_issue: "→analyzer persona"
    optimize_performance: "→performance persona"
    secure_auth_vulnerability: "→security persona"

  例：
  - 「バグを修正して」→ 「/troubleshoot --analyzerが適切かもしれません」
  - 「パフォーマンスを改善」→ 「/analyze --perfを推奨します」

  3. 混乱検出による提案

  Confusion_Detection:
    Multiple_Attempts: "3+ failed operations→suggest --introspect"
    Complex_Debugging: "Error persists after fix→suggest introspection"

  提案フォーマット：
  🤔 This seems complex. Would --introspect help understand?

  4. コンテキスト使用量による提案

  Activation: "Auto: context >75% usage"

  - コンテキスト75%超 → 「大規模な分析なので--ucフラグで圧縮モードを推奨」

  5. エラーパターンによる提案

  Context_Intelligence:
    TypeError: "→dependency analysis"
    Module_errors: "→installation workflows"
    Build_failures: "→systematic debugging"

  例：
  - ModuleNotFoundError → 「/build --depsで依存関係を確認しましょう」
  - ビルドエラー連続 → 「/troubleshoot --systematicを試してみてください」

  実際の動作例

  ユーザー: 「このReactコンポーネントのパフォーマンスが悪いんだけど...」

  SuperClaude:
  パフォーマンス問題を検出しました。以下のコマンドが役立つかもしれません：

  1. `/analyze --perf --persona-performance` - 詳細なパフォーマンス分析
  2. `/profile --react` - Reactコンポーネント固有の分析
  3. `/refactor --optimize` - 最適化提案付きリファクタリング

  どれか試してみますか？

  自動提案のタイミング

  1. タスクの複雑さを検出
    - 高複雑度 → TodoWrite自動作成
    - 中複雑度 → 適切なコマンド提案
    - 低複雑度 → 直接実行
  2. 繰り返し失敗を検出
    - 3回以上の失敗 → --introspect提案
    - エラー継続 → より深い分析コマンド提案
  3. プロジェクトサイズを検出
    - 10k+ファイル → --uc圧縮モード提案
    - 大規模分析 → バッチ処理提案

  この仕組みにより、ユーザーはSuperClaudeの全機能を覚える必要がなく、状況に応じて最適なコ
  マンドを教えてもらえます！