Claude Code 60+スキルの設計哲学 — Opus/Sonnet使い分けとパイプライン設計の実践知

Claude Code 60+スキルの設計哲 学 Opus/Sonnet使い分けとパイプライン設計の実践知 takish

60+スキルを破綻させない5つの設計原則 • 1. モデル選択は「判断」vs「実行」で分ける • 2. allowed-tools で安全境界を作る • 3. パイプラインは明示的に繋ぐ • 4. ルーティングテーブルで迷わせない • 5. コンテキストサイズは用途で決める

スキルが増えると起きる問題 • 「とりあえずOpus」がコストとレイテンシを膨張させる • Opusが本当に必要な場面は全体の20〜30%程度 • 責務の重複がツール制限の甘さを生む • レビューを依頼→AIがコードを直接修正してしまう事故 • スキル間の境界が曖昧 → 予期しない副作用

原則1: モデル選択は「判断」vs「実行」で分ける • 判断ミスのコストが高い場面だけ Opus を使う • 設計判断を間違えると後の実装がすべてやり直し • コミットやブランチ作成は間違えてもすぐ修正できる • コストの非対称性を基準にモデルを選ぶ

Opus = "Should we?" Sonnet = "How to?" ┌──────────────────────────────────────┐ │ リクエスト受信 │ └──────────┬───────────────────────────┘ │ ┌─────▼─────┐ │ 判断が必要？│ └──┬────┬───┘ Yes │ │ No ┌─────▼┐ ┌▼──────┐ │ Opus │ │Sonnet │ │Should│ │How to?│ │ we? │ │ │ └──────┘ └───────┘

Opus を使う場面（判断・設計） • /plan — アーキテクチャ設計 • /code-review — コードレビュー • /gate — 品質ゲート判定 • /agent-split — 大きな Issue の分解 • /agent-lead — PR レビュー & マージ判定

Sonnet を使う場面（実行・実装） • /engineer — コード実装 • /debugger — バグ切り分け・修正 • /commit — コミット • /create-pr — PR 作成 • /chrome, /agent-browser — ブラウザ操作

5カテゴリ65スキルの分類マップ カテゴリ スキル数 主要モデル 代表スキル 設計・判断系 12 Opus plan, code-review, arch-review 実行・実装系 10 Sonnet engineer, debugger, chrome コンテンツ系 6 Sonnet seo, aieo, imagenprompt チーム 1 Opus team ワークフロー 19 混在 kickoff, ship, gate, issue-work Private 13 混在 （非公開） その他 4 — quick-impl, split-issue 等

エスカレーションルール • Sonnet 実行中に設計判断が必要になるケースがある • ルール: 迷ったら /plan（Opus）への切り替えを提案 • AIに判断を委ねず、適切なモデルに切り替える • 発生頻度は月に数回程度 • 誤検知があっても手戻りよりトータルコストは低い

原則2: allowed-tools で安全境界を作る • allowed-tools = スキルが使えるツールを制限するフロントマター • 省略すると全ツールが承認ベースで使用可能 • 明示指定すると承認なしで使用可能（トレードオフ） • 利便性のためにガードレールを外す行為 • 必要最小限のツールだけを指定する

ツール制限の4パターン パターン 許可ツール 用途 例 レビュー系 全ツール（プロンプト 制御） 分析・指摘のみ code-review 実装系 全ツール（承認フロ ー） コード読み書き+実 行 engineer ワークフロー系 Bash + Read git操作・読み取り commit コンテンツ系 Read + Write ファイル読み書きのみ note-draft

「レビューがコードを変更する」事故防止 • プロンプト制御なしだと AIが「親切に」コードを修正してしまう • レビュー = 問題発見 + 改善案提示。修正判断は人間の責務 • プロンプト制御はソフトな制約（コンテキスト長で遵守率低下あり） • 理想は allowed-tools のハード制約との併用 • スキルの責務 = 何をすべきか + 何をしてはいけないか

