bidirekt

Bidirekt コントラクト

サービスのコードをもとに、サービスの Bidirekt コントラクトファイルを作成・更新し、ブローカーと照合して、デプロイチェックレポートに基づいて修正します。

https://bidirekt.com/llms.txt が唯一の参照元です。コントラクトファイルの規則、CLI コマンドとそのフラグやメッセージ、レポートの形式と各 break 行の意味はすべてそこに記載されています。このファイルには手順だけが記載されています。各手順では、次のルールに従ってください。

• コントラクトはコードの動作を記述するものです。変更するのはサービス独自のコントラクトファイルだけとし、コードは変更しないでください。また、チェックに合格させることだけを目的にコントラクトを変更しないでください。
• 読み取りを行う CLI コマンドのみ実行してください。対象は、ローカル検証（ファイルをチェックして、環境にデプロイされた対応ファイルと比較し、何も保存しません）、参加者一覧、環境一覧です。
• ブローカーにコントラクトのバージョンを保存しないでください。デプロイチェック（保存済みのバージョンをデプロイできるか確認し、その結果をブローカーに記録します）は実行しないでください。デプロイを記録しないでください。参加者や環境を作成しないでください。参加者の名前を変更しないでください。これらはエンジニアが行います。

1. llms.txt を読む

何よりも先に、https://bidirekt.com/llms.txt を取得し、ファイル全体を未加工のテキストとして読み取ってください。フラグを追加したり、別のコマンドと連結したりせず、curl -sSfL https://bidirekt.com/llms.txt だけを正確に実行してください。-f は 2xx 以外の応答をすべて失敗として扱います。シェルを使えない場合に限り、ウェブ取得を使用してください。ファイルそのものではなく要約が返された場合は、参照元を読み取れなかったものとして扱ってください。以降のすべての手順で、そこに記載された規則、コマンド、メッセージに従ってください。

取得に失敗した場合、応答が 200 でない場合、または内容が Bidirekt の参照元ではない場合（HTML ページ、ドメインのパーキングページ、エラーページなど）は、そこで中止してください。エンジニアに https://bidirekt.com/llms.txt の参照元を読み取れなかったと伝え、何も書き込まないでください。記憶や別のコピーをもとにコントラクトを作成したり、文法を推測したりしないでください。

2. CLI とブローカーを確認する

何かを書き込む前に、参加者一覧を実行してください。この実行には、llms.txt に記載された CLI バイナリが PATH 上にあり、ブローカーが設定されている必要があります。

• バイナリが見つからない場合：中止し、llms.txt の ## Setup セクションにある、CLI をインストールしてブローカーを指定するコマンドを提示してください。
• CLI がブローカー未設定という応答を返した場合（llms.txt に記載されたメッセージ）：
  • 設定ファイルのプロファイルが 1 つ指定されている場合：そのプロファイルを使い、以降のすべてのコマンドで BIDIREKT_PROFILE=<name> または --profile <name> を指定し、使用したプロファイルをエンジニアに伝えてください。
  • 複数指定されている場合：どれを使うかエンジニアに尋ね、返答を待ってください。
  • 1 つも指定されていない場合：中止し、ブローカーを指定するための ## Setup のコマンドを提示してください。
• その他のエラーの場合：中止し、エンジニアにエラーを提示してください。

CLI のインストールやブローカーの指定は、決して自分で行わないでください。エンジニアが行います。

3. 名前を確定する

コードを読み、何かを書き込む前に、すべての名前を確定してください。エンジニアへの確認が必要な名前については、質問して返答を待ってください。

• サービス独自の参加者名：プロジェクトが CLI に渡している箇所（CI ワークフローやスクリプト）から取得してください。該当箇所がなければ、エンジニアに尋ねてください。どこにも保存しないでください。
• ローカル検証に使う環境名：同じ箇所から取得するか、エンジニアに尋ねてください。環境一覧と照合してください。一覧にない場合は、その名前を使って何も実行しないでください。一覧内の似た名前を提示して確認を求めてください。
• サービスが呼び出す各プロバイダー：コードから参加者名を推定してください（クライアント名、または PETSTORE_API_URL → petstore_api のような環境変数）。参加者一覧と照合してください。一覧にない場合は、その名前を書き込まず、似た名前（petstore_apl → petstore_api？など）を提示して確認を求めてください。ブローカーにまだ登録されていない新しいプロバイダーであることをエンジニアが確認した場合は、そのプロバイダーを書き込み、ブローカーにコントラクトが保存されるまでデプロイチェックが失敗することを警告してください。そのプロバイダーにのみ起因する break は想定どおりです。呼び出しはそのまま残し、break を報告してください。

4. コードからコントラクトを記述する

言語にかかわらず、コードを確認して、次の項目を見つけます。

