FKScanner_PlusX では足りなかった。「Yもだよ、Zもだよ」から始まった命名再設計

統合テーブルのマージと、FKスキャナー4本のリネーム大工事。前者は作業、後者は議論になった。記事になったのは、議論のほうだ。

💡 Key Takeaway

ファイル名は、AIが読み、人間が読み、将来のツールが読むインターフェースだ。「今Xで足りる」ではなく「未来の読み手が迷わないか」で決める。命名はコードのリファクタリングではなく、UX設計だ。

リネームは、作業のつもりだった

引き継ぎ書にはこう書かれていた。

スキャナー名と実態の乖離：PlaceRight → 実はUnity負X側、LowerLeft → 実はUnity正X側。リネーム大工事予定。

命名規則の二系統混在が、物理的な位置と完全にねじれていた。PlaceRightFKScanner はUnityのX負側（白箱側）を向いているのに「Right」と名付けられている。LowerLeftFKScanner はX正側（赤ブロック側）なのに「Left」と呼ばれている。以前に符号を反転させたとき、名前だけが物理位置から取り残された。

取り掛かる前、Claude が示した初期案はこうだった。

PlaceRightFKScanner.cs → FKScanner_MinusX.cs
LowerLeftFKScanner.cs  → FKScanner_PlusX.cs
CentralFKScanner.cs    → FKScanner_Central.cs
ParallelFKScanner.cs   → FKScanner_MotionBased.cs

クラス名を置換、ログプレフィックスを置換、.meta ファイルを対でリネーム、Inspector で MissingScript 警告を確認。手順が並び、影響範囲は見えた。承認を出せば Claude Code に投げて終わる——そう思っていた。

Yの座標名、入れなくていい？

初期案を見た瞬間、問いが返ってきた。

FKScanner_MinusX.cs / FKScanner_PlusX.cs Yの座標名入れなくていい？入れた方が後々いいんじゃない？

Claude の最初の返答は論理的だった。「現時点でY軸方向のスキャン分割は無いから、Xだけで足りる。将来Y軸方向に分割する場面が来てから名前を拡張しても遅くない」。

でも、問いの本質は違っていた。

聞きたかったのは「今、必要か」ではなく「未来の自分が読んだときに誤解しないか」だった。_PlusX とだけ書かれた名前を見て、半年後に「X以外の次元は？ 高さは全域？ 奥行きは？」と毎回確認し直す未来が、見えていた。

命名は、未来への伝達だ

プログラマーの命名は、コードのリファクタリングとして語られることが多い。変数名を明確にする、クラス名を責務に合わせる、メソッド名を動詞で始める。どれも「今のコードが読みやすくなるか」の議論だ。

デザイナーの命名は、違う。

ファイル名は、ファイルを開く前に見るものだ。Finder でリストされたときに、Git のコミット履歴に並んだときに、数年後の自分や他のAIがディレクトリを見渡したときに、ファイルを開かずに意味を伝えるのが命名の仕事だ。

命名はインターフェース設計だ。未来の自分（または他のAI）に対するUXデザインだ。

UIUX 29年の直感が、ここで Claude の実装論理を追い越した。Claude は「今Xだけで足りる」という実装視点で答えた。「半年後の自分がこの名前を見て迷うか」というUX視点で問い返したのは、こちら側だった。

YだけじゃなくZもか

問いを受けて、Claude は案を書き直した。Y軸を明示する _PlusX_AnyY を提示してきた。Yは任意、Xが主軸、という意味だった。

すぐに返した。

YだけじゃなくZもか

Claude はここで、もう一つの抜けに気づいた。Unityの座標系を思い出す。

Unity座標系:  X (左右)   Y (上下=高さ)   Z (前後)
Robot座標系:  X (前後)   Y (左右)        Z (上下=高さ)

スキャナーのCSVヘッダーは ee_x, ee_y, ee_z でUnity基準だ。空間分割に使えるのは本当は2次元（XとZ、Yは高さでフィルタ条件）。初期案の PlusX/MinusX はX軸での左右分割を命名していたが、Z軸（奥行き）は暗黙に全域と仮定していた。

赤ブロックと白箱の座標をUnity XZ平面で見ると：

X軸で対称に左右、Z軸では白箱のほうが少し手前（ロボットに近い）。将来ロボットの作業エリアを4象限に分ける日が来たら、XだけでなくZでも領域分割が要る。FKScanner_PlusX_ZNeg のような命名に自然に拡張できる形になっていなければ、そのとき命名をまたやり直すことになる。

「Yもだよ、Zもだよ」と二言で言った。Claude は数段落かけてこの構造を説明した。事実を先に捉えたのは、シーンを直接触っている側だった。

＋は書けるけど、読まれない

Claude は次の案として、記号ベースを持ち出した。

FKScanner_X+.cs / FKScanner_X-.cs
FKScanner_X+Z-.cs  （複数軸の場合）

簡潔で、拡張が自然で、Unity/macOS どちらも許容する。Claude 自身「ファイル名に + を含める行儀の悪さ」と弱点を付け加えながらも、本命として推してきた。

返事は即断だった。

ファイル名に + を含める行儀の悪さ。これはダメ。別の命名規則を考えて。データはAIやサービスが読み込みやすいのは当然です。

この一文が、Claude の命名要件を書き換えた。

