glubean

Glubean

このスキルは、Glubean のベストプラクティスガイドとして使用してください。基本的には実際のプロジェクトのワークフローを選択してください。Scratch モードは拡張機能の簡易デモ用であり、通常のエージェント向けの手順ではありません。

モード

1. ドキュメント：製品に関する質問、概念、比較、移行、エディターのサポート、またはクラウド機能。
2. オンボーディング：まだ Glubean プロジェクトがなく、ユーザーが拡張機能、MCP、クックブック、またはプロジェクトの初期化に関するガイダンスを必要としている。
3. プロジェクト：ユーザーがすでに Glubean プロジェクト内にいる、または既存の API 資産からの移行を含め、実際のプロジェクトのテスト作業を明確に希望している。

最初にルーティングする

モードを選択する前に：

• package.json、config/、schemas/、contracts/、tests/、explore/、.env、.env.secrets、GLUBEAN.md があるか確認します。
• @glubean/sdk がすでに dependencies または devDependencies に含まれているか確認します。
• MCP ツールが利用可能か確認します。
• GLUBEAN.md がある場合は、プロジェクトのコンテキストファイルとして最初に読みます。
• ユーザーは、関連するコード、ドキュメント、仕様、関連ワークスペースへの参照など、重要なコンテキストをそこに記載しておく必要があります。
• ユーザーが追加のコンテキストの場所を明示した場合は、API だけを見て推測する前に、それらも読みます。

次に、意図と環境に基づいてルーティングします：

• ドキュメント：進行中のプロジェクトタスクがなく、説明だけを求めている場合。references/docs-mode.md を読みます。
• オンボーディング：まだ Glubean プロジェクトがなく、ユーザーが適切なセットアップを希望している場合。references/onboarding.md を読みます。
• プロジェクト：リポジトリがすでに Glubean プロジェクトのように見える場合、またはユーザーがプロジェクトで実際のテスト作業を希望している場合。references/project-mode.md を読みます。
• 実装に基づく検証：動作がすでに実装されており、ユーザーがテスト、コントラクト、カバレッジ、または検証を求めている場合、contract()、workflow()、test() のいずれを出力するか決める前に references/implementation-derived-verification.md を読みます。
• 設計優先／コントラクト優先：ユーザーが実装前に新しい動作を定義したい、または新しい API サーフェスを計画したい場合は、すぐに references/contract-first.md に進みます。実際のコントラクトを書く際には、references/patterns/contract-first.md も読みます。

意図の例

• ドキュメント
  • 「Glubean とは何ですか？」
  • 「Glubean は Postman とどう違いますか？」
  • 「CI でテストを実行するにはどうすればよいですか？」
  • 「Postman から移行するにはどうすればよいですか？」（patterns/migration.md をもとに回答）
• オンボーディング
  • 「プロジェクトに Glubean をセットアップする」
  • 「Glubean を試してみたい」
  • 「Cursor 用に MCP を設定する」
• 移行（複数の領域にまたがる — 実行の依頼では、振り分ける前に確認する）
  • 「Postman コレクションを移行する」
  • 「Apifox または OpenAPI のエクスポートを変換する」
  • 「古い API テストを Glubean に移植する」
  • → 確認：「このために新しい Glubean プロジェクトをセットアップしますか？ それとも現在のプロジェクトに追加しますか？」
  • → 新しいプロジェクト → オンボーディング → 初期化 → 移行パターン
  • → 現在のプロジェクト → プロジェクト → テスト後 → 移行パターン
• プロジェクト — シンプルモード（デフォルト、テスト後）
  • 「/users のスモークテストを書いて」
  • 「テストカバレッジを向上させて」
  • 「失敗するテストを修正して」
  • 「認証境界のテストを追加して」
  • → 既存の動作については、implementation-derived-verification.md を読み、結果として得られる命令的なエビデンスには explore/ または tests/ で test() を使用します
• クラウドの診断
  • 「この Glubean の実行が失敗したのはなぜですか？」
  • 「この Cloud の実行を診断して：clr_...」
  • 「アップロードした CI 実行の失敗を取得して」
  • → Cloud の実行データを取得する前に、references/patterns/cloud-diagnosis.md を読みます
