Lv5 Claude Code マスター

前提: L1 修了（L2 推奨）。L2〜L4 と並行受講可（前提グラフ上の分岐）。 対応: CCA（Claude Certified Architect – Foundations の略。同日ローンチの非技術者向け新資格「Claude Certified Associate – Foundations」とは別物）ドメイン③／力量マップ B（Claude Code 運用）。

このレベルのゴール

Claude Code を「チャット付きエディタ」ではなく 設定可能なエージェント基盤 として運用する: (1) ワークフローとコンテキスト管理の日常運用化、(2) CLAUDE.md・permissions・コマンド・Skills・Subagents・Hooks・MCP の使い分け、(3) 危険操作を hooks と権限設定で 決定的に 防ぐこと。

主参照教材

• 全文日本語ガイド: Claude Code 101／Claude Code in Action／Introduction to Agent Skills／Introduction to Subagents
• 動画（ずんだもん×四国めたん解説）: 各モジュールの「読む」に埋め込み（5.1・5.4・5.5・5.6）

演習の型（DESIGN.md 共通）: ①ベースライン→②設計・実装→③敵対テスト→④測定→⑤言語化。提出物は最低4点（実装／テスト・evalデータ／実行結果／設計判断メモ）。足場は 5.1〜5.3 が手順付き、5.4〜5.6 が要件のみ、5.7〜5.8 が障害シナリオ。演習は 自分の実リポジトリ（またはキャップストーン）で行う。

5.1 基本操作とワークフロー（Explore→Plan→Code→Commit）

学ぶこと

• agentic loop の5ステップ（プロンプト→コンテキスト収集→行動→検証→完了/再試行）。ループ中いつでも介入できる
• 権限3モード（承認制／Auto-accept＝編集のみ自動／Plan Mode＝read-only）と Shift+Tab 切替
• Explore→Plan→Code→Commit: コードが書かれる前が最も軌道修正しやすい。成功基準の明示・テストスイート・ツール追加で往復を減らす
• Plan Mode（幅優先: 広い理解・複数ステップ）と extended thinking（深さ優先: 難ロジック・バグ調査）。併用可・トークンコストあり

読む

▍

• Claude Code 101 §2・§4・§5／Claude Code in Action「Making changes」

やる（手順付き）

1. ベースライン: 中規模の機能追加を 計画なしで 依頼し、軌道修正回数・過剰実装を記録
2. 設計・実装: 同種タスクを Plan Mode で開始→計画の穴を指摘→承認→実装。成功基準を計画に明記させる
3. 敵対テスト: 曖昧なプロンプトと大きすぎるタスクを Plan Mode に投げ、計画の破綻箇所を観察
4. 測定: 両アプローチの軌道修正回数・所要時間・/context 消費を比較
5. 言語化: 「Plan Mode／thinking／どちらも不使用」の条件判断表を書く

自己チェック

5.2 コンテキスト管理

学ぶこと

• context window は有限の作業記憶。上限接近で自動 compaction が走り、細部が失われうる
• /compact（要約して続行）／/clear（完全リセット）／/context（消費内訳）: 同じ作業の続き=compact、無関係な新タスク=clear
• Escape（中断）・Escape 2回（履歴巻き戻し）・#（CLAUDE.md へ追記）・@（ファイルメンション）
• 節約: 具体的な指示（曖昧さは探索コストで跳ね返る）・未使用 MCP サーバの無効化・結果だけ欲しいタスクの subagent 委譲

次の図で、context window に何が積まれ、/compact・/clear がそれぞれどこに効くかを掴む。

読む

• Claude Code 101 §6／Claude Code in Action「Adding context」「Controlling context」

やる（手順付き）

1. ベースライン: 長めのセッションで節目ごとに /context のカテゴリ別消費を記録
2. 設計・実装: テストを1関数ずつ書かせ、(a) 汚れた履歴の Escape×2 巻き戻し、(b) 完了時 /compact、(c) 別機能へ移るとき /clear+CLAUDE.md 追記、を使い分ける
3. 敵対テスト: compaction が自動発火するまで続け、圧縮後に「さっきの決定事項」を質問して情報喪失を確認
4. 測定: 巻き戻し・compact・clear 後の消費と遂行品質を記録
5. 言語化: 「場面 × 打ち手」対応表を書く

