shinpr/technical-spec

技術設計ルール

技術スタックの基本方針

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プロセスのクリーンアップ

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

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

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

品質チェック要件

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

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