ntucker/エージェント向けデザインシステム

エージェント利用のためのデザインシステム

このスキルは設計上の決定を指示するものではありません。すべての推奨事項は、正当なプロジェクト目標（専門家の表現力、ブランド要件、プラットフォームの制約、既存の規約）に優先される可能性があります。トレードオフを明示し、意図的な相反する選択に委ねてください。例はReactとTypeScriptを使用しています。これはモデルの事前分布が最も明確な領域だからです。ただし、この考え方はあらゆるスタックに移植可能です。

目的

コード生成モデルはサンプラーです。トレーニングで学習した内容（事前分布）とセッション内の内容（コンテキスト）に基づいて最も確からしいと判断したプログラムを出力し、実行可能なチェックを通過したものだけを保持します。人間向けのAPIは「正しい動作を表現できるか？」を問います。エージェント向けのAPIは「正しく見えるもののうち、どれだけが実際に正しいか？」を問います。したがって、目的は2つに分かれます。最も確からしいプログラムを正しいものにすることと、確からしくないプログラムが出荷前に失敗するようにすることです。

これは、より厳しい2つの仮定の下での通常のAPI設計（Blochの「正しく使いやすく、誤って使いにくく」、Minskyの「違法な状態を表現不可能にする」、成功の奈落）です。すなわち、消費者の習熟度は公開コード上の測定可能な分布であり、消費者は実行できるものだけを検証する、という仮定です。

消費者の3つの特性

以下はすべてこれらに基づいています。以下の主張が意思決定に重要である場合、またはローカルで測定する必要がある場合は、エビデンス元帳を参照してください。出典、範囲の注意点、測定プロトコルが記載されています。

1. 事前分布は頻度形成、バージョン混合、パッチ不可能です。 モデルは、パターンがトレーニングに出現した頻度に比例してパターンを認識します。精度はコーパス頻度とともに対数線形的に向上します。これまでに存在したすべてのバージョンのライブラリが1つの分布に重ね合わされるため、モデルは非推奨APIを25～38%の確率で出力し、バージョン固定タスクでは約50%のスコアになります。ライブラリが提供するものでこれを編集することはできません。一致させるか、上書きすることのみ可能です。

2. コンテキストは事前分布を上書きしますが、実際に存在するコンテキストのみです。 古いコードから引き出されたプロンプトは70～90%の非推奨使用を生成しました。現在のコードから引き出されたプロンプトは9～18%でした。ファイル内の兄弟コードは、ライブラリが公開するものよりも出力を強く誘導します。取得されたドキュメントは役立ちます。ベアのバージョンラベルは少し役立ちます。エージェントが決して読み込まない公開ドキュメントは何の効果もありません。

3. 実行可能なフィードバックのみが検証です。 型チェッカーは決定論的で安価であり、常にループ内にあります。LLMが生成したTypeScriptのコンパイルエラーの94%は型エラーであるため、多くの問題を捕捉します。レンダリングは高価でセットアップが必要であり、レイアウトの視覚言語による判断はスクリーンショットがあっても弱いです。型がエンコードしていないものは、モデルが誤っても出荷されます。

2つの結果があります。エラーのコストは非対称です。人間は悪いギャップを見て数秒で修正しますが、エージェントの悪いギャップは出荷されます。そのため、「修正が簡単」は「間違えにくい」よりもはるかに価値が低くなります。そして、進化は追加的でなければなりません。名前の変更や意味の変更は、次のトレーニング実行までエージェントにコストがかかり、古い形式が分布から完全に消えることはありません。したがって、どうしても変更が必要な場合は、変更ログだけでなく、型と同じ場所にあるドキュメントに移行を記載してください。

3つの動作

すべての設計レバーはこれらのいずれかです。設計を評価するときは、それがどの動作を行うのか、そしてどの動作を損なうのかを問いかけてください。

動作1: デフォルトの推測を正しくする

エージェントの最初の推測は、事前分布と可視コンテキストの組み合わせです。2つの要素がこれを形成します。

