Claude Code の5段階を実運用で辿り直す — 足踏みしたのは Level 3 と Level 5 でした

同じ指示を、その週だけで3回打ち直していました。「表は HTML タグで書いてください」「日本語版と英語版は必ずセットで」「push の前にチェックスクリプトを通してください」。

3回目を打ち込んでいる途中で、手が止まりました。悪いのは Claude ではありません。同じことを毎回伝えている私の使い方が、どこかで頭打ちになっているのです。

Claude Code の習熟は、Raw Prompting → CLAUDE.md → Skills → Hooks → Orchestration の5段階で語られることが多いと思います。個人開発でアプリと4つのサイトを並行して回しながら、この5段階を実際に辿り直してみました。

分かったのは、段差の高さが均等ではないということでした。低い段差は一晩で越えられます。高い段差は、数ヶ月足踏みしました。

Level 1・2: プロンプトから CLAUDE.md へ — 最初の段差は低い

Level 1 の Raw Prompting は、立ち上げてプロンプトを打つだけの使い方です。ワンショットの修正や、動くかどうかを確かめたいだけの検証なら、これで十分に足ります。無理に上の段へ行く必要はありません。

頭打ちのサインは分かりやすいものでした。同じ前提を毎回説明している。これに気づいたら Level 2 です。

Level 2 は、プロジェクトルートに CLAUDE.md を置いて、前提と判断基準を書き留める段階です。ここでひとつ、私が誤解していたことがあります。

「CLAUDE.md は200行まで」という話を見かけることがあります。実際に運用してみると、明確な行数の壁があるわけではありませんでした。私のワークスペースの CLAUDE.md は、一時 113KB まで膨らんでいます。それでも読み込みはされます。

問題は別のところにありました。長くなるほど、末尾に書いたルールが守られにくくなる のです。上限に当たって止まるのではなく、じわじわ薄まっていく。この滲み方が厄介でした。

対処はシンプルでした。過去の経緯や診断の記録を別ファイルへ退避し、いま効いているルールだけを残して 31KB まで削ります。行数を守るためではなく、注意を薄めないために削る。そう捉え直してから、指示の通りが安定しました。

# プロジェクト概要
Next.js 16 (App Router) + TypeScript + Cloudflare Workers
 
## 判断に迷ったときの基準
1. 記事は必ず日本語版と英語版をセットで作る（片方だけだと言語切替で404）
2. 表は HTML の <table> で書く（remark-gfm 未導入のため | 記法は本番で崩れる）
3. リポジトリへの push は作業用ディレクトリへ clone してから行う
 
## やってはいけないこと
- 存在しない記事への内部リンク
- コード例に API キーの実フォーマットを書く（YOUR_API_KEY を使う）

書く内容を「手順」ではなく「判断基準」に寄せるのがコツでした。手順を書き始めると、CLAUDE.md はすぐに肥大します。

Level 3: Skills — 「トークン消費ゼロ」ではありません

ここが1つ目の段差でした。数ヶ月、足踏みしています。

スキルの解説で「同じスキルを何度使ってもトークン消費はゼロ」と書かれているのを見たことがあります。私も最初はそう理解していました。実際には違いました。

スキルは、呼び出された時点で SKILL.md の中身がコンテキストに読み込まれます。ゼロなのは「毎回同じ手順を人間が打ち込む手間」であって、トークンではありません。ここを取り違えると、スキルを増やせば増やすほど軽くなるはずだ、という誤った期待を持つことになります。

この理解が実務に効いてくるのは、description の書き方でした。私が最初に書いた description は「記事を更新する」の一行です。これでは発火しませんでした。何を指示すれば呼ばれるのか、Claude が判断する材料がないからです。

---
name: claudelab-content-update
description: |
  Claude Lab の記事を新規作成・更新するときに使う。
  「記事を書いて」「更新して」「push して」と言われた場合、
  および日英セット作成・品質チェック・ログ記録が必要な場合に必ず使用する。
---
 
1. リポジトリ準備 — 作業用ディレクトリへ clone する（ワークスペース内のリポジトリは直接触らない）
2. 日本語版を作成 — content/articles/ja/{category}/{slug}.mdx
3. 英語版を作成 — content/articles/en/{category}/{slug}.mdx（直訳ではなく英語圏の読者に自然な文体で）
4. 件数の一致を確認 — find content/articles/ja -name "*.mdx" | wc -l と en 側が一致すること
5. チェックスクリプトを通す — 1件でも違反があれば push しない

発火条件を description に書き切ることと、本文を番号付きの Step にすること。この2点を直しただけで、スキルが実際に使われるようになりました。

そして、私が Level 2 から Level 3 へ抜けられなかった理由もここで分かりました。「ルール」と「手順」を CLAUDE.md に混ぜて書いていたから です。判断基準は CLAUDE.md へ、順番のある作業は SKILL.md へ。この線引きをしてから、両方が短くなりました。

Level 4: Hooks — 自動化の前に「止める仕組み」を置く

