Milvus
Zilliz
  • Home
  • Blog

  • クロード・コードが安定した理由：開発者がローカル・ストレージの設計を深く掘り下げる

クロード・コードが安定した理由：開発者がローカル・ストレージの設計を深く掘り下げる

  • Engineering
January 30, 2026
Bill Chen

最近、クロード・コードがあちこちで見かけるようになった。開発者は、より速く機能を出荷し、ワークフローを自動化し、実際のプロジェクトで実際に機能するエージェントのプロトタイプを作成するためにコードを使っている。さらに驚きなのは、多くの非コーダーが、ツールを構築し、タスクを配線し、ほとんど何も設定することなく、有用な結果を得ていることだ。AIコーディング・ツールがこれほど早く、さまざまなスキル・レベルに普及するのは珍しいことだ。

しかし、本当に際立っているのは、その安定感だ。Claude Codeは、セッションをまたいでも何が起こったかを覚えていて、進行状況を失うことなくクラッシュを生き延び、チャット・インターフェースというよりローカル開発ツールのように動作する。その信頼性は、ローカルストレージの扱い方に由来する。

コーディングセッションを一時的なチャットとして扱う代わりに、Claude Code は実際のファイルを読み書きし、プロジェクトの状態をディスクに保存し、エージェントの作業のすべてのステップを記録します。セッションは推測なしに再開、検査、ロールバックすることができ、各プロジェクトはきれいに分離されたままです。

この記事では、その安定性の背後にあるストレージ・アーキテクチャと、Claude Codeが日常的な開発に実用的であると感じさせる大きな役割を担っている理由を詳しく見ていきます。

ローカルAIコーディングアシスタントが直面する課題

Claude Codeがストレージにどのようにアプローチしているかを説明する前に、ローカルAIコーディングツールがぶつかりがちな一般的な問題を見てみよう。これらは、アシスタントがあなたのファイルシステム上で直接作業し、時間をかけて状態を保持するときに自然に出てくるものです。

1.プロジェクトデータがワークスペース間で混在してしまう。

ほとんどの開発者は、1日中複数のレポを切り替えている。アシスタントが1つのプロジェクトから別のプロジェクトへ状態を引き継ぐと、その動作を理解するのが難しくなり、間違った仮定をしやすくなります。各プロジェクトには、状態と履歴のための、クリーンで隔離された独自のスペースが必要です。

2.クラッシュはデータ損失の原因になります。

コーディングセッション中、アシスタントは有用なデータ-ファイルの編集、ツールの呼び出し、中間ステップ-を着実に生成する。このデータがすぐに保存されないと、クラッシュや強制再起動で消えてしまうことがあります。信頼できるシステムは、重要な状態が作成されるとすぐにディスクに書き込むので、作業が予期せず失われることはありません。

3.エージェントが実際に何をしたかは、必ずしも明らかではありません。

典型的なセッションには多くの小さなアクションが含まれます。これらのアクションの明確で整然とした記録がなければ、アシスタントがどのように特定の出力に到達したかを辿ったり、何かが間違ったステップを見つけることは困難です。完全な履歴は、デバッグとレビューをより管理しやすくします。

4.ミスの取り消しに手間がかかりすぎる。

アシスタントがうまくいかない変更をすることがあります。そのような変更をロールバックする組み込みの方法がない場合、結局は手動でリポジトリ全体の編集を探すことになります。システムは自動的に何が変更されたかを追跡し、余分な作業をせずにきれいに元に戻せるようにすべきです。

5.プロジェクトによって異なる設定が必要。

ローカル環境はさまざまです。特定のパーミッション、ツール、ディレクトリルールを必要とするプロジェクトもあれば、カスタムスクリプトやワークフローを持つプロジェクトもあります。アシスタントは、このような違いを尊重し、プロジェクトごとの設定を可能にしながら、コアの動作を一貫したものにする必要があります。

Claude Codeを支えるストレージ設計の原則

Claude Codeのストレージ設計は、4つの分かりやすいアイデアを中心に構築されている。これらは単純に見えるかもしれないが、一緒になることで、AIアシスタントがあなたのマシンで、複数のプロジェクトにまたがって直接作業するときに出てくる現実的な問題に対処する。

1.各プロジェクトは独自のストレージを持つ。

