Claude Code サブエージェントの記憶と隔離【2026年10月】— 点検役に指摘を覚えさせ、書く役を worktree で切り離す

Claude Code のサブエージェントを「調べる・書く・点検する」に分けて使い始めた会社が、次にぶつかるのが2つの不満です。ひとつは「点検役が、先週も指摘した同じ問題を、また初見のように指摘してくる」こと。もうひとつは「書く役が途中で失敗すると、本体の作業フォルダに中途半端な変更が残る」ことです。

公式ドキュメント（2026年10月時点）には、この2つに対応する設定があります。memory フィールドで、サブエージェントに会話をまたいで残る専用の記憶を持たせる。isolation: worktree で、サブエージェントを本体とは別のチェックアウト（git worktree）の中で動かす。

この記事では、Claude Code の公式ドキュメントだけを出典に、記憶と隔離がそれぞれ何を変えて何を変えないのか、社内で先に決めておくこと、定義ファイルの雛形、隔離の限界と後片付けまでを整理します。読者は、業務改善・情報システム・Web の担当として Claude Code の自動化を組んでいる方です。サブエージェントの基本（役割分担・権限の引き継ぎ・上限）は、前回の記事を前提にします。

1. 記憶は memory: project が公式推奨の既定。 記憶は .claude/agent-memory/<エージェント名>/ に Markdown で保存され、バージョン管理でチームに配れます。配れるということは、誤った記憶も配られるということなので、レビューの対象にします
2. 記憶の先頭 200行または 25KB だけが毎回読み込まれる。 索引ファイル MEMORY.md が上限を超えると、超えた分は次回から読まれません。「一行一項目・詳細は別ファイル」を守らせる文を定義に書きます
3. 隔離は「既定ブランチから分岐した一時的な worktree」。 本体の HEAD からではなく既定ブランチ（通常 main）から分岐します。作業中のブランチを前提に動かすなら worktree.baseRef を "head" にします
4. 隔離が止めるのは、ファイル編集ツールと git を伴うコマンド。 cp やリダイレクトで本体に書くコマンドは止まりません。permissions とサンドボックスの設定と重ねて使います
5. 後片付けは自動と手動の2段。 変更が無い worktree は終了時に消え、変更が残ったものは保持期間を過ぎた定期的な掃除の対象になります。-p の無人実行で作った worktree は自分では消えないので、掃除の手順を決めておきます

サブエージェントの定義ファイル（.claude/agents/ 配下の Markdown）の frontmatter に memory を書くと、そのサブエージェントは会話をまたいで残る専用のディレクトリを持ちます。公式ドキュメントはこの用途を「コードベースのパターン、デバッグで得た知見、設計上の判断など、時間をかけて知識を積み上げる」ことだと説明しています。

値は3つの中から選びます。

※ 出典: Claude Code Docs — Custom subagents（Enable persistent memory）（取得 2026-10）

公式は project を推奨の既定としています。理由は「サブエージェントの知識をバージョン管理で共有できる」ことです。

記憶が有効なとき、サブエージェントには次の3つが起きます。システムプロンプトに「記憶ディレクトリを読み書きする手順」が入る。同じプロンプトに、記憶ディレクトリの MEMORY.md の先頭 200行または 25KB（どちらか先に達した方）が入り、上限を超えたら整理するよう指示される。記憶ファイルを管理できるように、Read・Write・Edit の3つの道具が自動で有効になる。

前提として、サブエージェントの記憶は「自動メモリ（auto memory）」の一部です。autoMemoryEnabled の設定、または環境変数 CLAUDE_CODE_DISABLE_AUTO_MEMORY で自動メモリを切っていると、memory フィールドは効かず、記憶の指示も道具の追加も行われません。自動メモリはローカルのセッションでは既定で有効ですが、自社ホストの環境では既定で無効になると公式ドキュメントに書かれています。

※ 出典: Claude Code Docs — Manage Claude's memory（Auto memory）（取得 2026-10）

もう一点、混同しやすいのが「メインの会話の記憶」との関係です。メインの会話が覚えた自動メモリは、サブエージェントには読み込まれません。例外は、会話の全文脈を引き継ぐフォークだけです。つまり、点検役に過去の指摘を覚えさせたいなら、メインではなく点検役の定義に memory を書く必要があります。

MEMORY.md は「一行一項目の索引」として設計されています。上限に近づくと Claude Code は「一行一項目を守り、詳細は別ファイルへ移し、古い項目は統合か削除する」よう促します。上限を超えた書き込みそのものは成功しますが、エラーが返され、次回の読み込みでは超えた分が捨てられます。詳細を書いた個別ファイル（トピックファイル）は起動時には読まれず、必要になったときに通常のファイル操作で読まれます。

