AIにFigmaのデザインを実装させるとき、規約チェックやチェックリストを何枚重ねても、再現度が低い実装は相変わらず出てくる――そんな経験はないだろうか。
うちのチームでも同じことが起きていた。照合フロー（スクショを撮ってFigma基準と見比べ、直してまた見比べる一連の手順）を通した実装は再現度が高い。だが、そのフローを使わない小さな修正では、再現度が落ちる。lintを足しても、規約チェックを足しても、チェックリストを足しても、この傾向は変わらなかった。
この記事で分かること
- 「照合artifact（工程の記録ファイル）の有無」と「あとから見つかる指摘件数」の実測相関
- 品質ゲートを増やしても再現度が上がらなかった理由
- 重い照合フローを避けて小修正が”素書き”に逃げる構造そのものへの対処法
背景：ゲートを増やしても、低い再現度は消えなかった
AIにFigmaを実装させる仕組みには、もともと品質ゲート（lint・命名規約チェック・完了前チェックリスト）を何段も用意していた。狙いは「悪い実装を通さないこと」。
ところが、実際に低い再現度が出るのは、ゲートをすり抜けた実装ではなかった。むしろ、フルの照合フローを一度も回さないまま「完了」と報告された実装だった。フルの照合フローはスクショ取得・基準比較・修正・再比較を繰り返すぶん重く、1〜2行の小さな修正のたびに回すには気が重い。その重さのせいで、小修正はフローを迂回して直接コードを触る”素書き”に流れていた。
結論：差は腕でなく、工程だった
チームの実装記録（工程ごとに残る記録ファイル一式）を横断して調べたところ、はっきりした差が出た。
- 照合ループを最後まで回し切ったページ：スクショ比較→修正→再比較を4周繰り返して、指摘0件まで収束。工程の記録ファイルも一式そろっていた
- 照合ループを一度も回さなかったページ：照合の記録ファイルが1件も存在しないまま「完了」と報告 → あとから見つかった指摘が21件（再チェックで見つけた分が7件、私の目視で見つけた分が14件）
同じチーム・同じ仕組みで作業していて、この差が出た。再現度を分けたのは実装者の腕前ではなく、照合ループを回したかどうかという工程の違いだった。
しくみ：ゲートは関所、収束ループは基準との往復
ここで整理しておきたいのは、ゲートと収束ループの役割の違いだ。
| 役割 | 何をするか | 再現度を上げるか |
|---|---|---|
| 品質ゲート（lint・規約チェック・チェックリスト） | 「悪いものを止める」判定だけをする | 上げない。通過/不通過を仕分けるだけ |
| 収束ループ（スクショ→基準比較→修正→再比較） | 基準（Figma）と実装を実際に見比べて近づける | 上げる。往復した回数だけ差が縮まる |
関所（ゲート）をどれだけ厳しくしても、そこを通る実装の中身は変わらない。中身を基準に近づけるのは、基準と何度も往復する工程そのものだ。一度も基準画像と比較しなければ、いくら判定を重ねても再現度には近づかない。
実測でも、この違いがそのまま結果に出ていた。
| 項目 | 回し切ったページ | 回さなかったページ |
|---|---|---|
| 照合の往復回数 | 4周 | 0周（記録なし） |
| 収束時の指摘件数 | 0件 | ―（未計測） |
| 完了報告後に見つかった指摘 | ― | 21件（自己発見7＋指摘14） |
| 照合の記録ファイル一式 | すべてあり | すべてなし |
もう一つの発見：指摘の大半は、そもそも静止画照合では捕まらない種類だった
あとから見つかった指摘を1件ずつ症状で分類すると、意外な傾向が出た。大半は「Figmaと見比べれば分かる静的なズレ」ではなく、動きや実データが絡む種類だった。
- 特定の画面幅の帯だけで要素がはみ出す（中間幅の崩れ）
- スクロール追従の挙動が途中で止まる／潜り込む
- 仮データを本番相当のデータに差し替えたときだけ出る文字数オーバー
- 特定のブラウザだけで折り返しが変わる（クロスブラウザ差）
これらは、静止画1枚をFigmaの基準と比べる自動照合では原理的に検出できない。実ブラウザで幅を動かしながら見て、初めて見つかる種類のものだ。
ここは正直に書いておきたい。「照合を回さなかったから指摘が出た」のは事実だが、「照合さえ回せば全部防げた」わけではない。ゲートや照合ツールを責める前に、そもそも何を検出できる設計になっているかを疑う必要がある、というのがもう一つの学びだった。
手順：重い照合フローの”軽い入口”を作る
構造上の原因ははっきりしていた。フルの照合フローが重いから、小修正が素書きに逃げる。逃げ先を塞ぐのではなく、逃げなくて済む軽い入口を用意することにした。
やったことは3つ。
- 適用範囲を客観基準で決める：新規ページ・新規セクション・DOM構造の大幅な組み直しはフルフローへ。それ以外の「既存実装への部分修正で、Figma基準がすでにある」ケースだけを軽量入口の対象にする。「今回は急ぎだから」で自己申告して範囲を広げるのは禁止にした
- 照合ループだけを切り出す：フルフローから、実装計画書のような重い前工程を省き、「スクショを撮る→基準と比べる→直す→また撮る」の往復だけを残した。往復の停止条件（最大周回数・変化がなくなったら止める）はフルフローと共通の値を流用し、軽量版のためだけの別基準は作らない
- 出口側の素通りも塞ぐ：照合の記録ファイルが無いのに「見た目は確認した」として通過扱いにできないよう、出口のチェック側にも歯止めを入れた。記録が無ければ、その項目は「未確認」と申告することが必須になる
軽い入口を作ったこと自体より、「使う気になる重さまで軽くした」ことが要点だった。重いフローを維持したまま「ちゃんと回せ」と言い続けても、忙しいときは素書きに逃げる。逃げ先の方を、回しても苦にならない設計に変えた。
コスト感・効果
- 収束まで回したページ：往復4周・最終指摘0件・記録ファイル一式（実装計画・照合結果・自動チェック結果）が全部そろっていた
- 回さなかったページ：記録ファイルが1件も無いまま完了報告 → 再チェックと目視指摘で合計21件
- 症状別に見ると、指摘の大半（6分類中4分類）は静止画照合の検出範囲の外側（動的挙動・実データ・クロスブラウザ差）だった。照合ループを回すことと、検出範囲を広げることは別の対策として両方必要
まとめ
- 品質ゲート（lint・規約チェック・チェックリスト）は「悪いものを止める」判定装置であって、再現度そのものを作らない
- 再現度を作るのは、基準画像と実装を何度も見比べる収束ループ。今回は4周回して指摘0件まで収束させたページと、1周も回さず記録ゼロで「完了」報告したページで、あとから21件の指摘という差が出た
- 差は実装者の腕前ではなく、照合ループを回したかどうかという工程の違いだった
- 見つかった指摘の大半は、動きや実データが絡み静止画照合では原理的に検出できない種類だった。ゲートを責める前に、検出範囲の設計を疑う
- 重いフローを維持したまま「ちゃんと回せ」と言い続けるのではなく、照合ループだけを切り出した軽い入口を作り、小修正が素書きへ逃げずに済む距離まで近づけた
AI実装のFigma再現度・照合フローの仕組み作りのご相談は、お問い合わせからどうぞ。