自己チェック

5.3 CLAUDE.md 設計と権限・設定

学ぶこと

• CLAUDE.md は毎セッション自動読み込みの「オンボーディング用スクリプト」。Project / Commands / Code Style などのセクション例
• 階層: プロジェクト（コミットして共有）／CLAUDE.local.md（個人）／ユーザー（全プロジェクト横断）。/init で生成、# で追記、@パス で要ドキュメントを参照
• 小さく始める: まず無しで運用し、頻繁な軌道修正が起きた箇所だけ書く。常時読み込み＝肥大化はコンテキスト税
• settings の階層（ユーザーレベル ~/.claude/settings.json／共有 .claude/settings.json／個人 settings.local.json。ユーザーレベルは公式 docs 由来の層で、教材が明示するのは共有と個人の2つ）と permissions。permissions は allow／ask／deny の3配列に Tool(specifier) 形式で記述し、評価順は deny → ask → allow（deny はどの層の allow でも上書きできない）。許可は必要最小限に — 自由度を上げるほど間違いに気づけなくなる

次の図で、ツールの実行要求が deny → ask → allow の順に照合され、deny が最優先で効く流れを掴む。

読む

• Claude Code 101 §8／Claude Code in Action「Adding context」／Agent Skills ガイド §4（CLAUDE.md vs Skills）

やる（手順付き）

1. ベースライン: CLAUDE.md の無いリポジトリで数タスクこなし、繰り返した説明・軌道修正を列挙
2. 設計・実装: /init で生成→スタック・コマンド・規約・@ 参照だけの最小構成に編集
3. 敵対テスト: わざと無関係な長文を足し、/context 占有と応答品質の劣化を確認してから削る
4. 測定: 導入前後で同種タスクの軌道修正回数と /context 占有を比較
5. 言語化: 「CLAUDE.md／skills／settings」の振り分け基準をメモにする

自己チェック

5.4 カスタムコマンド

学ぶこと

• .claude/commands/<name>.md を作るとファイル名がそのまま /name になる。作成・変更後の反映は教材収録時点では再起動が必要とされていた（現行はライブ検出されることが多い。「反映されないときの確認項目の一つ」と捉える）
• $ARGUMENTS プレースホルダで引数（任意文字列）を受け取れる
• スラッシュコマンドは「明示的に呼んだときだけ」。常時オンの CLAUDE.md、自動マッチの Skills との三段構え

読む

▍

• Claude Code in Action「Custom commands」／Agent Skills ガイド §1（三者比較）

やる（要件のみ・5段階）

1. ベースライン: 繰り返し手打ちしている定型指示を2つ選び、手打ちでの所要やり取り回数と起きたミス（貼り忘れ・表記揺れ）を記録
2. 設計・実装: そこから引数なし1つ・$ARGUMENTS 付き1つのコマンドを作る
3. 敵対テスト: 引数なし実行・意図しない引数で破綻を確認し、指示文を頑健化
4. 測定: 手打ち時（ベースライン）とコマンド化後で、目的達成までのやり取り回数を比較
5. 言語化: 「skill にしなかった理由」（明示起動で十分／自動発火が不要）をメモに書く

自己チェック

5.5 Skills

学ぶこと

• skill ＝ SKILL.md を持つフォルダ。frontmatter は name・description（教材では必須と説明）と、allowed-tools・model など

  ⚠️ 現行仕様注記（2026-07-11確認）: frontmatter 項目は現行仕様ではすべて任意（name・description は推奨——description が無いと後述の意味的マッチングが機能しない）。また allowed-tools は「使えるツールの制限」ではなく「事前承認」: 列挙したツールを承認プロンプトなしで使えるようにする項目で、列挙外のツールも通常の permissions 設定に従って使用できる。ツールを制限したいなら permissions の deny（5.3）や sandbox で行う。

