技術設計ルール
技術スタックの基本方針
TypeScriptをベースとしたアプリケーション実装。アーキテクチャパターンはプロジェクトの要件と規模に応じて選択すること。
環境変数管理とセキュリティ
環境変数管理
- 環境変数は一元管理し、型安全性を確保する仕組みを構築すること
process.envの直接参照は避け、設定管理層を通じて取得すること- デフォルト値の設定や必須チェックを適切に実装すること
セキュリティ
.envファイルはGitに含めない- APIキーやシークレットは必ず環境変数として管理
- 機密情報のログ出力は禁止
- エラーメッセージに機密情報を含めない
アーキテクチャ設計
アーキテクチャ設計の原則
プロジェクトごとに適切なアーキテクチャを選択し、明確に定義すること：
- 責務の分離: 各層やモジュールの責務を明確に定義し、境界を守ること
データフロー統一原則
基本原則
- 単一データソース: 同じ情報は1箇所にのみ保存する
- 構造化データ優先: JSON文字列ではなくパース済みオブジェクトを使用
- 明確な責務分離: 各層の責務を明確に定義
データフローのベストプラクティス
- 入力時点での検証: データは入力層で検証し、型安全な形で内部に渡す
- 変換の一元化: データ変換ロジックは専用のユーティリティに集約
- ログの構造化: データフローの各段階で構造化ログを出力
ビルドとテスト
package.jsonのpackageManagerフィールドに応じた実行コマンドを使用すること。
ビルドコマンド
build- TypeScriptビルドtype-check- 型チェック（emit なし）
テストコマンド
test- テスト実行test:coverage- カバレッジ測定test:coverage:fresh- カバレッジ測定（キャッシュクリア）test:safe- 安全なテスト実行（自動クリーンアップ付き）cleanup:processes- Vitestプロセスのクリーンアップ
品質チェック要件
品質チェックは実装完了時に必須：
Phase 1-3: コード品質チェック
- package.jsonから以下に該当するスクリプトを自動検出して実行:
- lint + format チェック
- 未使用エクスポートの検出
- 循環依存の検出
- 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