レシピ規約

レシピ規約

インテグレーションクックブックに掲載する実行可能なレシピは、すべて同じ契約に従います。このページはその契約を文書化したもので、読者はレシピに何を期待できるかを把握でき、著者はレシピが満たすべき要件を確認できます。このページは解説的な位置づけであり、規約を記録するものです。強制（enforcement）はリポジトリのツールおよびスタイルオーバーライドシートが担い、ここでは行いません。

各インテグレーションのソースリポジトリは、自身のレシピを docs/public/ 配下に保持し、aggregator がそれらを本サイトに取り込みます。以下の規約は、レシピがどこに置かれていても適用されます。

1. サンプルは実コードであり、手書きの断片ではない

レシピのコードはリポジトリに実在するコードであり、本文に手書きで入力された断片ではありません。

• 5 行を超える PHP コードブロックはいずれも、対応するリポジトリ内の examples/ ディレクトリ、または tests/Cookbook/ ディレクトリから取得されます。
• ブロックは、その出自をフェンスブロックの情報文字列で宣言します。たとえば title="examples/standalone.php" のように記述します。
• 対応するテストは、その例が引き続きコンパイル可能であり、かつ文書化された出力を生成することをアサートします。これにより、レンダリングされたページが、掲載しているコードから乖離することはありません。

この規約は、ドキュメントスタイルオーバーライドシート §3.4（「サンプルはランナブルでなければならない」）に相当します。裏づけとなる例やテストのないコードを掲載するレシピは、この規約を満たしません。

2. ブロックごとに一言語、エラー処理を可視化

• フェンス付きコードブロックには、明示的に宣言された言語をちょうど 1 つだけ含めます（ ```php, ```bash, ```yaml, ```json）。言語指定のないフェンスは使用しません。
• 本番運用向けハウツーとしてマークされたレシピは、try / catch を明示的に示し、素の \Exception ではなく、適用可能なもっとも具体的な例外型をキャッチします。また、catch ブロックでは、読者がそのままコピーできる処理（ログ出力、再スロー、または定義済みエラーオブジェクトの返却）を行います。空の catch ブロックは使用しません。
• HTTP トランスポートを用いるインテグレーションでは、レシピはトランスポートの失敗と非成功の HTTP ステータスを 2 つの別個のケースとして扱います。PSR-18 クライアントは、リクエストを送信できない場合にのみ、型付きのクライアント例外をスローします。4xx または 5xx のレスポンスは、レシピがキャッチする例外ではなく、レシピが検査する通常の戻り値です。

3. 再現性フロントマター

各レシピは、サイトのコンテンツスキーマによって強制される §5.1 のフロントマター契約を用いて、その出力がどの程度再現可能かを宣言します。関連するフィールドは次のとおりです。

• reproducibility_profile — bitwise、structural、semantic のいずれか。bitwise は、ピン留めされた入力が与えられたとき、出力バイトが実行をまたいで同一になることを意味します。structural は、ドキュメント構造は同一である一方、付随的なバイト（タイムスタンプ、オブジェクト順）は異なる場合があることを意味します。semantic は、バイトや構造の保証はないものの、レンダリング結果が等価であることを意味します。レシピは、存在するもっとも強いプロファイルではなく、正直に保証できるもっとも強いプロファイルを記載します。
• output_hash — プロファイルが bitwise の場合の、期待される出力の SHA-256。読者が文書化された結果を検証できるようにします。プロファイルが安定したハッシュをサポートしない場合は空にします。
• runnable_example — レシピの出力を生成する examples/… パス。ページを §1 の、ソースに裏づけられたサンプルに結びつけます。
• performance_budget — レシピに対する任意指定の実時間およびピークメモリの上限。性能に関する主張も兼ねるレシピが、境界づけられ、かつテスト可能な状態を保てるようにします。
• compatibility — レシピが動作すると主張する PHP のバージョン。レシピのデフォルトは PHP 8.4 です。8.4 専用の機能を挙げるレシピは、フロントマターにバックポートを記載し、コードブロックでその機能を明示します。

再現性プロファイルは、§8.4 の再現性契約に相当します。読者はこれを用いて、「出力」が厳密なバイトを意味するのか、それとも等価なドキュメントを意味するのかを把握します。

4. 公開ゲート

本クックブックのすべてのページは、Writing Gate を通過するまで publish: false を保持します。デフォルトは拒否（deny）です。ページをマージしても公開されるわけではなく、フロントマターに記録された明示的なゲート判定によってのみ公開されます。compliance-engine の実際の障害により規範的な引用をピン留めできなかったレシピには、まだ resolve（解決）できていない引用を示すマーカーが追加で付与されます。引用が再ピン留めされるまで、そのレシピは publish: false のままになります。そのマーカーはリポジトリの RAG インフラ障害フォールバックプロトコルによって管理されます。レシピの著者は、引用を捏造したり主張を取り下げたりするのではなく、このプロトコルに従います。

5. provenance（来歴情報）フィールドは aggregator が書き込む

レシピの著者は、aggregator が所有する 4 つのソース来歴（provenance）フィールド、すなわち source_repo、source_ref、source_hash、manifest_hash を手書きしません。aggregator は、レシピをソースリポジトリから取り込むときにこれらを記入します。これにより、公開されたページには、どのリポジトリリビジョンから生成されたかが正確に記録されます。著者がこれらのフィールドのいずれかにプレースホルダーを残した場合、aggregator がそれを上書きします。プレースホルダーが公開ページに到達することはありません。

まとめ

本クックブックにおけるレシピとは、テストを伴う、ソースに裏づけられたコード、ブロックごとに一言語、本番向けハウツーに対する明示的なエラー処理、正直な再現性プロファイル、Writing Gate を通過するまでの publish: false のデフォルト、そして aggregator が注入する来歴情報を備えたものです。6 つすべてを満たすページはレシピであり、満たす数がそれより少ないページはドラフトです。

関連項目

• インテグレーションクックブック — パッケージおよびコア制約のリファレンス。
• インテグレーションを選ぶ — ユースケース別の意思決定マトリクス。