Claude Codeは、すべてのセッションデータを、それが属するプロジェクトディレクトリに結びつけます。つまり、会話、編集、ログはそのプロジェクトに残り、他のプロジェクトに漏れることはありません。ストレージを別にすることで、アシスタントの動作が理解しやすくなり、特定のレポのデータを検査したり削除したりするのが簡単になります。

2.データはすぐにディスクに保存されます。

インタラクションデータをメモリに保持する代わりに、Claude Codeはデータが作成されるとすぐにディスクに書き込みます。各イベント（メッセージ、ツールの呼び出し、状態の更新）は新しいエントリとして追加されます。プログラムがクラッシュしたり、不意に終了したりしても、ほとんどすべてが残っている。このアプローチは、それほど複雑さを増すことなく、セッションの耐久性を保つ。

3.すべてのアクションは、履歴の中で明確な場所を持つ。

Claude Codeは、各メッセージやツールのアクションをその前のものとリンクさせ、完全なシーケンスを形成します。この順番に並んだ履歴によって、セッションがどのように展開したかをレビューし、特定の結果に至ったステップをトレースすることが可能になる。開発者にとっては、このようなトレースがあることで、エージェントの動作のデバッグや理解が非常に容易になります。

4.コード編集のロールバックが簡単

アシスタントがファイルを更新する前に、Claude Codeは以前の状態のスナップショットを保存します。変更が間違っていることが判明した場合、レポを調べたり、何が変更されたかを推測したりすることなく、以前のバージョンを復元することができます。このシンプルなセーフティネットにより、AIによる編集のリスクは大幅に軽減される。

クロード・コードのローカル・ストレージ・レイアウト

Claude Codeは、すべてのローカルデータをホームディレクトリという単一の場所に保存します。これはシステムを予測可能な状態に保ち、必要なときに検査、デバッグ、クリーンアップを容易にします。ストレージ・レイアウトは、2つの主要なコンポーネントを中心に構築されています：小さなグローバル設定ファイルと、すべてのプロジェクト・レベルの状態が存在する大きなデータ・ディレクトリです。

2つのコア・コンポーネント

  • ~/.claude.jsonプロジェクトマッピング、MCPサーバー設定、最近使用したプロンプトを含む、グローバル設定とショートカットを保存します。

  • ~/.claude/メインのデータディレクトリには、Claude Code の会話、プロジェクトセッション、パーミッション、プラグイン、スキル、履歴、および関連するランタイムデータが保存されます。

次に、これら2つのコアコンポーネントについて詳しく見ていきましょう。

(1) グローバル・コンフィギュレーション：~/.claude.json

このファイルは、データストアというよりインデックスとして機能する。どのプロジェクトで作業したか、各プロジェクトにどのツールが付属しているか、最近どのプロンプトを使用したかが記録される。会話データ自体はここには保存されない。

{
  "projects": {
    "/Users/xxx/my-project": {
      "mcpServers": {
        "jarvis-tasks": {
          "type": "stdio",
          "command": "python",
          "args": ["/path/to/run_mcp.py"]
        }
      }
    }
  },
  "recentPrompts": [
    "Fix the bug in auth module",
    "Add unit tests"
  ]
}

(2) メインデータディレクトリ：~/.claude/

~/.claude/ ディレクトリには、クロードコードのほとんどのローカル状態が保存されます。このディレクトリの構造は、プロジェクトの分離、即時の永続化、ミスからの安全なリカバリという、設計の核となるアイデアを反映しています。

~/.claude/
├── settings.json                    # Global settings (permissions, plugins, cleanup intervals)
├── settings.local.json              # Local settings (machine-specific, not committed to Git)
├── history.jsonl                    # Command history
│
├── projects/                        # 📁 Session data (organized by project, core directory)
│   └── -Users-xxx-project/          # Path-encoded project directory
│       ├── {session-id}.jsonl       # Primary session data (JSONL format)
│       └── agent-{agentId}.jsonl    # Sub-agent session data
│
├── session-env/                     # Session environment variables
│   └── {session-id}/                # Isolated by session ID
│
├── skills/                          # 📁 User-level skills (globally available)
│   └── mac-mail/
│       └── SKILL.md
│
├── plugins/                         # 📁 Plugin management
│   ├── config.json                  # Global plugin configuration
│   ├── installed_plugins.json       # List of installed plugins
│   ├── known_marketplaces.json      # Marketplace source configuration
│   ├── cache/                       # Plugin cache
│   └── marketplaces/
│       └── anthropic-agent-skills/
│           ├── .claude-plugin/
│           │   └── marketplace.json
│           └── skills/
│               ├── pdf/
│               ├── docx/
│               └── frontend-design/
│
├── todos/                           # Task list storage
│   └── {session-id}-*.json          # Session-linked task files
│
├── file-history/                    # File edit history (stored by content hash)
│   └── {content-hash}/              # Hash-named backup directory
│
├── shell-snapshots/                 # Shell state snapshots
├── plans/                           # Plan Mode storage
├── local/                           # Local tools / node_modules
│   └── claude                       # Claude CLI executable
│   └── node_modules/                # Local dependencies
│
├── statsig/                         # Feature flag cache
├── telemetry/                       # Telemetry data
└── debug/                           # Debug logs