名前は分布に対する賭けです。 名前の価値は、鋭さと一致度の積です。すなわち、その公開された使用法がどれだけ単一の意味を持っているか、そしてその意味があなたのものと一致するかです。鋭さはコーパスのサイズ、古さ、安定性に追従するため、HTMLやCSS仕様の語彙はARIAパターン名よりも優れ、ARIAパターン名は汎用ライブラリ語彙（sm/md/lg、primary/danger、solid/outline/ghost）よりも優れ、どの単一ライブラリのイディオムよりも優れます。セマンティクスが許す限り深くアンカーを打ってください。一致度は二値であり、異なる動作を持つ馴染みのある名前が最悪のケースです。モデルは学習した意味を自信を持って適用し、コードはコンパイルされます。あなたのセマンティクスに一致する鋭い名前がない場合は、学習された文法から新しい名前を構成してください。Page/PageHeader/PageTitleは主要なライブラリには存在しませんが、X/XHeader/XTitleの活用は階層と子の順序を無料で伝え、オートコンプリートやエージェント自身の計画で発見可能なままです。別のプロップに依存するプロップ（directionスイッチの下のalign）は、2つの結合された賭けです。それらを1つの軸ごとに1つのコンポーネント、または明示的な名前に分離してください。その利点は自由度が1つ減ることではなく、事前分布が救われることでもありません。モデルはCSS自身の軸切り替えを問題なく処理します。

可視コードベースがプロンプトです。 兄弟の使用法、カタログ、および標準的な例が、エージェントが実際に条件付けするものです。規則性はそのプロンプトを圧縮します。すべてのコンポーネントが同じ語彙で同じ軸を活用する場合、コンテキスト内の2つのコンポーネントがカタログ全体を教え、すべての同義語やコンポーネントごとの例外は教えられる必要があり、通常は教えられない別個の事実になります。カタログは出力を分割します。エージェントはコードを読む前に「ページヘッダー」や「ツールバー」のような単位で計画し、存在するものを通して計画を強制します。したがって、コンポーネントにはそれらの単位にちなんで名前を付けてください。例が示すものがワークフローになります（classNameオーバーライドも含む）。意図したパスを示し、例をバージョン一致させ、エージェントが触れる必要のあるコードと同じ場所に配置してください。

事前分布の強さは、エージェントが書かなければならない構文に準拠することを正当化します。しかし、エージェントが行うべきでない決定を公開することを決して正当化しません。それは動作3です。

動作2: 間違った出力を出荷前に失敗させる

レンダリングやランタイムで捕捉されるはずだったものはすべて、より早い段階で失敗しなければなりません。そうしないと出荷されます。

型で表現できるものは、型に入れてください。 誰も設計していない真偽値の組み合わせの代わりに、閉じた共用体型。モード依存のプロップには識別共用体。パーツがサポートしていないものを、"ここでは使用しないでください"と文書化する代わりにOmit。意味のある動作レイヤーがコンシューマーに委ねるもの（ダイアログのタイトル、アイコンボタンのラベル、エラーテキスト。RadixやReact Ariaはこれらをエージェントが見ることのないコンソールでのみ警告します）には必須プロップ。asChild/asのサポートされていないケースや、ButtonLinkのような明示的な非ポリモーフィックバリアントにはコンパイルエラー。テストは毎回同じです。プロップを補完するエージェントは合法な語彙を見ることができ、違法なプログラムはコンパイルされません。

型で表現できない場合は、コードが書かれている場所で乖離を可視化してください。 名前は、型がエンコードしないレイアウトの期待値を伝えます（コンテナは自身のパディングを持ち、ブロックは親を埋め、スペーシングは親のギャップから来ます。ケーススタディにリストがあります）。その名前が作る期待を破るコンポーネントは、エージェントが見ることのできない次元でコンパイルされ、静かに間違ってレンダリングされます。コールサイト（必須プロップ、衝突しない名前）またはエージェントが確実に読み込むコンテキスト（コードの横にあるルール）で、その乖離を信号で伝えてください。エージェントが遭遇しないドキュメントはカウントされません。

動作3: 決定を排除する

正しさがレンダリング時にのみ可視となる決定は、コールサイトではなくライブラリに属します。4つの粒度での1つの原則です。

• 値。 すべての大きさを量子化し、セマンティックな役割を通して外観を解決します。コールサイトではgap="3"やtone="danger"、テーマではpxやhexを使用します。モデルはflexやgridのメカニズムを知っていますが、12と16をブラインドで選ぶことはできません。独立した選択はファイルをまたいで誰も見ることのないリズムへと漂流します。スペックキーワード（justify="space-between"）はセマンティクスを自由に保ちながら、スケールが推測を排除します。
• 構成。 ウィジェットだけでなく、レイアウトを所有してください。Braidのルールがクリーンなバージョンです。コンポーネントは外部のホワイトスペースを出荷せず、レイアウトコンポーネントがすべてのスペーシングを所有します。ウィジェット境界で止まるシステムは、すべてのコールサイトに即興を強いることになります。
• パターン。 構成が繰り返される場合（FormField、EmptyState、PageHeader、ConfirmDialog）、それを出荷してください。プリミティブからの再導出は毎回、分岐する機会です。
• 適応。 ビューポート、コンテンツの長さ、書字方向、モーションとコントラストの設定、ローディング/空/エラー状態を、構築的に処理するか、型で要求してください。コールサイトのメディアロジックはブラインドな決定です。

