--- title: Claude Code 60+スキルの設計哲学 — Opus/Sonnet使い分けとパイプライン設計の実践知 tags: author: [takish](https://image.docswell.com/user/takish) site: [Docswell](https://www.docswell.com/) thumbnail: https://bcdn.docswell.com/page/YE9PW6ZPJ3.jpg?width=480 description: Claude Code 60+スキルの設計哲学 — Opus/Sonnet使い分けとパイプライン設計の実践知 by takish published: March 24, 26 canonical: https://image.docswell.com/s/takish/5E1NQ7-2026-03-24-144148 --- # Page. 1 ![Page Image](https://bcdn.docswell.com/page/YE9PW6ZPJ3.jpg) Claude Code 60+スキルの設計哲 学 Opus/Sonnet使い分けとパイプライン設計の実践知 takish # Page. 2 ![Page Image](https://bcdn.docswell.com/page/GE8DNZ1XED.jpg) 60+スキルを破綻させない5つの設計原則 • 1. モデル選択は「判断」vs「実行」で分ける • 2. allowed-tools で安全境界を作る • 3. パイプラインは明示的に繋ぐ • 4. ルーティングテーブルで迷わせない • 5. コンテキストサイズは用途で決める # Page. 3 ![Page Image](https://bcdn.docswell.com/page/LELMPDQN7R.jpg) スキルが増えると起きる問題 • 「とりあえずOpus」がコストとレイテンシを膨張させる • Opusが本当に必要な場面は全体の20〜30%程度 • 責務の重複がツール制限の甘さを生む • レビューを依頼→AIがコードを直接修正してしまう事故 • スキル間の境界が曖昧 → 予期しない副作用 # Page. 4 ![Page Image](https://bcdn.docswell.com/page/4JMY4P1QJW.jpg) 原則1: モデル選択は「判断」vs「実行」で分ける • 判断ミスのコストが高い場面だけ Opus を使う • 設計判断を間違えると後の実装がすべてやり直し • コミットやブランチ作成は間違えてもすぐ修正できる • コストの非対称性を基準にモデルを選ぶ # Page. 5 ![Page Image](https://bcdn.docswell.com/page/PJR9W1LK79.jpg) Opus = "Should we?" Sonnet = "How to?" ┌──────────────────────────────────────┐ │ リクエスト受信 │ └──────────┬───────────────────────────┘ │ ┌─────▼─────┐ │ 判断が必要？│ └──┬────┬───┘ Yes │ │ No ┌─────▼┐ ┌▼──────┐ │ Opus │ │Sonnet │ │Should│ │How to?│ │ we? │ │ │ └──────┘ └───────┘ # Page. 6 ![Page Image](https://bcdn.docswell.com/page/PEXQPYW5JX.jpg) Opus を使う場面（判断・設計） • /plan — アーキテクチャ設計 • /code-review — コードレビュー • /gate — 品質ゲート判定 • /agent-split — 大きな Issue の分解 • /agent-lead — PR レビュー & マージ判定 # Page. 7 ![Page Image](https://bcdn.docswell.com/page/3EK9D3VRED.jpg) Sonnet を使う場面（実行・実装） • /engineer — コード実装 • /debugger — バグ切り分け・修正 • /commit — コミット • /create-pr — PR 作成 • /chrome, /agent-browser — ブラウザ操作 # Page. 8 ![Page Image](https://bcdn.docswell.com/page/L73WRGMG75.jpg) 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 等 # Page. 9 ![Page Image](https://bcdn.docswell.com/page/87DKY16NJG.jpg) エスカレーションルール • Sonnet 実行中に設計判断が必要になるケースがある • ルール: 迷ったら /plan（Opus）への切り替えを提案 • AIに判断を委ねず、適切なモデルに切り替える • 発生頻度は月に数回程度 • 誤検知があっても手戻りよりトータルコストは低い # Page. 10 ![Page Image](https://bcdn.docswell.com/page/VJPK6QYNE8.jpg) 原則2: allowed-tools で安全境界を作る • allowed-tools = スキルが使えるツールを制限するフロントマター • 省略すると全ツールが承認ベースで使用可能 • 明示指定すると承認なしで使用可能（トレードオフ） • 利便性のためにガードレールを外す行為 • 必要最小限のツールだけを指定する # Page. 11 ![Page Image](https://bcdn.docswell.com/page/2EVV35GYEQ.jpg) ツール制限の4パターン パターン 許可ツール 用途 例 レビュー系 全ツール（プロンプト 制御） 分析・指摘のみ code-review 実装系 全ツール（承認フロ ー） コード読み書き+実 行 engineer ワークフロー系 Bash + Read git操作・読み取り commit コンテンツ系 Read + Write ファイル読み書きのみ note-draft # Page. 12 ![Page Image](https://bcdn.docswell.com/page/57GL368WEL.jpg) 「レビューがコードを変更する」事故防止 • プロンプト制御なしだと AIが「親切に」コードを修正してしまう • レビュー = 問題発見 + 改善案提示。修正判断は人間の責務 • プロンプト制御はソフトな制約（コンテキスト長で遵守率低下あり） • 理想は allowed-tools のハード制約との併用 • スキルの責務 = 何をすべきか + 何をしてはいけないか # Page. 13 ![Page Image](https://bcdn.docswell.com/page/4EQY549QJP.jpg) レビュー系スキルの設定例 --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 がないのでコード変更不可 --- # Page. 14 ![Page Image](https://bcdn.docswell.com/page/KJ4W9QXY71.jpg) 原則3: パイプラインは明示的に繋ぐ • スキルは単体より連携（パイプライン）で真価を発揮 • ただし連携を暗黙にしてはいけない • 12のワークフローチェーンを明示的に定義 • 各スキル完了時に「次のステップ」を提案できる • 「次に何をすべきか」を定義することが目的 # Page. 15 ![Page Image](https://bcdn.docswell.com/page/LE1YKPNN7G.jpg) 代表的なワークフローチェーン ■ 新機能開発: /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スキルで完結） # Page. 16 ![Page Image](https://bcdn.docswell.com/page/GEWGDVMMJ2.jpg) gate — 並列オーケストレーションの設計 ┌──────────────┐ │ /gate (Opus)│ │ オーケストレーター │ └──────┬───────┘ ┌──────┬──────┼──────┬──────┐ ▼ コード ▼ TS解析 品質 ▼ 重複 ▼ 設計 検出 ▼ シークレット 原則 検出 (Sonnet) (Sonnet)(Sonnet)(Sonnet)(Sonnet) └──────┴──────┼──────┴──────┘ ┌──────▼───────┐ │ Go / No-Go │ └──────────────┘ # Page. 17 ![Page Image](https://bcdn.docswell.com/page/47ZLG4QMJ3.jpg) 原則4: ルーティングテーブルで迷わせない • 65個のスキルを全部覚えるのは非現実的 • CLAUDE.md に 33行のインテント→スキル対応表を定義 • 自然言語で意図を伝えるだけで適切なスキルが提案される • 「機能を実装したい」→ /engineer が候補に挙がる • スキル名を知らなくても使える仕組み # Page. 18 ![Page Image](https://bcdn.docswell.com/page/YJ6WY365JV.jpg) CLAUDE.md に書くべき3つのメタ情報 • ルーティングテーブル — どのスキルをいつ使うか • ワークフローチェーン — スキルの連携パターン • エスカレーションルール — モデル切り替えの条件 • すべて「スキル横断的な情報」→ 常に参照可能な場所に置く • スキル本体には「何をするか」だけ。「いつ使うか」はCLAUDE.md # Page. 19 ![Page Image](https://bcdn.docswell.com/page/GJ5MGL6GJ4.jpg) 原則5: コンテキストサイズは用途で決める • ほとんどのスキルは標準コンテキストで十分 • 1M が必要なのはコードベース全体を俯瞰する場面のみ • 判断基準:「複数ファイルを横断的に読む必要があるか？」 • Yes → 1M、No → 標準 • デフォルトは軽量、必要なときだけリッチに # Page. 20 ![Page Image](https://bcdn.docswell.com/page/LE3WRLQPE5.jpg) 標準 vs 1M コンテキストの使い分け コンテキスト スキル例 理由 標準 /ask, /commit, /kickoff 局所的な情報で処理が完結 標準 /create-pr, /imagenprompt コードベース全体の知識は不 要 1M /plan, /code-review 設計パターンとの整合性判断 1M /engineer, /issue-work 複数箇所を横断的に参照 1M /agent-split 大きなIssue全体の構造を 把握 # Page. 21 ![Page Image](https://bcdn.docswell.com/page/8EDKYN937G.jpg) まとめ: 5つの設計原則 • 1. モデル選択は「判断」vs「実行」で分ける • 2. allowed-tools で安全境界を作る • 3. パイプラインは明示的に繋ぐ • 4. ルーティングテーブルで迷わせない • 5. コンテキストサイズは用途で決める # Page. 22 ![Page Image](https://bcdn.docswell.com/page/V7PK65ZPJ8.jpg) まず3つから始めよう • 65個を最初から作る必要はない • /engineer（実装）— コードを書く • /commit（コミット）— 変更を記録する • /code-review（レビュー）— 品質を守る • この3つだけで日常の開発ワークフローは大きく改善 • 必要を感じたときに5原則に沿って追加していく # Page. 23 ![Page Image](https://bcdn.docswell.com/page/2JVV3PWVJQ.jpg) Thank you! https://zenn.dev/takish/articles/skill-philosophy https://zenn.dev/takish/articles/skill-philosophy @takish