このレイアウトは意図的にシンプルにしています。Claude Codeが生成するものはすべて、プロジェクトとセッションごとに整理された1つのディレクトリの下にあります。システム上に隠された状態が散乱することはなく、必要なときに検査したりクリーンアップしたりするのも簡単です。

Claude Codeの設定管理方法

Claude Codeのコンフィギュレーションシステムは、シンプルなアイデアに基づいて設計されています。デフォルトの動作はマシン間で一貫性を保ちつつ、個々の環境やプロジェクトが必要なものをカスタマイズできるようにしています。これを実現するために、Claude Codeは3層の設定モデルを使用しています。同じ設定が複数の場所に現れる場合、より具体的なレイヤーが常に優先されます。

3つの設定レベル

Claude Codeは、優先順位の低いものから高いものへと、以下の順序で設定を読み込みます：

┌─────────────────────────────────────────┐
│    Project-level configuration          │  Highest priority
│    project/.claude/settings.json        │  Project-specific, overrides other configs
├─────────────────────────────────────────┤
│    Local configuration                  │  Machine-specific, not version-controlled
│    ~/.claude/settings.local.json        │  Overrides global configuration
├─────────────────────────────────────────┤
│    Global configuration                 │  Lowest priority
│    ~/.claude/settings.json              │  Base default configuration
└─────────────────────────────────────────┘

これは、グローバルなデフォルトから始まり、マシン固有の調整を適用し、最後にプロジェクト固有のルールを適用すると考えることができます。

次に、それぞれの設定レベルについて詳しく説明します。

(1) グローバル・コンフィギュレーション：~/.claude/settings.json

グローバル設定は、すべてのプロジェクトにおけるクロードコードのデフォルトの動作を定義します。ここでベースラインのパーミッションを設定し、プラグインを有効にし、クリーンアップの動作を設定します。

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Read(**)", "Bash(npm:*)"],
    "deny": ["Bash(rm -rf:*)"],
    "ask": ["Edit", "Write"]
  },
  "enabledPlugins": {
    "document-skills@anthropic-agent-skills": true
  },
  "cleanupPeriodDays": 30
}

(2) ローカル設定：~/.claude/settings.local.json

ローカルコンフィギュレーションは単一のマシンに固有のものです。共有されたりバージョン管理でチェックされたりするものではありません。そのため、APIキーやローカルツール、環境固有のパーミッションを設定するのに適しています。

{
  "permissions": {
    "allow": ["Bash(git:*)", "Bash(docker:*)"]
  },
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-xxx"
  }
}

(3) プロジェクトレベルの設定：project/.claude/settings.json

プロジェクトレベルのコンフィギュレーションは単一のプロジェクトにのみ適用され、最も優先度が高い。ここでは、そのリポジトリで作業するときに常に適用されるルールを定義します。

{
  "permissions": {
    "allow": ["Bash(pytest:*)"]
  }
}

設定レイヤーが定義されたので、次の問題はClaude Codeが実行時にどのように設定と権限を実際に解決するかです。

Claude Codeは3つのレイヤーで設定を適用します。グローバルデフォルトから始まり、マシン固有のオーバーライドを適用し、最後にプロジェクト固有のルールを適用します。同じ設定が複数の場所に現れる場合、最も具体的な設定が優先されます。

パーミッションは固定された評価順序に従います：

  1. deny- 常にブロック

  2. ask- 確認が必要

  3. allow- 自動的に実行されます。

  4. default- 一致するルールがない場合にのみ適用されます。

