手元で動くAIデザインのデスクトップアプリを、決まった制約の中で直す

## 指示ファイルどうしが食い違う時は、エージェント向けのガイドを優先する 変更を加える前にこのファイルを読むこと。リポジトリ内の他のエージェント向け指示ファイルは、現在の計画より遅れている場合がある。それらとこのファイルが食い違う場合は、このファイルが優先される。 ビジョン文書、原則文書、現在のリリース計画といった社内向け設計文書は、自分のチェックアウトに存在する場合には有用な追加コンテキストになる。社内ドキュメントのディレクトリは gitignore 対象なので、メンテナーは計画・引き継ぎ・調査をローカルに置いており、外部のコントリビューターはそれらを一切持っていない可能性がある。 - メンテナーしか見られないファイルを理由に、外部コントリビューターの作業を止めてはならない。 - gitignore 対象のドキュメントディレクトリ配下のパスを、公開のレビューコメントで引用してはならない。そのファイルが公開チェックアウトにも存在する場合のみ例外とする。 - それらの文書が手元にないときは、このファイル、公開されている issue とプルリクエスト、そして README を拠り所にする。 ## 1つのデザインを、専用のワークスペースを持つ長いセッションとして扱う このプロダクトは単発プロンプトのジェネレーターではない。作業の1単位は、利用者のマシン上にある実際のワークスペースに支えられた長時間稼働のエージェントセッションであり、エージェントはファイルの読み取りと編集、権限付きコマンドの実行、構造化された質問、成果物のプレビュー、微調整コントロールの提示、設定されたモデルが対応している場合の画像生成、そしてデザインシステム文書の作成を行える。 - 1つのデザインが1つのワークスペースを持つ。封じられた領域と開かれた領域という分割は存在しない。ワークスペースのファイルシステムが成果物とアセットの正本である。 - エージェントはワークスペース内のソースファイルを編集し、プレビューランタイムがそのソースを閲覧可能なドキュメントへレンダリングし、エクスポーターがレンダリング済みまたはソースのドキュメントを HTML、PDF、PPTX、ZIP、Markdown といった標準的な出力へ変換する。 - 現在のフォーマットにおける正本のソースエントリーファイルは1つだけ保つこと（たとえば JSX コンポーネントファイル）。単体の HTML ファイルはエクスポート用、または旧来のワークスペースファイル用に取っておく。 - 実績あるコーディングエージェントの仕組みを借りてくることは想定内である。プロダクトとしての境界は、ドメイン固有のツールとローカルファーストのワークスペースモデルこそが、その上に自分たちで積み上げる部分だという点にある。 ## モデルを同梱しない・鍵は利用者が持つ、などの制約を守る これらは好みではなくプロジェクトとしての約束である。利便性と引き換えに手放してはならない。 1. モデルランタイムを同梱しない。推論エンジン、言語インタープリタ、ブラウザバイナリ、モデルの重みをインストーラーの中に同梱してはならない。システムにインストール済みのものを使うか、利用者に見える形で同意を取ったうえで遅延ダウンロードすること。 2. 鍵は利用者自身のものだけを使う（BYOK）。ホスティングされたアカウント、プロキシ経由のAPI、デフォルトでのテレメトリーは持たない。利用者の資格情報は人間が読める形のローカル設定に留める。 3. ローカルファーストのストレージ。セッションは追記専用のセッションファイルと実際のワークスペースファイルとして存在する。旧来の埋め込みデータベースにある既存データは移行してよいが、セッション、チャット履歴、コメント、スナップショット、デザインファイルのために、そこへ新しいテーブルを追加してはならない。 4. すべてのデザインはワークスペースを持つ。重要なものがセッションレコードの中だけに存在してはならない。 5. 出荷されるもの、同梱されるもの、リンクされるもの、アプリコードが取り込むもの、利用者へ配布されるものは、すべてパーミッシブなライセンスであり、プロジェクトのライセンスと両立していなければならない。その範囲では、コピーレフト、ソースアベイラブル、プロプライエタリ、およびライセンスが不明確なサードパーティ資産を対象から外す。ワークフロー専用のCI・リリースツールは、それがプロダクトへベンダリング・同梱・リンク・コピーされない場合に限り、コピーレフトライセンスを使ってよい。その場合は理由を記録し、その出力は通常のメタデータやマニフェストの範囲に留めること。 6. 重い機能は遅延読み込みにする。エクスポーター、Webキャプチャ、スキャフォールド、スキル、リファレンスアセット、画像生成は、アプリケーション起動時ではなく必要になった時点で読み込まれなければならない。 7. まず土台となるエージェントフレームワークのプリミティブを再利用する。セッション、組み込みツール、シェル実行、イベントストリーミング、モデルレジストリ、プロバイダー登録、ケイパビリティデータはフレームワークが所有しており、ドメイン固有の必要性が別の結論を裏づけない限りそれに従う。 8. リファレンスデータはデータであって、モデルの記憶ではない。ブランドやスタイルの値は、ワークスペースのデザイン文書、利用者のファイル、公式アセット、公表された情報源から取ること。ブランドカラーや仕様を記憶から創作してはならない。 9. 変更は互換性があり、アップグレード可能で、軽量かつエレガントであるべきであり、プロジェクトの詳細な原則チェックリストがある場合はそれに従うべきである。 ## Webサイトを作る時は、llms.txt などAI向けのファイルも用意する ウェブサイト、プロジェクトのホームページ、プロダクトページ、個人サイト、ドキュメントサイト、ブログ、公開プロジェクトページを構築または更新するときは、利用者が明示的に不要と言わない限り、AI からの可視性をデフォルトの納品スコープに含めること。 - `/llms.txt` ファイルを追加し、サイトの簡潔な Markdown 概要、著者または組織、主要ページ、プロジェクトまたはプロダクトの正本となる説明、機械可読リソースへのリンクを記載する。 - サイトに、より充実した AI 可読のコンテキストファイルを正当化できるだけの実質的な公開コンテンツがある場合は、`/llms-full.txt` ファイルを追加する。 - `robots.txt` は意図をもって設定する。AI システムが公開コンテンツを引用・取得する助けになる検索・取得系クローラーは許可し、学習用クローラーは別個のポリシー判断として扱う。 - `sitemap.xml` を維持し、重要な公開ページを網羅していることを確認する。関連がある場合はウェブマスターツールへの登録にも触れる。 - 人物、組織、ウェブサイト、記事、ソフトウェアアプリケーション、FAQ、クリエイティブワークといった型など、有用な箇所には適切な JSON-LD 構造化データを追加する。 - プロフィール、プロジェクト、投稿、ドキュメント、リリース、FAQ、プロダクト情報といった重要なエンティティについては、クリーンな Markdown または JSON の機械可読エンドポイントを優先する。 - コンテンツは事実に忠実で、出典に裏づけられ、スパム的でないものに保つ。目的は、AI システムが実在するコンテンツを正確に理解し引用できるよう助けることであって、質の低い水増しを生み出すことではない。 ## モデル呼び出しとツールは、共有のエージェントフレームワークを通す - 自作の同等品ではなく、共有のエージェントフレームワークとそのモデル抽象化レイヤーの上に構築する。 - 読み取り、書き込み、編集、シェル、grep、find、一覧の各操作には、並行する独自版を書くのではなくフレームワークの組み込みツールを使う。 - すべてのツール呼び出しは、フレームワークのツール呼び出しフックとアプリケーションの権限UIを通す。 - モデルのケイパビリティは、受け付ける入力の種類、推論のサポート、コスト、コンテキストウィンドウ、応答長の上限（最大トークン数）など、フレームワークのモデル記述フィールドから読み取る。ケイパビリティの表をハードコードしてはならない。 - カスタムプロバイダーはフレームワークのプロバイダー登録APIを通じて登録する。並行するプロバイダーSDKレイヤーを作ってはならない。 - モデル呼び出しはすべてフレームワークのモデル抽象化を経由する。アプリケーションコードでベンダーのSDKを直接インポートしてはならない。 ## セッションは追記専用のファイルに、デザインはワークスペースに置く - デザインはセッションである。セッション履歴は、アプリケーションのユーザーデータディレクトリ配下に追記専用のセッションファイルとして存在する。 - デザインのソースファイル、生成されたマークアップとスタイル、アセット、エクスポート、ワークスペースレベルのエージェント文書とデザイン文書は、アプリケーションのデータベースではなく利用者のワークスペースに置く。 - ワークスペース設定は、明示的なスキーマバージョンのフィールドを持つバージョン管理された設定ファイルに置く。 - 個人のローカル設定ファイルはユーザーごとのものであり、gitignore 対象のままにしなければならない。 - 旧来の埋め込みデータベースは移行対象のデータであって、現在のストレージモデルではない。新しい機能の状態でそれを拡張してはならない。 ## ツールは組み込みと少数のデザイン用ツールだけにする ツールの表面積は、フレームワークの組み込みツールに加えて、短いドメインツールの一覧だけである。 - `ask(questions)` は構造化された質問を表示し、利用者を待つ。 - `scaffold(kind, path)` は厳選されたスターターをワークスペースへコピーする。 - `skill(name)` はマニフェストからスキルのテキストを遅延読み込みする。 - `preview(path)` は成果物をレンダリングし、コンソールエラー、アセットエラー、DOMアウトライン、メトリクス、そしてビジョンモデル向けのスクリーンショットを返す。 - `gen_image(prompt, path)` は、ケイパビリティとプロバイダー設定が許す場合に、生成した画像をディスクへ書き出す。 - `tweaks(blocks)` は複数ファイルにまたがる編集可能なコントロールを宣言する。 - `todos(items)` は複雑なターンにおけるタスクの状態を表示する。 - `done(path)` はプレビューによる自己チェックの後にターンを終える。 計画が変わらない限り、検証用サブエージェント、スニペット取得ツール、独自のシェルツール、独自のファイル一覧ツール、エージェントが書き込むワーキングメモリを復活させてはならない。 ## 4種類のデザイン用リソースを混ぜずに使い分ける デザイン文書は公表されている仕様に従い、入力にも出力にもなり得る。エージェントが生成する複数画面の作業は、トークンが現れるたびにその文書を更新することで視覚的な一貫性を保つ。組み込みのリファレンスシステムは、帰属表示、出典、ライセンスのメタデータ、および「提携関係はない」旨の注記を備えていなければならず、組み込みスキルは標準のスキルファイル形式を用いる。スキルとスキャフォールドのマニフェストには、ライセンスと出典のメタデータを持たせなければならない。 4種類のリソースは互いに置き換えられるものではない。 - Markdown のスキルは手法のルールである。エージェントにどう働くかを伝えるものであり、ファイルをワークスペースへコピーはしない。 - リファレンスデザインシステムは読み取り専用で、名前を指定してスキルとして読み込まれる。プロジェクトのためにそれらを編集してはならない。採用した選択はワークスペースのデザイン文書へ翻訳して反映すること。 - スキャフォールドは、ワークスペースへコピーされる具体的なスターターおよびソースのアセットである。マニフェストが正確に記述している限り、どのテキスト形式であってもよい。 - デザインスキルのスニペットは、仮想ファイルシステムを通じて公開されるコピー可能なコンポーネントパターンである。これらはソースのスニペットであって、手法のルールではなく、ブランドの権威でもない。 ワークスペースのデザイン文書は、プロジェクト固有のバトンである。ひとたび存在すれば現在のデザインについての権威であり、生成される作業はそれを単なるもう1つのプリセットとして扱うのではなく、保持するか修復すべきである。 ## スターターをプロダクトコードとして見直し、拡張子を中身に合わせる - スターターとスキャフォールドのアセットは、プロンプトの埋め草ではなくプロダクトコードとして扱う。プリセットを変更または追加する前に、マニフェストだけでなく実際のファイルの中身をレビューすること。 - ソースの形式とファイル名の拡張子を一致させる。完全な HTML ドキュメントは `.html` ファイルに、コンポーネントのスターターはコンポーネント用の拡張子に、スタイルのスニペットは `.css` に置く。コピーツールはソースの拡張子を保持するはずだが、それでもアセット自体が正しく命名・記述されていなければならない。 - 組み込みの HTML スターターは自己完結していて、現在のランタイムでプレビューできなければならない。スキャフォールドのアセットに CDN やサードパーティのランタイムスクリプトを追加してはならない。スターターにランタイムの挙動が必要なら、ローカルの素の HTML、CSS、JavaScript を使うか、ライセンス経路が明確でアプリケーションが提供する遅延読み込みの依存関係を使う。 - 「Deck title」「Page content」「Replace this」「Point one」のような弱いプレースホルダー文言は避ける。中立で実用に耐えるサンプルコンテンツを使い、置き換えるべき明らかな箇所はスターターが宣言する微調整のデフォルト値を通じて見えるようにする。 - マニフェストの説明は、そのスターターがどの形式なのかを述べなければならず、拡張子に敏感なアセット、とりわけエージェントが誤った拡張子でコピーしかねないファイルを明示しなければならない。 - スキャフォールドのツリーに手を入れるときは、拡張子と内容の不一致、外部ネットワークURL、古くなったプレースホルダー文言、マニフェストのずれを点検する。変更がコピー経路、プレビューの分類、ツールの挙動に影響する場合は、対象を絞ったスキャフォールドおよびランタイムのテストを追加または更新する。 ## 決められたツールを使い、バージョンはロックファイルで確かめる - リポジトリ全体でパッケージマネージャーは1つ。2つ目を混ぜてはならない。 - 代替を持ち込むのではなく、リポジトリが選んだビルドオーケストレーター、単一のリント兼フォーマットツール、ユニットテストランナー、エンドツーエンドテストランナーを使う。 - TypeScript は strict モードで、verbatim module syntax と bundler resolution を用いる。`any` は使わない。 - コミットメッセージは Conventional Commits、バージョニングは changeset ツールを使う。changelog を手で編集してはならない。ランタイムのバージョンは、バージョンファイルと engines フィールドの両方で固定する。 - パッケージの正確なバージョンはマニフェストとロックファイルにある。古くなったドキュメントを信用せず、それらのファイルを読むこと。 - フロントエンドの選択はすでに決着している。選定済みのビューライブラリとビルドツール、CSS変数を用いたユーティリティCSS、軽量な状態管理ライブラリ1つ、共有UIパッケージでラップされたアクセシブルなヘッドレスプリミティブ、アイコンセット1つ、フォームデータを使うネイティブフォーム、アニメーションには CSS トランジション。競合する状態管理・アニメーション・コンポーネントのライブラリを持ち込んではならない。 - アプリケーションのクロームは共有UIパッケージのトークンを使わなければならない。生成されるデザインのソースとエクスポートは、独自のビジュアルシステムを定義してよい。 - リポジトリは、アプリケーションシェル、エージェントコア、プロバイダー連携、プレビューランタイム、共有UI、成果物スキーマ、エクスポーター、テンプレート、共有型を別々のパッケージに分割している。関心事を所有するパッケージにコードを置くこと。 ## 大きい作業は計画ファイルを書き、編集の範囲を絞る - 自明でないアーキテクチャやプロダクトの作業では、ビジョン、原則、現在の計画の各文書がローカルに存在する場合はそれらを読む。存在しない場合は、このファイルと公開の議論を拠り所にする。 - おおよそ5回を超えるツール呼び出し、または3ファイルを超える範囲にまたがるタスクでは、恒久的なローカルの計画ファイルを書く。小さく直接的な修正のために計画作りの空回りを生まないこと。 - 並行作業や無関係な機能の作業には別々のワークツリーを使う。無関係な2つのブランチを1つのチェックアウトに混ぜてはならない。 - サンドボックス、インラインコメント、微調整コントロール、エクスポーター、フレームワークのケイパビリティ、スキャフォールド、スキル、リファレンスアセットに手を入れる前に、そのファイルがローカルに存在する場合はリサーチキューを確認する。 - 編集の範囲は絞ったままにし、ついでのリファクタリングは避ける。 - 出荷物やランタイムの依存関係を追加する前に、そのライセンス、インストールサイズ、代替、そしてピア依存にできるかどうかを確認する。ワークフロー専用のツールについては、なぜ同梱しないのか、そしてその出力が配布される成果物に影響するかどうかを記録する。 - 機能作業にはユニットテストのカバレッジを追加または更新し、マイグレーション、権限、ツールフック、共有の契約を変更するときはテストの範囲を広げる。 - 実際の呼び出し元が2つ必要になるまでは、レジストリよりもマニフェストと分岐ロジックの組み合わせを優先する。 - コメントは、その理由が次のメンテナーにとって意外である箇所にだけ書く。 ## コマンドを4段階の権限で分け、止めた理由を見せる 権限モデルは1つだけで、段階的に上がるティアを持つ。 - ティア0: ワークスペース内のローカルな読み書き、単純なファイルコマンド、読み取り専用のバージョン管理コマンドは、中断なしに実行してよい。 - ティア1: インストール、ビルドコマンド、ローカル外へのネットワーク取得、作業ディレクトリ外のコマンドは、一度だけ確認を求め、その後は許可リストに載せてよい。 - ティア2: 公開・発行、プッシュ、管理者権限を要する操作、その他影響範囲の大きいコマンドは、毎回確認を求める。 - ティア3: 破壊的なシステムコマンド、ダウンロードしたスクリプトをそのままシェルへパイプすること、システムディレクトリへの書き込みは、明示的なオーバーライドがない限りブロックされる。 ブロックされたツール呼び出しを隠してはならない。コマンド、パス、ティア、そしてブロックされた理由を示すこと。 ## ベンダーのSDKの直接読み込みや、同意なしのトラッキングを足さない - 依存関係のディレクトリ、ビルド出力、環境ファイル、生成されたリリース成果物、私的なローカルファイルをバージョン管理に加えること。 - アプリケーションコードでモデルベンダーのSDKをインポートすること、またはベンダーSDKのレベルでモデルをモックするテストを書くこと。代わりにコアまたはフレームワークの境界でモックすること。 - 明示的なオプトインの体験なしに、トラッキング、アナリティクス、アカウントのフロー、クラウド同期、自動アップデートを追加すること。 - 利用者のパスをハードコードすること。プラットフォームのディレクトリ規約、アプリケーションのパスAPI、ワークスペースのルートを尊重すること。 - セッションやデザインのデータについて、旧来のデータベースに支えられた新しい機能の状態を追加すること。 - ワークスペースの上に、より重いグルーピングの抽象を導入すること。複数のセッションが1つのワークスペースを共有してもよいが、サイドバーが並べるのはセッションである。 - 計画が変わらない限り、セッションの分岐、取り消しとバージョンのロールバック、外部ツールサーバーのサポート、コミュニティスキルのインストールを表に出すこと。 - メインプロセス、コア、プロバイダー、エクスポーター、共有パッケージで生のコンソール呼び出しを使うこと。プロジェクトのロガーを使うこと。