レビュー系スキルの設定例 --name: code-review model: claude-opus-4-6[1m] # allowed-tools 省略 = 全ツール使用可能（承認ベース） # プロンプトで行動を制御: # 「分析・指摘のみ行い、コードを変更しない」 ----name: commit model: claude-sonnet-4-6 allowed-tools: Bash, Read, Glob, Grep # Edit/Write がないのでコード変更不可 ---

原則3: パイプラインは明示的に繋ぐ • スキルは単体より連携（パイプライン）で真価を発揮 • ただし連携を暗黙にしてはいけない • 12のワークフローチェーンを明示的に定義 • 各スキル完了時に「次のステップ」を提案できる • 「次に何をすべきか」を定義することが目的

代表的なワークフローチェーン ■ 新機能開発: /kickoff → /engineer → /gate → /ship ■ バグ修正: /debugger → /engineer → /gate → /ship ■ 設計からの実装: /plan → /kickoff → /engineer → /code-review → /ship ■ @claude 自律パイプライン: /agent-split → /agent-impl → /agent-lead ■ Issue 駆動（単発自動）: /issue-work（解析→実装→検証→PR を1スキルで完結）

gate — 並列オーケストレーションの設計 ┌──────────────┐ │ /gate (Opus)│ │ オーケストレーター │ └──────┬───────┘ ┌──────┬──────┼──────┬──────┐ ▼ コード ▼ TS解析 品質 ▼ 重複 ▼ 設計 検出 ▼ シークレット 原則 検出 (Sonnet) (Sonnet)(Sonnet)(Sonnet)(Sonnet) └──────┴──────┼──────┴──────┘ ┌──────▼───────┐ │ Go / No-Go │ └──────────────┘

原則4: ルーティングテーブルで迷わせない • 65個のスキルを全部覚えるのは非現実的 • CLAUDE.md に 33行のインテント→スキル対応表を定義 • 自然言語で意図を伝えるだけで適切なスキルが提案される • 「機能を実装したい」→ /engineer が候補に挙がる • スキル名を知らなくても使える仕組み

CLAUDE.md に書くべき3つのメタ情報 • ルーティングテーブル — どのスキルをいつ使うか • ワークフローチェーン — スキルの連携パターン • エスカレーションルール — モデル切り替えの条件 • すべて「スキル横断的な情報」→ 常に参照可能な場所に置く • スキル本体には「何をするか」だけ。「いつ使うか」はCLAUDE.md

原則5: コンテキストサイズは用途で決める • ほとんどのスキルは標準コンテキストで十分 • 1M が必要なのはコードベース全体を俯瞰する場面のみ • 判断基準:「複数ファイルを横断的に読む必要があるか？」 • Yes → 1M、No → 標準 • デフォルトは軽量、必要なときだけリッチに

標準 vs 1M コンテキストの使い分け コンテキスト スキル例 理由 標準 /ask, /commit, /kickoff 局所的な情報で処理が完結 標準 /create-pr, /imagenprompt コードベース全体の知識は不 要 1M /plan, /code-review 設計パターンとの整合性判断 1M /engineer, /issue-work 複数箇所を横断的に参照 1M /agent-split 大きなIssue全体の構造を 把握

まとめ: 5つの設計原則 • 1. モデル選択は「判断」vs「実行」で分ける • 2. allowed-tools で安全境界を作る • 3. パイプラインは明示的に繋ぐ • 4. ルーティングテーブルで迷わせない • 5. コンテキストサイズは用途で決める

まず3つから始めよう • 65個を最初から作る必要はない • /engineer（実装）— コードを書く • /commit（コミット）— 変更を記録する • /code-review（レビュー）— 品質を守る • この3つだけで日常の開発ワークフローは大きく改善 • 必要を感じたときに5原則に沿って追加していく

Thank you! https://zenn.dev/takish/articles/skill-philosophy https://zenn.dev/takish/articles/skill-philosophy @takish

• https://zenn.dev/takish/articles/skill-philosophy