これにより、デフォルトでシステムを安全に保ちつつ、プロジェクトや個々のマシンに必要な柔軟性を与えることができます。

セッションストレージ：Claude Codeがインタラクションのコアデータを永続化する方法

Claude Codeでは、セッションがデータのコア単位です。セッションは、会話そのもの、ツールの呼び出し、ファイルの変更、関連するコンテキストを含む、ユーザーとAI間のインタラクション全体をキャプチャします。セッションをどのように保存するかは、システムの信頼性、デバッグ性、全体的な安全性に直接影響します。

プロジェクトごとにセッションデータを分ける

セッションが定義されたら、次の問題は、Claude Codeがデータを整理して分離した状態でどのように保存するかです。

Claude Codeはセッションデータをプロジェクトごとに分離します。各プロジェクトのセッションは、プロジェクトのファイルパスから派生したディレクトリの下に保存されます。

保存パスはこのパターンに従います：

~/.claude/projects/ + path-encoded project directory

有効なディレクトリ名を作成するために、/ 、スペース、~ などの特殊文字は、- に置き換えられます。

例えば

/Users/bill/My Project → -Users-bill-My-Project

この方法によって、異なるプロジェクトのセッションデータが混在することがなく、プロジェクトごとに 管理や削除ができるようになります。

セッションがJSONL形式で保存される理由

Claude Code はセッションデータを標準的な JSON ではなく JSONL (JSON Lines) を使って保存します。

従来のJSONファイルでは、すべてのメッセージが1つの大きな構造体の中にまとめられているため、変更があるたびにファイル全体を読み取って書き直す必要がありました。対照的に、JSONLは、各メッセージをファイル内の独自の行として保存します。1行は1メッセージに等しく、外側のラッパーはありません。

アスペクト標準的なJSONJSONL（JSON行）
データの格納方法1つの大きな構造体1行に1メッセージ
データが保存されるタイミング通常は最後メッセージごとに即時
クラッシュの影響ファイル全体が壊れる最後の行のみ影響
新しいデータの書き込みファイル全体を書き換える1行の追加
メモリ使用量すべてを読み込む1行ずつ読み込む

JSONLはいくつかの点で優れている：

  • 即時保存：各メッセージは、セッションの終了を待つのではなく、生成されるとすぐにディスクに書き込まれます。

  • クラッシュに強い:プログラムがクラッシュした場合、最後の未完成のメッセージだけが失われる可能性があります。それ以前に書かれたものはすべてそのまま残ります。

  • 高速な追加：新しいメッセージは、既存のデータを読んだり書き換えたりすることなく、ファイルの最後に追加されます。

  • メモリ使用量が少ない：セッションファイルは一度に1行ずつ読み込むことができるので、ファイル全体をメモリに読み込む必要はありません。

簡略化したJSONLセッションファイルは次のようになります：

{"type":"user","message":{"role":"user","content":"Hello"},"timestamp":"2026-01-05T10:00:00Z"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"Hi!"}]}}
{"type":"user","message":{"role":"user","content":"Help me fix this bug"}}

セッション・メッセージ・タイプ

セッションファイルは、Claude Code とのインタラクション中に発生するすべてのことを記録します。これを明確にするために、イベントの種類ごとに異なるメッセージタイプを使用します。

  • ユーザーメッセージはシステムに入ってくる新しい入力を表します。これにはユーザーが入力したものだけでなく、シェルコマンドの出力のようなツールによって返された結果も含まれます。AIから見れば、どちらも応答する必要のある入力です。

  • アシスタント・メッセージは、それに対してクロードが何をするかを捉えます。これらのメッセージには、AIの推論、AIが生成したテキスト、AIが使用を決定したツールなどが含まれる。また、トークン数などの使用状況の詳細も記録し、インタラクションの全体像を提供する。

  • ファイル履歴スナップショットは、クロードがファイルを変更する前に作成される安全性のチェックポイントである。オリジナルのファイル状態を最初に保存することで、Claude Codeは何か問題が発生した場合に変更を取り消すことができます。

  • 要約は、セッションの簡潔な概要を提供し、最終的な結果にリンクされています。すべてのステップを再生することなく、セッションの内容を簡単に理解することができます。

これらのメッセージタイプは、一緒になって、会話だけでなく、セッション中に起こるアクションとエ フェクトの完全なシーケンスを記録します。