• ロード: 起動時は name と description のみ がコンテキストに常駐 → Claude が関連性を判断（または利用者が /name で直接呼び出す）→ 自動的に本文がフルロードされる（ユーザー承認の必須ステップはない）。このオンデマンド性が CLAUDE.md との決定的な違い
• description がすべて: 「何をするか」＋「いつ使うか」＋ユーザーが実際に使いそうな言い回し。起動しない原因はほぼ description
• 優先順位: Enterprise ＞ Personal（~/.claude/skills）＞ Project（.claude/skills）。Plugin 由来の skill は plugin-name:skill-name という名前空間で管理され、他レベルと衝突しない別枠の扱い（単純に「最下位」として同じ優先順位チェーンに並ぶわけではない）。共有はコミット／プラグイン配布／managed settings
• progressive disclosure: SKILL.md は必須指示のみ（500行未満目安）、詳細は scripts/・references/・assets/ へ。スクリプトは「読ませる」でなく「実行させる」

読む

• Agent Skills 全文ガイド §1〜6（主教材）／Claude Code 101 §10

やる（要件のみ・5段階）

1. ベースライン: skill 化する予定の「同じ説明」を手で与えて課題を1件こなし、説明の手間（やり取り回数・貼り付けたテキスト量）を記録
2. 設計・実装: その事項を skill 化。references/ を持つ複数ファイル構成とし、頻用ツールを allowed-tools で事前承認する（ツールの制限が要件なら permissions の deny で実現し、allowed-tools との違いを設計判断メモに書く——上の現行仕様注記）
3. 敵対テスト: (1) description に無い言い回し5種で発火テスト、(2) 似た description の競合 skill をわざと作って誤発火を再現→書き分けて解消
4. 測定: 言い回し別の発火率を before/after で記録
5. 言語化: CLAUDE.md でもコマンドでもなく skill にした根拠（頻度・自動性・コンテキスト税）

自己チェック

5.6 Subagents

学ぶこと

• subagent は 独立した context window で作業し、メインには サマリだけ 返す。メインを汚さない代わりに途中経過の可視性を失う
• 組み込みは General purpose／Explore／Plan（注: 組み込み subagent の名称は教材間で不一致——Subagents コースは General purpose / Explore / Plan、Agent Skills コース §5 は Explorer / Plan / Verify と紹介。実環境の名称は /agents で確認する）。実体は .claude/agents/<name>.md（name / description / tools / model / color ＋本文＝システムプロンプト）

  ⚠️ 現行仕様注記（2026-07-11確認）: /agents は教材収録時点の対話式作成ウィザードとしてはもはや機能せず（Claude Code v2.1.198以降）、実行しても「Claudeに依頼するか .claude/agents/ を直接編集するように」というリマインダーが出るだけになった。カスタム subagent の作成は、Claude に依頼するか .claude/agents/<name>.md を直接編集して行う。ファイル構造と frontmatter フィールドの説明自体は現行も正しい。

• 設計4本柱: 具体的な description（起動タイミングと親が書く入力プロンプトを左右）／出力フォーマット定義（最重要・自然な終了点を作る）／障害の報告（Obstacles 欄）／ツールアクセス制限
• 判断基準は「途中経過の作業がメインスレッドに重要か」。重要でない→委譲、重要→手元。アンチパターンは「専門家」ペルソナだけの指示／前段依存の逐次パイプライン（バグ修正はほぼ常にこれ）／出力全体を隠すテストランナー（実測で最低成績）
• skills は subagent に 自動継承されない。カスタム subagent の frontmatter に skills: で明示列挙（組み込みは不可）

次の図で、subagent が独立した context window で作業し、メインにはサマリだけが返る（途中経過は見えない）構図を掴む。

読む

上の図で見た通り、subagent は独立した context window を持つ。この対話でその意味を掘り下げる。

• Subagents 全文ガイド §1〜4（主教材）／Claude Code 101 §7・§9

やる（要件のみ・5段階）

1. ベースライン: subagent なしの同一スレッドでセルフレビューを1回行い、指摘の質とメインコンテキストの消費を記録
2. 設計・実装: レビュー用 subagent を作る: read-only＋git diff 用 Bash のみ、出力フォーマット（Summary・重大度別 Issues・Recommendations・Obstacles）を本文に定義
3. 敵対テスト: (1) ベースラインのセルフレビューと同じ diff を subagent に渡して指摘の質を比較、(2) description を曖昧化して親の指示の劣化を観察→「対象ファイルを正確に伝えること」を足して回復
4. 測定: 指摘数・重大度分布・メインコンテキストの消費差を記録
5. 言語化: 「subagent に出すタスク／出さないタスク」を判断基準つきでリスト化