• プロジェクト — 実装に基づく検証
  • 「この既存のエンドポイントのテストを書いて」
  • 「この API 実装からコントラクトを生成して」
  • 「すべてのケースを列挙せずにカバレッジを向上させて」
  • → ルート／コントローラー、バリデーション、認証、ドメイン／サービスの分岐、永続化の制約、エラーマッピング、既存のテストを調べます
  • → 動作／ケースのマトリックスを導き出します。ユーザーが明示的にスモークテストを依頼していない限り、ハッピーパスだけのケースやステータスだけのケースをデフォルトにしないでください
  • → 安定した保証はコントラクト、ライフサイクルの保証は workflow()、命令的なエビデンスは test() で表現します
• プロジェクト — コントラクトファーストモード（上級者向け、新しい構造化された仕様）
  • 「CRUD を備えた users API が必要です」
  • 「実装前に請求エンドポイントを設計して」
  • 「まだ実装していない API のコントラクトを書いて」
  • 「コントラクトのカバレッジはどのくらいですか？」
  • 「プロジェクションレポートを生成して」
  • → 新しい動作を定義する場合にのみ、設計ファーストとして扱います。シンプルモードのデフォルトより先に contract-first.md を読みます
  • → エンドポイントの保証には contract.http.with()、ライフサイクルの保証には workflow() を使用します
  • → ユーザーが明示的にコントラクトを依頼した場合、またはプロジェクトに contracts/ がすでに存在する場合に限ります
• プロジェクト — 負荷テスト（オプトイン、同時実行時のパフォーマンス）
  • 「/checkout を同時ユーザー数 100 人で負荷テストして」
  • 「負荷時の p95／スループットはどのくらいですか？」
  • 「CI にパフォーマンスゲートを追加して」
  • → references/load-testing.md を読み、loadScenario() + loadRunner() + しきい値を含む *.load.ts を作成します。glubean load <file|dir|glob> で実行し、ユーザーが意図的に Cloud へのアップロードを希望する場合に限り、--upload／--upload-target を追加します
  • → オプトインのみです。実際の同時トラフィックを発生させるため、通常の機能カバレッジ作成時に負荷テストを自動で作成してはいけません
• プロジェクト — ブラウザーと Chrome 拡張機能のテスト
  • 「展開した拡張機能のオプションページ、コンテンツスクリプト、またはサイドパネルをテストして」
  • 「ツールバーのアクションでネイティブのサイドパネルが開閉することを確認して」
  • → references/patterns/browser.md を読み、拡張機能が提供するページには createExtensionTest() を使用します。ドキュメントの直接レンダリングの証明と、ネイティブのツールバーアクションのライフサイクルは別々に保ちます

全般的なルール

プロジェクト固有の指示で上書きされない限り、以下を適用します：

