Claude Codeを設計思想として読み解く

Claude Code を「使い方」ではなく
「どう作られているか」「なぜそう作られているか」という
設計思想の側から読み解くスライドです。
社内勉強会用に作成しました。

# 取り上げているテーマ

- Part 1. Claude Code はどう動いているか
(OS 的な土台, ターミナルへのマウント, プロンプト階層, 短期記憶の Skeptical Memory,
コンテキスト劣化と /compact, md に落とす作法, ツールアクセスのレバー,
確率的な LLM × 決定論的なツール, MCP, Bash/CLI 経由アクセス)
- Part 2. エージェントを加速する
(並行開発, 待ち時間とコストの最適化, サブエージェントによる粒度調整,
ヘッドレスモードでの部品化, 拡張機構の全体像)
- Part 3. 検証ループ
(Huang 2023「LLM は自己反省できない」, 外部信号があってこその反復改善,
explore → plan → code, hooks による自動化ループ, hooks から claude -p を呼ぶ)
- Part 4. エージェントを縛る
(なぜ縛る必要があるのか, 縛る道具を 4 レイヤー (モード / 指示 / 設定 / 隔離) で捉える,
揮発・お願いから永続・物理まで, evals による劣化の測定と段階的アプローチ)
- Part 5. まとめ
(押さえるべき 5 点)

Copilot 系 (補完の速度・正確性を最適化) との対比で、Claude Code が「長対話の中で
一貫した解決」を最適化しているという見立てを起点に組み立てています。

# こんな方向け

- Claude Code を「コマンド集」ではなく「設計判断の集合」として読み解きたい方
- Copilot 系との違いを、モチベーションを含めて言語化したい方
- LLM/エージェントを使うチームで、運用設計 (検証信号・縛る道具・evals) を考えたい方

Transcript

