---

name: technical-spec description: 環境変数、アーキテクチャ設計、ビルド・テストコマンドを定義。環境設定、アーキテクチャ設計時に使用。

技術設計ルール

技術スタックの基本方針

TypeScriptをベースとしたアプリケーション実装。アーキテクチャパターンはプロジェクトの要件と規模に応じて選択すること。

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

環境変数管理

• 環境変数は一元管理し、型安全性を確保する仕組みを構築すること
• process.env の直接参照は避け、設定管理層を通じて取得すること
• デフォルト値の設定や必須チェックを適切に実装すること

セキュリティ

• .envファイルはGitに含めない
• APIキーやシークレットは必ず環境変数として管理
• 機密情報のログ出力は禁止
• エラーメッセージに機密情報を含めない

アーキテクチャ設計

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

プロジェクトごとに適切なアーキテクチャを選択し、明確に定義すること：

• 責務の分離: 各層やモジュールの責務を明確に定義し、境界を守ること

データフロー統一原則

基本原則

1. 単一データソース: 同じ情報は1箇所にのみ保存する
2. 構造化データ優先: JSON文字列ではなくパース済みオブジェクトを使用
3. 明確な責務分離: 各層の責務を明確に定義

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

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

ビルドとテスト

package.jsonのpackageManagerフィールドに応じた実行コマンドを使用すること。

ビルドコマンド

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

テストコマンド

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

品質チェック要件

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

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

• check - Biome（lint + format）
• check:unused - 未使用エクスポートの検出
• check:deps - 循環依存の検出
• build - TypeScriptビルド

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 スクリプトを実行
• 依存関係エラー: 依存関係のクリーンインストールを実行

カバレッジ要件

• 必須: ユニットテストカバレッジは70%以上
• メトリクス: Statements、Branches、Functions、Lines