コマンド、スキル、サブエージェント、ルール：139の拡張機能を整理して学んだこと

Claude Codeで95のフック、44のスキル、85のコマンド、そして11のルールファイルを構築してきた結果、間違った抽象化を選ぶことは、間違った機能を作ることよりも多くの時間を無駄にすると学びました。ルールにすべきだったスキルはコンテキストを40%も肥大化させました。スキルにすべきだったコマンドは、APIエンドポイントに触れるたびに毎回/fastapiと入力することを覚えておく必要がありました。¹

TL;DR

Claude Codeには動作を拡張する4つの方法があります：コマンド（ユーザーが手動で実行するプロンプト）、スキル（自動的に呼び出されるコンテキスト）、サブエージェント（タスクを委任する実行者）、そしてルール（常時有効な制約）です。139の拡張機能を整理した結果、判断のフレームワークはシンプルだとわかりました：ルールは不変条件に、スキルはドメイン専門知識に、コマンドはワークフローに、サブエージェントは隔離が必要な場面に。難しいのは、間違った選択をしたことに気づき、移行することです。

4つの抽象化（実例付き）

コマンド：「/commit」と他84個

コマンドは/command-nameと入力すると起動します。各コマンドはプロンプトテンプレートに展開されます。²

85のコマンドには、/commit（スマートなgitコミット）、/review（コードレビューエージェントの起動）、/deploy（デプロイチェックリスト）、/publish-check（ブログ公開前の検証）、/deliberate（マルチエージェントリサーチ）などがあります。

犯した間違い： /fastapiをコマンドとして構築し、必要に応じてFastAPIのパターンを注入するようにしていました。問題は、半分くらいの確率で入力を忘れてしまうことでした。入力を忘れるたびに、エージェントは適用してほしいパターンを見逃していました。解決策は、/fastapiを自動起動するスキルに移行することでした。

スキル：44の自動起動されるナレッジモジュール

スキルは、会話がスキルの説明文と一致すると自動的に起動します。コマンドを入力する必要はなく、コンテキストに基づいて関連する専門知識がシステムによって注入されます。³

---
description: FastAPI backend development patterns and conventions
---
# FastAPI Skill
When working on FastAPI endpoints, follow these patterns...

44のスキルの内訳は以下の通りです： - ドメイン知識（8個）：FastAPI、SwiftUI、HTMX/Alpine、データベース、テスト、デバッグ、アーキテクチャ、セキュリティ - ブログインフラ（7個）：blog-writer-core、blog-evaluator、citation-verifier、SEOプレイブック - フィロソフィー/品質（5個）：匠（Jiro）、No Shortcuts、Rubin essence、デザイン原則 - マルチエージェント（3個）：審議、レビュー、コンテンツ作成 - プロジェクト固有（4個）：個人サイトコンテンツ、ResumeGeniブログ、Obsidianキャプチャ

コンテキスト40%肥大化事件： 初期の頃、FastAPIパターンガイド全体（800行）をルールファイルに入れていました。ルールはすべてのセッションに読み込まれます。iOSアプリ、CSS、ブログコンテンツの作業をしているときに、800行もの無関係なFastAPIパターンがコンテキストトークンを消費していました。そのコンテンツを「FastAPI backend development」という説明文のスキルに移動することで問題が解決しました。スキルはAPI関連の作業時にのみ読み込まれるようになったのです。⁴

サブエージェント：隔離されたレビュアー

サブエージェントは独自のコンテキストウィンドウ内で動作し、制限されたツールアクセスと独立した権限を持ちます。⁵

サブエージェントには、security-reviewer（読み取り専用アクセス、OWASP脆弱性スキャン）、test-runner（テストの実行と失敗の分析）、conventions-reviewer（プロジェクト標準のチェック）などがあります。

隔離が重要な理由： コードレビュー中、レビュアーはファイルを編集できるべきではありません。スキルはレビューの知識を注入できますが、レビュー自体はフル書き込み権限を持つメインコンテキストで行われます。サブエージェントはアーキテクチャ的に読み取り専用アクセスを強制します。

ルール：11の常時有効な制約ファイル

ルールはすべての会話に自動的に読み込まれます。11のルールファイルの内容は以下の通りです：⁶