1. Claude Code を設計思想として読み解く C L A U D E C O D E G U I D E 使い方ではなく 「どう作られているか」 と 「なぜ」 を見る Mamoru Okamoto / @okmtx 2026/05/11 1 / 50
2. 今日のスタンス 手順 Tips ではなく、 設計思想を読み解く インストール手順や便利コマンドには踏み込まない 代わりに 「どう作られたか」 「なぜそうなったか」 を見る 設計思想が見えれば、 自分の現場で道具を組み立てられる 内容には公式情報と私の読み解きが混在する Anthropic の根本原則 2 つを各所で繰り返し参照 2 / 50
3. Claude Code はどう動いているか P a r t 1 3 / 50
4. OS 的な土台 Claude Code を支える OS 的構造を順に見る ターミナル / コード探索 / 短期記憶 / プロンプト階層という 4 つの土台。 それぞれ 「なぜそう設計した か」 が以降の話の前提になる。 4 / 50
5. Claude Code の最適化 「次の行を速く出す」 ではなく 「長い対話で一貫した解決」 を最適化 Copilot 系: 補完の速度・正確性を最適化 Claude Code: 長対話の中での一貫した問題解決を最適化 結果として指示の真意を読み、 トレードオフを能動提示する 命令的(手順指定)でなく宣言的(目的指定)な指示でも動く 「parse する AI」 ではなく 「understand しようとする AI」 PART 1 · CLAUDE CODE はどう動いているか 5 / 50
6. ターミナルとマウント Claude Code はターミナルセッションそのものに乗る デスクトップ版はクラウド sandbox 動作、 成果物はコピペが必要 Claude Code はローカル環境そのもので動く ファイルシステム / git / シェル / 認証情報がそのまま使える Boris Cherny: 「どんな UI も 6 ヶ月で陳腐化する」 ターミナルなら陳腐化しない、 という賭け PART 1 · CLAUDE CODE はどう動いているか 6 / 50
7. コード探索 ベクトル DB を持たず、 人間と同じ grep / glob / read で探索する (agentic search) 初期は RAG + ベクトル DB だったが、 agentic search に切り替えて性能向上 モデルが賢くなれば探索も賢くなる(6 ヶ月先のモデル原則) インデックス鮮度問題が原理的に起きない 構造的情報を文脈として活用できる 複雑な RAG よりシンプル(Do the simple thing first) PART 1 · CLAUDE CODE はどう動いているか 7 / 50
8. 短期記憶の利用 「記憶は当てにならない、 ヒント程度に扱え」 が組み込まれている 外部解釈では Skeptical Memory と呼ばれる CLAUDE.md や memory.md は 「ポインタ」 として扱われる 「ここに書いてあったはず」 を信じず毎回確認しに行く シニアエンジニアの 「念のため確認する」 作法が構造化 記憶への過信を捨てた設計が、 長対話の精度を支える PART 1 · CLAUDE CODE はどう動いているか 8 / 50
9. プロンプト階層 01 システムプロンプト 層 → 02 プロジェクト層 → 03 セッション層 → 04 実行時層 PART 1 · CLAUDE CODE はどう動いているか 9 / 50
10. セッションの仕組み 長時間使うための文脈設計を見る セッション独立 / 劣化前提 / 自動要約 / md 落としという 4 つの作法。 「コンテキストは劣化する」 とい う前提から逆算された設計群。 10 / 50
11. ディレクトリ単位のセッション管理 セッションはディレクトリ単位で独立、 文脈を混ぜない プロジェクト A の内容は B に影響しない 同じ単語でもプロジェクトごとに意味が違う(User、 deploy 等) 文脈を混ぜないことが精度に直結する --continue / --resume で再開可能 リモートオンリー版(claude.ai/code)もある PART 1 · CLAUDE CODE はどう動いているか 11 / 50
12. コンテキストは劣化する 文脈には 3 つの性質がある、 直感に反するのは 2 番目 有限 トークン上限がある 物理的な限界 劣化する 情報量が増えるほど精度が下がる 「念のため」 が逆効果 注意は有限 重要情報が埋もれる 量より配置が効く PART 1 · CLAUDE CODE はどう動いているか 12 / 50
13. /compact — 自動要約という選択肢 便利さと引き換えにコントロールを失う 履歴を Claude に自動要約させて文脈窓を圧縮 どう要約されたかが見えない(ブラックボックス) 量を調整できない、 何が捨てられたか分からない 自動の便利さと引き換えに透明性を失う だから次の 「md に落とす」 が生きてくる PART 1 · CLAUDE CODE はどう動いているか 13 / 50
14. md に落とすという作法 自動要約の弱点を、 手動の選別で埋める セッション終了時に 「決定事項を handoff.md に書き出して」 と依頼 次セッションで @handoff.md として明示的に読み込ませる --continue / /compact との違いは 「選別して引き継ぐ」 点 試行錯誤や脱線は捨て、 必要なものだけを残す 人間が読める形式で残るので可監査性も上がる PART 1 · CLAUDE CODE はどう動いているか 14 / 50
15. ツール Claude を世界に作用させる接点としてのツール LLM の構造的弱点(計算 / 検索 / 状態確認)をツール経由で外注する。 MCP と bash/CLI がアクセス経 路として並立する。 15 / 50
16. ツールアクセスがモデルサイズを超える 「大きさよりツール」 を実証した Toolformer (2023) Toolformer 論文 (Schick et al., 2023) の結果 6.7B モデル + ツールアクセス > 175B GPT-3 (ツールなし) 計算 / 検索 / 翻訳など特定タスクで逆転が起きた モデルサイズより 「外部接続」 が効く、 と分かった瞬間 エージェント時代の前提として広く参照されている PART 1 · CLAUDE CODE はどう動いているか 16 / 50
17. 確率的な LLM × 決定論的なツール Claude Code 理解の基本構図、 検証ループの土台 決定論的: bash / grep / テスト / lint / コンパイラ (再現可能) 確率的: LLM (同じ入力でも揺らぐ) Claude Code はこの 2 つを組み合わせる ループ: 確率的にツール選択 → 決定論的に世界に作用 結果を文脈に取り込み、 また確率的に判断する PART 1 · CLAUDE CODE はどう動いているか 17 / 50
18. MCP という拡張点 自分でツールを足せる、 ベンダーに縛られないエコシステム MCP (Model Context Protocol) で独自ツールを追加できる Claude Code 以外のクライアントとも互換 社内 DB、 独自 API、 Slack、 GitHub、 Linear なども接続可能 「対話する相手」 ではなく 「環境に接続するエージェント」 拡張点があることが MCP の本質 PART 1 · CLAUDE CODE はどう動いているか 18 / 50
19. Bash/CLI 経由アクセスという選択肢 MCP より速いが、 権限制御は MCP のほうが厚い bash で gh issue list のような CLI を直接叩く レスポンスが軽く、 コンテキストも節約できる 一方 MCP はサーバ単位で権限制御を挟める 速度・コンテキスト効率重視なら bash/CLI 権限制御重視なら MCP、 どちらが正解でもない PART 1 · CLAUDE CODE はどう動いているか 19 / 50
20. エージェントを加速する P a r t 2 20 / 50
21. 並行開発:複数セッションを並べる 人間が複数 Claude を監督するスタイル Git worktree で物理的に分離、 各 worktree で独立セッション セッションがディレクトリ単位なので設計が噛み合う Boris Cherny 本人は 5 タブ運用(機能 / テスト / レビュー / デバッグ / docs) iTerm2 通知で入力待ちに気づける 待ち時間を別 Claude で埋める PART 2 · エージェントを加速する 21 / 50
22. 待ち時間を減らす 待つ時間を減らすほど、 思考のフロー状態を維持できる Ctrl+B でフォアグラウンドを背景化、/bashes で並列管理 サーバ起動 / docker build / npm install 中も別作業を進める サブエージェントを背景で走らせる ヘッドレスモード( claude -p )を別プロセスで cron 実行 hooks で 「編集後 → 自動テスト → 失敗なら再注入」 を回す PART 2 · エージェントを加速する 22 / 50
23. コスト・効率の最適化 効率最適化の本質は 「何を Claude に渡さないか」 モデル使い分け メイン Opus、 サブ Sonnet 探索は Haiku まで下げる CLAUDE_CODE_SUBAGENT_MODEL で個別指定 コンテキスト節約 /compact や md 落としを活用 不要情報を入れない判断 失敗パターン回避 過剰並列化はトークンを焼く 「念のため全部読ませる」 は精度悪化 PART 2 · エージェントを加速する 23 / 50
24. 並列の粒度を上げる:サブエージェント 3 段階の並列粒度を整理する 前提:シングルセッションで足りるケースが大半 親と独立した文脈で子が動く(試行錯誤が親に混ざらない) worktree = プロジェクト単位 サブエージェント = タスク単位(基本) Agent Teams = ロール単位(実験機能) PART 2 · エージェントを加速する 24 / 50
25. エージェントを部品化する:ヘッドレスモード 「Claude Code を Unix ツールの一種として使える」 という視座 # ログから異常検知 tail -f app.log | claude -p "anomaly 検知" # CI に組み込み claude -p "Review this PR for security" --output-format json PART 2 · エージェントを加速する 25 / 50
26. 拡張機構の全体像 機構 呼び出し 文脈 配布 スラッシュコマンド 明示 ( /foo ) メインに合流 プラグインで可 スキル 自動 (Claude が選ぶ) メインに合流 プラグインで可 サブエージェント 自動 or 明示 独立コンテキスト プラグインで可 プラグイン 配布の単位 上記をまとめる 配布前提 PART 2 · エージェントを加速する 26 / 50
27. 検証ループ P a r t 3 27 / 50
28. 研究知見 「自己反省で賢くなる」 は 2023 年に否定されている LLM は自己訂正できないという論文と、 それでもエージェントが反復で賢くなる理由(外部検証信号) を順に見る。 28 / 50
29. LLM は自己反省できない、 という研究 Large Language Models Cannot Self-Correct Reasoning Yet — Huang et al. (2023) PART 3 · 検証ループ 29 / 50
30. Huang 2023 論文の主張 「自己反省で改善する」 の根拠は外部信号に依存していた 既存の self-correction 研究は暗に oracle (正解情報) を使っていた oracle なしの純粋な intrinsic self-correction は性能が改善しない むしろ自己批判で正解を間違いに書き換えるケースもある multi-agent debate も結局は self-consistency と等価 反省で賢くなるには 「正解の手掛かり」 が外側から要る PART 3 · 検証ループ 30 / 50
31. では、 なぜエージェントは反復で賢くなるのか 外部からのフィードバックがある時だけ反復が機能する CRITIC 論文の ablation:LLM 自己評価のみではほぼ効果なし ツール経由の検証では大幅な性能向上 「reflection に見えるものは、 よく見ると verification」 LLM には内的な 「正解検出器」 がない 検証は生成より易しい(Brown et al. 2024) PART 3 · 検証ループ 31 / 50
32. Claude Code での実装 研究知見を踏まえると Claude Code の設計が全部つながる 検証ツール群 / プランモード / hooks による検証ループの自動化、 それぞれが 「外部検証信号を LLM に与える」 ための実装になっている。 32 / 50
33. Claude Code の検証ツール群 LLM に自己検証ループを回させるための実装 テスト・lint 編集直後にテスト実行 結果を文脈に取り込む Claude in Chrome UI をスクショで確認 反復修正 Ralph Loop 完了条件を満たすまで反復 探索ループの自動化 PART 3 · 検証ループ 33 / 50
34. explore → plan → code 「すぐコーディングを始めない」 が検証ループの土台 LLM には 「指示を受けるとすぐ書き始める」 訓練バイアスがある 現状理解の前に解決策に飛びつき 「間違った問題」 を解く プランモードは書き込みツールを封じて探索を延長する装置 「理解 → 設計 → コード」 のフローを構造で再現する PART 3 · 検証ループ 34 / 50
35. 3 段階の役割分担と検証信号 検証信号がある領域でのみ反復改善が効く explore: Read で関連ファイル / テストを読み、 材料を集める plan: 集めた材料で計画を立て、 人間が合意するチェックポイント code: 計画通りに書き、 テスト / lint で外部検証を回す 検証信号がある領域 = エージェントが反復で改善できる 検証信号がない領域 = 反復しても改善は望めない PART 3 · 検証ループ 35 / 50
36. hooks で自動化ループを組み込む ライフサイクルイベントで決定論的に発火、 モデル判断より確実 { "hooks": { "PostToolUse": [{ "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "npm test" }] }] } } PART 3 · 検証ループ 36 / 50
37. hooks から claude -p を呼ぶ 反応的から先回り的への転換、 自動化の自動化 hooks の中で claude -p を呼ぶと、 エージェントがエージェントを呼ぶ PreToolUse で 「破壊的か?」 を別 Claude に判定させる(LLM ジャッジ) SessionStart で最近の PR を要約してコンテキスト注入 v2.1.118 から prompt 型 hook と agent 型 hook が追加 shell 経由せず LLM ジャッジを直接定義できる PART 3 · 検証ループ 37 / 50
38. エージェントを縛る P a r t 4 38 / 50
39. 制約を課す エージェントの限界と業務利用の論点をふまえて縛る コンテキスト長 / 計画崩壊 / 検証コスト非対称 / 確率的挙動という限界に対し、 最小権限・可逆性・人 間チェックポイント・自己懐疑指示で縛る。 39 / 50
40. なぜ縛る必要があるのか エージェントには物理的・原理的限界がある コンテキスト長:巨大リポを全読みすると詰む long-horizon での計画崩壊:20 ステップ先で目的を見失う 検証コストの非対称性:生成は速いが検証は人間が要る 確率的挙動:同じ入力で同じ出力が保証されない 業務利用ではログ・データ保持・監査可能性も問われる PART 4 · エージェントを縛る 40 / 50
41. 縛り方の指針 1. 最小権限の原則:必要最小限のツールだけ許可 2. 可逆性の原則:rm より mv to trash、 force より通常 push 3. 人間承認チェックポイント:PR マージ・本番デプロイ 4. 「自己懐疑させる」 指示:CLAUDE.md で確認手順を強制 5. 失敗を蓄積する作法:ミスのたびに CLAUDE.md に追記 PART 4 · エージェントを縛る 41 / 50
42. 縛る道具をレイヤーで捉える レイヤー 性質 代表例 モード層 揮発・即興 プランモード / Auto Mode 指示層 永続・お願い CLAUDE.md 設定層 永続・強制 settings.json / hooks 隔離層 永続・物理 sandbox / コンテナ PART 4 · エージェントを縛る 42 / 50
43. モード層と設定層 揮発・お願い vs 永続・強制、 状況に応じて使い分ける モード層: プランモード / Auto Mode の即興的な切替 Auto Mode は分類器がツール呼び出しを審査し危険なもののみ止める 設定層: settings.json の permissions と hooks による永続的な強制 PreToolUse で rm -rf や .env 書き込みを物理ブロック可能 攻めの hooks (自動化) と守りの hooks (制約) は同じ形で書ける PART 4 · エージェントを縛る 43 / 50
44. 劣化の測定 「Claude の調子が悪い気がする」 を測定可能にする evals(評価)で確率的出力の品質傾向を体系的に測る。 感想ベース運用の限界が見えてきたら段階的 に導入する。 44 / 50
45. 飛行盲目から測定ベースへ — evals プログラム的チェック テスト通過 / JSON 形式の自動検査 LLM-as-a-Judge 別の LLM に採点させる(人間と 80% 一致) end-to-end シナリオ エージェントを走らせ最終状態を見る 複数試行で安定化 1 回の結果は嘘をつくので 5 回走らせる PART 4 · エージェントを縛る 45 / 50
46. evals の段階的アプローチ 1. 失敗事例を集める(変な答えを md に記録) 2. プログラム的チェックを書く( claude -p + テストで CI 連携) 3. LLM judge を書く(ルーブリックで採点) 4. 複数試行で安定化(1 回の結果は信用しない) 5. CI gate として組み込む PART 4 · エージェントを縛る 46 / 50
47. まとめ P a r t 5 47 / 50
48. 押さえるべき 5 点 1. 確率的 × 決定論的: LLM とツールの組み合わせが基本構図 2. コンテキストは劣化する: 文脈設計が精度に直結する 3. 自己反省は効かない: 外部検証信号だけが反復を機能させる 4. 賢さを枠で囲う: 攻めの hooks / 守りの hooks は同じ形 5. 縛りはレイヤー化: モード / 指示 / 設定 / 隔離を使い分ける 48 / 50
49. 最後に 必要な時に思い出してもらえればいい 最初から全部組まなくていい。 必要になれば対応すればよい。 ただ、 これらの概念を知っているほうが動きやすい。 マルチエージェント協調 / 長期計画維持 / コンテキスト圧縮の品質保証など、 未解決の領域もまだ多い。 Claude Code は完成形ではなく進化中のシステムで、 バランスよく付き合うのが大事。 PART 5 · まとめ 49 / 50
50. ご質問をどうぞ Q&A PART 5 · まとめ 50 / 50