自己チェック

5.7 Hooks

学ぶこと

• hooks は 決定的（deterministic）: CLAUDE.md の指示は「たいてい」実行されるが、hook は必ず実行される。「必ず毎回」が要件ならプロンプトでなく hook
• イベント: PreToolUse／PostToolUse／UserPromptSubmit／Stop／Notification。設定は /hooks か settings、matcher は Edit|MultiEdit|Write のようにパイプ区切り
• hook コマンドは stdin から tool call の JSON（ツール名・入力）を受け取る。終了コード: 0=許可／2=ブロック（stderr が Claude へのフィードバック）／その他=非ブロックのエラー表示。終了コード2によるブロックは PreToolUse だけでなく、Stop・SubagentStop・UserPromptSubmit など多くのイベントで可能
• 実用例: 編集後の自動フォーマット・型チェック結果のフィードバック・危険操作（rm -rf 等）のブロック・秘密ファイル読み取りの防止
• 注意: Read だけでなく Grep もファイル内容を読める。CLAUDE_PROJECT_DIR でプロジェクト内スクリプトを参照。設定ファイルへの直接編集はファイルウォッチャーが自動検出し、再起動なしで現在のセッションに即座に反映される。重い hook は対象ディレクトリを絞る

読む

• Claude Code 101 §12／Claude Code in Action「Introducing hooks」〜「Useful hooks!」（.env 読み取りブロック・型チェック・重複クエリレビューの実装例）
• safety-security.md のミニ演習 S-3（.env 読み取りを hook で塞ぎ、Bash 経由の迂回を deny ルールで塞ぎ直す）と相互参照。本節の演習はその実装版

やる（障害シナリオ・5段階: 「秘密情報ファイルがあり、過去に本番設定を書き換えかけた」リポジトリを守る）

1. ベースライン: hook なしで CLAUDE.md の禁止指示だけを置き、.env 読み取りや危険コマンドをわざと依頼して「プロンプト指示は確率的にしか効かない」ことを記録
2. 設計・実装: PreToolUse hook を2本実装: (1) 秘密ファイル（.env 等）の読み取りブロック（matcher は Read と Grep の両方）、(2) 危険 Bash コマンド（rm -rf 等）のブロック。いずれも exit 2＋stderr で理由を返す
3. 敵対テスト: 自分で回避経路を攻める — Bash 経由の cat .env、相対パス・別表記、Grep での内容検索 — すり抜けたら matcher と判定を強化
4. 測定: 攻撃パターンごとのブロック成功率と、正当な操作の誤ブロック率を表にする
5. 言語化: 「hook で強制すべきもの／CLAUDE.md の指示で足りるもの」の線引きを、ベースラインとの差を根拠に書く

自己チェック

5.8 MCP 連携と GitHub 連携

学ぶこと

• 追加は claude mcp add（ターミナル側）。接続方式は主に HTTP（リモート）と Stdio（ローカル）の2つだが、SSE（非推奨だが現存）・WebSocket も含めると計4種。管理はセッション内 /mcp
• スコープ3種: Local（自分×このプロジェクト）／User（自分×全プロジェクト）／Project（.mcp.json をコミットしてチームに配布）
• コンテキストコスト: MCP サーバは未使用でもツール定義を context window に載せる。未使用は無効化、CLI 同等品（gh 等）があれば CLI が効率的。現行のデフォルトでは閾値に関わらず常に MCP ツールが遅延ロードされる（tool search mode は既定で ON）。コンテキストの10%を閾値にした自動切替は ENABLE_TOOL_SEARCH=auto を明示指定した場合のみの挙動。許可の省略は settings.local.json の allow に mcp__<server名>（アンダースコア2つ）
• GitHub 連携: /install-github-app → アプリインストール → API キー → 自動 PR で、2つの GitHub Actions（@claude メンション対応／PR 自動レビュー）が入る。Actions 内では許可する権限を個別にすべて列挙（MCP のツールもワイルドカード不可）

