Claude Codeのadd-dirで「couldn't be resolved」と出る原因と対処
作業ディレクトリ配下のサブディレクトリを/add-dirしたとき、実体パスを解決できずskills・commands・agentsが読み込まれない場合の意味と、確認手順を示します。
/add-dir packages/appを実行すると、「packages/app couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded」と表示されることがあります。意味は、そのディレクトリの実体の場所を解決できなかったため、中の.claude/にあるskills・commands・agentsを読み込まなかった、というものです。
ファイルへのアクセスが失われるわけではありません。読み込みが見送られただけです。この記事では、メッセージが出る条件、何が読み込まれなかったのか、確かめる順番を示します。
このメッセージは何を伝えているのか
出るのは、作業ディレクトリのサブディレクトリを/add-dirしたときです。作業ディレクトリの外を追加したときの話ではありません。
サブディレクトリは、追加しなくてもすでに読み書きできます。そのため、この場面での/add-dirの役目は、そのディレクトリの.claude/配下にあるskills・commands・agentsを読み込むことだけです。
読み込む前に、Claude Codeは次の確認をします。
- ディレクトリの実体の場所を、シンボリックリンクをたどって解決する
- その実体が作業ディレクトリの内側にあるか調べる
1の解決に失敗すると、何も読み込まずに次の文言を出します。
packages/app couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded. Check that it is a directory inside the working directory and try again.末尾は「作業ディレクトリの内側にあるディレクトリか確認して、もう一度試してください」という案内です。
ファイルアクセスは変わらない
メッセージが示すのは「.claude/の中身を読み込まなかった」ことだけです。サブディレクトリのファイルは、このエラーの前後で変わらず読み書きの対象です。権限の問題ではないので、permissionsの許可ルールをいじっても直りません。
何が読み込まれなかったのか
サブディレクトリを/add-dirすると、セッションの残りの間、次のものが読み込まれます。プロンプトは出ず、作業ディレクトリの追加も起きません。この動作にはClaude Code v2.1.257以降が必要です。
| 置き場所 | 読み込み | 変更の反映 |
|---|---|---|
.claude/skills/ | 読み込み読み込まれる | 変更の反映自動で反映される |
.claude/commands/ | 読み込み読み込まれる | 変更の反映再起動が要る |
.claude/agents/ | 読み込み読み込まれる | 変更の反映再起動が要る |
メッセージが出ると、この3つがまとめて読み込まれません。症状としては、/メニューに期待したskillが出ない、サブエージェントを名前で呼べない、といった形で現れます。
読み込まれないものの線引きも押さえておきます。CLAUDE.mdや.claude/rules/は、/add-dirでは読み込まれません。環境変数CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1を設定したときだけ対象になります。settings.jsonも、読まれるのはenabledPluginsとextraKnownMarketplacesの2つのキーだけです。
「/add-dirしたのにルールが効かない」という症状の多くは、このエラーではなく、そもそもCLAUDE.mdの読み込み対象外という仕様に当たっています。メッセージが出ていないなら、こちらを疑います。
直し方の手順
案内は2点だけです。パスが作業ディレクトリ内の実在するディレクトリを指しているか確かめ、もう一度/add-dirを実行します。再起動は不要で、直したあとは同じセッションで再実行できます。
メッセージが出たときの切り分け
- Q/add-dirに渡したパスは、起動したディレクトリの内側にあるか?答えがいいえのとき答えがはい
作業ディレクトリの外なら、この仕組みの対象外です。外側のディレクトリは、起動時の
--add-dirか/add-dirでふつうに追加します。 - Qそのパスは実在するディレクトリか?答えがいいえのとき答えがはい
綴り、相対パスの起点、消えたディレクトリを疑います。実在する名前で
/add-dirをやり直します。 - Qパスの途中にシンボリックリンクを含むか?答えがはいのとき答えがはい
リンクの先が実在し、かつ作業ディレクトリの内側にあるかを確かめます。リンク切れや、外へ向いたリンクは条件を満たしません。
実体が作業ディレクトリ内の実在ディレクトリなら、もう一度実行
それでも出るなら、次の節の自動マウントの場合を確認します。
メッセージからは、個々のパスがなぜ解決できなかったかまでは分かりません。そこで、実体のパスをシェルで先に見ておくと切り分けが速くなります。次はその一例です。
# 作業ディレクトリのルートで実行
pwd -P # 作業ディレクトリの実体パス
ls -ld packages/app # リンクなら -> で行き先が出る
(cd packages/app && pwd -P) # 解決後の実体パス。失敗すれば実在しない2行目の出力が->を含めばシンボリックリンクです。3行目の結果が1行目のパスで始まっていれば、実体は作業ディレクトリの内側にあります。始まっていなければ外へ出ていて、チェックの前提から外れます。これはシェルでの確認方法であり、Claude Code内部の判定そのものを再現するものではありません。
自動マウント上ではv2.1.261より前に誤って出ていた
作業ディレクトリが/net/<host>の自動マウント上にあるときは、事情が違います。v2.1.261より前は、/add-dir <サブディレクトリ>のたびにこのメッセージが出ていました。
原因はパスの側ではありません。Claude Codeはネットワーク上のパスを引くとホストに接触して通信が発生することがあるため、自動マウントのパスは実体解決をしない設計になっています。そのため、ディレクトリ自体は正常でも解決に失敗したことになり、何度やり直しても結果は変わりませんでした。
v2.1.261の更新内容には、この誤表示の修正が「/netの自動マウント上で/add-dir <サブディレクトリ>が誤って『couldn't be resolved』を出す問題を修正」として載っています。v2.1.261の更新内容は/skill-doctorや出力上限の設定が目立ちますが、バグ修正の項目に含まれています。自動マウント上でこの症状が出るなら、まずバージョンを確認します。
claude --versionv2.1.261以降でも出る場合は、自動マウントではなく、通常のパス側の問題を疑います。
似た警告との見分け方
/add-dirまわりには、文言の近い別のメッセージがあります。
2つのメッセージの違い
couldn't be resolved to a real location
作業ディレクトリ内のサブディレクトリが対象です。ファイルアクセスは維持され、.claude/の読み込みだけが見送られます。
is a network path, which cannot be added
UNC共有などを作業ディレクトリに加えようとした場合の拒否です。ディレクトリそのものが追加されません。仕様と回避策はnetwork path警告の記事にまとめています。
見分けるポイントは、渡したパスが作業ディレクトリの中か外かです。中なら本記事の話、ネットワーク上の場所なら後者です。
settings側の設定で読み込みが止まっている場合
メッセージが出ていないのに、/add-dir後もskillsが現れないことがあります。次の設定や起動モードでは、--add-dir由来の読み込み自体が制限されます。
project設定ソースを外している(--setting-sourcesなどで除外した場合)strictPluginOnlyCustomizationのポリシーが有効- bare modeや
--safe-modeで起動している
また、settings.jsonのpermissions.additionalDirectoriesに書いたディレクトリは、ファイルアクセスを与えるだけで、skills・commands・agentsを読み込みません。「設定ファイルに書いたのにskillが出ない」場合は、--add-dirか/add-dirに切り替えます。
追加の経路が使われたかどうかを記録したい場合は、DirectoryAddedフックの記事にあるように、/add-dir直後に発火するフックで監査する方法もあります。
読み込みを待たずに済むケース
そもそも/add-dirが要らない場面もあります。作業ディレクトリより下にある.claude/skills/は、起動時には読み込まれません。Claudeがそのサブディレクトリのファイルを初めて読むか編集した時点で読み込まれ、以降はセッション中使えます。読み込まれるまでは/メニューに出ず、名前で呼べません。
すぐ呼びたいなら/add-dir、使うときに読み込まれれば足りるならそのままで構いません。その違いだけです。skillsの置き場所ごとの読み込み規則はClaude Code Skillsの解説にも整理があります。
具体例 — モノレポでpackages/appのスキルを呼び出す
たとえば、モノレポのルートでClaude Codeを起動し、packages/appの下に専用のskillを置いているとします。
repo/
packages/
app/
.claude/
skills/
release-check/
SKILL.md
agents/
app-reviewer.mdルートで起動した直後は、release-checkは/メニューに出ません。packages/appのファイルをClaudeが読むまで読み込まれないためです。/add-dir packages/appを実行して通れば、release-checkとapp-reviewerがそのセッションから使えます。
通ったかどうかは、/メニューにrelease-checkが現れるかで確かめられます。出ていなければ、本記事のメッセージが出ていないか、直前の出力を見返します。メッセージも出ず、メニューにも現れない場合は、前節の設定ソースやポリシーの制限が候補です。
.claude/agents/に置いたファイルは、追加後に編集しても反映されません。編集したらセッションを再起動します。skillの編集だけは、同じセッション内で反映されます。
まとめ
メッセージは「.claude/の中身が読み込まれなかった」だけを伝えていて、ファイルアクセスは損なわれません。手元で試す順番は、パスの実在確認、シンボリックリンクの行き先確認、バージョン確認の3つです。自動マウント上のv2.1.261より前なら、パスを疑う前にまず更新です。通常のパスなら、まずシンボリックリンクを疑います。それ以外で読み込みが止まるときは、設定ソースやポリシー側を見ます。