macOSで半濁点入りフォルダ名がls/grepにヒットしない ―― 原因はUnicode正規化(NFD)だっとという話

macOSでフォルダやファイル名に半濁点を含む日本語を使うと、lsやgrepといったコマンドが「そんなファイルは存在しない」と返すことがある。見た目は明らかにそこにあるのに、ターミナルからは幽霊のように見えない。この奇妙な症状は、ファイルシステムが日本語文字をUnicodeの異なる正規化形式で保存しているために起きる。macOSのAPFSは内部的にNFD（分解形）を使うが、ユーザーが入力する文字列のほとんどはNFC（合成形）だ。見た目は同じ「ポ」でも、内部では別物として扱われる仕様になっている。

エンジニアにとっては既知の落とし穴だが、AIエージェント（Claude Codeなど）にMac上でファイル操作をさせる場合、この問題が急に表面化する。エージェントがファイル名を検索して「無い」と判定し、処理をスキップしてしまう、という失敗が起きやすいからだ。ワイルドカード指定で半濁点を避けるか、Pythonの場合は正規化を揃えてから比較する、といった回避策がある。この問題が発生する背景には、自動処理とファイルシステムの仕様の微妙なズレがあり、ユーザーが気づきにくい形で潜在しているという点がある。

実務の視点では、自動化の対象になるフォルダやファイルには、最初から半濁点を含めない命名規則を使うのが無難だ。「システムが正しく処理できるようにデータを整える」という原則が、ここでも効く。AIに操作させる対象は、英数字ベースの名前にしておくと、こうした不可視の仕様差による失敗を避けられる。