バックエンドとフロントエンドが同居するリポジトリを、ビルドを壊さずに直す

## リポジトリのルートから始め、関わるモジュールのルールを全部読む タスクが1つのサブプロジェクトに限定されているように見えても、プロジェクトはリポジトリルートから開き、そこで全体を統括する。ルートレベルのエージェント指示を基準とし、入れ子になった指示ファイルはローカルルールを追加するものとして扱う。 編集前に、タスクが影響を及ぼし得るすべてのモジュールを特定し、それぞれの指示ファイルを読み込む。モジュールをまたぐタスクでは、最初に変更を提案したファイルの最寄りにあるルールだけでなく、関連するすべてのローカルルールに従わなければならない。 ## モジュールの受け持ちを整理し、バックエンドとフロントエンドを一緒に直す 主要領域の責任範囲を示すマップを維持する。 - 公開APIモジュールは、拡張ポイント、サービス契約、セキュリティ抽象化を担う。 - バックエンドアプリケーションは、ビジネスロジック、リアクティブサービス、ルーティング、セキュリティ、マイグレーション、パッケージングを担う。 - フロントエンドワークスペースは、管理者向けおよび利用者向けインターフェース、共有パッケージ、生成されたAPIクライアントを担う。 - 依存関係プラットフォームのモジュールは、アプリケーションと下流の拡張機能に対する制約を担う。 - 開発者向け文書は、人が読むアーキテクチャとワークフローの案内を担う。 契約、ペイロード、認証、ナビゲーション、利用体験が境界をまたぐ場合は、バックエンドとフロントエンドの変更を1つのフルスタックタスクとして扱う。同じ変更の中で、公開契約、バックエンドのハンドラー、フロントエンドでの利用を同期させる。 ## APIが変わったらクライアントを作り直し、手で直さない 公開されるリクエスト型またはレスポンス型、ルート、ルーター契約、APIスキーマの注釈、生成スキーマ、認証、セッション動作が変わるたびに、フロントエンドへの影響を評価する。元の契約を更新した後、リポジトリ所定のコマンドでAPI記述とクライアントを再生成する。 生成されたクライアントファイルを直接編集してはならない。契約またはジェネレーターへの入力を修正し、出力を再生成して、生成された差分を確認する。生成出力を破壊的に変更する場合や、下流の利用者が依存している可能性のある公開APIを変更する場合は、事前に確認を取る。 ## フロントエンドの出力がバックエンドのビルドに入る流れを確かめる フロントエンドの出力が、デプロイ可能なバックエンド成果物へどのように組み込まれるかを把握する。バックエンドのビルドがコンパイル済みインターフェースをアプリケーションリソースへ埋め込む場合、フロントエンド出力の変更はすべてバックエンドのパッケージング経路にも影響するため、そこで検証しなければならない。 バックエンドのコンパイル、インターフェースのパッケージング、テストが同じ依存関係グラフを使うように、スタックをまたぐ統括処理はルートから実行する。ビルド時のダウンロード、プリセット拡張機能、コピーされた配布用成果物は、付随的なファイルではなくビルド契約の一部として扱う。 ## バージョンと整形ルールは、決められたファイルから読む 依存関係のバージョン、プロジェクトバージョン、言語リリース、プラグインのバージョン、フロントエンド依存関係は、それぞれ所定のカタログ、プロパティファイル、ビルドスクリプト、パッケージマニフェストから読み取る。すでに正本があるバージョンをハードコードしてはならない。 インデント、行幅、対応構文については、設定済みのフォーマッターとリンターを正本として使う。指定されている場合は`release 21`を含む宣言済みの言語リリースに従い、ルートレベルの整形ルールは、ビルドが期待するスコープに保つ。 ## リアクティブ処理にブロッキングI/Oを入れず、データベースの置き場所を守る 別の場所で仮想スレッドが有効になっていても、リアクティブな実行経路へブロッキングI/Oを持ち込んではならない。プロジェクトが選択したマイグレーションエンジンを、無断で別のものに置き換えず、データベース方言固有のマイグレーションは所定のデータベースディレクトリに置く。 拡張機能のスキーマ、実行時のJSONデータ、プロファイル固有の設定、上書き可能な作業ディレクトリは、それぞれの管理領域に保つ。埋め込み型のファイルベースデータベースには絶対ファイルパスを使う。相対URIを使うと、アプリケーションモジュール配下に意図しないディレクトリが作られ、開かれるデータベースが変わる可能性がある。 ## 変えた所がバックエンドかフロントエンドかで、テストを選ぶ 実際の変更範囲に応じて確認項目を選ぶ。 - バックエンドだけの変更では、リポジトリの整形処理と、影響を受けるバックエンドテストを実行する。 - フロントエンドだけの変更では、フロントエンドの整形、型検査、リント、関連するユニットテストを実行する。 - 契約変更では、API記述の生成、クライアントの再生成、フロントエンドの検証、バックエンドテストを実行する。 - スタックをまたぐ変更では、契約の両側に加え、最終的にパッケージ化された成果物も検証する。 まず対象を絞った確認を行い、必要に応じて範囲を広げる。変更したすべての動作についてテストを追加または更新し、必須の継続的インテグレーション検査に失敗が残っている間は作業を提出してはならない。 ## プッシュ前に正しいアップストリームを確かめ、必要なファイルだけステージする プッシュまたはレビュー開始の前に、現在のリポジトリを特定し、リモートを確認する。そのチェックアウトに対応する正しいアップストリームを対象にする。関連する公開リポジトリや専用リポジトリのアップストリームを使うと、元に戻すための負担が大きくなる可能性がある。 意図したアップストリームのベースから作業を始め、`upgrade/gradle-X`、`feat/name`、`fix/name`、`improvement/name`など、リポジトリのブランチ規約に従う。タスクに属するファイルだけをステージする。ビルド出力やデータベース成果物が存在する可能性がある場合は、`git add -A`や`git add .`を決して使わない。 古いワークツリーがメインブランチをロックしている場合は、ワークツリー一覧を調べ、古いと確認できた項目だけを明示的に取り除く。正確なロック所有者を特定する代わりに、広範囲のクリーンアップを使ってはならない。 ## マイグレーションや依存関係の追加は先に聞き、秘密情報はコミットしない 3段階の制御を使う。 - 常にルートから作業し、該当する入れ子のルールをすべて読み込み、ファイルを明示的にステージし、派生クライアントを元データから再生成し、変更した動作のテストを追加し、AI支援を受けた内容であることをレビュー説明に明記する。 - 公開APIの変更、ビルド依存関係またはパッケージ依存関係の追加、データベースマイグレーションの作成、セキュリティ設定または継続的インテグレーションのワークフローの変更、生成出力の破壊的な置換を行う前には確認を取る。 - 秘密情報のコミット、正本となるバージョンのハードコード、リアクティブ経路へのブロッキング処理の追加、生成クライアントの直接編集、正しいアップストリームを確認しないままのレビュー開始は、決して行わない。 実装自体が単純でも、これらの境界は適用される。実装の容易さによって、互換性、セキュリティ、データ、リリースに関するリスクが減るわけではない。 ## データベースの相対パスなど、ビルドでつまずきやすい点を避ける 既知のツール固有の不変条件を維持する。 1. ファイルベースの埋め込み型データベースの場所は、絶対ファイルシステムパスへ解決されなければならない。相対パス形式は、意図しないモジュールディレクトリを作り、アプリケーションが誤ったデータベースを開く原因になり得る。 2. ビルドラッパーのアップグレードには、バージョンを指定したラッパーコマンドと、2回目のラッパー生成コマンドの両方が必要である。最初のコマンドだけを実行すると、生成されたラッパーファイルの整合性が失われる。 3. リポジトリ全体に適用するその他の整形設定はルートに保つ。アプリケーションのサブモジュールへ移すと、互換性のないフォーマッタータスクが結合され、ビルドツール`9.x`の暗黙的依存関係の検証エラーが発生する。 これらの落とし穴は、正本となるビルド案内の近くに記録し、影響を受ける設定を変更するたびに検証する。