ai-docs

How Claude Code works

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

12 min read

一行要約

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 serves as the agentic harness around Claude: it provides the tools, context management, and execution environment that turn a language model into a capable coding agent. Claude Code は Claude を包む agentic harness として機能する。言語モデルを有能なコーディングエージェントに変えるためのツール、context 管理、実行環境を提供する。

組み込みツールの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
  • 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 のツール定義は既定で遅延ロードされ、ツール名だけが context を消費する。/mcp でサーバごとのコストを確認できる

安全機構は2つ

1. checkpoints（取り消し）

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

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

モード挙動
Manualファイル編集とシェルコマンドの前に必ず確認する
Accept editsファイル編集と mkdir / mv などよくあるファイルシステム操作は確認なし。他は確認する
Plan探索して計画を提案する。ソースファイルは編集しない
Autoバックグラウンドの安全チェックを通した上ですべての操作を評価する

.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即座に停止。実行中のツール呼び出しをキャンセルして次の指示を待つ
訂正を打って Enter実行中のツールは止めずに送る。現在の操作が終わり次第 Claude が読み、次の判断の前に調整する

最初に具体的に書く — ファイル、制約、参照すべきパターンを挙げる。

検証できるものを与える — テストケース、期待する UI のスクリーンショット、望む出力を含める。

実装の前に探索する — 複雑な問題では調査とコーディングを分ける。Shift+Tab を2回で plan mode に入り、計画をレビュー・洗練してから実装させる。

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

そのまま使える具体例

曖昧なプロンプトと具体的なプロンプト:

The checkout flow is broken for users with expired cards.
Check src/payments/ for the issue, especially token refresh.
Write a failing test first, then fix it.

検証対象を与える:

Implement validateEmail. Test cases: 'user@example.com' → true,
'invalid' → false, 'user@.com' → false. Run the tests after.

探索と実装を分ける（plan mode と併用）:

Read src/auth/ and understand how we handle sessions.
Then create a plan for adding OAuth support.

委譲する書き方:

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 Esc        checkpoint まで巻き戻す
Shift+Tab      permission mode を巡回
Shift+Tab ×2   plan mode
/context       context を何が消費しているか見る
/mcp           MCP サーバごとのトークンコスト
/compact focus on the API changes
/init          CLAUDE.md を作る
/doctor        設定の健診と修正

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

未取得の派生リンク

グラフビュー

バックリンク