~/.claude/rules/
├── security.md        # Never commit secrets, parameterized queries
├── git-workflow.md    # Conventional commits, branch naming
├── corrections.md     # Always use Claude (not OpenAI), current date
├── quality-loop.md    # Quality review loop, pride check
├── api-design.md      # REST conventions, response format
├── testing.md         # pytest conventions, coverage targets
└── aio.md             # AI Overview optimization for web content

サイジングの教訓： ルールは11ファイルで合計約180行です。すべての行がすべてのセッションに読み込まれます。トピック固有のコンテンツをスキルに移行する前は、400行以上ありました。180行のルールセットは本物の不変条件（セキュリティ制約、gitワークフロー、修正事項）をカバーしています。それ以外はすべてスキルに属するべきものです。

判断フレームワーク

移行パターン

.claude/の構造は3つのフェーズを経て進化しました：

フェーズ1（1〜2ヶ月目）： すべてをルールに格納。400行以上が常時読み込まれるコンテキスト。iOSパターン、FastAPIパターン、デザインガイドライン、テスト標準。すべてのセッションでコンテキストが肥大化していました。

フェーズ2（3〜4ヶ月目）： トピック固有のコンテンツをスキルに移行。ルールは200行に減少。スキルは20以上のディレクトリに成長。コンテキストの肥大化が40%減少しました。

フェーズ3（5ヶ月目以降）： 隔離が必要なタスク（コードレビュー、セキュリティ監査）にサブエージェントを追加。コマンドは明示的なワークフロー用に85個で安定。ドメイン固有の専門知識を追加するにつれ、スキルは44個に成長しました。⁷

教訓：まずルールから始め（安価で常に利用可能）、トピック固有のものを発見したらスキルに移行し、隔離が必要な場合にのみサブエージェントを追加することです。

スキルによるサブエージェントの強化

強力なパターンがあります：skillsフロントマターフィールドを使って、スキルをサブエージェントのコンテキストに注入できます：

---
description: Code reviewer with security expertise
allowed-tools: [Read, Grep, Glob]
skills: [security, testing-philosophy]
---
Review code for quality, security, and test coverage...

securityとtesting-philosophyのスキルがサブエージェントのシステムプロンプトにコンテンツを注入します。レビュアーは隔離された読み取り専用コンテキスト内で、専門的な知識を得ることができます。⁸

レビューパイプラインではこのパターンを使用しています：3つのサブエージェント（correctness-reviewer、security-reviewer、conventions-reviewer）がそれぞれ異なるスキルの注入を受けます。correctness-reviewerはdebugging-philosophyを取得します。security-reviewerはセキュリティルールセットを取得します。conventions-reviewerはプロジェクトのコーディング標準を取得します。

本番アーキテクチャ

~/.claude/
├── commands/     # 85 — User-triggered workflows
│   ├── commit.md, review.md, deploy.md
│   ├── publish-check.md, deliberate.md
│   └── morning.md, analytics.md, plan.md
│
├── skills/       # 44 — Auto-invoked expertise
│   ├── fastapi/, swiftui/, htmx-alpine/
│   ├── blog-writer-core/, citation-verifier/
│   └── jiro/, no-shortcuts/, rubin-essence/
│
├── agents/       # Isolated task executors
│   ├── security-reviewer.md
│   ├── correctness-reviewer.md
│   └── conventions-reviewer.md
│
├── rules/        # 11 files, ~180 lines — Always-on constraints
│   ├── security.md, git-workflow.md
│   ├── corrections.md, quality-loop.md
│   └── api-design.md, testing.md, aio.md
│
└── hooks/        # 95 — Lifecycle event handlers
    ├── git-safety-guardian.sh
    ├── recursion-guard.sh
    └── blog-quality-gate.sh

重要なポイント

個人開発者向け： - まずプロジェクト固有の標準としてルールから始めましょう（合計200行以内に収めること） - 最もよく使う技術スタックにスキルを追加しましょう。自動起動により「呼び出し忘れ」の問題が解消されます - 最もよく使う3つのワークフローからコマンドを作成しましょう - ツール制限やコンテキスト隔離が必要な場合にのみサブエージェントを追加しましょう

チーム向け： - チーム全体の一貫性のため、プロジェクトレベルでルールを標準化しましょう - 共通リポジトリでスキルを共有しましょう。プロジェクト間でのスキルのポータビリティが、プロジェクトレベルの設定に対するスキルの主要な利点です

参照