additionalDirectoriesは権限だけ拡張する

Claude Codeが扱うディレクトリを増やす方法は3つあります。起動時の--add-dirフラグ、セッション中の/add-dirコマンド、そしてsettings.jsonに書くadditionalDirectoriesキーです。3つとも「ディレクトリを追加する」という見た目は同じですが、効果は同じではありません。additionalDirectoriesで追加したディレクトリはファイルの読み書きが許可されるだけで、そこに置いたSkillsやhooks、subagentsは一切読み込まれません。共有ディレクトリをsettings.jsonに登録して安心していたら、実は設定が一つも効いていなかった、という事故がここから生まれます。

additionalDirectoriesは権限だけ拡張する

デフォルトでは、Claudeが読み書きできるのは起動したディレクトリの中だけです。この範囲を広げる正式な入り口がsettings.jsonのpermissions.additionalDirectoriesで、settingsファイルに永続的な設定として書きます。

{
  "permissions": {
    "additionalDirectories": ["../shared-lib/"]
  }
}

このキーで追加したディレクトリは、元の作業ディレクトリと同じ権限ルールに従います。読み取りは常にプロンプトなしで通り、書き込みや編集は現在の権限モード(Manual / Auto / acceptEditsなど)がそのまま適用されます。ここまでは直感通りです。

問題はその先です。公式ドキュメントは「ディレクトリを追加してもフル設定ルートにはならない」と明記しています。settings.jsonのadditionalDirectoriesキー経由で追加したディレクトリからは、下で挙げる設定が一切読み込まれません。追加先の.claude/配下にあるSkills・commands・subagents・hooks・CLAUDE.md、それにenabledPluginsとextraKnownMarketplacesも含めて、すべて対象外です。この2つの設定キーが読み込まれるのは、--add-dirフラグや/add-dirコマンドで追加した場合だけです。共有ライブラリのディレクトリに便利なSkillを置いていても、additionalDirectoriesに登録しただけでは呼び出せません。

--add-dirとadditionalDirectoriesの挙動の違い

紛らわしいのは、同じ「ディレクトリ追加」でも--add-dirフラグと/add-dirコマンドはadditionalDirectoriesキーより多くの設定を読み込む点です。

claude --add-dir ../shared-lib

--add-dirまたは/add-dirで追加したディレクトリでは、次の設定が読み込まれます。

CLAUDE.mdの行だけ条件付きです。CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1を設定した場合に限り、--add-dir配下のCLAUDE.mdと.claude/rules/が読み込まれます。CLAUDE.local.mdはさらに、デフォルトで有効なlocal設定ソースが必要です。この環境変数を設定しない限り、--add-dirでもCLAUDE.mdは無視されます。

追加ディレクトリのcommandsとプロジェクト側のcommandsで同名のファイルがある場合は、プロジェクト側のコマンドが優先して実行されます。

サンドボックスの書き込み許可にも含まれない

Bashサンドボックスを有効にしている場合、この違いはサンドボックス側の既定にも及びます。サンドボックス化されたコマンドがデフォルトで書き込めるのは、作業ディレクトリと--add-dir・/add-dirで追加したディレクトリ、それにセッションの一時ディレクトリだけです。公式ドキュメントはこの既定の書き込み許可リストに--add-dirまたは/add-dirとだけ書いており、settings.jsonのadditionalDirectoriesキーは名前として挙がっていません。

共有ディレクトリをサンドボックス内のビルドコマンドから書き込ませたい場合は、--add-dirで追加するか、sandboxフィールドのfilesystem.allowWriteに個別のパスを足す必要があります。additionalDirectoriesに登録しただけでは、サンドボックスの外の権限プロンプトは通っても、サンドボックスの中では書き込みが拒否される可能性が残ります。

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/work/shared-lib"]
    }
  }
}

Agent SDKのadditionalDirectoriesはさらに紛らわしい

名前の一致がもう一段ややこしくなるのがAgent SDKです。TypeScript版のオプション名はadditionalDirectoriesで、settings.jsonのキーと文字通り同じ名前です。しかし挙動は--add-dir側の例外扱いを受け継ぎます。SDKは指定した各ディレクトリを内部的に--add-dirとしてClaude Codeへ渡すため、フラグで追加した場合と同じくSkillsやcommands、subagentsが読み込まれます。

Python版のオプション名はadd_dirsで、こちらは名前からして--add-dir寄りだと分かります。名前だけでは判断せず、「settings.jsonのキーそのもの」か「--add-dir扱いを受けるオプション」かを実装のドキュメントで確認するのが安全です。

ただし、--add-dir扱いを受けるからといって無条件にSkillsやcommandsが読み込まれるわけではありません。追加ディレクトリの設定はproject設定ソース経由で読み込まれる仕組みのため、SDK側で--setting-sourcesやsettingSourcesオプションからprojectを外すと、追加ディレクトリのSkills・commands・subagentsも読み込まれなくなります。また--bareモードではcommandsとsubagentsが読み込まれない点も、追加ディレクトリを使う設計では見落としやすいポイントです。

