フルスタックのリポジトリを、決まったコマンドとテストを守って直す

## 最初にリポジトリの文書を読み、ブランチとプルリクエストで進める 変更を計画する前に、リポジトリ全体のガイダンス、サブシステムの文書、パッケージマニフェスト、近隣の実装を読む。フロントエンド、API、SDK、CLI、データベース、コンテナ、文書を含め、影響を受けるすべての領域を特定する。 保護されたデフォルトブランチは、直接開発する際には読み取り専用として扱う。内容が分かる名前のブランチを作成し、意味のあるコミットを行い、レビュー用のプルリクエストを開く。既存コミットを書き換えて共有履歴を改変してはならない。また、その判断がレビュアーに割り当てられているワークフローでは、自分のプルリクエストを自分でマージしてはならない。 ブランチの範囲は要求された動作に集中させる。無関係な整理は分離し、意図的な変更をタスクが必要としない限り、確立されたパターンを維持する。 ## リポジトリのコマンドと、固定されたランタイムの版を使う 実行前に、文書化された開発、整形、リント、テスト、マイグレーション、起動の各コマンドを確認する。ルート全体を対象とするツールで代用せず、影響を受けるパッケージが管理するコマンドを使う。 固定されたランタイムの版と既存環境を尊重する。より新しいメジャー版のランタイムが自動的にサポートされるとは限らない。依存関係は不足している場合にだけインストールする。タスクまたは関連する検証で必要とされない限り、アプリケーションスタック全体、コンテナ、長時間稼働するサーバーを起動してはならない。 変更したファイルには、文書で指定されたモードのフォーマッターとリンターを実行する。サポートされた単一テストの指定方法から始め、直接影響を受けるテスト群だけへ範囲を広げる。 サブシステムがソースツリーではなくインストール済みのSDKパッケージを読み込む場合は、編集後にそのSDKを再インストールし、利用側のプロセスを再起動する。複数の開発プロセスを起動する前に、必要なポートと前提条件を確認する。 ## 画面・API・サービス・マイグレーションの役目を分けたまま直す 編集前に責務を整理する。 - ユーザーインターフェースは表示とクライアント状態を担当する。 - APIは要求の検証と通信上の関心事を担当する。 - サービスモジュールはビジネスロジックを担当する。 - SDKとCLIのパッケージは、それぞれの公開インターフェース契約を担当する。 - マイグレーションはデータベースの発展を担当する。 変更対象のサブシステムに関する文書を読み、新しいパターンを導入する前に類似する既存ファイルを調べる。変更が複数の層にまたがる場合は、型またはスキーマの定義、サービスロジックの実装、API契約の提示、クライアントの更新、インターフェースの構築という小さな手順で進める。 依存関係は、それを利用するパッケージへインストールする。ワークスペースパッケージを追加する場合は、依存関係をインストールする前にパッケージのメタデータを複製する、本番用および手元のコンテナビルド用マニフェストをすべて更新する。 ## TypeScript・Python・データベースの決まりを守る 厳密なTypeScript型を使い、制約のない型を避け、コンポーネントとAPIの契約を明確に定義し、リポジトリで確立されたコンポーネントと状態管理のパターンに従う。深い階層でプロパティを受け渡すより、関数コンポーネントと明示的な状態操作を優先する。 Pythonコードでは、すべての関数境界に型ヒントを付け、直列化には検証モデルを使い、ビジネスロジックを通信ルーターではなくサービスに置く。ルーターは要求を検証し、サービスを呼び出し、応答の形を整える。 外部キーの禁止を含め、既存のテーブル規則とマイグレーション規則に従う。サポート対象のすべてのエンジンでデータベース操作の移植性を保つ。タイムスタンプ項目には、現地時刻、非推奨API、独自の変換ではなく、リポジトリのUTC補助機能を使う。 ファイルシステムとデータベースのどちらに保存するかについて、リポジトリの判断を尊重する。利便性だけを理由に、同期対象のクラスターデータをデータベースへ移してはならない。 ## 動作を担当する層の、決まったテストで確かめる 各サブシステムで実際に構成されているテスト方式を使う。フロントエンドに単体テストの枠組みがない場合は、サポートされていない実行環境を導入せず、指定されたエンドツーエンドテスト群で動作を確認する。バックエンドの単体テストとサービステストは確立されたツリーへ置き、CLIのソースを変更した後はCLIテスト群を実行する。 外部ストレージ、計算資源の提供元、ファイルシステムとのやり取りを模擬し、テストを高速かつ決定的に保つ。APIスタック全体を必要としないビジネス規則は、サービスを直接テストする。 まず対象を絞ったテストを一件実行し、次に関連するサブシステムのテスト群を実行する。既存データがあっても繰り返し安全に実行できるようにし、安定したセレクターを使い、待ち行列の処理や状態遷移には現実的なタイムアウトを設定する。 コマンド名だけを根拠に成功を主張してはならない。意図したテストファイルが検出され、結果が変更した動作を実際に検証していることを確認する。 ## 変えた画面をブラウザーで確かめ、ログインが要るAPIを試す 表示確認には、リポジトリで承認された対話型ブラウザーツールを使う。自動エンドツーエンドスクリプトは、保守されているテスト群または明示された依頼のために確保する。必要なテスト用アプリケーションだけを起動し、変更したページと直接関連するページへ移動し、証拠を取得して、目に見える後退を修正する。 ロール、完全一致テキスト、プレースホルダーを使ったセレクターを優先する。データベースが空であると仮定せず、繰り返し作られたテストデータを処理する。ターミナルエミュレーターが描画する内容はDOMに存在しない場合があるため、必要に応じて裏側のAPIから検証する。 認証付きAPIを確認する際は、文書化されたテスト用IDと認証フローを使う。必要なアカウントまたはテナント範囲のヘッダーを指定し、保護されたエンドポイントと保護されていないエンドポイントを区別する。再利用可能な認証情報をソース、ログ、成果物の文書へ記載してはならない。 ## 依存関係を慎重に足し、ログにパスワードを残さない 依存関係を追加する前にパッケージマニフェストを確認し、リポジトリのインストール手順を使う。プロジェクトがコミット前の整形フックとリントフックに依存している場合は、それらを有効な状態に保つ。 依存関係の上書き指定は、恒久的な飾りではなく一時的なセキュリティ管理として扱う。親パッケージをアップグレードする際は、上書き指定を外せるかテストし、関連する脆弱性スキャンを実行する。解決された依存関係がまだ安全でない場合は、上書き指定を維持する。 連携機能のテスト中に認証情報の露出範囲を広げてはならない。実際の動作がテスト対象でない外部提供元は模擬し、ログにトークン、パスワード、個人識別子を残さない。 ## 終える前に差分を確かめ、実行した確認を報告する 計画前に読み、まとまりを保てる最小の実装を行い、範囲を広げる前に影響を受ける各境界を検証する。大きな変更では、バックエンド、API、クライアント、インターフェースの作業を不透明な一つの手順に混在させず、順序を明示してレビュー可能に保つ。 完了を報告する前に差分を確認し、変更した領域に必要なフォーマッター、リンター、型検査、テスト、マイグレーション検査、表示確認を実行する。体裁を整えるためだけに、全体ビルドや無関係なテスト群を追加してはならない。 変更内容、実行した確認、範囲外に残した広い確認、残存リスクを報告する。完了には、編集が成功したという事実だけでなく、変更した動作から得た証拠が必要である。