【体験談】iCloud Drive と開発環境を混ぜたら地味にハマった話と、やめておいた方がいい理由
はじめに
自分の知識不足だっただけなのですが、ある日突然 Claude Code が謎のエラーを吐き続けて全く開発できない、Cursor を再起動してもファイルを読み込めず、ずっと真っ黒──そんな謎現象が起きました。
macOS 側の問題なのか、開発環境なのか、ファイルなのか、当初はまったく原因がわからず、本当に困りました。
最終的にはなんとか復旧できましたが、同じトラブルに遭う人が少なくなるよう、今回の経緯と学びを共有しておきます。
結論
原因が本当にこれなのか 100% ではありませんが、
iCloud の同期が ON のフォルダ内で開発するのは避けたほうがいい というのが今回の結論です。
iCloud の同期外にある ローカルフォルダで開発するほうが無難 です。
理由としては、おそらく以下のような点が影響していると考えています：
- iCloud は大量のファイル更新（I/O）を同期するのが苦手
- Claude Code や Antigravity などは多数のファイルを高速で読み書きする
- その結果、ファイルコピー・編集・読み込みがうまくいかなくなることがある
- 壊れたあとに復旧するのが意外と面倒
なにが起きたのか？
ある日、Cursor（またはエディタ）が突然：
- Claude Code でファイルが読み込めないエラーが多発
- Cursor でプロジェクトを読み込めない
- Cursor / Antigravity が真っ黒のまま動かない
- Finder でコピーができない
-
cpやrsyncがタイムアウトする
など、明らかに通常では起きない不具合が連続で発生しました。
最初は「エディタのバグかな？」と思っていましたが、
調べるほど怪しくなっていったのが iCloud Drive の同期状態 でした。
iCloud Drive 内のフォルダの状態
- 「アップデートを待機中 ☁️」のまま進まない
- 一部のファイルが開けない
- 実体ファイルがどこにあるのか分からない
開発環境を iCloud 管理下に置いていたため、
そこで大量に発生するファイル更新が同期処理に負荷をかけたのでは、と推測しています。
iCloud 同期と開発の相性が良くない理由（推測）
iCloud は 普段使いのドキュメントや写真の同期にはとても便利です。
ただし、Claude Code などで高速に大量のファイルが書き換わるディレクトリを同期しようとすると、
内部の状態管理が追いつかず、結果として挙動が不安定になる……
そんな印象を受けました。
どう対処したか？
了解！
復旧手順の部分を シンプルで読みやすく、短く、ポイントだけ にまとめ直しました。
Zenn でも読みやすい長さにしています。
どう対処したか？（簡潔版）
最終的には、以下の手順で復旧できました。(githubにある程度残っていたので、無理に復旧する必要はなかったのですが、、）
1. iCloud の「デスクトップと書類フォルダの同期」を OFF にする
まず、開発フォルダを iCloud 管理から外すため、
システム設定 → Apple ID → iCloud → iCloud Drive → オプション
→ 「デスクトップと書類フォルダ」を OFF
を実行しました。
2. Apple ID を一度サインアウト → 再ログイン
同期を OFF にしただけでは復旧処理が動かなかったため、
Apple ID を一度サインアウトし、すぐ再ログインしました。
これにより、iCloud の内部データが再読み込みされ、
macOS が自動で復旧プロセスを開始しました。
3. 「iCloud Drive（アーカイブ）」フォルダが自動で作成された
再ログイン後、ホームディレクトリに
iCloud Drive（アーカイブ）
というフォルダが生成され、
元の iCloud 管理下の書類データがここに移動されていました。
この中から必要なプロジェクトを救出できます。
4. 開発用ディレクトリをローカル（~/Development）に作成し移動
今後同じことが起きないように、
ローカル専用の開発フォルダとして
~/Development
を作成し、
必要なプロジェクトをここに移動しました。
おわりに
久しぶりに開発環境のエラーが起きて、非常にストレスがかかりました。環境自体がうまくいかない時って、かなり気分損なわれますよね。一番楽しくない作業。こんな非生産的な時間をすごしたのは久々でした。みなさまにはこんなこと起きないこと祈ってます
Discussion