大きなプラットフォームのモノレポで、公開APIと使う側をそろえて変更する

## ルートの決まりを読み、次に各フォルダの指示を足す リポジトリのルートを調整拠点とし、最も近いローカル指示ファイルを、その作業に固有の正本として扱います。まずルートのルールを適用し、一つのモジュールの規約が変更全体を支配すると決めつけず、影響を受ける各ディレクトリが管理するルールを追加します。 ローカル指示ファイルがない領域では、最も近くにある保守済みの開発ガイド、モジュールの`README`、継続的インテグレーションのワークフローを次の正本として使います。複数領域にまたがる変更を編集する前に、該当するガイドをすべて読みます。 ## 編集の前に、どのモジュールが何を受け持つか調べる コントロールプレーン、ランタイムコンポーネント、公開仕様、クライアントライブラリ、デプロイ資源、コマンドラインインターフェース、エンドツーエンドテスト、文書、例、アーキテクチャ提案を、どのモジュールが所有しているかを特定します。 ライフサイクルと構成の動作はコントロールプレーンの所有者へ、ランタイムプロセスの動作は最も近いコンポーネントガイドへ、公開スキーマの変更は仕様の所有者へ、クライアント生成はライブラリの所有者へ振り分けます。デプロイ動作はその運用担当またはパッケージングの所有者へ、コマンドの動作は`CLI`の所有者へ振り分けます。 契約、実装、クライアントにまたがる変更では、公開仕様から始め、影響を受けるすべての利用側のガイドを読み込みます。コンポーネントの`API`、テストの前提、デプロイ連携を、同じ契約に沿って整合させます。 ## 目的を確かめ、必要な行だけを変える 前提を明示し、曖昧さを表面化し、依頼に相反する解釈がある場合は方針を尋ねます。複雑な作業は実装前に観察可能な成功基準へ変換し、意思決定が必要になった時点で停止します。 依頼を満たす最小の解決策を選びます。推測に基づく機能、一度きりの抽象化、不要な設定項目、無関係なリファクタリング、既存作業を消すことは避けます。 作業に必要なファイルと行だけに触れ、ローカルの書式に合わせます。動作を変える場合は焦点を絞ったテストを追加または更新し、確認が通るか、残る障害が明確になるまで反復します。 ## 公開仕様を変えたら、クライアントとドキュメントもそろえる 公開仕様を、契約の正本として扱います。ユーザーから見える動作が変わる場合は、仕様、実装、クライアントライブラリ、文書、例、構成、コマンド動作、リリース成果物を同期させます。 デプロイ用`API`またはオーケストレーター資源が変わる場合は、生成マニフェスト、デプロイパッケージ、コントローラーの動作、サーバー連携、運用文書も更新または検証します。明示的な承認なしに、契約と実装を意図的に乖離させてはいけません。 ユーザー向け文書と運用担当者向け文書は、実装前または実装と同時に更新し、文書化された動作が引き続き公開上の約束を規定するようにします。 ## 生成ファイルは手で直さず、正本から作り直す 生成成果物だけを編集して修正を済ませてはいけません。正本となるスキーマ、テンプレート、構成、生成処理の入力を見つけて変更し、影響を受けるクライアント、マニフェスト、参照資料、例、パッケージ成果物を、対応しているワークフローですべて再生成します。 生成された差分に予期しない変更がないかを確認し、再生成した契約に対して下流の利用側を検証します。手書きのアダプターを生成コードから分離し、両者の間にあるリポジトリの所有境界を保ちます。 再生成が妨げられた場合は、不足しているツールまたは環境を報告します。正本と派生成果物を明確に識別できる未完了状態のまま残し、同期済みとして示してはいけません。 ## 互換性を壊す公開の変更は、先に聞く 公開`API`、クライアントインターフェース、構成、プロトコル、コマンド動作、デプロイ資源、注釈、ラベル、パッケージ値には、追加的で後方互換性のある変更を優先します。 公開上の破壊的変更、意図的な契約の乖離、明確な移行経路を伴わない可視動作の変更を行う前に確認を求めます。承認を求める前に、影響を受ける利用側、互換性への影響、移行要件、リリースへの影響を説明します。 生成差分の中に破壊的変更を隠したり、無関係なコンポーネント作業を同じ変更へ混ぜたりしてはいけません。承認された互換性の判断を、実装、文書、テスト、リリースノートで明示します。 ## ファイル単位で検証し、境界をまたぐ時だけ範囲を広げる 広い検証へ進む前に、ファイルまたはパッケージに範囲を限定したフォーマッター、リンター、単体テスト、契約確認、コマンド出力のアサーションを実行します。変更が境界をまたぐ場合は、統合、言語横断、デプロイ、文書ビルドへ検証を広げます。 コマンドのヘルプと出力は`CLI`テストとともに、契約の例はスキーマ確認とともに検証します。対応言語全体でのクライアント動作と、影響を受けるプラットフォーム上のデプロイ出力も検証します。動作を変えた場合やバグを修正した場合は、焦点を絞ったテストを更新します。 実行しなかった確認や妨げられた確認は、最終引き継ぎですべて明記します。必須の確認が失敗している間や、影響を受ける利用側が明示的な制約説明なしに未検証のままである間は、完了を主張してはいけません。 ## ドキュメントは1か所に置き、写さずにリンクする ユーザー向けおよび運用向けの詳細なガイドは、指定された文書ツリーで管理します。ルートの`README`はリポジトリの入口に限定し、公開可能なパッケージの`README`はインストール、クイックスタート、パッケージの入口に使います。 保守されている文書ページがある場合は、内部コンポーネントの`README`を最小限に保ちます。実行可能な例は例示ツリーに、その解説ページは文書ツリーに置きます。リポジトリの規約でそう定められている場合は、提案文書を正本とし、コミュニティページは索引としてのみ使います。 コミュニティ方針と開発方針は複製せずリンクします。リポジトリ内のファイルからはバージョン相対リンクを優先し、文書がチェックアウト中のブランチまたはタグに追従するようにします。バージョン管理されたコードから参照する唯一の正本として、公開Webサイトだけを使ってはいけません。 ## ドキュメントサイトのページの決まりを守り、エラーなしでビルドする 設定済みの文書エンジンと静的サイト構成を使い、文書化されていないビルド時生成を導入してはいけません。画像は指定された公開アセットディレクトリに置き、サイトで承認されたパス規約に従って参照します。 公開する各ページに必要なメタデータを付け、設定済みの内部リンク形式を使います。文書ツリーの外へリンクする場合は、完全なソースリンクを使います。承認済みのコールアウト、コードグループ、ナビゲーション規約を一貫して適用します。 コントリビューター専用の指示は公開サイトに含めません。ローカライズ方針で許可されている場合に限り翻訳版を追加し、公開可能な変更を完了と見なす前に、文書ビルドをエラーなしで通します。 ## 互換性を壊す変更を重点的にレビューし、残るリスクを報告する 公開仕様、クライアントインターフェース、構成、コマンド動作、デプロイ資源、プロトコルにおける破壊的変更を優先してレビューします。不要な変更、内部で矛盾する変更、利用側が実装しにくい変更、信頼できる移行経路が欠けた変更を指摘します。 正本の境界が崩れていないか、レイヤー構造への違反、古い生成成果物、テスト不足、文書化されていない動作、互換性の後退がないかを確認します。確認済みの不具合と未検証のリスクを分け、影響を受ける契約または利用側を示します。 最後に、変更領域、同期した利用側、実行した確認、妨げられた検証、互換性に関する判断、残るリスクを網羅した、証拠に基づく報告を行います。