ソフトウェアチームはツールチェーンに決定論を組み込むために何十年も費やしてきました。パッケージマネージャー用のロックファイル。コンテナ用のピン留めされたベースイメージ。コンパイルされたアーティファクトの再現可能なビルド。原則はよく理解されています。同じ入力は常に、どのマシンでも、いつでも同じ出力を生成すべきです。

デザインハンドオフはこの原則を適用したことがありません。デフォルトで、根本的に人間的であり、したがって非決定論的なプロセスでした。デザイナーがデベロッパーにデザインを説明します。デベロッパーがそれを解釈します。解釈は人によって、日によって、Zeplinのコメントがどれほど明確に書かれていたかによって異なります。それを再現することはできません。テストすることもできません。差分を取ることもできません。

AIコーディングエージェントの世界では、非決定論的なハンドオフは一流のエンジニアリング問題となっています。figmascope は凍結されたポータブルなコンテキストバンドルでそれに対処します。

現在のツールがエージェントに対して非決定論的な理由

ZeplinとAvocodeはFigmaから抽出した数値（レイヤーの寸法、カラー値、フォントサイズ）を提供します。しかし、それらは機械可読なアーティファクトではなく、ブラウザブルなUIとして提供します。Zeplinを指したエージェントは値を見つけるためにUIをナビゲートしなければならず、これは脆弱で、レートリミットがあり、注釈の書き方に依存します。

Figma Dev Modeはさらに進んでいます。デザインからインラインで生成されたコードスニペットを提供します。しかし、スニペットはステートレスです。オンデマンドで再生成され、バージョン管理されていません。チェックインできるバンドルはありません。差分を取れるファイルはありません。デザイナーがデザインを更新すると、Dev Modeビューはサイレントに更新されます。最後にエクスポートしたものと比較して、基礎となるデザインがいつ変更されたかわかりません。

スクリーンショットは最悪のケースです。純粋なピクセルデータで、解析するのが完全に非決定論的で、毎回異なる構造推論を生成します。

ライブMCP接続（エージェントにFigmaファイルへのリアルタイムAPIアクセスを与えるツール）は定義上非決定論的です。エージェントがそれを読んでいる間にファイルが変わります。エージェントの午前9時の実行と午後2時の実行では異なる入力が見えます。ソースが変わったため、午前9時の実行を再現することはできません。

エージェントは確率的なシステムです。非決定論的な入力を与えることは単にばらつきを生むだけではありません。システムをテスト不可能にします。悪い出力がモデルによるものか、プロンプトによるものか、誰かが実行の間にレイヤーを移動したことによるものかを区別できません。

コンパイルユニットとしてのバンドル

figmascope のエクスポートの適切なメンタルモデルはコンパイルアーティファクトです。コンパイラがソースコードを取り込んで決定論的なバイナリを生成するように（同じソース、同じフラグ、同じバイナリ）、figmascopeはFigmaファイルの状態を取り込んで決定論的なバンドルを生成します。同じファイル状態、同じバンドル、毎回。

バンドルは凍結されたスナップショットです。デザインの特定のバージョンをキャプチャし、関連するすべてのプロパティをシリアライズします。空間レイアウト、コンポーネントアイデンティティ、トークンバインディング、文字列コンテンツ、階層。エクスポートされると、バンドルは不変です。Figmaファイルは変わるかもしれませんが、バンドルは変わりません。それらの変更を組み込みたい場合は、再エクスポートして新しいバンドルを取得します。

これがコンパイルユニットモデルです。デザインファイルはソースです。バンドルはアーティファクトです。エージェントはアーティファクトを消費し、ソースは消費しません。

決定論的ハンドオフの4つの特性

スナップショット可能。 ハンドオフアーティファクトは特定の時点を表す必要があります。「Figmaファイルの現在の状態」ではなく、名前付きのバージョン管理されたエクスポートです。figmascopeバンドルにはエクスポートタイムスタンプと含まれているもののフィンガープリントを持つ _meta.json があります。バンドルはライブビューではなくスナップショットです。

ポータブル。 アーティファクトは自己完結型でなければなりません。外部サービス、ライブAPI、ログインセッションへの依存はありません。figmascopeバンドルはプレーンファイルのZIPです。JSON、Markdown、PNG。コピー、メール送信、gitチェックイン、PRへの添付、ジュニアデベロッパーまたはコーディングエージェントへの手渡しがセットアップなしでできます。

検査可能。 決定論的なアーティファクトは中身を確認できなければ役に立ちません。バンドル内のすべてのファイルは人間可読です。CONTEXT.mdはMarkdownです。tokens.jsonはW3C風の構造です。画面ごとのIRは明確なフィールド名を持つJSONです。エンジニアはバンドルを開いてエージェントに伝えられた内容を正確に監査できます。これは「スクリーンショットを貼り付けてコードをもらった」とは質的に異なります。