これをより具体的にするために、ユーザーメッセージとアシスタントメッセージの具体例を見てみましょう。

(1) ユーザーメッセージの例：

{
  "type": "user",
  "uuid": "7d90e1c9-e727-4291-8eb9-0e7b844c4348",
  "parentUuid": null,
  "sessionId": "e5d52290-e2c1-41d6-8e97-371401502fdf",
  "timestamp": "2026-01-05T10:00:00.000Z",
  "message": {
    "role": "user",
    "content": "Analyze the architecture of this project"
  },
  "cwd": "/Users/xxx/project",
  "gitBranch": "main",
  "version": "2.0.76"
}

(2) アシスタントメッセージの例：

{
  "type": "assistant",
  "uuid": "e684816e-f476-424d-92e3-1fe404f13212",
  "parentUuid": "7d90e1c9-e727-4291-8eb9-0e7b844c4348",
  "message": {
    "role": "assistant",
    "model": "claude-opus-4-5-20251101",
    "content": [
      {
        "type": "thinking",
        "thinking": "The user wants to understand the project architecture, so I need to check the directory structure first..."
      },
      {
        "type": "text",
        "text": "Let me take a look at the project structure first."
      },
      {
        "type": "tool_use",
        "id": "toolu_01ABC",
        "name": "Bash",
        "input": {"command": "ls -la"}
      }
    ],
    "usage": {
      "input_tokens": 1500,
      "output_tokens": 200,
      "cache_read_input_tokens": 50000
    }
  }
}

セッションメッセージのリンク方法

Claude Code はセッションメッセージを孤立したエントリとして保存しません。その代わりに、それらをリンクして、イベントの明確な連鎖を形成します。各メッセージには一意の識別子(uuid)と、その前に来たメッセージへの参照(parentUuid)が含まれています。これにより、何が起こったかだけでなく、なぜそれが起こったかを見ることができる。

セッションはユーザーメッセージから始まり、それが連鎖を始める。クロードからの各返信は、その原因となったメッセージを指し返します。ツールの呼び出しとその出力は同じように追加され、すべてのステップはその前のステップにリンクしている。セッションが終了すると、最後のメッセージに要約が添付される。

すべてのステップがリンクされているため、Claude Codeはアクションの完全なシーケンスを再生し、結果がどのように生成されたかを理解することができます。

ファイルスナップショットでコード変更を簡単に元に戻す

AIが生成した編集は常に正しいとは限らず、時には完全に間違った方向に進むこともあります。このような変更を安全に実験できるようにするため、Claude Codeはシンプルなスナップショットシステムを採用しており、差分を調べたりファイルを手動でクリーンアップしたりすることなく、編集を取り消すことができます。

Claude Codeがファイルを変更する前に、元のコンテンツのコピーを保存します。編集が間違いであることが判明した場合、システムは即座に以前のバージョンを復元することができます。

ファイル履歴スナップショットとは何ですか？

ファイル履歴スナップショットは、ファイルが変更される前に作成されるチェックポイントです。クロードが編集しようとしているすべてのファイルのオリジナルの内容を記録します。これらのスナップショットは、アンドゥやロールバック操作のデータソースとして機能します。

ユーザがファイルを変更する可能性のあるメッセージを送信すると、Claude Codeはそのメッセージに対して空のスナップショットを作成します。編集の前に、システムは各ターゲットファイルのオリジナルコンテンツをスナップショットにバックアップし、その後、編集をディスクに直接適用します。ユーザーがアンドゥをトリガーした場合、Claude Codeは保存された内容を復元し、変更されたファイルを上書きします。

実際には、アンドゥ可能な編集のライフサイクルは次のようになります：

  1. ユーザーがメッセージを送信するClaudeCodeが新しい空のfile-history-snapshot レコードを作成する。

  2. Claudeはファイルを変更する準備をする。システムはどのファイルが編集されるかを特定し、元の内容をtrackedFileBackups にバックアップする。

  3. クロードが編集を実行する編集と書き込みが実行され、変更された内容がディスクに書き込まれる。

  4. ユーザがアンドゥを実行ユーザがEsc + Escキーを押し、変更を取り消すことを知らせる。

  5. 元のコンテンツが復元されるClaudeCodeがtrackedFileBackups 、保存されたコンテンツを読み込み、現在のファイルを上書きし、アンドゥが完了する。

