technical-spec

# 技術設計ルール ## 前提条件の検出 技術やコマンドに固有のルールを適用する前に、マニフェスト、ロックファイル、ビルド・テスト設定、CI定義、代表的なソースファイルを確認する。ツール、スクリプト、パスエイリアス、ランタイムは、リポ��トリ内の根拠に明記されている場合にのみ確認済みとして扱う。周辺のパターンから導いた結論には推測であることを明記する。不足している判断によってアーキテクチャ、互換性、セキュリティ、検証方法が変わる場合は作業を止め、必要な設定またはユーザー判断を具体的に示す。 ## 技術スタックの基本方針 リポジトリ設定からTypeScriptアプリケーションであることを確認できる場合に、このルールを適用する。現行要件と合意済みの制約を、モジュールの責務、依存方向、データフロー、検証境界へ明示的に対応づけてアーキテクチャを選択する。 ## 環境変数管理とセキュリティ ### 環境変数管理 - 環境変数と、その型安全性を担保するビルド時の検証機構を一元管理する - 環境変数は1つの型付き設定境界で読み取り、アプリケーションコードでは検証済みの設定値を使用する - 要件で未設定時の有効な振る舞いが定義されている場合にのみデフォルト値を設ける。それ以外は、変数名と期待する形式を示して設定検証を失敗させる ### セキュリティ - ローカルの`.env`ファイルはバージョン管理の対象外とし、必要な変数名はシークレットを含まないサンプルファイルで示す - APIキーやシークレットは、設定済みのシークレットストアまたはランタイム環境との境界から読み込む - 現在の信頼境界で許可されたフィールドだけをログおよびレスポンスに含める。認証情報、トークン、個人データ、内部診断情報は、信頼されていない相手に返す前に除去する ## アーキテクチャ設計 ### アーキテクチャ設計の原則 以下の観測可能な判断に基づいてアーキテクチャを選択する： - **責務**: 各モジュールや層について、自身が担う振る舞いと委譲する振る舞いを明記する - **依存方向**: importとランタイム呼び出しは、設定または代表的な実装から確認したプロジェクトの境界ルールに従う - **状態・データの所有者**: 永続化される値または可変値ごとに、唯一の正規の所有者を定める - **検証境界**: 公開契約ごとに、それを観測できるUnit、Integration、E2Eいずれかのチェックを設ける ## データフロー統一原則 #### 基本原則 1. **単一データソース**: 同じ情報は1箇所にのみ保存する 2. **構造化データ優先**: JSON文字列ではなくパース済みオブジェクトを使用 3. **責務の分離**: 各層が所有するデータまたは振る舞いと、他の層が利用するための境界を明記する #### データフロ��のベストプラクティス - **入力時点での検証**: データは入力層で検証し、型安全な形で内部に渡す - **変換の一元化**: データ変換ロジックは専用のユーティリティに集約 - **ログの構造化**: データフローの各段階で構造化ログを出力 ## ビルドとテスト `packageManager`フィールド、ロックファイル、確立済みのCIコマンドの順にパッケージマネージャーを判定する。選択したマニフェストに存在するスクリプトだけを実行する。 ### ビルドコマンド - `build` - TypeScriptビルド - `type-c...