観察を先に、修正は後に — ランタイム挙動デバッグの鉄則#
ブラウザDOM・サードパーティライブラリの出力・レンダリング後HTML・Shadow DOM・非同期描画など、ランタイムで動くものを扱うときは、修正コードを書く前に必ず実物の出力を観察する。コード読解とドキュメント知識からの推測だけで実装に進まない。
なぜ重要か#
2026年4月にMermaid v11のSVG拡大機能を実装した際、container構造を4回連続で誤って仮定し5往復を浪費した。実際にはMermaid v11はclosed Shadow DOMを使ってSVGを隔離していたが、これはコードや公式ドキュメントを読んでも分からない。最初にDevToolsのquerySelectorAll('svg')の出力を確認していれば、1〜2往復で根本原因に到達できた。
適用ルール#
- ブラウザDOM・レンダリング・動的出力に関わる修正の前に、必ず実機での観察コマンド出力を確認する
- Shadow DOM・Web Components・Custom Elementsは現代のライブラリで標準化しつつあるので最初に疑う
- setTimeoutを増やす・retryを太くする・observerを太くする、は症状ベースの後追い修正のシグナル。3回続けたら立ち止まり根本原因の観察に戻る
- 推測段階では「これが正しいと仮定して進めますが、外れたら次は実物を見せてください」と明示的に断る
関連する反パターン#
- 「とりあえず動くまで試行錯誤」モード突入
- ライブラリのバージョンアップで出力構造が変わる場合への耐性ゼロ
- 同一エラーに対する5回以上の異なる修正試行