Technical spec

技術設計ルール

前提条件の検出

技術やコマンドに固有のルールを適用する前に、マニフェスト、ロックファイル、ビルド・テスト設定、CI定義、代表的なソースファイルを確認する。ツール、スクリプト、パスエイリアス、ランタイムは、リポジトリ内の根拠に明記されている場合にのみ確認済みとして扱う。周辺のパターンから導いた結論には推測であることを明記する。不足している判断によってアーキテクチャ、互換性、セキュリティ、検証方法が変わる場合は作業を止め、必要な設定またはユーザー判断を具体的に示す。

技術スタックの基本方針

リポジトリ設定からTypeScriptアプリケーションであることを確認できる場合に、このルールを適用する。現行要件と合意済みの制約を、モジュールの責務、依存方向、データフロー、検証境界へ明示的に対応づけてアーキテクチャを選択する。

環境変数管理とセキュリティ

環境変数管理

• 環境変数と、その型安全性を担保するビルド時の検証機構を一元管理する
• 環境変数は1つの型付き設定境界で読み取り、アプリケーションコードでは検証済みの設定値を使用する
• 要件で未設定時の有効な振る舞いが定義されている場合にのみデフォルト値を設ける。それ以外は、変数名と期待する形式を示して設定検証を失敗させる

セキュリティ

• ローカルの.envファイルはバージョン管理の対象外とし、必要な変数名はシークレットを含まないサンプルファイルで示す
• APIキーやシークレットは、設定済みのシークレットストアまたはランタイム環境との境界から読み込む
• 現在の信頼境界で許可されたフィールドだけをログおよびレスポンスに含める。認証情報、トークン、個人データ、内部診断情報は、信頼されていない相手に返す前に除去する

アーキテクチャ設計

アーキテクチャ設計の原則

以下の観測可能な判断に基づいてアーキテクチャを選択する：

• 責務: 各モジュールや層について、自身が担う振る舞いと委譲する振る舞いを明記する
• 依存方向: importとランタイム呼び出しは、設定または代表的な実装から確認したプロジェクトの境界ルールに従う
• 状態・データの所有者: 永続化される値または可変値ごとに、唯一の正規の所有者を定める
• 検証境界: 公開契約ごとに、それを観測できるUnit、Integration、E2Eいずれかのチェックを設ける

データフロー統一原則

基本原則

1. 単一データソース: 同じ情報は1箇所にのみ保存する
2. 構造化データ優先: JSON文字列ではなくパース済みオブジェクトを使用
3. 責務の分離: 各層が所有するデータまたは振る舞いと、他の層が利用するための境界を明記する

データフローのベストプラクティス

• 入力時点での検証: データは入力層で検証し、型安全な形で内部に渡す
• 変換の一元化: データ変換ロジックは専用のユーティリティに集約
• ログの構造化: データフローの各段階で構造化ログを出力

ビルドとテスト

packageManagerフィールド、ロックファイル、確立済みのCIコマンドの順にパッケージマネージャーを判定する。選択したマニフェストに存在するスクリプトだけを実行する。

ビルドコマンド

• build - TypeScriptビルド
• type-check - 型チェック（emit なし）

テストコマンド

• test - テスト実行
• test:coverage - カバレッジ測定
• test:coverage:fresh - カバレッジ測定（キャッシュクリア）
• test:safe - 安全なテスト実行（自動クリーンアップ付き）
• cleanup:processes - Vitestプロセスのクリーンアップ

品質保証メカニズムの認識

品質チェック実行前に、変更対象領域にどのような品質メカニズムが存在するかを特定する:

• 一次検出: 変更対象のファイル種別、プロジェクトマニフェスト、設定から適用可能な品質ツールを特定
  • 影響パスをカバーするCIパイプライン定義を確認
  • ドメイン固有のlinterやバリデータ設定（スキーマバリデータ、API specバリデータ、設定ファイルリンター等）を確認
  • プロジェクト設定におけるドメイン固有の制約（命名規約、文字数制限、フォーマット要件）を確認
• 補助ヒント: タスクファイルに品質保証メカニズムが記載されている場合 → どのドメイン固有チェックを探すべきかの追加ヒントとして使用
• 検出したドメイン固有チェックを以下の標準品質フェーズに併せて実行

品質チェック要件

品質チェックは実装完了時に必須：

Phase 1-3: コード品質チェック

• package.jsonから以下に該当するスクリプトを自動検出して実行:
  • lint + format チェック
  • 未使用エクスポートの検出
  • 循環依存の検出
  • TypeScriptビルド

フェーズ移行の証跡: 適用対象となる静的チェックとドメイン固有チェックがすべて正常終了していること。必須スクリプトが存在しない場合はマニフェストまたは設定のパスとともに報告し、確立済みの同等コマンドが特定されるまで次のPhaseへ進まない。

Phase 4: テスト

• test - テスト実行

フェーズ移行の証跡: 適用対象として設定されているテストスイートがすべて成功していること。環境依存のテストスイートを実行できない場合は、ブロック要因となる前提条件を具体的に記録する。

Phase 5: コード品質再検証

• check:code - コード品質の再検証（Phase 4でのテスト修正による副作用を清掃）

完了証跡: テストに伴う修正後も静的チェックとドメイン固有チェックが成功し、ビルドが成功していること。必須テストはすべて成功しているか、実行を妨げる要因が明示されていること。

補助コマンド

• check:all - 全体統合チェック（check:code + test）※手動一括確認用
• open coverage/index.html - カバレッジレポート確認
• format - フォーマット修正
• lint:fix - Lint修正

トラブルシューティング

• ポート使用中エラー: cleanup:processes スクリプトを実行
• キャッシュ問題: test:coverage:fresh スクリプトを実行
• 依存関係エラー: まず、失敗した依存解決処理の出力、選択したパッケージマネージャー、マニフェスト、ロックファイルの状態を記録する。ロックファイルと生成物を維持できる、リポジトリで確立済みのクリーンインストールコマンドだけを使用する。依存関係の状態を削除または再生成する操作には事前承認を得る

カバレッジ

• カバレッジは目標ではなく未テスト領域を見つける診断シグナルとして扱う（目標化すると自明なテストに歪む — グッドハートの法則）。クリティカルパスとビジネスロジックなど、リグレッションが問題になる箇所にテストを集中させる
• 強制する数値しきい値はプロジェクトの CI / カバレッジ設定であり、それ自体が目的ではない
• メトリクス（カバレッジレポートの内訳）: Statements、Branches、Functions、Lines