元に戻すが機能する理由スナップショットは旧バージョンを保存する

Claude CodeのUndoが機能するのは、編集が行われる前に元のファイルの内容が保存されるからです。

後から変更を元に戻そうとするのではなく、Claude Codeはよりシンプルなアプローチをとります。変更前のファイルをコピーし、そのコピーをtrackedFileBackups 。ユーザーがアンドゥをトリガーすると、システムはこの保存されたバージョンを復元し、編集されたファイルを上書きする。

下の図は、この流れをステップごとに示しています：

┌─────────────────────────┐
│    before edit,  app.py │
│    print("old")         │───────→  Backed up into snapshot trackedFileBackups
└─────────────────────────┘

↓


┌──────────────────────────┐
│   After Claude edits     │
│    print(“new”)          │───────→  Written to disk (overwrites the original file)
└──────────────────────────┘


↓


┌──────────────────────────┐
│    User triggers undo    │
│    Press   Esc + Esc     │───────→ Restore “old” content to disk from snapshot
└──────────────────────────┘

ファイル履歴スナップショットは内部的にどのように見えるか

スナップショット自体は構造化レコードとして保存されます。これは、ユーザーメッセージ、スナップショットの時間、そして最も重要な、元のコンテンツへのファイルのマップに関するメタデータをキャプチャします。

以下の例は、クロードがファイルを編集する前に作成されたfile-history-snapshot レコードを示しています。trackedFileBackups の各エントリには、編集前のファイルの内容が保存されており、この内容は後でアンドゥを行う際にファイルを復元するために使用されます。

{
  "type": "file-history-snapshot",
  "messageId": "7d90e1c9-e727-4291-8eb9-0e7b844c4348",
  "snapshot": {
    "messageId": "7d90e1c9-e727-4291-8eb9-0e7b844c4348",
    "trackedFileBackups": {
      "/path/to/file1.py": "Original file content\ndef hello():\n    print('old')",
      "/path/to/file2.js": "// Original content..."
    },
    "timestamp": "2026-01-05T10:00:00.000Z"
  },
  "isSnapshotUpdate": false
}

スナップショットの保存場所と保存期間

  • スナップショットのメタデータが保存される場所：スナップショットレコードは特定のセッションにバインドされ、~/.claude/projects/-path-to-project/{session-id}.jsonl の下にJSONLファイルとして保存されます。

  • 元のファイルの内容がバックアップされる場所：各ファイルの編集前のコンテンツは、~/.claude/file-history/{content-hash}/ のコンテンツハッシュによって個別に保存されます。

  • スナップショットのデフォルト保存期間：スナップショット・データは、グローバルなcleanupPeriodDays の設定と同様に、30日間保持されます。

  • 保持期間の変更方法：保持日数は~/.claude/settings.json のcleanupPeriodDays フィールドで調整できます。

コマンド/アクション説明
Esc + Esc直近のファイル編集を元に戻す（最も一般的に使用される）
/巻き戻し以前に指定したチェックポイント（スナップショット）に戻す。
/diff現在のファイルとスナップショットバックアップの差分を表示する。

その他の重要なディレクトリ

(1) plugins/ - プラグイン管理

plugins/ ディレクトリはクロードコードに追加機能を与えるアドオンを保存します。

このディレクトリにはどのプラグインがインストールされているか、そのプラグインはどこから来たのか、そしてそれらのプラグインが提供する追加スキルが保存されます。また、ダウンロードしたプラグインのローカルコピーも保存されるので、再度取得する必要はありません。

~/.claude/plugins/
├── config.json
│   Global plugin configuration (e.g., enable/disable rules)
├── installed_plugins.json
│   List of installed plugins (including version and status)
├── known_marketplaces.json
│   Plugin marketplace source configuration (e.g., Anthropic official marketplace)
├── cache/
│   Plugin download cache (avoids repeated downloads)
└── marketplaces/
    Marketplace source storage
    └── anthropic-agent-skills/
        Official plugin marketplace
        ├── .claude-plugin/
        │   └── marketplace.json
        │       Marketplace metadata
        └── skills/
            Skills provided by the marketplace
            ├── pdf/
            │   PDF-related skills
            ├── docx/
            │   Word document processing skills
            └── frontend-design/
                Frontend design skills

