COURSE 01 · Harness Engineering
Claude Code の内部アーキテクチャ
AnthropicのCLIエージェントClaude Codeを、共通の軸(ループと権限・コンテキストとセッション・ツールと拡張・実行環境・サブエージェント)で内部から見る。公式ドキュメントで確認した機能を中立に整理する。
これは詳細編「各ハーネスの中身」のレッスンです。ハーネスの一般論は入口のハーネスとは何かから読めます。ここからは、実在するハーネスを1つずつ内部から見ます。最初はClaude Codeです。
このレッスンの見方
Claude Codeは、Anthropicのコマンドライン型のコーディングエージェントです。ここでは使い方ではなく、中で何が起きているかを5つの軸で見ます。ループと権限、コンテキストとセッション、ツールと拡張、実行環境、サブエージェント。以降のCodex・Cursor・Devinも同じ軸で見るので、横に並べて比べられます。記述は調査時点(2026年11月)に公式ドキュメントで確認した範囲です。
1. エージェントループと権限ゲート
中心は、ほかのハーネスと同じエージェントループです。考える、ツールで動く、結果を見る、を繰り返します。Claude Codeの個性は、ツールを実行する直前に権限ゲートを必ず通すことです。
公式ドキュメントによると、各アクションは固定の順序で判定されます。
- 拒否ルール(Deny):どのモードでも、
bypassPermissionsでもブロックする最優先 - 確認ルール(Ask):モードに関わらずプロンプトを出す
- 許可ルール(Allow):事前承認する
- 権限モードの既定:モードごとに自動承認の範囲が決まる
- 分類器レビュー(autoモード時):残りを安全性でチェックする
- 重要パス保護:
rm・rmdirの危険な削除をブロックする
拒否が最優先、という並びが設計の芯です。モデルの出力やプロンプトでこの順序を動かせません。
権限モードは複数あります(調査時点)。
| モード | 設定値 | プロンプトなしで動くもの |
|---|---|---|
| Manual | default |
読み取りのみ |
| Accept Edits | acceptEdits |
読み取りと、作業ディレクトリ内の編集・基本的なファイル操作 |
| Plan | plan |
読み取りと、auto時は分類器が通したコマンド。変更は承認まで保留 |
| Auto | auto |
ブロック対象以外。背景で安全チェック |
| Don't Ask | dontAsk |
事前承認したものだけ。プロンプトになるものは拒否 |
| Bypass Permissions | bypassPermissions |
すべて。安全チェックなし。隔離環境専用 |
autoモードでは、別の分類器モデルがアクションを安全性でふるい分けます。ローカルの編集や依存のインストールは通し、curl | bash・本番デプロイ・強制pushなどは既定で止めます。PreToolUse フックを使えば、実行の直前に割り込んで allow・deny・ask を差し込めます。ガードが何層にもなっている、ということです。
2. コンテキストとセッション
モデルに渡すコンテキストを、Claude Codeは複数の源から組み立てます。CLAUDE.md(プロジェクトやユーザーの決まりごと)、読み込んだファイル、ツールの結果、会話の履歴です。長くなると /compact で要約して窓を空けます。コンテキスト設計そのものは、別の詳細編レッスンで扱います(順次公開)。
セッションはローカルに永続保存され、/clear で現在の文脈を切り離し、/resume で読み直して再構築します。ここはこのコースの会話履歴の保存・Clear・Resumeの内部構造で詳しく見たとおりです。
3. ツールと拡張
Claude Codeには、ファイルの読み書き・検索・シェル実行・Web取得などの組み込みツールがあります。その上に、外から能力を足す口が大きく4つあります。
- MCP(Model Context Protocol):外部のツールやデータ源を、標準のやり方でつなぐ
- プラグイン:コマンドや設定をまとめて配布・導入する
- スキル:特定の作業手順を、必要なときに読み込ませる
- フック(Hooks):ツール実行の前後などに、自分の処理を差し込む
拡張の口が複数ある点が、Claude Codeの設計の個性です。ガード(権限)と拡張(4つの口)の両方が厚い、と言えます。
4. 実行環境とサンドボックス
Claude Codeは、実行の範囲を既定で絞ります。作業ディレクトリの外や、.git・各種設定ファイルといった保護パスへの書き込みは、自動承認されず確認に回ります。rm・rmdir の危険な対象は、許可ルールでも抑制できません。実行環境の一般論は実行環境とサンドボックスの基本で扱っています。
5. サブエージェント
重い脇作業を本筋の会話から切り離すために、サブエージェントを使えます。公式ドキュメントによると、サブエージェントは自分のコンテキスト窓で動き、独自のシステムプロンプト・使えるツール・権限・モデルを持ちます。本筋の会話履歴や、すでに読んだファイルは見えません。終わると要約だけを返します。isolation: worktree を付ければ、専用のgit worktreeで動かせます。
これは、コンテキストを汚さずに探索や検証を並行させる仕組みです。メタハーネスで複数のハーネスを束ねる話とは層が違います。こちらは、ひとつのハーネスの中の分業です。
まとめ:Claude Codeの重心
Claude Codeは、エージェントループの周りに厚いガード(拒否優先の権限判定・分類器・保護パス)と、複数の拡張の口(MCP・プラグイン・スキル・フック)を備え、サブエージェントで作業を分けます。どれが優れているという話ではありません。これがClaude Codeの重心で、次に見るCodexは、同じ軸でも重心が違います。
次に読む
同じ軸で、Codex・Cursor・Devinの内部も順に見ていきます(順次公開)。概観の比較はハーネス比較に、複数を束ねる話はMeta-Harnessコースにあります。