課題：隣のフォルダにある共有部品を、AI が『見つかりません』と返す
アプリの表示を直させようとしています。構成はこれ:
~/src/acme-web ← いま作業している
~/src/acme-shared ← 表示の部品はこっちに切り出してあるMulmoTerminal で acme-web を開いて、「ボタンの色を直して」と頼みます。返事:
そのファイルが見つかりません。
ボタンは acme-shared/Button.vue にあって、AI はそれを読めません。
なぜそうなるか — AI は作業フォルダの中しか読めない
これは制限ではなく、既定として正しい挙動です。
AI が動いているのは acme-web の中です。そこから見て acme-shared は外なので、読み書きの許可がありません。
もし外も読めてしまったら、AI はマシンのどこでも読み書きできることになります。入館証に何も書いていないのと同じ状態です。~/.ssh も ~/Documents も読める AI を、プロジェクトの作業中に動かしたくはありません。
ただ、今回は外のフォルダを読んでほしい。
既存の回避策とそのコスト
一番上のフォルダから起動する
~/src から AI を起動すれば両方見えます。ただし ~/src の下には他のプロジェクトもあります。全部読まれます。範囲が広すぎます。
複数フォルダを開けるエディタで作業する
VS Code や Cursor は複数フォルダをひとつのワークスペースとして開けます。ただしターミナルで動く Claude Code や Codex は作業フォルダを一つしか持たないので、エディタ側の設定は効きません。
共有の部品を一旦コピーする
本物の修正をコピーに当てても意味がないので、作業後に手で戻すことになります。手で戻し忘れると、どちらが本物か分からなくなります。
MulmoTerminal の解決：.mulmoterminal.json の addDirs に追加フォルダを宣言する
プロジェクトのフォルダの一番上に .mulmoterminal.json を置いて、こう書きます(グローバルの ~/.mulmoterminal/config.json ではなく、プロジェクトごとの設定ファイル)。
{
"addDirs": ["../shared-lib", "/Users/me/notes"]
}このフォルダで次に開くセッションから、両方が読み書きできるようになります。
Claude Code の --add-dir フラグをそのまま使っていて、MulmoTerminal 側はそれを設定として受け取る層を増やしているだけです。CLI の既存の仕組みを使っているので、裏で何かしているわけではありません。
相対パスの基準が、事故になりやすい
ここが一番大事なところです。
相対パスは、この設定ファイルがあるフォルダを基準に解決します。 "../shared-lib" はプロジェクトの隣であって、AI が実際に動いている場所の隣ではありません。
なぜこの区別が必要か。
MulmoTerminal の worktree セッションは ~/.mulmoterminal/worktrees/<リポ>-<ハッシュ>/<タスク名>/ から動きます。そこを基準に ../shared-lib を解決すると、ハッシュ名の隣のフォルダを指すことになり、そこには何もありません。
基準は設定ファイルの場所です。書いた人が見ている景色と一致します。
worktree には引き継がれない — 権限の話
関連して、この設定は worktree に引き継がれません。意図的です。
worktree の作業ディレクトリを基準に解決すると、まったく違うフォルダを黙って許可してしまいます。この設定は「AI が読み書きしてよい場所」の宣言なので、それが意図しない場所を指すのは事故になります。
同じ理由で sound と sounds も引き継がれません(プロジェクト内のパスを指しているため)。
黙って別の場所を許可するより、引き継がないほうが安全という判断です。AI にコードを書かせていて一番怖いのは見てはいけないものを見ていたという形なので、ここが慎重なのは正しい方向です。
存在しないパスは、読んだ時点で捨てる
一つ親切な作りがあります。存在しないパスは設定を読んだ時点で捨てます。
渡してしまうと、フラグは付いているのに AI には何も見えない状態になります。症状は「AI が共有の部品を見つけられない」で、設定は書いてあるので、設定ファイルを見ても気づけません。
捨てられていれば、設定画面の Directory settings の「捨てられたキー」で、どこで落ちたかが分かります。
上限は 16 件です。
Claude Code 専用
これは MulmoTerminal の制約ではなく、CLI 側の違いです。
Claude Code には --add-dir がありますが、Codex には同等のフラグがありません。Codex のセルでは addDirs は無視されます。
同じグリッドに両方を混ぜている場合、Claude のセルにだけ効きます。
書く範囲は、いつも狭いほうを選ぶ
これは自分で気をつける部分です。
addDirs が許すのは読み書きです。書いた範囲がそのまま「AI に見せていい情報の範囲」になります。
| 書き方 | 範囲 | 判定 |
|---|---|---|
"../shared-lib" |
プロジェクトの隣の 1 フォルダ | 良い |
".." |
親フォルダ全部(兄弟プロジェクトも全部) | 広すぎる |
"~" |
ホーム全体(~/.ssh も ~/Documents も) |
やってはいけない |
AI は「見ていいものだけ見る」という判断はしません。必要だと思えば読みます。~ を書くと ~/.ssh/id_rsa も ~/Downloads/invoice.pdf も読める AI を、プロジェクトの作業中に動かすことになります。
狭く書くのが唯一の守りです。入館証に区画を一つ足す形で、全部の鍵は渡さない。
monorepo との違い
似ているので区別しておきます。
一つのリポジトリの中に複数のパッケージがある形(monorepo)なら、一番上から AI を起動すれば全部見えるので、この設定は不要です。
addDirs が要るのは、別のプロジェクトを同時に見たいときです。
- 共有の部品を別リポジトリに切り出している
- 設計のメモを別のフォルダに置いている
- 参照したい他のプロジェクトのコードがある
使ってみる
既存の MulmoTerminal インストールがあれば、addDirs は追加のインストールなしで動きます。初めての方は MulmoTerminal 完全ガイド の「使い方 3 ステップ」から。
動作確認の最小シナリオ
- プロジェクトのフォルダの一番上に
.mulmoterminal.jsonを作る(グローバルの~/.mulmoterminal/config.jsonではない) { "addDirs": ["../shared-lib"] }を書く- そのフォルダで新しいセルを開く(いま動いているセルには反映されない)
- AI に「隣のフォルダの
README.mdを読んで」と頼み、読めたら成功 - 存在しないパスは黙って捨てられるので、効かないときは綴りを確かめる(設定 → Directory settings でも確かめられる)
やめるときはその項目を消せば、元の一フォルダに戻ります。広い範囲を書いてしまったときはすぐ消してください。
まとめ
- AI は作業フォルダの中しか読めない。これは既定として正しい(マシン全体を読める AI を動かしたくない)
- 外を読ませたいときは
.mulmoterminal.jsonのaddDirsに追加フォルダを宣言する - 相対パスは設定ファイルがあるフォルダ基準。AI が実際に動いている場所基準ではない(worktree で違う場所になる)
- worktree には引き継がれない(基準が変わると黙って別の場所を許可してしまうため)
- 存在しないパスは読んだ時点で捨てられる。上限 16 件
- 書く範囲は狭く。
~はホーム全体を許可するのでやってはいけない - Claude Code 専用(Codex には同等のフラグが無い)
関連: MulmoTerminal 公式ガイドの addDirs / MulmoTerminal の worktree 隔離 / MulmoTerminal の decisionDigest で先週決めたことを AI に思い出させる
