stitch-sdk-readme

Stitch SDK README ジェネレーター

このスキルは、@google/stitch-sdk の README を作成します。構成の指針（Bookstore Test）と、コードベースから最新の API を取得する方法を組み合わせることで、SDK の進化に合わせて README の正確さを保ちます。

---

最新の API の取得方法

API の内容をハードコードしないでください。呼び出し時にコードベースから読み取ってください。

必要な情報	参照先
公開エクスポート（全体）	packages/sdk/src/index.ts
ドメインクラスのメソッドとシグネチャ	エクスポートされた各クラスのソースファイル（sdk.ts、project.ts、screen.ts）
生成されたメソッドのバインディング	packages/sdk/generated/domain-map.json → bindings[] 配列
手書きのメソッド	domain-map のバインディングに含まれないクラスのソースファイル内のメソッド（例：Screen.edit、Screen.variants）
AI SDK ツールアダプター	packages/sdk/src/ai.ts → stitchTools() のサブパスエントリ
生成されたツール定義	packages/sdk/generated/src/tool-definitions.ts → 各ツールの JSON Schema
ツールクライアントのメソッド	packages/sdk/src/client.ts
エラーコード	packages/sdk/src/spec/errors.ts → StitchErrorCode
設定オプション	packages/sdk/src/spec/client.ts → StitchConfigSchema
プロキシ設定	packages/sdk/src/proxy/core.ts

これらのファイルを読めば、API 全体を把握できます。以下の Bookstore Test テンプレートを使って構成してください。

---

Bookstore Test

読者がライブラリを使うかどうかを決める過程は、人が本を買うかどうかを決める過程と同じです。まず表紙に目を通し、次に内表紙を読み、それから本を読むことを決めます。README は各段階で読者の関心を引く必要があります。

表紙

このライブラリが「何であるか」ではなく、どのような問題を解決するのかを一文で述べます。読者が自分の状況に当てはまると感じられる内容にしてください。キャッチコピー、バッジ、ロゴは不要です。

この SDK の場合、テキストから UI を生成し、HTML やスクリーンショットをプログラムから抽出できることを説明します。

良い例：「テキストプロンプトから UI 画面を生成し、HTML とスクリーンショットをプログラムから抽出できます。」 悪い例：「Google Stitch の公式 TypeScript SDK です。強力な AI 搭載 UI 生成プラットフォームです。」

内側のそで

ライブラリが実際に使われている様子をすぐに示します。セットアップではなく、まずコードです。

主要なワークフロー — SDK に存在するすべてが生み出すべき結論:

project(id) → generate → getHtml

これを最初のコードブロックとして示し、環境変数が必要であることを1行で記します。これより前にインストール、インポート、設定を示さないでください。プロジェクト作成については、callTool("create_project", ...) を別途示してください。

二次的なワークフロー — 段階的に深さを明かします:

1. 既存のプロジェクト/画面を一覧表示し、反復処理する
2. 画面を編集し、バリエーションを生成する
3. シングルトン経由のツールアクセス(stitch.listTools()、stitch.callTool()) — セットアップ不要
4. StitchToolClient による明示的な設定(カスタム API キー、ベース URL)
5. stitchTools() による AI SDK 統合 — @google/stitch-sdk/ai からインポートし、tools: stitchTools() と stepCountIs を指定した generateText を示す

このセクションのルール:

• 最初にセットアップを持ってこない。 最初の例の前に、STITCH_API_KEY に言及する1行で十分です。
• 2つのインストール経路。 まず npm install @google/stitch-sdk を示します(コア SDK、スタンドアロン)。次に AI SDK ユーザー向けに npm install @google/stitch-sdk ai を示します。ai パッケージが必要になるのは、@google/stitch-sdk/ai からインポートする場合だけです。
• 率直な言葉遣い。 「強力」「シームレス」「堅牢」「エンタープライズグレード」は使いません。
• 動作する例。 すべてのコードブロックは、// ... で省略された断片ではなく、有効で実行可能なコードでなければなりません。
• 段階的な複雑さ。 最も単純な呼び出しを最初に、その後により深い機能を示します。

本を読む

読者はすでにコミットしています。完全な API をリファレンスとして文書化します。

この順序でクラスごとに構成します: Stitch → Project → DesignSystem → Screen → StitchToolClient → toolDefinitions / toolMap → stitchTools()(AI SDK) → StitchProxy → stitch シングルトン。

各項目には次を含めます:

• 何をするか(1行)
• 使用例(最小限で実行可能)
• パラメータ(表)
• 戻り値の型とエラー時の動作

セットアップ、認証、設定はここに置きます — 読者がすでにこのライブラリを使う価値があると判断した後にです。

トーン

同僚が別のエンジニアに自分の仕事を説明するように書きます。直接的であれ。具体的であれ。売り込むのではなく、伝えるのです。ある機能に制限があるなら、それを明記します。セットアップが複雑なら、そう述べます。

---

検証

README を生成した後、次を確認します:

• 読者は10秒以内にライブラリが何をするか理解できるか?
• 最初のスクロール内に実行可能なコード例があるか?
• セットアップ/設定は最初のコード例の_後に_現れるか?
• すべてのコードブロックは有効でコピー&ペースト可能なコードか?
• 言葉遣いは宣伝的ではなく説明的か?
• リファレンスセクションは index.ts のすべての公開エクスポートを網羅しているか?
• 例の中のすべてのメソッド名が、そのクラスのソースファイルに存在するか
• 例の中のすべてのインポートが、index.ts のエクスポートと一致するか
• 3つのモダリティがすべて文書化されているか: ドメインクラス(スクリプト)、StitchToolClient(エージェント)、stitchTools()(AI SDK)

アンチパターン

アンチパターン	なぜ失敗するか
バッジ、ロゴ、ステータスシールドから始める	読者がライブラリの動作を知る前の視覚的なノイズ
最初のセクションが「はじめに」	価値を示す前にセットアップを強要する
コードのない機能箇条書き	見せるのではなく語っている
「使いやすい」「シンプル」「すぐ動く」	懐疑を招く自己称賛的な主張
使用例より前に長いインストール/設定ブロック	見返りを示す前に投資を求める
コア API ドキュメントを隠す折りたたみセクション	コミットした読者が求めてきた内容を埋もれさせる
ソースを示さずドキュメントに API をハードコードする	ツールが追加されると古くなる