✅ 解決方法

Macをご使用の場合、内蔵ストレージ・外付けストレージに関わらず、プロジェクトのパスに「日本語（マルチバイト文字）」が含まれていると発生します。
フォルダ名を「半角英数字」に変更すると解決する可能性があります。

Mac環境において、パスに日本語（特に濁点・半濁点を含む文字）が含まれていると、エージェントがバックグラウンドで実行するシェルがカレントディレクトリを正しく認識できず、コマンド実行前にフリーズ（無限待機）したり、アクセス権限エラーになったりする現象が確認されました。
例:

• ❌ NG: /dev/日本語プロジェクト名/app
• ✅ OK: /dev/project-name/app

フォルダ名を変更し、VS Codeで開き直すことで、すべてのコマンド機能が正常に動作するようになります。

また、試してはおりませんが、おそらくAntigravityに限らず、VSCodeまたはVSCodeからフォークされたエディタ（ Cursorなど ）でも発生する可能性があります。

🔍 検証プロセスと原因特定までの流れ

今回発生した「コマンドを実行すると処理が止まってしまう」現象に対し、以下の手順で切り分けと検証を行いました。

1. 現象の確認

• 症状: npm run dev などの長時間実行コマンドだけでなく、ls -F や echo といった一瞬で終わるはずのコマンドも含め、すべてのコマンド実行が "Running…" のまま進行しなくなる。
• 環境: macOS, VS Code, 作業ディレクトリは外付けSSD上 (/Volumes/SSD/...)。

2. 仮説と検証

仮説①：永続プロセスの残留

サーバー起動コマンドなどがバックグラウンドに残り、エージェントがその終了を待ち続けているのではないか？

• 検証: VS Codeの再起動（Developer: Reload Window）およびアプリの完全終了・再起動を実施。
• 結果: 改善せず。単純なコマンド実行でも即座にフリーズする。

仮説②：ディスクアクセス権限と接続不良

外付けSSDへのアクセスが macOS のセキュリティ機能（SIP/TCC）にブロックされている、またはSSDの接続が不安定なのではないか？

• 検証:
  • Finderでのアクセス確認 → 正常に閲覧可能。
  • 「システム設定 > プライバシーとセキュリティ > フルディスクアクセス」に VS Code と Terminal を追加。
  • SSDの物理的な再接続。
• 結果: 改善せず。権限周りの問題ではない可能性が高い。

仮説③：パスに含まれるマルチバイト文字（日本語）の影響

作業ディレクトリ名「日本語プロジェクト名」に含まれる日本語文字コード（NFD/NFC問題など）が、シェルのパス解決処理に干渉しているのではないか？

• 検証:
  • 日本語を含まないテスト用ディレクトリ /Volumes/SSD/dev/test を作成。
  • 同ディレクトリ内でエージェントによるコマンド実行 (ls -F) をテスト。
• 結果: 成功。テスト環境では即座にコマンドが応答した。

仮説④：ディスクの種類（外付けSSD vs 内蔵ストレージ）の影響

日本語パスの問題が「外付けSSD」特有のものか、ディスクの種類に関わらず発生するのか？

• 検証:
  • プロジェクトを Mac本体の内蔵ストレージ（/Users/...）へ移動。
  • 日本語パス（.../日本語プロジェクト名/...）を維持した状態でコマンド実行をテスト。
• 結果: 失敗（実行不可）。
  • 今度はフリーズではなく、即座に「ワークスペースへのアクセス権限エラー」が発生。
  • Macのファイルシステムにおける日本語（濁点・半濁点）の文字コード正規化（NFD/NFC）の違いにより、エージェントが指定されたパスを「許可されたワークスペースとは異なるパス」と誤認し、セキュリティブロックが働いたと考えられる。

3. 原因の特定

検証の結果、外付けSSDか内蔵ストレージかといったディスクの物理的な配置には関係なく、「作業ディレクトリのパスに日本語が含まれていること」が根本的な原因であることが確定しました。

これはmacOSのファイルシステム特有のNFD（Normalization Form D）と、ツール側が期待するNFC（Normalization Form C）というUnicode正規化形式の違いに起因しています。この文字コードの差異がパス解決処理に干渉し、フリーズ（デッドロック）や権限エラー等の不具合を引き起こします。

ディレクトリ名を英数字（project-name）に変更した後は、すべての機能が正常に動作することを確認しました。