読む

• Claude Code 101 §11／Claude Code in Action「MCP servers with Claude Code」「Github integration」

やる（障害シナリオ・5段階: 「MCP サーバを足し続けてセッションが重くなった」チームを立て直す）

1. ベースライン: MCP サーバ接続前の /context 内訳を記録（比較の基準値）
2. 設計・実装: キャップストーンで L4 に作った自作 MCP サーバを Claude Code に接続し（L4 未修了なら Playwright 等で代替）、実タスクで使う
3. 敵対テスト: ツール数の多いサーバを複数有効にして /context で占有を観察 → 各サーバを「無効化／CLI 代替／skill 化／Project スコープ配布」のどれにするか決めて実行
4. 測定: 整理前後の MCP 定義の占有率と遂行への影響を、ベースラインと合わせて記録
5. 言語化: 「MCP で足す／CLI で済ます／skill にする」の選択基準（永続的なツール定義のコスト vs 能力）

自己チェック

注: Claude Code SDK（現 Claude Agent SDK）は L6 で扱う

Claude Code in Action 最終盤の「The Claude Code SDK」（プログラムからの起動・デフォルト read-only・options.allowedTools）は L6「エージェント設計と本番運用」の設計パートで扱う。CLI 運用（本レベル）と SDK 開発は別領域のため、workflows / agents の設計論とセットで学ぶ。

キャップストーン増分（第6形態）: プロジェクトを Claude Code で保守できる状態にする

ここまでに育てた「ドキュメント調査アシスタント」のリポジトリ（受講時点の最新形態でよい——L5 は L1 の直後から受講できるため、第1形態しか無くても成立する）を、他人（と将来の自分）が Claude Code で安全に保守できる状態 に整備する。

連鎖規則（L5 を早期受講した場合）: Claude Code 設定は受講時点の最新形態に適用する。その後 L2〜L4 の増分（eval ハーネス・tool・RAG・MCP 化）をリポジトリに加えたら、そのたびに CLAUDE.md・hook・skill を再適用・再評価する（例: eval 実行コマンドを CLAUDE.md/コマンドへ追記、MCP サーバ追加後に /context 占有を再確認、秘密情報ファイルの増加に合わせて hook の対象を拡張）。差分レビューで足り、L5 ゲートの再受験は不要。

次の4点を 各1つ以上:

提出物は共通4点: 実装（.claude/ 一式）／テスト・evalデータ（hook の攻撃パターン表・skill の発火テスト）／実行結果（新セッションで第三者想定タスクを完遂したログ）／設計判断メモ（振り分け根拠）。

修了ゲート

共通構成（README.md 参照）: 知識確認 20%／実技成果物 60%／設計判断の説明 20%、総合 80% 以上。実技は第6形態を5観点ルーブリック（機能/堅牢性/安全性/評価/説明 × 0〜3）で採点。知識確認は類題2〜3種、修了1〜2週間後に遅延チェック（不合格モジュールは復習キューへ）。

実技ルーブリック（5観点 × 0〜3点）

安全必須問題（配点と独立に全問正解が必要・詳細は safety-security.md）:

1. hooks による危険コマンドのブロック: PreToolUse＋exit 2＋stderr の設計と、PostToolUse や exit 1 では防げない理由。Read だけでなく Grep・Bash 経由の読み取り経路まで塞げること
2. permissions の最小化: allow 全許可の危険性と、「個別 allow＋hook の決定的ブロック＋settings の共有/個人の層別」による最小権限の構成。allow／ask／deny の評価順（deny → ask → allow、deny は上書き不能）を含めて説明できること
3. 秘密情報ファイル（.env 等）を読み取りから保護する複数経路の対策

部分合格方式: 不合格項目のみ補習して再受験する（合格済み項目は保持。共通運用は README.md 参照）。

• 力量マップ対応: B. Claude Code 運用。数値更新は本レベルの提出物を証拠にリンク
• CCA 副線: ドメイン③（Claude Code、比率目安 ~20%）。修了後に cca-prep.md の該当ドリルで再診断
• 最終確認日: 2026-07-11（製品仕様依存の記述は Academy 教材 2026-07 時点の内容に基づく）