また、記憶ファイルはセッション記録の自動削除（cleanupPeriodDays）の対象から外されています。人か Claude が編集・削除するまで残ります。「放っておけば消える」ものではないので、棚卸しの担当と頻度を決めておく必要があります。

※ 出典: Claude Code Docs — Manage Claude's memory（How it works）（取得 2026-10）

isolation: worktree を定義に書くと、そのサブエージェントは一時的な git worktree の中で動きます。公式ドキュメントの説明は「リポジトリの隔離されたコピーを与える。既定では、親セッションの HEAD ではなく既定ブランチから分岐する。サブエージェントが変更を加えなければ、worktree は自動で片付けられる」です。

worktree 自体は git の機能で、ひとつのリポジトリの履歴とリモートを共有しながら、別のディレクトリに別のブランチをチェックアウトしたものです。Claude Code が作る worktree はリポジトリ直下の .claude/worktrees/<名前>/ に置かれ、ブランチ名は worktree-<名前> になります。公式は .claude/worktrees/ を .gitignore に入れるよう勧めています。

※ 出典: Claude Code Docs — Run parallel sessions with worktrees（取得 2026-10）

分岐元の "fresh"（既定）には、もうひとつ実務で効く仕様があります。リポジトリが直近 24時間に fetch されていなければ、Claude Code は既定ブランチを fetch してから分岐します。この fetch は 5秒で打ち切られ、失敗すればローカルに残っている参照を使います。パスワードや SSH の鍵のパスフレーズ、新しいホストの確認を git や ssh が求める状況では、入力を待たずに失敗扱いになります。無人実行の環境で「なぜ古い main から分岐したのか」を調べるときは、この fetch が通る認証になっているかを確かめます。

※ 出典: Claude Code Docs — Run parallel sessions with worktrees（Choose the base branch）（取得 2026-10）

隔離中のサブエージェントに対して、Claude Code は4つの検査を行います。

※ 出典: Claude Code Docs — Run parallel sessions with worktrees（How Claude Code enforces isolation）（取得 2026-10）

重要なのは、この4つが「編集の対象パス・コマンドの実行ディレクトリ・コマンドの文面」しか見ていないことです。公式ドキュメントは、シェルコマンドがどのファイルに書き込むかは追跡しないと明記しています。cp やリダイレクトで本体のチェックアウトに書き込むコマンドは、隔離の検査では止まらず、通常どおり permissions とサンドボックスの設定に委ねられます。PowerShell については作業ディレクトリの検査しか行われません。

言い換えると、隔離は「書く役が git 経由で本体を汚す事故」を防ぐ仕組みであって、「書く役が本体に一切触れられない」保証ではありません。本体に触れさせない線引きは、社内ルールの記事で整理した permissions.deny とサンドボックスの側で引きます。

公式ドキュメントは、memory と isolation: worktree を同じサブエージェントに付けたときの記憶の保存先を個別には説明していません。隔離した worktree は既定ブランチから分岐した一時的なコピーで、変更が無ければ消えるものです。迷いを避けるには、「点検役は記憶あり・隔離なし」「書く役は隔離あり・記憶なし」と役割ごとに分けておくのが確実です。

※ 出典: Claude Code Docs — Custom subagents / Run parallel sessions with worktrees（取得 2026-10）

5番目の .worktreeinclude は、便利さと引き換えに秘密情報の置き場を増やします。公式ドキュメントの説明では、このファイルは .gitignore と同じ構文で、パターンに一致し、かつ gitignore の対象でもあるファイルだけを新しい worktree に複製します。--worktree で始めたセッション、サブエージェントの worktree、デスクトップアプリの並列セッションのすべてに適用されます。公式の例には .env・.env.local・config/secrets.json が載っていますが、書く役のサブエージェントが鍵を必要としない業務（下書きの生成・一括置換・テストの実行）なら、入れない判断が安全側です。

---
name: monthly-report-checker
description: 月次集計レポートの下書きを点検し、数字の整合・出典の有無・社内規約との食い違いを指摘する。レビューを頼まれたら使う
tools: Read, Glob, Grep
model: sonnet
memory: project
---
あなたは月次集計レポートの点検役です。ファイルを変更せず、指摘だけを返します。

作業の前に、必ず自分の記憶（agent memory）を読み、過去に見つけた指摘のパターンと
「指摘しなくてよいと決まった例外」を確認してください。

作業の後、新しく分かった次のことを記憶に書いてください。
- 繰り返し見つかる指摘のパターン（どのファイル・どの列で起きやすいか）
- 担当者が「これは例外として許可する」と判断した項目
- 点検に使う基準ファイルの所在