1. シークレットは .env.secrets に、公開設定は .env に記述します。複数環境のセットアップについては、references/patterns/multi-env.md を参照してください。
2. configure() を使用して共有 HTTP クライアントを作成し、テストでは ctx.http ではなく、エクスポートされたクライアント（例：api）を使用します。ctx.http はスクラッチデモ専用です。
3. 環境変数やシークレットの埋め込みには {{KEY}} を使用し、リテラルには通常の文字列を使用します。
4. すべてのテストにタグを付けます。
5. test() にティアダウン、複数ステップ間の状態受け渡し、実行時の分岐、または実行時のポーリングが必要な場合は、ビルダーモードを使用します。
6. テスト ID には kebab-case を使用し、プロジェクト全体で一意にします。
7. 人が読めるテスト内の文字列はすべて、診断情報になり得るものとして扱います。ケースのタイトル、テスト名、ステップ名、スキーマラベル、アサーションメッセージ、警告、ログには、確認対象の不変条件やビジネスルールが伝わる内容を記述します。「動作する」「有効」「レスポンスを確認」「成功するはず」のような汎用的なラベルは避けます。
8. ctx.assert を使用する場合、メッセージを省略してはいけません。失敗の原因を診断できる具体的なメッセージを記述し、実行時の値を比較するアサーションでは { actual, expected } を渡します。構造化された actual/expected の出力をすでに生成する場合は、ctx.expect(...) のマッチャーを優先します。
9. 実際のプロジェクトでは、再利用可能なレスポンスタイプを types/ に置きます。ユーザーから明示的に求められた、使い捨ての小さな例に限り、インラインで定義します。
10. .json<any>() は使用しません。レスポンスの形状がまだ不明な場合は、.json<unknown>() から始めます。トップレベルの値がオブジェクトだと分かっている場合に限り、Record<string, unknown> を使用します。その後、フィールドが分かり次第、実際の型または Zod に絞り込みます。
11. 実際のプロジェクトでは、再利用可能な Zod スキーマを schemas/ に置きます。ユーザーから明示的に求められた、使い捨ての小さな例に限り、インラインで定義します。
12. すべてのケースで同じエンドポイントまたは同じ操作パターンを使用する場合に限り、test.each と test.pick を使用します。エンドポイントが無関係な場合は、別々のエクスポート済みテストを作成します。各ケースに実行時の一意な ID が割り当てられるよう、テスト ID には $field または $_pick のプレースホルダーを含めてください（例："search-$q"、"user-$_pick"）。
13. 認証が必要な対象で、認証設定がまだない場合は、その対象を扱う最初の段階で作業を止め、認証設定のベースを作成する前にオーナーから認証の詳細を確認します。 条件となるのは、対象に認証境界があり、それをカバーする認証設定がまだ確認されていないことです。401／403、Authorization／Cookie ヘッダー、ログイン／トークンのエンドポイント、保護されたルート、OpenAPI／仕様の security スキームはいずれも、その境界を示します。スキームを推測してはいけません。また、「とりあえず動かす」ために認証を省略したテストを作成してはいけません。読み取った内容（どの方式か（bearer／apiKey／login-exchange）、ヘッダー名とシークレット名、認証情報の入手元、およびそれぞれの根拠）を提示し、オーナーの確認、訂正、または不足情報の提供を待ちます。対象の認証設定が存在する場合（configure() のクライアントが設定済み、シークレットが .env.secrets にある、または GLUBEAN.md に認証の決定が記録されている場合）は、黙って再利用します。コントラクトやテストごとに再確認してはいけません。 推測に基づいて認証を黙って設定してはいけません。
14. シークレットの値をユーザーにそのまま返してはいけません。生成するコードや設定では、解決済みの値ではなく {{KEY}} プレースホルダーを使用します。CLI の出力やレスポンス本文をチャットで引用する場合は、Authorization ヘッダー、Cookie／Set-Cookie の値、トークンらしきフィールド（ベアラートークン、API キー、セッション ID）を削除またはマスキングします。ユーザーがマスキングされたような文字列（例：sk-****）を共有した場合、それを復元しようとしたり、文脈から完全な値を推測したりしてはいけません。
15. プロジェクトの基本構成がない場合、自分でスキャフォールドを作成してはいけません。対象ディレクトリとベース URL が分かっている場合は npx glubean@latest init --no-interactive を、ユーザーが対話形式のプロンプトを希望する場合は npx glubean@latest init を推奨します。
16. ユーザーがプロジェクトレベルの決定（認証方式、コンテキストの場所、命名規則、ビジネスルール）を確認した場合は、今後のセッションでも参照できるよう GLUBEAN.md への追記を提案します。
17. GLUBEAN.md には、プロジェクトレベルのビジネスルール、ロール／状態の意味、命名の決定を記述します。エンドポイント一覧、ステータステーブル、リクエスト／レスポンスの形状、ケース一覧を手動で管理してはいけません。これらは contracts/ に置き、projection または Cloud 経由で表示します。
18. ライフサイクル仕様はトップレベルの workflow() で作成します。contract.http.with() はエンドポイントの動作を定義し、workflow() は既存のコントラクトケースを call()／poll() と型付きの状態で組み合わせます。test() は、projection する価値がないケース向けの命令型実行時エスケープハッチとして使用します。
19. コントラクトケースの中に setup／teardown を入れてはいけません。コントラクトケースは意味上の約束（description、given、needs、expect、verifyRules、runnability）です。実行時のセットアップ／クリーンアップは、問題に応じて contract.bootstrap() のオーバーレイ、defineSession()、workflow().setup/teardown()、または test() ビルダーのセットアップ／ティアダウンに置きます。
20. アップロードと同期は分けます。glubean run --upload／glubean load ... --upload は、対象スコープのエビデンスを送信します。glubean sync は、仕様／OpenAPI／エージェントコンテキストのプロジェクトスコープのソース projection を送信し、テストは実行しません。
21. 現在の Cloud コードでは、トークンカタログに本来コントラクト／同期用の contracts:write が含まれているにもかかわらず、glubean sync の projection 書き込みに runs:write が必須とされています。まず実際の動作を教え、正確さが重要な場合はスコープの不一致を指摘してください。
22. 作成したコントラクトのソースは、レビュー用にそのまま公開されます。コントラクト宣言の中にシークレットをインラインで記述してはいけません。glubean ≥ 0.10.2 の sync は、各コントラクトの export const … = contract.…(…) の範囲をそのまま（verify 本文も含めて）取得し、Cloud の Specs「Source」ビューに未編集のままアップロードします。これが仕様です。レビュアーが実際のコントラクトを読むため、宣言内の内容は何もマスキングされません。認証情報はすべてこの範囲の外に置きます。実際のシークレットは .env.secrets に置き、{{KEY}}／ctx.vars.require("KEY") で参照します。具体的でもシークレットではない値（ID、ホスト名）はファイル先頭の const に置き、名前で参照します。どちらも値ではなくシンボルとして projection されます。コントラクトオブジェクト内にリテラルのトークン／Cookie／パスワードを記述すると、必ず公開されます。
23. すべてのコントラクトケースの verify() には、必ず verifyRules を付けてください。各アサーションにつき1項目を設け、そのアサーションが適用する内容を完全なビジネス上の記述で示します（例：「返されたプロジェクト ID がアクティブな dogfood プロジェクトと一致する」。 「ID OK」ではありません）。verify() は実行時のクロージャーです。projection で記録できるのは、それが存在すること（hasVerify）だけです。そのため verifyRules がないと、レビュー画面には内容不明の「カスタムアサーションを実行」という注記が表示され、レビュアーはソースを確認するために画面を切り替えなければなりません。Cloud の Specs ケースカードでは、ケースの約束が表示される箇所に verifyRules が Verify ステップとして表示されます。レビュアー向けの verify 本文の仕様として記述し、アサーションを変更したときは内容も合わせて更新します。verifyRules のない verify() は、description のない test()（ルール25）と同じ種類の、レビュー画面上の欠落です。ルールに安定した ID または独自の重要度が必要な場合はオブジェクト形式（{ id, description, severity }）を使用します。それ以外は文字列だけで構いません。
24. コントラクト ID は操作の「タイトル」であり、名前空間ではありません。 OpenAPI の summary の役割と同じく、操作の内容を示す短い説明句として記述します：list-projects、get-project、sign-in-with-email、validate-run-upload。ドット区切りの名前空間付きキーワードの羅列（platform.projects.list）は絶対に使用しません。スコープ付きインスタンス名、feature、tags、endpoint がすでに階層を示すため、ドット区切りの ID はそれらを繰り返すだけで、意味ではなく機械的な名前に見えます。kebab-case（ルール6）を使用し、プロジェクト全体で一意にします（2つのサービスが同じ操作を提供する場合は、platform-health-check と dashboard-health-check のように内容が分かる形で区別します）。ID はコントラクトのアイデンティティです。OpenAPI の operationId に投影され、run エビデンスを関連付け、リビジョン履歴のキーになるため、後から名前を変えると履歴が切り離されます。最初から適切なタイトルを付けてください。
25. 優先順位に沿ったレビュー画面の情報：まずテストの description（#1、最重要）、次に各アサーションの message（#2）です。どちらも完全な記述にし、省略形にしてはいけません。 Cloud の Specs ビューはテストを実行せずにレビュー用に表示します。表示されるのはテストの description、アサーションのメッセージ、ctx.when/switch/while 分岐の describe ラベル、tags、エンドポイントだけです。実行時の値は projection されません（それらは testId で関連付けられる run エビデンスに記録されます）。そのため：
    • description は見出しです。 レビュアーが最初に読むため、すべてのテストに、テスト全体で検証する内容を示す完全な1行の記述を付けます（「認証し、成功時のセッション契約と失敗時の拒否契約を検証する」など）。testId の言い換え、「ログインをテストする」、空欄はいずれも避けます。
    • 各アサーションの message はチェックごとの記述であり、そのチェックが何を検証するかを示す唯一の情報です。すべてのアサーションに、結果を示す完全で独立した記述を付け、省略を一切含めません。「有効なセッショントークンが返される」と記述し、「トークンあり」とはしません。「注文が見つからない場合、500 ではなく 404 が返される」と記述し、「404 OK」とはしません。簡略なラベル、コードの単なる言い換え、空のメッセージでは、テストをレビューできません。 マッチャーが適切な場合は、単なる ctx.assert(cond, "message") より ctx.expect(...).matcher(expected, "message") を優先します（expect.toBe、expect.toContain、expect.toHaveProperty などのマッチャー名自体が意味のある形として projection されます）。分岐の実行時に選択された1つの分岐だけでなく、すべての結果の意図が projection されるよう、単純な if/for/while より ctx.when/switch/while（それぞれ describe を付ける）を使用します。