• サービスが提供するリソースのうち、llms.txt が文書化する種類のもの → provides；
• 他のサービスに対して行う呼び出し → consumes。手順 3 の各プロバイダー名の下に記述します；
• サービスが提供、読み取り、送信するボディの型 → schemas。

llms.txt の記述に従って記述します。コードが llms.txt では表現できない処理を行っている場合は、その項目を省略してエンジニアに伝えます。構文を決して創作しないでください。

optional と nullable は、宣言された型ではなく、llms.txt の null と不在のモデリング規則に従い、コードの動作に基づいて記述します。型では nullable または optional とされているものの、コードパスで null が生成されたり、キーが省略されたりしない場合は、どちらも記述せず、型の範囲がコードより広いことをエンジニアに伝えます。コードから判断できない場合は、確認してください。

フォルダー：contracts/、またはプロジェクトですでにコントラクトに使用しているフォルダー（たとえば、CI が CLI に渡すファイルのある場所）。

ファイルの構成方法（推奨事項であり、規則ではありません）：

• モジュール化されたプロジェクト：モジュールごとに 1 ファイル；
• モジュール化されておらず、リソースが少数：1 ファイル；
• リソースが 50 を超える場合、またはスキーマが 50 を超える場合：provides.yaml や consumes.yaml など、ファイルを増やします；
• モノリスかマイクロサービスかは関係ありません。コンテキストは現在のサービスです；
• プロジェクトですでに構成がある場合：それに従います。

複数のファイルを使用する場合は、複数ファイルに関する llms.txt の規則に従います。

5. 既存のコントラクトを更新する

コントラクトファイルがすでに存在する場合は、ファイルを再生成せず、その場で編集します。

• コードで変更された箇所だけを変更します。コメント、順序、書式、すべての description を維持します。
• コードで使われなくなった場合に限り、リソースまたはプロパティを削除します。削除した項目はすべて最終回答に記載します。プロバイダー側での削除は、コンシューマーにとって破壊的変更になる可能性があります。

6. 変更を確認する

1. 参加者リストを実行し、手順 3 と同様に、consumes の各プロバイダー名をリストと照合します。
2. 参加者、環境、ファイルを指定してローカル検証を実行します。
3. llms.txt の説明に従い、検証結果に基づいてコントラクトを修正します。手順 8 に従って各破壊的変更を判断し、検証に合格するまで両方を再度実行します。

残っている修正がコードに反するものだけになったら、繰り返しを止めます。コードを変更するか、相手側に依頼する必要があることをエンジニアに伝え、手順 8 に従って依頼内容を記述します。残っている破壊的変更が、新しいプロバイダーに対して想定されるもの（手順 3）のみになった場合も停止し、その内容を報告します。

ローカル検証で、サービス自身の参加者が存在しないと返された場合は、作業を止め、参加者リストにある類似の名前を添えてエンジニアに伝えます。参加者を作成するかどうかは、エンジニアが判断します。

7. 完了

作成または変更したファイル、削除した項目、警告、相手側への依頼をすべて列挙します。コントラクトファイルを変更した場合は、回答の末尾に次に実行するコマンドを記載します。参加者とファイルを指定して、バージョンをプレースホルダー（またはプロジェクトの CI が使用するバージョン）にした、コントラクトをブローカーに保存するための llms.txt のコマンドです。

8. デプロイチェックレポートに基づいてコントラクトを修正する

エンジニアはレポートを会話に貼り付けるか、レポートが保存されているファイル（CI ログなど）を指定します。手順 1 と 2 を行い、手順 3 と同様にサービス自身の参加者と環境を確定します（レポートに環境が記載されています）。llms.txt が説明する形式に従ってレポートを見つけ、各エラー行について、そのエラー行と修正方法を説明する llms.txt のセクションを参照します。

各エラー行について、サービスのコントラクトとコード内で、指定された箇所（相手方、エンドポイント、メソッド、リクエストまたはレスポンスのステータス、プロパティパス）を特定し、どちらの変更で修正できるかを判断します。

• サービス側の変更で修正できる場合：その箇所のコードが行っていることをコントラクトが記述していないときです（たとえば、コードがそのプロパティを読み取らない、またはそのプロパティがなくても動作する場合）。llms.txt がそのエラー行に示す方法で、コードに合わせてコントラクトを変更し、手順 6 をもう一度行います。
• 相手方の変更で修正できる場合：コントラクトがすでにコードの動作を記述しているときです。相手方のファイルにアクセスできる場合でも、相手方のものは変更せず、相手方への変更依頼を作成します。変更内容、変更箇所（エンドポイント、メソッド、リクエストまたはレスポンスのステータス、プロパティパス）、理由（エラー行）を記載します。代わりにサービスのコードを変更して修正できる場合は、その選択はエンジニアに委ねられることも伝えます。

その後、手順 7 と同様に完了します。