以前、こんな記事を書いたのでちゃんと公式ドキュメントを読んで理解を進める。
参照：Claude Code Docs「How Claude Code works」
エージェントループ
エージェントループとは、タスクをClaudeに与えたときに
- コンテキストの収集（gather context）
- アクション実行（take action）
- 結果の検証（verify results）
という3つのフェーズを経てタスクが進むこと。 ただしこの3フェーズはきれいに分かれて直列で走るというより、状況に応じて混ざり合い、必要な分だけ何度も回る。たとえば「コードベースについて質問する」だけなら収集だけで終わることもあるし、バグ修正なら収集→実行→検証を何度も回す。途中でユーザーが割り込んで方向修正できるのも、このループの前提になっている。 ([Claude Code][1])
-- Claude Code Docs「How Claude Code works」より
このループは、モデルとツールの2つのコンポーネントで動く。 Claude Codeはこの「モデルが考える」＋「ツールが手を動かす」を成立させるための“土台（ハーネス）”になっている。
モデル
Claude CodeはClaudeモデルを使ってタスクに対応する。複数のモデルがあり、用途によって使い分ける。
Sonnet
- 多くのコーディングタスクをうまく捌ける
Opus
- 複雑な推論、特にアーキテクチャ上の意思決定などで強い
なお、モデルはセッション中に /model で切り替えたり、起動時に claude --model <name> のように指定できる。
ツール
ツールは「Claudeがテキストで答えるだけ」から「実際に行動する」へ拡張するもの。 Claude Codeでは、ツール実行の結果が次の意思決定（次の一手）に戻っていくので、ここがエージェントっぽさの中核になる。
ざっくり分類すると、たとえばこんな方向性がある。
- ファイル操作：読む／編集する／作る／移動・リネームする
- 検索：ファイルを探す／パターン検索する／参照関係を追う
- 実行：シェルコマンド、テスト、サーバ起動、git操作など
- Web検索：ドキュメントやエラーを調べる
- コードインテリジェンス：型エラーや警告、定義ジャンプ等（プラグインが必要なものもある）
「テストが落ちてるから直して」みたいな依頼だと、テストを回す→ログ読む→関連ファイル探す→修正→テスト再実行…みたいに、ツールが連鎖してループが回る。
Claudeがアクセスできる範囲
claude をあるディレクトリで実行すると、Claude Codeは基本的に次のようなものにアクセスできる（＝ここが“コンテキスト収集”の材料になる）。
- プロジェクトのファイル（ディレクトリ配下。必要に応じて許可した範囲も）
- ターミナルで実行できるコマンド（ビルド、テスト、git、スクリプト等）
- gitの状態（ブランチ、未コミット差分、履歴など）
CLAUDE.md（プロジェクト固有の指示・慣習・背景の置き場所）- MCP/skills/subagents 等の拡張（設定したもの）
ここを理解しておくと、「Claudeが何を見て判断しているのか」が掴みやすい。
セッション
Claude Codeにおけるセッションとは、ざっくり言うと あるディレクトリ（プロジェクト）に紐づいた会話単位。 Claude Codeは会話をローカルに保存し、巻き戻し／再開／フォークができる。会話だけじゃなく、ツール実行の結果も含めて保存される。
ただし重要なのはここで、Claude Codeには「セッションをまたいだ永続的な記憶」がない。
つまり「前回こうしてたよね」を自然に覚えてくれるわけではない。毎回の新規セッションは基本“新しく始まる”。覚えていてほしいルールは CLAUDE.md に置く。
セッションを再開する
起動時に過去の会話へ戻る方法がある。
# 現在のディレクトリで「直近の会話」を再開 claude --continue # セッションピッカーを開く、または名前で指定して再開 claude --resume claude --resume auth-refactor # 例：名前で指定
--continue：そのディレクトリ（プロジェクト）の直近セッションを再開--resume：ピッカーで選ぶ（または名前で指定して再開）- PRに紐づいたセッションを再開する
--from-prもある
フォークして別アプローチを試す
元のセッションに影響を与えず、同じ履歴を引き継いで別分岐を作りたいときはこれ。
claude --continue --fork-session
- 履歴はその時点まで引き継ぐ
- ただし 新しいセッションID になる（元セッションは変更されない）
注意点として、再開・フォークをした場合でも セッション単位の許可（権限の承認）は引き継がれない。つまり再度承認が必要になることがある。
同じセッションを複数ターミナルで再開するとどうなる？
同じセッションを複数のターミナルで再開すると、両方が同じセッションファイルへ書き込むため、会話が交互に混ざって“ノートがぐちゃぐちゃ”になりがち。壊れるわけではないけど読みづらくなる。
並列にやりたいなら --fork-session で分けたほうが良い。
セッションを命名する
セッションが増えてくると、後から見つけられない問題が出る。 その対策として、セッションに名前をつけられる。
セッション中：
> /rename auth-refactor
起動時：
$ claude --resume auth-refactor
ピッカーでもリネーム可能。
コンテキストウィンドウ
Claude Codeのコンテキストウィンドウには、だいたい次が入る。
- 会話履歴
- ファイルの中身
- コマンド出力
CLAUDE.md- 読み込まれたskills
- システム指示
など
作業が進むにつれてコンテキストが溜まる。溜まりすぎると、Claude Codeは自動で圧縮（compaction）する。
このとき、古いツール出力を先に捨て、それでも足りなければ会話を要約する。ただし 会話の冒頭で書いた細かい指示が落ちることがある。永続ルールは CLAUDE.md に置け、というのはここが理由。
コンテキストの中身を確認する
「何がスペースを食ってる？」を見たいときは /context。
> /context
圧縮（compact）の制御
圧縮で何を残すかを制御したい場合は2パターン。
CLAUDE.mdに Compact Instructions セクションを追加する- セッション中に
/compactを focus 付きで実行する
例：
> /compact focus on the API changes
これで「何を中心に要約してほしいか」を寄せられる。
※ MCPサーバをいくつも繋ぐと、ツール定義が常にコンテキストを消費する。必要なら /mcp でコストを見る。
skills / subagents でコンテキストを太らせない
- skills：必要なときだけ本体が読み込まれる（常時全文を抱えない）
- subagents：メイン会話とは別の“新しいコンテキスト”で動き、最後に要約だけ返す
長い作業になりそうなとき、subagents はコンテキスト節約としても効く。
チェックポイントと権限
Claude Codeには安全装置が2つある。
- チェックポイント：ファイル変更を元に戻すためのもの
- 権限：Claudeが何を無断でできるか／都度確認するかの制御
チェックポイント：ファイル編集は巻き戻せる
Claudeがファイルを編集する前に、対象ファイルのスナップショットを取るので、ファイル編集は基本的に戻せる。
巻き戻しは Esc を2回、または「undoして」と頼む。
重要な制約もある。
- チェックポイントは gitとは別（gitの履歴とは独立）
- ファイル変更だけが対象
- DBや外部API、デプロイなど 外部へ副作用が出る操作は戻せない → だから外部影響のあるコマンドは実行前に確認が入りやすい
権限：Claudeが勝手にできる範囲を切り替える
Shift+Tab で権限モードを切り替えられる。
- Default：ファイル編集とコマンド実行は基本確認
- Auto-accept edits：編集は自動、コマンドは確認
- Plan mode：読み取り中心で計画だけ作る（実行はしない）
また、信頼できるコマンド（例：npm test や git status）を .claude/settings.json に登録して、毎回の確認を減らすこともできる。
次は、CLAUDE.md をどれくらい“具体”に書くと実務で効くのか（最小構成）を整理してみたい。