エスケープハッチ（className、style、CSS変数）は存在すべきであり、デフォルトパスよりも確率が低い位置に配置します。利用可能で、ランク付けされ、決して目立たせないこと。もしそれらが実証されたワークフローであるなら、動作1はそれらをデフォルトの推測にしてしまっています。

体制が可読性と契約を決定する

2つの首尾一貫した哲学が存在します。shadcnは最初のものの最も明確な表明です。

• 可読性。 ソースをリポジトリに出荷します。エージェントはそれを読み、編集します。スタイリングは書かれた場所で可視です。エージェントがコンポーネントを所有する場合に正しいです。エージェントはファイルを開き、読みやすい実装（同じ場所にあるスタイリング、最小限の間接参照）が必要です。
• 契約。 型付きAPIを公開し、実装を隠蔽します。エージェントがアプリケーションコードからコンポーネントを消費する場合に正しいです。エージェントはインポート、型、およびいくつかの兄弟使用法を見て、実装を開くことはほとんどありません。読みやすいスタイリングは書きやすいスタイリングであり、コールサイトのスタイリングは動作3が排除するエントロピーです。

ほとんどのシステムは両方を必要とし、オーディエンスによって分割します。components/を維持する人にとっては可読性、そこからインポートするすべての人にとっては契約です。動作を適用する前に、ファイルがどの体制にあるかを決定してください。システムがshadcn上に構築されているか、shadcnと比較されている場合は、shadcnケーススタディを参照してください。何を維持し、何を変更し、なぜかを検討しています。

緊張関係

2つあり、それぞれにいくつかの側面があります。トレードオフを明示してください。それが無料であるふりをしないでください。

• 集中確率 vs 表現力。 排除された自由度はすべて、誰かの失われた能力です。これは、意図コンポーネント対プリミティブ、閉じた軸対直交プロップ、そして軸の拡張対分割（すべての値が同じ質問に答える場合に拡張、shadcnのButtonバリアントは意図、処理、要素の同一性を融合しており、標準的な融合軸です）として現れます。ランク付けされたエスケープハッチが通常の答えです。
• 事前分布の一致 vs 所有権。 慣習に一致することで無料の正確性を得る一方で、その慣習の欠点と変動を輸入します。これは、馴染みのある名前対明確な名前（明確な名前は発見可能性を犠牲にします。文法に準拠した新しい名前はそのほとんどを回復します）として、また事前分布に優しい設計対より良い設計として現れます。乖離は一度の調整コストがかかります。維持された欠点は永遠に正確性を犠牲にします。

信頼する代わりに測定する

3つの特性はモデルレベルで測定されています。動作はそれらの測定値と一致するメカニズムであり、UIライブラリで測定されたものではありません。エビデンスファイルはどちらがどちらかを示しています。ルールを採用する前に、実行してみてください。20～40の現実的なUIタスクを、体制ごとに複数回サンプリングします（コンテキストなし、型と2つの兄弟使用法、完全なソース）。初回試行のコンパイル、型で捕捉された誤用 vs サイレント、兄弟コールサイト間のトークンのばらつき、アクセシビリティリント、短い視覚的パスをスコアリングします。1つの設計決定を変更し、再実行します。数値を動かすものを維持してください。

レビューチェックリスト

• 動作1: 同等のライブラリに精通したモデルは、これを最初の試行で推測するでしょうか？また、名前が借用されている場合、同じように動作するでしょうか？標準的な例は意図したパスを示していますか？
• 動作2: すべての現実的な誤用はコンパイルに失敗しますか？名前の視覚的な期待が破られている場合、その破綻はコードが書かれている場所で可視ですか？
• 動作3: 値、構成、パターン、適応のうち、コールサイトがブラインドで決定するために残されているものはありますか？
• 体制: このファイルはエージェントによって所有されているか消費されていますか？可読性/契約の選択は意図的ですか？
• 進化: この変更は昨年の事前分布から書かれたコードを壊すでしょうか？移行は型と同じ場所にあるドキュメントで可視ですか？