26. 生の ctx.http 呼び出しには .track("METHOD /path") を付け、エンドポイント単位でレビューできるようにします。 Cloud の Specs ビューは API の表面であるエンドポイントを中心に構成されています。各エンドポイントには、そのエンドポイントのコントラクト、呼び出すテスト、ワークフローがまとまり、カバレッジの欠落が示されます。コントラクトケースを実行するテストは、そのケースがエンドポイントを示すため、自動的に関連付けられます。しかし、生の ctx.http.get(/users/${id}) はリテラル URL（/users/123）として projection されるため、カバレッジ一覧でコントラクトの GET /users/:id から分離し、単発のパスでエンドポイント一覧を増やします。したがって、生の ctx.http（ルール2で設定済みクライアントまたはコントラクトケースを推奨する、スクラッチ／エスケープハッチの方法）を使う場合は、正規のエンドポイントを指定します：await ctx.http.get(/users/${id}).track("GET /users/:id")。コントラクトに記載されているものと同じ METHOD /path 文字列を使用し、テストが同じエンドポイント項目に表示されるようにします。（GET /users のようにリテラル URL がすでに正規のものであれば、.track() は任意です。）
27. ステータスだけでなく、コントラクトのリクエストとレスポンスの形状をすべて宣言します。 Cloud は各コントラクトを OpenAPI オペレーション（公開される API リファレンスの表示）としてレンダリングします。パス／クエリ／ヘッダーのパラメーター、リクエストボディ、レスポンスが表示され、すべてのフィールドに制約のピル（format、enum、minLength／maximum、required）とフィールドごとの description が付きます。expect: { status } しか宣言していないコントラクトは、ほとんど何もないオペレーションとして投影され、レビューできません。そのため、ボディの書き込みまたは読み取りを行うコントラクトでは、制約付きで形状を宣言します：
    • リクエストボディとリクエストヘッダーはコントラクトレベルで指定します：request: { body: <SchemaLike>, headers: <SchemaLike>, contentType }（request: <SchemaLike> だけの場合は、ボディの省略形です）。ボディスキーマが OpenAPI の requestBody の元になります。
    • クエリとパスパラメーターはケースごとに指定します：query: { page: { value, schema, description, required } } および params: { id: { value, schema, description } }（スキーマと説明を保持するのは、文字列だけではなく ParamValue オブジェクトです。パスパラメーターは自動的に必須になります）。
    • レスポンスボディとレスポンスヘッダーはケースごとに指定します：expect: { status, schema: <SchemaLike>, headers: <SchemaLike> }。 実際の SchemaLike（format／enum／境界値／description を含む JSON Schema を返す { safeParse, toJSONSchema }、または Zod スキーマ）を使用します。型だけのプレースホルダー（{} as SchemaLike<T>）では何も projection されず、requestBody は空になります。スキーマの制約が、レビュアーの読むコントラクトです。