(2) skills/ - スキルが保存され適用される場所

クロードコードでは、スキルとは、クロードが特定のタスクを実行するのに役立つ、再利用可能な小さな能力です。

すべてのスキルがどこでも使えるわけではありません。グローバルに適用されるものもあれば、単一のプロジェクトに限定されたり、プラグインによって提供されるものもあります。Claude Code では、各スキルを使用できる場所を制御するために、さまざまな場所にスキルを保存します。

以下の階層は、グローバルに利用可能なスキルから、プロジェクト固有のスキルやプラグインによって提供されるスキルまで、スキルが範囲ごとにどのように階層化されているかを示しています。

レベル保存場所説明
ユーザー~/.claude/skills/グローバルに利用可能、すべてのプロジェクトからアクセス可能
プロジェクトプロジェクト/.claude/スキル現在のプロジェクトでのみ利用可能、プロジェクトごとにカスタマイズ可能
プラグイン~/.claude/plugins/marketplaces/*/skills/ プラグインと一緒にインストールされます。プラグインと一緒にインストールされ、プラグインの有効化ステータスに依存する

(3) todos/ - タスクリストストレージ

todos/ ディレクトリは、クロードが会話中の作業を追跡するために作成する、完了するステップ、進行中のアイテム、完了したタスクなどのタスクリストを保存します。

タスクリストは~/.claude/todos/{session-id}-*.json の下に JSON ファイルとして保存されます。各ファイル名はタスクリストを特定の会話に結びつけるセッション ID を含みます。

これらのファイルの内容は、TodoWrite ツールに由来し、タスクの説明、現在のステータス、優先度、関連するメタデータなどの基本的なタスク情報を含む。

(4) local/ - ローカルランタイムとツール

local/ ディレクトリには、クロードコードがあなたのマシンで実行するために必要なコアファイルがあります。

これには、claude コマンドライン実行ファイルと、ランタイムの依存関係を含むnode_modules/ ディレクトリが含まれます。これらのコンポーネントをローカルに保つことで、クロードコードは外部サービスやシステム全体のインストールに依存することなく、独立して実行することができます。

（5）その他のサポートディレクトリ

  • shell-snapshots/：シェルセッションの状態スナップショット（カレントディレクトリや環境変数など）を保存し、シェル操作のロールバックを可能にします。

  • plans/：プランモードで生成された実行計画（複数ステップのプログラミングタスクのステップごとの内訳など）を格納する。

  • statsig/：機能フラグの設定（新機能が有効かどうかなど）をキャッシュし、繰り返しリクエストを減らす。

  • telemetry/：製品の最適化のために、匿名の遠隔測定データ（機能の使用頻度など）を保存します。

  • debug/：トラブルシューティングのためのデバッグログ（エラースタックや実行トレースを含む）を保存します。

結論

Claude Codeがどのようにすべてをローカルに保存し、管理しているのかを調べてみると、かなりはっきりしたことがわかる。派手さはない。各プロジェクトには独自のスペースがあり、すべてのアクションは書き留められ、ファイルの編集は何かが変更される前にバックアップされる。黙々と仕事をこなし、自分の仕事に集中できるようなデザインだ。

私が最も気に入っているのは、ここには神秘的なものが何もないことだ。クロード・コードがうまく機能しているのは、基本がきちんとできているからだ。実際のファイルに触れるエージェントを作ろうとしたことがある人なら、状態が混ざってしまったり、クラッシュで進捗が消えてしまったり、アンドゥが当てずっぽうになってしまったりと、物事がどれだけ簡単に崩れてしまうか知っているはずだ。Claude Codeは、シンプルで一貫性があり、壊れにくいストレージモデルによって、そのような事態を回避します。

ローカルまたはオンプレミスでAIエージェントを構築するチームにとって、特にセキュアな環境では、このアプローチは、強力なストレージと永続性がAIツールをいかに信頼性の高い、日常的な開発に実用的なものにするかを示している。

ローカルまたはオンプレミスのAIエージェントを設計していて、ストレージアーキテクチャ、セッション設計、または安全なロールバックについてより詳しく議論したい場合は、お気軽にSlackチャンネルにご参加ください。

    Try Managed Milvus for Free

    Zilliz Cloud is hassle-free, powered by Milvus and 10x faster.

    Get Started

    Like the article? Spread the word

    続けて読む