Claude にとって「行儀の悪さ」は「一般的には避けられている慣習」くらいの弱い制約だった。でもファイル名は人間だけでなく、AI・git・シェル・URL・JSON key・外部サービスが読み書きするデータだ。記号を含めれば、どこかのツールが引っかかる。引っかかる可能性があるなら、最初から避ける。「AIやサービスが読み込みやすい」を一次要件に置くなら、記号の選択肢は候補にも入らない。

これはUXデザイナーが日常的にやっている判断だった。インターフェースは、一番能力の低いケースに合わせて設計する。一番能力が低いのは「未知のツールが将来このファイル名を処理する」ケースだ。そこで失敗しないものを選ぶ。

FKScanner_XPos

Claude は要件を書き直した。

1. ASCII のみ、記号なし

2. キャメルケース統一

3. 語順が一貫

4. 略称でも意味が自明

5. 将来の多軸分割で破綻しない

この5条件で候補を絞り、キャメルケース + 軸名 + Pos/Neg に落ちた。

将来の拡張は自然に FKScanner_XPos_ZNeg のように伸ばせる。Pos/Neg は国際的に通じる略称で、Unity C# の PascalCase とも整合する。

最初の FKScanner_MinusX から最終の FKScanner_XNeg まで、見た目は似ている。でも後ろにある要件定義がまったく違う。前者は「Unityの座標系で方向を示した」だけ、後者は「データとしての可読性・国際性・将来拡張性を全部満たす」名前だった。対話は約15ターンかかった。

実装は、56箇所の文字列と8ファイルのリネームだった

命名が決まってからの作業は、すべて機械的だった。

Claude Code に指示書を渡した。リネーム対象は .cs 4ファイル + .cs.meta 4ファイルの計8ファイル。文字列参照の置換は PlacePosePreview.cs に4箇所、各スキャナー相互参照に6箇所、合計10箇所。ログプレフィックスは合計56箇所。3分で作業は完了し、grep での残存ゼロ確認も返ってきた。

Unity で Inspector を開くと、GameObject 名は LowerLeftFKScanner のまま残っていたが、スクリプト欄には新しい FK Scanner_X Pos (Script) が自動で追従していた。.meta ファイルを対でリネームしたので、GUID が保持され、Unity 側の参照が自動で引き継がれた。手動再リンクはゼロだった。

Hierarchy 側の GameObject 名は C# コードから参照されていないことを grep で確認してから、Unity で4つ分リネームした。

Plastic へのチェックインは Moved 扱いのファイルを直接 cm ci で指定してもエラーになり、最終的に cm ci --all で一括コミットした。

cs:103  [DAY158] 統合テーブルマージ 512,088行
cs:104  [DAY158] シーン保存 + PlacePosePreview.cs 文字列参照更新
cs:105  [DAY158] FKスキャナーリネーム本体（Moved 8件）

Plastic が「Modified and moved」という形で履歴を残してくれた。あとで cm log を遡れば、PlaceRightFKScanner から FKScanner_XNeg へのリネームが一本の線で辿れる。

統合テーブル512,088点、最近傍0.30mm / 0.43mm

命名議論の裏側で、もう1つ仕事をしていた。

以前に4スキャナー全てを「グリッパ先端Brep中点」基準に再生成していた。そのCSVを1本にマージした。

fk_scan_motion_based.csv    : 134,456
fk_scan_central.csv         :   7,235
fk_scan_lowerleft_dense.csv : 354,294
fk_scan_place_right.csv     :  16,102
                    合計    : 512,087点

マージ後、赤ブロック・白箱それぞれへの最近傍距離を確認した。

lookup 閾値100mm に対して両方サブミリ。Pi 側の r2r2r_loop.py が統合テーブルを引けば、動的追従が成立する条件は揃った。

命名が終わった後に残るもの

リネーム大工事は終わった。Plastic にチェックインが入り、CLAUDE.md に命名規則が追記された。次にスキャナーを触るときは「FKScanner_XPos は Unity X正方向の赤ブロック側で、将来Z軸分割したければ _ZNeg を足せばいい」と即座に理解できる。

でも本当に残ったのは、対話のほうだった。

Claude は3回、問い返された。「Yの座標名入れなくていい？」「YだけじゃなくZもか」「ファイル名に + はダメ」。そのたびに、命名の要件定義が浅いことに気づいていった。最初は「今機能する名前」、次は「Unity座標系で正しい名前」、最後に「AIやサービスが読み込みやすい名前」と、要件のレイヤーが降りていった。

デザイナー29年の直感は、ファイル名という最小のインターフェースの上でも働いていた。

命名は、UX設計だ。そして UX 設計に「十分」はない。未来の読み手にとって一番能力の低いケース——半年後の自分、初見のAI、未知のツール——に合わせて作るしかない。そう思い出させてくれたのが、FKScanner_XPos.cs というたった1つのファイル名だった。

※ プロジェクト名「R2R2R」は、UC Berkeley・Toyota Research Instituteの研究「Real2Render2Real」（Yu, Fu et al., 2025）の概念に触発されています。現実空間をデジタルツイン化し、仮想空間での試行から得た知見を実世界のモーター駆動へ還元する——その設計と実装過程を毎日記録しています。技術アプローチおよび目的は独自のものです。