ai-docs

How Claude Code works

Properties1
tagsclaude-code, agents, context, tools, permissions, sessions

原典: How Claude Code works ／ 日本語版

一行要約

Claude Code の正体は「推論するモデル」と「行動するツール」を gather context → take action → verify results のループで回す agentic harness であり、ユーザー自身もそのループの一部としていつでも割り込めるように設計されている。

要点

agentic loop

タスクを与えられた Claude は3つのフェーズを回す。この3つは明確に分かれておらず、混ざり合う。

  1. gather context（文脈を集める）
  2. take action（行動する）
  3. verify results（結果を検証する）

The loop adapts to what you ask.

このループは、あなたが何を頼むかに応じて形を変える。

  • コードベースへの質問なら context gathering だけで終わることもある
  • バグ修正は3フェーズを繰り返し回る
  • リファクタは検証に多くを費やす

Claude は前ステップで学んだことに基づいて次に何が要るかを決め、数十のアクションを連鎖させながら軌道修正する。

You’re part of this loop too.

あなた自身も、このループの一部である。

ユーザーはいつでも割り込んで方向を変えたり、追加の文脈を与えたりできる。

Claude Code is the layer around the model that provides the tools and manages the context the model sees. This surrounding layer is what the term agentic harness refers to.

Claude Code は、モデルを包む層であり、ツールを提供し、モデルが見る context を管理する。agentic harness という言葉が指すのは、この包む層である。

ループを動かすのは2つの部品 —— 推論するモデルと行動するツール。モデルは /model か claude --model <name> で切り替える（原典は、たいていのコーディングは Sonnet、複雑な設計判断には推論の強い Opus としている）。

組み込みツールの5分類

分類Claude ができること
File operationsファイルを読む、コードを編集する、新規作成する、リネーム・再構成する
Searchパターンでファイルを探す、正規表現で内容を検索する、コードベースを探索する
Executionシェルコマンドを実行する、サーバを起動する、テストを走らせる、git を使う
Webweb 検索、ドキュメント取得、エラーメッセージの調査
Code intelligence編集後の型エラー・警告の表示、定義へのジャンプ、参照検索（code intelligence プラグインが必要）

これに加えて subagent の起動、ユーザーへの質問などのオーケストレーション用ツールがある。

「fix the failing tests」と言われたときの実際の流れの例:

  1. テストスイートを実行して何が落ちているか見る
  2. エラー出力を読む
  3. 関係するソースファイルを検索する
  4. それらを読んでコードを理解する
  5. 編集して修正する
  6. 再度テストを走らせて検証する

Claude がアクセスできるもの

claude をディレクトリで起動した時点で得られるもの。

  • プロジェクト — カレントディレクトリとサブディレクトリのファイル。許可すればそれ以外も
  • ターミナル — 自分が打てるコマンドはすべて
  • git の状態 — 現在のブランチ、未コミットの変更、最近のコミット履歴
  • CLAUDE.md —— 他のコーディングエージェント向けの AGENTS.md があれば、それ単独でも CLAUDE.md と並べても読める
  • auto memory — MEMORY.md の先頭 200行または 25KB のうち先に達したほうが毎セッション冒頭にロードされる
  • 設定した拡張 — MCP server、skills、subagents、Claude in Chrome

Because Claude sees your whole project, it can work across it.

Claude はプロジェクト全体を見ているので、その全体にまたがって作業できる。

現在のファイルしか見ないインライン補完型のアシスタントとの決定的な違いがここにある。

実行環境とインターフェース

環境コードが動く場所用途
Local自分のマシン既定。ファイル・ツール・環境へのフルアクセス
CloudAnthropic 管理の VM、または組織が運用する self-hosted 環境作業のオフロード、手元にないリポジトリでの作業
Remote Control自分のマシン（ブラウザから操作）実行とファイルはローカルのまま web UI を使う

インターフェース（ターミナル / デスクトップアプリ / IDE 拡張 / claude.ai/code / Remote Control / Slack / CI/CD）が変わっても、下層の agentic loop は同一。

セッション

  • 会話は ~/.claude/projects/ 配下のプレーンテキスト JSONL としてローカルに保存される。これが rewind / resume / fork を可能にしている
  • コード変更の前に、影響を受けるファイルのスナップショットを取る
  • セッションは互いに独立。新しいセッションは毎回まっさらな context window から始まる
操作挙動
claude --continue / claude --resume同じ session ID で開き直し、既存の会話に追記する
--fork-session / /branch履歴を新しい session ID にコピーする。元は変わらない

ブランチを切り替えると Claude が見るファイルは変わるが、会話履歴はそのまま残る。セッションはディレクトリに紐づくので、git worktree を使えば並列セッションを走らせられる。

context window

context window が保持するもの: 会話履歴、ファイル内容、コマンド出力、CLAUDE.md、auto memory、ロード済み skill、システム指示。