Hooks は、コマンド実行の前後・ファイル変更時・プロンプト受信時といったライフサイクルの節目に、自分の処理を差し込む仕組みです。.claude/settings.json で設定します。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "$HOME/bin/guard-dangerous-command.sh" }
        ]
      }
    ]
  }
}

危険なコマンドをブロックする、コミット前に自動でリントを流す、といった使い方ができます。

ただ、私自身は品質チェックを Hooks には寄せていません。独立したスクリプトとして持ち、push の前に必ず通す形にしています。

理由は、失敗したときの読みやすさでした。Hooks に寄せると自動で止まってくれる代わりに、「どのチェックが、どのファイルの、何を理由に落ちたか」が手元に残りにくかったのです。私はこの一点を重く見て、明示的に呼ぶスクリプトを選びました。自動で止まる安心より、後から読める記録のほうが、結局は直す速度に効いています。

python3 _scripts/article_gate.py <ja.mdx> <en.mdx>       # 内容の密度
python3 _scripts/templating_gate.py <repo> --check ...   # 他記事との逐語重複
python3 _scripts/frontmatter_integrity.py <repo>         # YAML の壊れ
python3 _scripts/redirect_integrity.py <repo>            # リダイレクトの矛盾

全部が exit 0 を返してから、別のコマンドで push する。Hooks で自動化するか、スクリプトで明示的に呼ぶか。どちらが正解ということではなく、失敗したときに何が残ってほしいか で選ぶものだと考えています。

Level 5: Orchestration — Dynamic Workflows で段差が下がった

2つ目の段差がここでした。並列にすること自体は難しくありません。難しいのは、並列にした後に何が起きたか分からなくなることです。

2026年7月、Claude Code の Dynamic Workflows が一般提供になりました。Claude 自身が作業を計画し、1セッションの中で数百の並列サブエージェントを走らせ、報告の前に出力を検証する仕組みです。CLI・デスクトップ・VS Code 拡張に加えて、API 経由でも使えます（Dynamic Workflows の紹介 — Anthropic 公式ブログ）。

起動の仕方は2通りあります。Claude に直接依頼して組み立ててもらうか、Claude Code 固有の ultracode 設定（effort メニューから有効化）で effort を xhigh に上げ、ワークフローを使うかどうかを Claude 自身に判断させるか。/config の Dynamic workflow size で small / medium / large を選べば、エージェント数の目安も指定できます。

以前は、この段へ上がるには自分でエージェントを分割し、役割を決め、同期を設計する必要がありました。いまは Claude 側が計画と検証まで引き受けてくれます。段差は確実に下がりました。

レベル	頭打ちのサイン	次の一手
Level 1: Raw Prompting	同じ前提を毎回説明している	CLAUDE.md に判断基準を書く
Level 2: CLAUDE.md	手順まで書いて肥大している	順番のある作業を SKILL.md へ切り出す
Level 3: Skills	スキルが呼ばれない／使われない	description に発火条件を書き切る
Level 4: Hooks	同じミスを人力で見つけている	検証を先に用意する（Hooks かスクリプトかは記録の要否で選ぶ）
Level 5: Orchestration	直列で待ち時間が長い	Dynamic Workflows に計画と検証を任せる

それでも、私が Level 4 から Level 5 へ抜けられなかった理由は、道具の側にはありませんでした。失敗の記録が残る形を先に作っていなかったから です。1本ずつ順番に流していれば、どこで転んだかは見れば分かります。並列にした瞬間、それが分からなくなりました。

ゲートとログを先に用意し、それから並列化する。順番を逆にしただけで、抜けられました。個人開発では、転んだことを教えてくれる同僚がいません。記録の設計を先に置くかどうかが、そのまま速度差になりました。

次の一歩をどう選ぶか

5段階を順番に上がる必要はない、というのが辿り直してみての実感です。いま使っているやり方で天井を感じたときが、次へ進む合図でした。

同じ前提を毎回説明しているなら、CLAUDE.md を1枚書く。詳しい設計は「CLAUDE.md の設計で Claude Code の出力が安定する — 階層構造・サブエージェント・外部メモリの実践」に整理しています
CLAUDE.md が肥大しているなら、手順を SKILL.md へ切り出す。description に発火条件を書き切る
同じミスを人力で見つけているなら、検証スクリプトを1本書く。権限まわりの設計は「Claude Code のツール権限を自分好みに設定する：安全性と開発効率を両立させる」が参考になります
待ち時間が長いなら、Dynamic Workflows を試す。Hooks と並列運用の詳細は「Claude Code 実践マスター — Hooks・Orchestration・並列エージェント運用の極意」へ

今日できることを1つ挙げるなら、いま開いているプロジェクトの CLAUDE.md に「やってはいけないこと」を3行だけ書き足すことをおすすめします。判断基準は、増やすより減らすほうが効きました。

私自身、5段階を綺麗に上がったわけではありません。2箇所で長く足踏みして、道具のせいだと思い込んで、実際は自分の置き方の問題だった、というだけの話です。同じところで止まっている方の遠回りが少しでも短くなれば嬉しく思います。お読みいただきありがとうございました。