再現可能。 同じFigmaファイルの状態から、2つの別々のエクスポートは機能的に同等のバンドルを生成するはずです。バイト単位で同一ではありません（タイムスタンプが異なります）が、意味的に同一です。同じノード構造、同じトークン値、同じコンポーネントインベントリ。変更されていないファイルから2回エクスポートしてバンドルが意味的に異なる場合、何かが問題です。このプロパティにより、エクスポートパイプラインを検証し、エクストラクター自体のリグレッションを検出できます。

実際にどのように機能するか

デザイナーがスプリントの画面を完成させます。バンドルをエクスポートします。バンドルはチケットと共にリポジトリにコミットされます（またはJiraの課題に添付、共有ドライブにドロップ、ワークフローによって異なります）。この時点でハンドオフアーティファクトは固定されます。エージェント（またはデベロッパー）はライブFigmaファイルではなくバンドルから作業します。

実装の途中で、デザイナーが3つの画面を更新します。問題ありません。デベロッパーの作業バンドルは変更されていません。新しい画面は新しいエクスポートを取得します。今、2つのバンドルがあり、それらを差分できます。デベロッパーが始めた時のデザインと現在のデザインの間で何が変わったか。これはスクリーンショットベースやライブ接続ベースのワークフローでは不可能な変更の可視性の種類です。

マルチエージェントワークフローでは（1つのエージェントがコンポーネントライブラリを構築し、別のエージェントが画面レイアウトを構築し、3番目がテストを書く）、各エージェントは真実の情報源として同じバンドルを取得します。すべてが同じ凍結されたデザイン状態から作業しています。入力が共有されて固定されているため、出力は合成可能です。これが実際に信頼性の高いマルチエージェントUI生成の前提条件です。

バンドルの差分

バンドルはプレーンファイルなので、コードのように差分できます。同じファイルの2つのFigmaバージョンにわたる2つのエクスポートで、何が変わったかを正確に示すJSON差分が得られます：

これは現在のハンドオフツールには存在しないデザイン変更の可視性です。Figmaには独自のバージョン履歴がありますが、それは視覚的でデザイナー向けです。バンドルの差分は構造化されてデベロッパー向けです。自動テストを駆動し、変更ログを更新し、CIワークフローをトリガーできる機械可読な変更データです。

デザインハンドオフのCI/CD

ハンドオフが決定論的になると、CI/CDは自然に続きます。バンドルに対して実行するテストを書けます。「この画面にはButton/Primaryコンポーネントが含まれていなければならない」「このトークンはバインドされていなければならず、ハードコードされた値であってはならない」「この文字列はstringRefキーを持っていなければならない」。これらは構造化されたデータに対する静的解析チェックです。ミリ秒で実行されます。パイプラインで実行されます。

コード生成エージェントの出力を与えられたバンドルに対して検証することもできます。エージェントはトークンを使用したかリテラルをハードコードしたか？繰り返されるコンポーネントの正しい数のインスタンスを生成したか？正しいスペーシング値を使用したか？これらの質問は、真実の情報源が構造化されたファイルであり、PNGではない場合に答えられます。

MCPとの比較

MCP形式のFigmaへのライブ接続が人気を集めています。魅力は明らかです。エージェントは常に最新のデザインを見られ、エクスポートステップも手動のバンドル管理も不要です。しかし、ライブ接続は利便性のために決定論を犠牲にします。AIエージェントにとってその取引は悪いものです。

ライブ接続とは：エージェントのコンテキストがいつ実行されるかに依存します。デザイナーが日中作業した場合、午前9時の実行と午後2時の実行では異なるデータが見えます。以前の実行を再現することはできません。固定された入力に対してテストできません。エージェントに伝えられた内容を監査できません。生成されたコードが間違っている場合、「モデルが悪い推論をした」のか「エージェントの下でデザインが変わった」のかを区別できません。

正しいモデルは：デザイン探索と反復にはライブ接続（最新性が重要な場合）、ハンドオフと生成には決定論的バンドル（再現性が重要な場合）です。それらは競合していません。ワークフローの異なる時点で動作します。

ジュニアデベロッパーへのハンドオフ

バンドルをAIエージェントにとって良いものにする同じ特性は、コードベースに不慣れな人間のデベロッパーにとっても良いものにします。バンドルを渡されたジュニアデベロッパーは、CONTEXT.mdの完全な仕様、tokens.jsonのすべてのトークン値、プロパティと共にリストされたすべてのコンポーネント、アイデンティティと共にすべての文字列を持っています。Figmaファイルにアクセスする必要はありません。Figmaアカウントも不要です。どの画面が権威あるものかを知る必要もありません。

バンドルは完全な自己完結型の作業指示書です。エージェントが受け取るものと同じです。唯一の違いは人間がそれを読み、エージェントがプログラム的に処理することですが、アーティファクトは同一です。

その統一性（同じアーティファクト、人間またはエージェントの消費者）が要点です。バンドルはハンドオフの単位です。それ以外はすべて実装の詳細です。

決定論的ハンドオフを実際に確認するには Claude Code、Cursor、または Aider をご覧ください。すべて同じ figmascope エクスポートから始まります。