メインコンテンツへスキップ
見出し画像

Claude Codeでコードレビュー1回が38,000→2,800トークンに減った話|Subagent7個を捨ててSkillsに移した

    はじめに

    Claude Codeには「Subagent」と「Skills」という2種類の拡張機構がある。どちらもタスクを効率化するための仕組みだが、使い分けを間違えると、トークン消費が一桁変わる。

    結論を先に言う。繰り返し走る軽めのタスクは、迷わずSkillsにする。 これだけで、1回あたりのトークンも待ち時間もまったく別物になる。この記事では、私がSubagentを7個作って後悔した過程と、Skillsに置き換えてどこがどう変わったかを、数字と一緒にまとめる。

    Subagentを7個作って後悔した

    Claude Codeを触り始めた頃、私は「メインのコンテキストを汚したくない」という強迫観念に取り憑かれていた。
    コードレビュー、コミットメッセージのチェック、コーディング規約の検証、ドキュメント整形、思いついた軽作業を片っ端からSubagentに切り出せば、メイン会話がきれいに保てるはずだ、と。

    結果、Subagentは7個になった。

    しばらく動かしてようやく気づいた。
    Subagentは呼び出すたびに「ゼロから新しいClaudeが一人立ち上がる」構造をしている。
    起動のたびにフルのシステムプロンプトとツール定義を読み込むので、タスク本体が軽くても、毎回数万トークンのオーバーヘッドが固定で乗る。
    メインを汚さないために払っていた代償が、そのままトークン明細として返ってきていた。

    決定打になったのは @adriano_viana さんのXポストだった。
    コードレビューをSubagentからSkillに移行した実測値がそのまま投稿されていて、私とまったく同じ失敗をしていたことがわかった。

    コードレビュー1回あたり 38,000 → 2,800 トークン(約93%削減) 、
    処理時間 3分40秒 → 22秒 。

    1回あたりの削減幅がこの大きさだと、1日に何回も回すワークフローでは効き方が桁で違ってくる。
    コードレビューは典型的に「毎コミット回したい」タスクなので、ここが10倍効率化するだけでセッション全体の体感が変わる。

    SubagentとSkillsは何が違うのか

    両者の違いを1枚の表に整理する。

    比較項目SubagentSkillsコンテキスト完全隔離(独立)メイン会話と共有hline起動コスト高い(毎回ゼロから)低い(オンデマンド注入)トークン効率低い高い(93%削減の事例あり)並行処理可能(複数同時実行)不可(逐次)コンテキスト汚染なし設計次第でほぼなし\small\def\arraystretch{1.5} \begin{array}{|l|c|c|}\hline \textbf{\textsf{比較項目}} & \textbf{\textsf{Subagent}} & \textbf{\textsf{Skills}} \\ \hline\textsf{コンテキスト} & \textsf{完全隔離(独立)} & \textsf{メイン会話と共有} \\hline\textsf{起動コスト} & \textsf{高い(毎回ゼロから)} & \textsf{低い(オンデマンド注入)} \\ \hline\textsf{トークン効率} & \textsf{低い} & \textsf{高い(93\%削減の事例あり)} \\ \hline\textsf{並行処理} & \textsf{可能(複数同時実行)} & \textsf{不可(逐次)} \\ \hline\textsf{コンテキスト汚染} & \textsf{なし} & \textsf{設計次第でほぼなし} \\ \hline\end{array}

    Skillsの決定的な強みは「Progressive Disclosure(段階的開示)」という仕組みにある。
    セッション開始時に読み込まれるのはSkillの名前と1〜2行の説明文だけ、合計でせいぜい100トークン前後。
    実際にそのSkillに合致するタスクが来たときに初めて本体が展開される。
    使わないSkillは、存在していてもコンテキストを一切消費しない。
    10個登録していようが20個登録していようが、待機コストはほぼゼロだ。

    対してSubagentは、起動するたびに独立したコンテキストウィンドウを新しく持つ。
    完全隔離できる代わりに、毎回のセットアップ費が固定でかかる。軽い仕事を毎回このコストで回すのは、正直、車で100m先のコンビニに行くような無駄がある。

    どう使い分けるか

    判断基準はシンプルにしていい。

    Skillsに寄せるべきもの

    • コードレビュー

    • コミットメッセージやPR本文のチェック

    • コーディング規約の検証

    • ドキュメント整形・リネーム・テンプレ適用

    要するに、繰り返し走る / 軽い / メイン会話の文脈がそのまま使えるタスクはぜんぶSkillsでいい。

    Subagentのまま残すべきもの

    • 大規模リサーチを複数方向で同時並行に走らせたいとき

    • 本番コードに影響を与えずにプロトタイプを検証したいとき

    • タスク同士が互いに影響してほしくないとき

    並列実行の能力と「完全隔離」が本当に効く場面でのみ、Subagentのコストを払う価値がある。

    迷ったときの自問はこれ1つで足りる。

    「このタスク、メインの会話履歴を見てもらった方が精度が上がるか?」

    Yesなら Skills。Noなら Subagent。

    Subagentを1つだけSkillに置き換えてみる

    理屈より、置き換えの手触りを先に体験したほうが早い。
    いま使っているSubagentのうち、いちばん頻繁に呼んでいる軽作業を1つだけ選ぶ。コードレビュー係が定番だ。

    Skillsは
    "~/.claude/skills/<skill-name>/SKILL.md"
    を置くだけで登録できる。初めて書いたときは「これだけでいいのか」と拍子抜けした。中身はこれくらい短い。

    ---
    name: code-review-lite
    description: |
      軽量なコードレビューSkill。
      直前の差分(git diff)に対して、命名・例外処理・テスト漏れを
      3観点でざっとチェックする。
      「レビューして」「diffをチェックして」でトリガー。
    ---
    
    # Code Review (Lite)
    
    直前の差分に対して、以下の3観点でチェックする。
    
    1. 命名: 変数・関数名が意図を表しているか
    2. 例外処理: エラー経路が握り潰されていないか
    3. テスト: 変更に対応するテストが存在するか
    
    指摘は最大5件まで。重要度順に並べる。

    ポイントは `description` の書き方だ。
    Claude Codeは`name`と`description`だけを常時ロードしていて、ユーザーの発話を見て「このSkillを開くかどうか」を判断する。
    だから description には、トリガーになりそうな語(この例なら「レビュー」「diff」「チェック」)を必ず含めておく。
    ここを雑にすると、呼ばれずに終わるか、逆に呼ばれすぎて鬱陶しいSkillになる。

    これでSkillは動く。以降、私は同種のSubagentを削除した。
    注意点として、移行したらSubagent側の定義は消しておく。
    残したままだとルーティングが迷い、結局Subagentが呼ばれてトークンが元に戻ることがある。

    まとめ

    Skillsをデフォルトにして、Subagentは本当に必要なときだけ使う。

    これが、Subagent7個を作って撤退した私の結論だ。
    Subagentの「完全隔離」は響きは良いが、繰り返しタスクに使うとトークンがそのまま溶ける。
    Skillsの Progressive Disclosure を活かせば、10個以上登録しても、呼ばれない限り待機コストはほぼ発生しない。

    まずは、いまSubagentに任せている中から「コードレビュー」や「規約チェック」のような軽いものを1つだけ選んで、Skillに置き換えてみてほしい。ステータスラインのトークン使用量表示が、次の1回からはっきり変わる。

    この記事が役に立ったら、スキを押してもらえると励みになる。

    生成AIツールの使いこなしや失敗談は、Xでもリアルタイムで投げている。Claude CodeだけでなくCursor・Gemini CLI など最新のAIコーディング環境についてもつぶやいているので、よければフォローしてほしい。 → https://x.com/horizon_IT00

    自己紹介記事はこちら:

    Claude について体系的にまとめた記事はこちら:

    参考文献

    本記事で引用した数値と概念は、以下に基づいている。

    • @adriano_viana さんのXポスト — コードレビュー 38,000 → 2,800 トークン(約93%削減)、処理時間 3分40秒 → 22秒の実測値

    • Claude Code 公式ドキュメント — Agent Skills(Progressive Disclosure の仕組み)

    • Claude Code 公式ドキュメント — Subagents(独立コンテキストと並列実行)

     
     
    経歴:宇宙学→機械学習→生成AI(現在)→起業(未来) 実績:Signateグランドマスター / 総合7位。 「再現性ある成果を出し続けるエンジニア」になるための 実践知を発信しています。 特に生成AIツールの活用・AI実装を発信しています。

    あなたへのおすすめ