From e1f1ba64279d4241cafcb3d83774b36237d7e31d Mon Sep 17 00:00:00 2001
From: nyash-codex <codex@nyash.local>
Date: Fri, 5 Dec 2025 22:01:59 +0900
Subject: [PATCH] docs: Add NYASH_TRACE_VARMAP debug guide to MIR debugging
 section

---
 CLAUDE.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 1ee594ba..6ad2fdb0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -36,6 +36,13 @@ NYASH_OPTION_C_DEBUG=1 cargo test --release TEST_NAME 2>&1 | grep "Option C"
 # LoopForm デバッグ
 NYASH_LOOPFORM_DEBUG=1 cargo test --release TEST_NAME 2>&1 | grep "loopform"
 
+# variable_map トレース (JoinIR PHI接続デバッグ) ⭐超重要
+NYASH_TRACE_VARMAP=1 cargo test --release TEST_NAME 2>&1 | grep "varmap"
+# 出力例:
+#   [trace:varmap] pattern3_before_merge: sum→r123, count→r124
+#   [trace:varmap] pattern3_after_merge: (merge完了後)
+#   [trace:varmap] pattern3_exit_phi_connected: sum→r456(final)
+
 # 完全MIRダンプ（テスト時）
 NYASH_MIR_TEST_DUMP=1 cargo test --release TEST_NAME 2>&1 > /tmp/mir_dump.log
 
@@ -49,6 +56,26 @@ for i in 1 2 3; do
 done
 ```
 
+##### 🎯 **NYASH_TRACE_VARMAP の威力**
+
+**何ができる？**
+- JoinIR → MIR merge 時の variable_map 変化を可視化
+- Pattern 3 のような複雑な PHI 接続を段階的に追跡
+- Exit PHI が正しく variable_map に接続されたか確認
+- バグ発見時間: **1.5時間 → 30秒** に短縮！
+
+**戦略的なトレース点**:
+- `pattern3_before_merge`: Merge 実行前の ValueId マッピング
+- `pattern3_after_merge`: Merge 直後の状態
+- `pattern3_exit_phi_connected`: Exit PHI が variable に接続された最終状態
+
+**使用例**:
+```bash
+# Pattern 3 バグの高速診断
+NYASH_TRACE_VARMAP=1 cargo test --release test_loop_with_if_phi_sum -- --nocapture 2>&1 | tail -20
+# → sum の ValueId 変化が一目瞭然！
+```
+
 #### 📊 **重要な発見：HashMap非決定性**
 - Rustの`HashMap`/`HashSet`はHashDoS対策でランダムseed使用
 - PHI生成順序が毎回変わる → ValueId割り当てが変動