記憶に書かないこと。
- 顧客・取引先・個人の名前、金額などの業務データの中身
- 認証情報、鍵、URL のクエリに含まれるトークン
- CLAUDE.md にすでに書いてあること

MEMORY.md は一行一項目の索引に保ち、詳細は別ファイルに書いてください。

点検役に「作業の前に記憶を読む」「作業の後に記憶へ書く」と明記するのは、公式ドキュメントの「Persistent memory tips」にある3つの手順（開始前に記憶を参照させる・完了後に保存させる・定義ファイル自体に記憶の指示を書く）に沿ったものです。読み取り専用の道具だけを渡していても、memory を書けば記憶の読み書きに必要な Read・Write・Edit は自動で有効になります。

※ 出典: Claude Code Docs — Custom subagents（Persistent memory tips）（取得 2026-10）

---
name: bulk-editor
description: 複数ファイルにわたる機械的な修正（表記の統一・リンクの張り替え・テンプレの一括更新）を、本体から切り離した worktree で行う
isolation: worktree
---
依頼された修正を、該当するすべてのファイルに適用してください。
修正後にテストや検証コマンドがあれば実行し、結果を報告してください。
作業は自分の worktree の中だけで行い、本体のチェックアウトには触れないでください。
本体へ取り込むかどうかは人が判断します。コミットは作ってよいですが、push はしないでください。

公式ドキュメントの例（refactorer）もこの形で、「多数のファイルにわたる機械的なリファクタを適用し、テストを実行して結果を報告する」役に isolation: worktree を付けています。worktree の中で作られたコミットは、人が内容を確認してから本体のブランチに取り込みます。

※ 出典: Claude Code Docs — Run parallel sessions with worktrees（Isolate subagents with worktrees）（取得 2026-10）

1. .claude/agent-memory/<エージェント名>/MEMORY.md を開き、行数と内容を確認する。上限（200行または 25KB）に近い場合は、古い項目の統合・削除を指示する
2. トピックファイルに業務データの中身・個人情報・認証情報が書かれていないかを検索する
3. 「例外として許可」の項目が、いまも社内の判断と一致しているかを担当者が確認する
4. 修正は通常のコード変更として PR にまとめ、レビューを通してマージする
5. 自動メモリ全体の確認には、セッション内の /memory コマンドで記憶ファイルを開く

※ 出典: Claude Code Docs — Manage Claude's memory（Audit and edit your memory）（取得 2026-10）

社内でこの手順を自分たちで組む場合の進め方は、企業向けの有料の実務書にもまとめています。

worktree の片付けは、対話セッションと無人実行で動きが違います。

※ 出典: Claude Code Docs — Run parallel sessions with worktrees（Clean up subagent and background-session worktrees） / Custom subagents（Automatic cleanup）（取得 2026-10）

掃除が残した worktree を手で消すコマンドは次のとおりです。未コミットの変更や未追跡ファイルがあるときは --force が要り、ロックされていれば先に git worktree unlock を実行します。

# 残っている worktree の一覧
git worktree list

# 変更が残っていても削除する（内容が不要だと確認したうえで）
git worktree unlock .claude/worktrees/<名前>
git worktree remove --force .claude/worktrees/<名前>

定期実行の記事で組んだような -p の無人実行で隔離サブエージェントを使うなら、実行手順の最後にこの掃除を入れておきます。放置するとディスクと、git worktree list の見通しが悪くなります。

もう一点、フックの経路に注意が要ります。サブエージェントが worktree に入っても、フックの ${CLAUDE_PROJECT_DIR} はセッションを始めたプロジェクトのルートを指したままです。worktree のパスは、フックに渡される JSON の cwd フィールドで受け取ります。監視の記事で組んだログ用のフックが「本体のパスで検証を走らせてしまう」事故は、ここを読み違えると起きます。

※ 出典: Claude Code Docs — Run parallel sessions with worktrees（Ask Claude to create a worktree）（取得 2026-10）

1. メインの会話に「覚えておいて」と言い、点検役が覚えていると思う。 メインの自動メモリはサブエージェントに読み込まれません。点検役の定義に memory を書き、点検役自身に記憶させます
2. 自社ホストの環境で memory を書いたのに何も残らない。 自動メモリが無効だと memory フィールドは効きません。環境の autoMemoryEnabled と環境変数を確認します
3. MEMORY.md に長文を書かせ続け、ある日から古い指摘を忘れる。 上限を超えた分は次回の読み込みで捨てられます。「一行一項目・詳細は別ファイル」を定義に書き、月次で棚卸しします
4. 作業中ブランチの続きを隔離サブエージェントに任せたら、main から作業を始めた。 既定の分岐元はリモートの既定ブランチです。worktree.baseRef を "head" にするか、分岐元を前提にした依頼文にします
5. 隔離したから安全だと思い、permissions を緩めた。 隔離は git を伴う操作と編集ツールしか止めません。cp やリダイレクトは permissions とサンドボックスの側で止めます