context が埋まったときの挙動（順序が重要）:

  1. まず古いツール出力を捨てる
  2. 必要なら会話を要約する

ユーザーのリクエストと主要なコード片は保持されるが、会話の早い段階で出した詳細な指示は失われうる。

Put persistent rules in CLAUDE.md rather than relying on conversation history.

恒久的なルールは、会話履歴に頼らず CLAUDE.md に置け。

  • compaction で何を残すかは、CLAUDE.md に “Compact Instructions” セクションを置くか、/compact focus on the API changes のように焦点を指定して制御する
  • 単一のファイルやツール出力が巨大すぎて、要約直後に context が再び埋まる場合、Claude Code は数回で自動 compaction をやめてエラーを出す（無限ループを避けるため）
  • MCP のツール定義は既定で遅延ロードされ、Claude が特定のツールを使うまでは、ツール名とサーバの指示だけが context を消費する。/mcp でサーバごとのコストを確認できる

compaction 以外で context を絞る手:

  • skill はオンデマンドで読み込まれる。 セッション開始時に見えるのは説明文だけで、本文は使ったときに読まれる。自分で呼ぶだけの skill は disable-model-invocation: true で説明文も context から外せる。自分が書いていない skill は、設定の skillOverrides で同じことができる
  • subagent は自分の context window で動く。 fork でなければまっさらから始まり（fork は会話の写しを持って始まる）、どちらでも subagent のツール呼び出しは本流の context に入らず、終わると要約だけが返る

Claude Code が自分で足す context

自分で書いていない規則に Claude が従っていたら（コミットに Co-Authored-By の行を付ける、など）、その規則は system reminder から来ているかもしれない。作業中に Claude Code は、あなたのメッセージと並べて次のものを会話に足す:

  • CLAUDE.md
  • output style の指示
  • 前に読んだファイルがディスク上で変わったという知らせ
  • コミットと pull request の帰属行

帰属行は attribution 設定で変える・消す。Claude Code に組み込みのコミットと PR の指示を外すなら includeGitInstructions: false。

安全機構は2つ

1. checkpoints（取り消し）

  • ファイル編集の前に内容をスナップショットする。Esc を2回で巻き戻せる
  • git とは独立しており、会話を再開しても残る
  • ファイル変更しかカバーしない。symlink / hard link されたファイルは復元がスキップされる
  • リモートシステムに影響する操作（DB、API、デプロイ）は checkpoint できない。それらは permission mode と permission ルールで制御する

2. permission modes（Shift+Tab で巡回）

モード挙動
Manualファイル編集とシェルコマンドの前に確認する
Accept editsファイル編集と mkdir / mv などよくあるファイルシステム操作は確認なし。他は確認する
Plan探索して計画を提案する。ソースファイルは編集しない
Auto分類器が大半の操作をバックグラウンドで審査し、危険なものはあなたに聞く代わりにブロックする。v2.1.283 以降は、対話ターミナルと VS Code のセッションの組み込みの開始モード（それより前の版では Pro / Max / Team だけ）

.claude/settings.json で特定コマンド（npm test、git status など）を許可しておける。

うまく使うためのコツ

Claude Code 自身に聞く — 「how do I set up hooks?」のように聞けば説明してくれる。/init は CLAUDE.md 作成を案内し、/doctor はインストールと設定の健診をして修正まで行う。

会話である — 完璧なプロンプトは要らない。「Fix the login bug」→ 調査させる →「That’s not quite right. The issue is in the session handling.」と直していく。最初がずれても、やり直さずに反復する。

割り込みと操舵の2手:

操作挙動
Esc即座に停止。実行中のツール呼び出しをキャンセルして次の指示を待つ。キューにメッセージがあれば、それが次に送られる
訂正を打って EnterClaude を止めずに送る。メッセージはキューに入った状態で表示され、ツール呼び出しの最中ならそれが終わり次第、同じターンのうちに Claude が読み、次の手の前に調整する

指示するのではなく委譲する（Delegate, don’t dictate） — どのファイルを読むか、どのコマンドを打つかを指定する必要はない。

そのまま使える具体例

委譲する書き方（どのファイルを読むか、どのコマンドを打つかは指定しない）:

The checkout flow is broken for users with expired cards.
The relevant code is in src/payments/. Can you investigate and fix it?

主要なキー操作とコマンド:

キー / コマンド動作
Esc実行中のツールを止める
Esc Esccheckpoint まで巻き戻す
Shift+Tabpermission mode を巡回
/contextcontext を何が消費しているか見る
/mcpMCP サーバごとのトークンコスト
/compact focus on the API changes焦点を指定して畳む
/initCLAUDE.md を作る
/doctor設定の健診と修正

原典で言及されている関連文書

バックリンク