28. すべての不透明なワークフローノードに、実際の description を付けます。 compute／action ノードは opaque として projection されます（変換／IO ロジックの形状を静的に定められません）。そのため、ノードの description が、そのステップを理解するためにレビュアーが読める唯一の情報です。また、不透明なノードが1つでもあると、ワークフロー全体が部分的な projection になります。不透明なノードに、単語2つだけの名前を付けて終わらせてはいけません。文字列 ID の代わりに { id, description } を渡します。例：b.compute({ id: "mark-seed", description: "Mark the run as needing a seed user (sets state.seed=true) so a later step provisions the first account." }, (s) => ...)。形状から意味を復元できない場合に、その意味を伝えるのが部分 projection の説明です。
29. 正常に実行できるだけでなく、すべてのプロジェクトで typecheck と lint を必須にします。 glubean run は tsx で実行するため、型チェックは行いません。したがって、tsc が拒否するコントラクトでも実行は成功する可能性があります。また、tsc には非推奨の診断機能がありません（@deprecated はエディター上で取り消し線になるだけです）。これを検出できる CLI／CI の方法は、ESLint の @typescript-eslint/no-deprecated だけです。Glubean には Zod 4 が含まれており、非推奨になった API（.passthrough()、z.string().uuid()/email()/datetime()）は Zod 3 時代のコードで使われているため、プロジェクトが気付かれないまま劣化します。そのため、プロジェクトに npm run typecheck（tsc）と npm run lint（eslint no-deprecated）の両方があることを確認し、「完了」とする前に両方を実行し、それぞれの終了コードが 0 であることを run と併せて報告します。古い glubean init の出力を含め、プロジェクトにこれらがない場合は、ゲートを後付けで整備します（tsconfig + eslint.config.js + scripts + devDeps）。verify は async verify(ctx, res: T) と記述し、Zod 4 の形式（z.email()／z.uuid()／z.iso.datetime()、.loose()）を使用します。手順と既存プロジェクトへの適用方法の全容については、references/patterns/type-safety.md を参照してください。
30. 既存の動作を対象にする場合、原則として実装から検証内容を導きます。 テストまたはコントラクトを作成する前に、references/implementation-derived-verification.md を読んでください。アクセスできるソースと既存テストを調べ、意味のある成功、バリデーション、認証、状態、競合、エラーのケースを導き出し、見つかったルールをすべて、実行済みエビデンスまたは明示的なギャップに対応付けます。リクエスト／レスポンススキーマや OpenAPI projection に制約が記載されていても、実装がその制約を適用している証明にはなりません。ユーザーがスモークテストを明示的に求めた場合に限り、到達可能性／ステータスのみを確認するケースを作成します。
31. コントラクトの cases は、レスポンスステータスの昇順に並べ、成功ケースを先頭にします。 ケースは、レビューされる場所すべてでソースの順序どおりに表示されます。Cloud の Specs ケースカード、MCP x-glubean-cases、projection のいずれも同様です。そのため、ケースが10件以上ある場合に順序がばらばらだと、成功ケースが埋もれてレビュアーが探さなければなりません。expect.status の昇順（最初に 2xx の成功、その後 4xx を順に：400 → 401 → 403 → 404 → 409 → 422、最後に 5xx）に並べ、同じステータス内では一般的なものから極端なものへ（まれなエッジケースより、日常的なバリデーション失敗を先に）並べます。成功ケースは 2xx なので、常に先頭になります。これはルール23～28と同じ、レビュー画面を意識した規律です。読者がブロック全体を読み回さずに、操作の流れを、到達、成功、その後の予測可能な順序での失敗、とたどれるようにします。（ケース間にライフサイクル上の依存関係がある場合、たとえば後のケースが再利用する deferred のシードがある場合は、依存関係が読み取れる順序にします。並べ替えは既定の方針であり、必要な順序を壊す理由にはなりません。）
32. インベントリには discover を、Cloud への公開前には doctor を使用します。 glubean init が生成したパッケージスクリプトを優先します。npm run discover はアセットカタログを書き出し、npm run doctor はアセットとトークン／プロジェクト／スコープ／対象の準備状況を読み取り専用でチェックし、npm run sync は .env を明示的に使用してプロジェクトスコープのソース projection を公開し、npm run upload はローカルプロファイルを実行して対象スコープのエビデンスをアップロードします。doctor チェックに成功しても、sync／upload の実行が許可されるわけではありません。確認できるのは準備が整っていることだけです。sync と upload を1つの操作にまとめたり、doctor に合格しただけで公開したりしてはいけません。 詳細なナビゲーションについては、references/index.md から始めてください。

実際のプロジェクト内で移行する場合は、ファイルを生成する前に references/patterns/migration.md を読んでください。

$ARGUMENTS が指定されている場合は、それを対象のエンドポイント、ファイル、タグ、または自然言語によるテストのリクエストとして扱ってください。