skillsやhooksを複数プロジェクトで共有する方法

additionalDirectoriesでは共有できないと分かった上で、Skillsやsubagentsを複数プロジェクトにまたがって使いたいときの選択肢は3つです。

• ユーザーレベル設定: ~/.claude/agents/や~/.claude/settings.jsonに置けば、すべてのプロジェクトで有効になります
• プラグイン化: プラグインとしてパッケージし、チームに配布します
• 設定ディレクトリから起動: 共有したい.claude/があるディレクトリそのものからClaude Codeを起動します

hooksを共有したい場合も同様で、additionalDirectoriesには期待できません。ユーザーレベルのsettings.jsonに書くか、プラグインのhooksとして配布します。

信頼ダイアログを承認するまで反映されない

もう一つ見落としやすいのが、プロジェクトの.claude/settings.jsonに書いたadditionalDirectoriesは、ワークスペースの信頼ダイアログを承認するまで適用されない点です。permissions.allowルールと同じ扱いで、フォルダを信頼していない間はダイアログに追加先ディレクトリの一覧が表示されるだけで、実際のアクセス許可は発動しません。claude -pやAgent SDKのセッションでは、この信頼ダイアログ自体が表示されないため、this workspace has not been trustedという警告がstderrに出て、追加ディレクトリのルールは黙って無効のままになります。

一方で.claude/settings.local.jsonは通常あなた自身のファイルとして扱われるため、信頼ステップなしでadditionalDirectoriesが即座に適用されます。ただしこのファイルがgit管理下にあったり、.claudeがシンボリックリンクだったりする場合は、リポジトリ提供の設定として扱われ、通常のプロジェクト設定と同じく信頼を待つようになります。この判定にはgitコマンドの実行が要るため、フォルダを信頼するまでは判定自体が保留され、ホームディレクトリなど「設定ホーム」から起動したセッションだけはgit判定なしで即座にsettings.local.jsonを適用します。

信頼した内容がどこまで及ぶかも、追加ディレクトリの権限を考えるうえで押さえておきたい点です。リポジトリ内で信頼すると、その信頼はgitリポジトリのルートに紐づき、内部にネストしたサブモジュールなどの別リポジトリを除くリポジトリ全体に及びます。worktreeの場合はメインのチェックアウトのルートが基準になります。リポジトリの外で起動した場合は、起動したディレクトリそのものに信頼が紐づき、その配下のサブディレクトリ(内部にネストした別リポジトリを除く)まで及びます。ホームディレクトリで起動したときだけは例外で、信頼は現在のセッション限りとなりディスクには保存されません。

よくある質問

additionalDirectoriesを設定したのに反映されないときは

プロジェクトの.claude/settings.jsonに書いた場合、ワークスペースの信頼ダイアログを承認するまで適用されません。まず信頼ダイアログを確認し、承認済みかどうかを見ます。

SkillsをadditionalDirectories配下に置いて共有できませんか

settings.jsonのadditionalDirectoriesキーではSkillsは読み込まれません。共有したい場合は--add-dirフラグか/add-dirコマンドで追加するか、~/.claude/skills/に置くか、プラグイン化します。

/cdでプロジェクトを移動するとadditionalDirectoriesはどうなりますか

/cdで別ディレクトリへ移動すると、settings.jsonのadditionalDirectoriesは移動先の設定値に置き換わります。一方--add-dirや/add-dirで追加したディレクトリは、移動後も保持されます。この引き継ぎ挙動が入ったのはv2.1.246以降で、それより前は/cdしても移動先の設定・hooks・MCPサーバー・Skillsはセッションを再開するまで適用されず、信頼プロンプトにも何が有効化されるかが表示されていませんでした。移動と同時に、移動前のディレクトリのプロジェクトMCPサーバーとローカルスコープMCPサーバーは切断されます。

additionalDirectories配下のファイルは編集時に確認を求められますか

読み取りは常にプロンプトなしです。編集は現在の権限モードに従うので、確認が要るかどうかはモード次第です。

macOSで~/Desktopなどを追加すると何か注意点はありますか

バックグラウンドセッションでは、~/Desktop・~/Documents・~/Downloadsのような保護フォルダへのアクセスを、ターミナルとは別にOSへ要求する必要があります。読み取りがOperation not permittedで失敗する場合は、この権限設定を見直します。

まとめ

additionalDirectoriesはファイルアクセスを広げる設定であり、設定を共有する仕組みではありません。この違いを知らないまま共有ディレクトリを登録すると、Skillsやhooksが動かない原因を.claude/の中身ではなく別の場所で探すことになります。Skillsやsubagentsを複数プロジェクトで使い回したいなら、--add-dir・ユーザーレベル設定・プラグインのいずれかを選び、additionalDirectoriesはファイルアクセスの拡張だけに使うと決めておくと迷いません。settings.jsonの全体像はClaude Code settings.json完全ガイド、権限ルールの一覧操作は/permissionsコマンド、フィールドごとの実戦レシピはClaude Code設定ガイドで確認できます。