• 点検役の定義に memory があり、置き場（project / local / user）を理由付きで選んだ
• 記憶に「書くこと」「書かないこと」を定義ファイルに明記した
• 記憶に業務データの中身・個人情報・認証情報を書かせない文がある
• .claude/agent-memory/ の変更を PR レビューの対象に含めた
• 記憶の棚卸しの担当と頻度を決めた
• 実行環境で自動メモリが有効であることを確認した（自社ホストは既定で無効）
• 書く役の定義に isolation: worktree があり、分岐元（"fresh" / "head"）を決めた
• .claude/worktrees/ を .gitignore に入れた
• .worktreeinclude に秘密ファイルを入れるかを検討し、入れないか、理由を記録した
• 隔離が cp・リダイレクトを止めないことを前提に、permissions.deny とサンドボックスの設定を見直した
• -p の無人実行で作った worktree を消す手順を実行手順に入れた
• フックが worktree のパスを cwd から読むようになっている

• Custom subagents — memory・isolation を含む frontmatter の一覧、起動時に読み込まれるもの、記録の保持期間
• Run parallel sessions with worktrees — 隔離の検査、片付けの規則、worktree.baseRef、.worktreeinclude、フックでの置き換え
• Manage Claude's memory — 自動メモリの有効・無効、MEMORY.md の上限、記憶ファイルの確認と編集
• CLI reference — --worktree / -w フラグ
• Common workflows — worktree を使った並列セッションの始め方

別物です。公式ドキュメントは、メインの会話の自動メモリはサブエージェントに読み込まれないと明記しています。サブエージェントに記憶を持たせるには、定義ファイルの memory フィールドで専用の保存先を指定します。例外はフォーク（会話を引き継ぐ形）だけです。

.claude/agent-memory/ 配下の Markdown ファイルがリポジトリに入るため、バージョン管理を通じてチーム全員の Claude Code に同じ記憶が配られます。公式が推奨する既定の置き場ですが、記憶の中身が誤っていればそれも配られるので、通常のコード変更と同じレビューを通す運用にします。

ファイル編集ツールと git を伴うコマンドは止まりますが、cp やシェルのリダイレクトのように git を使わずに本体へ書き込むコマンドは止まりません。公式ドキュメントはこれを明記しており、隔離は permissions とサンドボックスの設定と併用する前提です。

変更が無ければ終了時に自動で消えます。変更が残っている worktree はディスクに残り、cleanupPeriodDays の保持期間（既定 30日）を過ぎたあとの定期的な掃除で、変更済み・未追跡のファイルや未 push のコミットが無いものだけが削除されます。手で消すには git worktree remove を使います。

定義ファイルのシステムプロンプトに「記憶に書いてよいもの・書かないもの」を明記し、記憶ファイル自体を定期的に人が読む運用にします。記憶は平文の Markdown なので、/memory コマンドやエディタでいつでも確認・削除できます。

まず、すでに動いている点検役ひとつに memory: project を足し、定義ファイルに「書くこと・書かないこと」の文を入れてください。数回の点検を回したあとで MEMORY.md を人が読み、指摘のパターンが残っているか、書いてはいけないものが混じっていないかを確認します。それが問題なく回ってから、書く役に isolation: worktree を足し、.gitignore と片付けの手順を整えます。

どの業務の点検役・書く役から始めるか、記憶のレビューや隔離の線引きを社内の権限・ログの要件にどう合わせるかを相談したい場合は、お問い合わせから現在の構成をお知らせください。契約前提ではなく、現在の定義ファイルと運用をもとに、見直す箇所を書面でお返しします。Claude 導入支援の全体像はClaude 導入支援ハブにまとめています。

• 2026-10-25: 初版公開

• Claude Code のサブエージェントで作業を分ける【2026年10月】— 調べる・書く・点検するを別々に任せる設定と、任せすぎの失敗例
• Claude Code の社内ルールの作り方【2026年10月】— フォルダ・コマンド・秘密情報を settings と CLAUDE.md で線引きする
• Claude Code を決まった時刻に動かす【2026年9月】— ヘッドレスモードの定期実行と、無人で許す操作の決め方
• Claude Code で作った自動化が止まっていないか確かめる【2026年10月】— 実行ログ・失敗の通知・やり直しの最小セット
• ハーネスエンジニアリング実践ガイド — Claude Code を「育てる」ための 5 つの型とテンプレ
• Claude 導入支援ハブ