create-ai-project 1.11.2

package/docs/rules-ja/technical-spec.md

@@ -0,0 +1,86 @@
+# 技術設計ルール
+
+## 技術スタックの基本方針
+TypeScriptをベースとしたアプリケーション実装。アーキテクチャパターンはプロジェクトの要件と規模に応じて選択すること。
+
+## 環境変数管理とセキュリティ
+
+### 環境変数管理
+- 環境変数は一元管理し、型安全性を確保する仕組みを構築すること
+- `process.env` の直接参照は避け、設定管理層を通じて取得すること
+- デフォルト値の設定や必須チェックを適切に実装すること
+
+### セキュリティ
+- `.env`ファイルはGitに含めない
+- APIキーやシークレットは必ず環境変数として管理
+- 機密情報のログ出力は禁止
+- エラーメッセージに機密情報を含めない
+
+## アーキテクチャ設計
+
+### アーキテクチャ設計の原則
+プロジェクトごとに適切なアーキテクチャを選択し、明確に定義すること：
+
+- **明確な定義**: プロジェクトのアーキテクチャは`docs/rules/architecture/`配下に専用ファイルで定義
+- **責務の分離**: 各層やモジュールの責務を明確に定義し、境界を守ること
+
+## パターン適用の一貫性
+
+選択したアーキテクチャパターンに厳密に従う。プロジェクト固有詳細は`docs/rules/architecture/`参照。
+
+## データフロー統一原則
+
+#### 基本原則
+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

package/docs/rules-ja/typescript-testing.md

@@ -0,0 +1,149 @@
+# TypeScript テストルール
+
+## テストフレームワーク
+- **Vitest**: このプロジェクトではVitestを使用
+- テストのインポート: `import { describe, it, expect, beforeEach, vi } from 'vitest'`
+- モックの作成: `vi.mock()` を使用
+
+## テストの基本方針
+
+### 品質要件
+- **カバレッジ**: 単体テストのカバレッジは70%以上を必須
+- **独立性**: 各テストは他のテストに依存せず実行可能
+- **再現性**: テストは環境に依存せず、常に同じ結果を返す
+- **可読性**: テストコードも製品コードと同様の品質を維持
+
+### カバレッジ要件
+**必須**: 単体テストのカバレッジは70%以上
+**指標**: Statements（文）、Branches（分岐）、Functions（関数）、Lines（行）
+
+### テストの種類と範囲
+1. **単体テスト（Unit Tests）**
+   - 個々の関数やクラスの動作を検証
+   - 外部依存はすべてモック化
+   - 最も数が多く、細かい粒度で実施
+
+2. **統合テスト（Integration Tests）**
+   - 複数のコンポーネントの連携を検証
+   - 実際の依存関係を使用（DBやAPI等）
+   - 主要な機能フローの検証
+
+3. **E2Eテストでの機能横断検証**
+   - 新機能追加時、既存機能への影響を必ず検証
+   - Design Docの「統合ポイントマップ」で影響度「高」「中」の箇所をカバー
+   - 検証パターン: 既存機能動作 → 新機能有効化 → 既存機能の継続性確認
+   - 判定基準: レスポンス内容の変化なし、処理時間5秒以内
+   - CI/CDでの自動実行を前提とした設計
+
+## テストの実装規約
+
+### ディレクトリ構造
+```
+src/
+└── application/
+    └── services/
+        ├── __tests__/
+        │   ├── service.test.ts      # 単体テスト
+        │   └── service.int.test.ts  # 統合テスト
+        └── service.ts
+```
+
+### 命名規則
+- テストファイル: `{対象ファイル名}.test.ts`
+- 統合テストファイル: `{対象ファイル名}.int.test.ts`
+- テストスイート: 対象の機能や状況を説明する名前
+- テストケース: 期待される動作を説明する名前
+
+
+### テストコードの品質ルール
+
+✅ **推奨: すべてのテストを常に有効に保つ**
+- メリット: テストスイートの完全性を保証
+- 実践: 問題があるテストは修正して有効化
+
+❌ **避けるべき: test.skip()やコメントアウト**
+- 理由: テストの穴が生まれ、品質チェックが不完全になる
+- 対処: 不要なテストは完全に削除する
+
+## テスト品質基準
+
+### 境界値・異常系の網羅
+正常系に加え、境界値と異常系を含める。
+```typescript
+it('returns 0 for empty array', () => expect(calc([])).toBe(0))
+it('throws on negative price', () => expect(() => calc([{price: -1}])).toThrow())
+```
+
+### 期待値の直接記述
+期待値はリテラルで記述。実装ロジックを再現しない。
+```typescript
+expect(calcTax(100)).toBe(10)  // not: 100 * TAX_RATE
+```
+
+### 結果ベースの検証
+呼び出し順序・回数ではなく結果を検証。
+```typescript
+expect(mock).toHaveBeenCalledWith('a')  // not: toHaveBeenNthCalledWith
+```
+
+### 意味あるアサーション
+各テストに最低1つの検証を含める。
+```typescript
+it('creates user', async () => {
+  const user = await createUser({name: 'test'})
+  expect(user.id).toBeDefined()
+})
+```
+
+### 適切なモック範囲
+直接依存の外部I/Oのみモック。間接依存は実物使用。
+```typescript
+vi.mock('./database')  // 外部I/Oのみ
+```
+
+### Property-based Testing（fast-check）
+不変条件やプロパティを検証する場合はfast-checkを使用。
+```typescript
+import fc from 'fast-check'
+
+it('reverses twice equals original', () => {
+  fc.assert(fc.property(fc.array(fc.integer()), (arr) => {
+    return JSON.stringify(arr.reverse().reverse()) === JSON.stringify(arr)
+  }))
+})
+```
+
+**使用条件**: Design DocのACにProperty注釈が付与されている場合に使用。
+
+## モックの型安全性
+
+### 必要最小限の型定義
+```typescript
+// ✅ 必要な部分のみ
+type TestRepo = Pick<Repository, 'find' | 'save'>
+const mock: TestRepo = { find: vi.fn(), save: vi.fn() }
+
+// やむを得ない場合のみ、理由明記
+const sdkMock = {
+  call: vi.fn()
+} as unknown as ExternalSDK // 外部SDKの複雑な型のため
+```
+
+## Vitestの基本例
+
+```typescript
+import { describe, it, expect, vi } from 'vitest'
+
+vi.mock('./userService', () => ({
+  getUserById: vi.fn(),
+  updateUser: vi.fn()
+}))
+
+describe('ComponentName', () => {
+  it('should follow AAA pattern', () => {
+    const input = 'test'
+    const result = someFunction(input)
+    expect(result).toBe('expected')
+  })
+})
+```

package/docs/rules-ja/typescript.md

@@ -0,0 +1,116 @@
+# TypeScript 開発ルール
+
+## Backend実装における型安全性
+
+**データフローでの型安全性**
+入力層（`unknown`） → 型ガード → ビジネス層（型保証） → 出力層（シリアライズ）
+
+**Backend固有の型シナリオ**:
+- **API通信**: レスポンスは必ず`unknown`で受け、型ガードで検証
+- **フォーム入力**: 外部入力は`unknown`、バリデーション後に型確定
+- **レガシー統合**: `window as unknown as LegacyWindow`のように段階的アサーション
+- **テストコード**: モックも必ず型定義、`Partial<T>`や`vi.fn<[Args], Return>()`活用
+
+## コーディング規約
+
+**クラス使用の判断基準**
+- **推奨：関数とinterfaceでの実装**
+  - 背景: テスタビリティと関数合成の柔軟性が向上
+- **クラス使用を許可**: 
+  - フレームワーク要求時（NestJSのController/Service、TypeORMのEntity等）
+  - カスタムエラークラス定義時
+  - 状態とビジネスロジックが密結合している場合（例: ShoppingCart、Session、StateMachine）
+- **判断基準**: 「このデータは振る舞いを持つか？」がYesならクラス検討
+  ```typescript
+  // ✅ 関数とinterface
+  interface UserService { create(data: UserData): User }
+  const userService: UserService = { create: (data) => {...} }
+  ```
+
+**関数設計**
+- **引数は0-2個まで**: 3個以上はオブジェクト化
+  ```typescript
+  // ✅ オブジェクト引数
+  function createUser({ name, email, role }: CreateUserParams) {}
+  ```
+
+**依存性注入**
+- **外部依存は引数で注入**: テスト可能性とモジュール性確保
+  ```typescript
+  // ✅ 依存性を引数で受け取る
+  function createService(repository: Repository) { return {...} }
+  ```
+
+**非同期処理**
+- Promise処理: 必ず`async/await`を使用
+- エラーハンドリング: 必ず`try-catch`でハンドリング
+- 型定義: 戻り値の型は明示的に定義（例: `Promise<Result>`）
+
+**フォーマット規則**
+- セミコロン省略（Biomeの設定に従う）
+- 型は`PascalCase`、変数・関数は`camelCase`
+- インポートは絶対パス（`src/`）
+
+**クリーンコード原則**
+- ✅ 使用されていないコードは即座に削除
+- ✅ デバッグ用`console.log()`は削除
+- ❌ コメントアウトされたコード（バージョン管理で履歴管理）
+- ✅ コメントは「なぜ」を説明（「何」ではなく）
+
+## エラーハンドリング
+
+**絶対ルール**: エラーの握りつぶし禁止。すべてのエラーは必ずログ出力と適切な処理を行う。
+
+**Fail-Fast原則**: エラー時は速やかに失敗させ、不正な状態での処理継続を防ぐ
+```typescript
+// ❌ 禁止: 無条件フォールバック
+catch (error) {
+  return defaultValue // エラーを隠蔽
+}
+
+// ✅ 必須: 明示的な失敗
+catch (error) {
+  logger.error('処理失敗', error)
+  throw error // 上位層で適切に処理
+}
+```
+
+**Result型パターン**: エラーを型で表現し、明示的に処理
+```typescript
+type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }
+
+// 使用例：エラーの可能性を型で表現
+function parseUser(data: unknown): Result<User, ValidationError> {
+  if (!isValid(data)) return { ok: false, error: new ValidationError() }
+  return { ok: true, value: data as User }
+}
+```
+
+**カスタムエラークラス**
+```typescript
+export class AppError extends Error {
+  constructor(message: string, public readonly code: string, public readonly statusCode = 500) {
+    super(message)
+    this.name = this.constructor.name
+  }
+}
+// 用途別: ValidationError(400), BusinessRuleError(400), DatabaseError(500), ExternalServiceError(502)
+```
+
+**層別エラー処理**
+- API層: HTTPレスポンスに変換、機密情報を除外してログ出力
+- サービス層: ビジネスルール違反を検出、AppErrorはそのまま伝播
+- リポジトリ層: 技術的エラーをドメインエラーに変換
+
+**構造化ログと機密情報保護**
+機密情報（password, token, apiKey, secret, creditCard）は絶対にログに含めない
+
+**非同期エラーハンドリング**
+- グローバルハンドラー設定必須: `unhandledRejection`, `uncaughtException`
+- すべてのasync/awaitでtry-catch使用
+- エラーは必ずログと再スロー
+
+## パフォーマンス最適化
+
+- ストリーミング処理: 大きなデータセットはストリームで処理
+- メモリリーク防止: 不要なオブジェクトは明示的に解放

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "create-ai-project",
+  "version": "1.11.2",
+  "packageManager": "npm@10.8.2",
+  "description": "TypeScript project boilerplate optimized for Claude Code development with comprehensive development rules, architecture patterns, and quality assurance tools",
+  "keywords": [
+    "typescript",
+    "boilerplate",
+    "template",
+    "starter",
+    "scaffolding",
+    "cli",
+    "claude-code",
+    "anthropic",
+    "ai-development",
+    "llm-development"
+  ],
+  "author": "Shinsuke Kagawa",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shinpr/ai-coding-project-boilerplate.git"
+  },
+  "bin": {
+    "create-ai-project": "./bin/create-project.js"
+  },
+  "scripts": {
+    "build": "tsc && tsc-alias",
+    "build:backend": "tsc && tsc-alias",
+    "build:frontend": "vite build",
+    "dev": "tsx src/index.ts",
+    "dev:frontend": "vite",
+    "watch": "tsx watch src/index.ts",
+    "preview": "vite preview",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "test:coverage:summary": "node scripts/show-coverage.js",
+    "test:coverage:clean": "rm -rf coverage .vitest-cache",
+    "test:coverage:fresh": "npm run test:coverage:clean && npm run test:coverage",
+    "test:watch": "vitest",
+    "format": "biome format --write src",
+    "format:check": "biome format src",
+    "lint": "biome lint src",
+    "lint:fix": "biome lint --write src",
+    "check": "biome check src",
+    "check:fix": "biome check --write src",
+    "check:unused": "node scripts/check-unused-exports.js",
+    "check:unused:all": "ts-prune --project tsconfig.json --ignore 'src/index.ts|__tests__|test|vitest'",
+    "check:deps": "madge --circular --extensions ts src",
+    "check:deps:graph": "madge --extensions ts --image graph.svg src",
+    "check:code": "npm run check && npm run check:unused && npm run check:deps && npm run build",
+    "check:all": "npm run check:code && npm run test",
+    "cleanup:processes": "bash ./scripts/cleanup-test-processes.sh",
+    "test:safe": "npm test && npm run cleanup:processes",
+    "lang:ja": "node scripts/set-language.js ja",
+    "lang:en": "node scripts/set-language.js en",
+    "lang:status": "node scripts/set-language.js --status",
+    "postinstall": "node scripts/set-language.js ja",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.0.0",
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/ui": "^3.2.4",
+    "c8": "^10.1.3",
+    "fast-check": "^4.3.0",
+    "husky": "^9.1.7",
+    "jsdom": "^25.0.0",
+    "lint-staged": "^16.1.0",
+    "madge": "^8.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "ts-node": "^10.9.1",
+    "ts-prune": "^0.10.3",
+    "tsc-alias": "^1.8.7",
+    "tsx": "^4.19.4",
+    "typescript": "^5.0.0",
+    "vite": "^5.0.0",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "lint-staged": {
+    "src/**/*.{ts,tsx}": [
+      "biome check --write --no-errors-on-unmatched",
+      "biome format --write --no-errors-on-unmatched"
+    ]
+  }
+}

package/scripts/check-unused-exports.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+/**
+ * Unused exports checker script
+ * Filters out "used in module" from ts-prune output to show only truly unused exports
+ */
+
+const { execSync } = require('child_process')
+
+try {
+  // Run ts-prune
+  const output = execSync(
+    'npx ts-prune --project tsconfig.json --ignore "src/index.ts|__tests__|test|vitest"',
+    { encoding: 'utf8' }
+  )
+
+  // Process each line
+  const lines = output.split('\n').filter(line => line.trim())
+  const results = {
+    usedInModule: [],
+    trulyUnused: [],
+    total: 0
+  }
+
+  for (const line of lines) {
+    if (line.includes(' - ')) {
+      results.total++
+      if (line.includes('(used in module)')) {
+        results.usedInModule.push(line)
+      } else {
+        results.trulyUnused.push(line)
+      }
+    }
+  }
+
+  // Display results
+  console.log('=== Unused Exports Analysis ===\n')
+  
+  if (results.trulyUnused.length > 0) {
+    console.log(`🔴 Truly unused exports: ${results.trulyUnused.length}`)
+    console.log('─'.repeat(50))
+    results.trulyUnused.forEach(line => console.log(line))
+    console.log('')
+  } else {
+    console.log('✅ No truly unused exports found\n')
+  }
+
+  if (results.usedInModule.length > 0) {
+    console.log(`⚠️ Used only in module (unnecessary exports): ${results.usedInModule.length}`)
+    console.log('─'.repeat(50))
+    results.usedInModule.forEach(line => console.log(line))
+    console.log('')
+  } else {
+    console.log('✅ No unnecessary internal exports found\n')
+  }
+
+  // Summary
+  console.log('=== Summary ===')
+  console.log(`Total unnecessary exports: ${results.total}`)
+  console.log(`├── Truly unused: ${results.trulyUnused.length} (delete immediately)`)
+  console.log(`└── Used in module only: ${results.usedInModule.length} (remove export keyword)`)
+
+  // Exit code
+  process.exit(results.trulyUnused.length > 0 ? 1 : 0)
+
+} catch (error) {
+  console.error('Error occurred:', error.message)
+  process.exit(1)
+}

package/scripts/cleanup-test-processes.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+
+# Vitest process cleanup script
+# Check and remove zombie processes after test execution
+
+echo "🔍 Checking for remaining test processes..."
+
+# Vitest process check
+VITEST_PROCESSES=$(ps aux | grep vitest | grep -v grep || true)
+if [ -n "$VITEST_PROCESSES" ]; then
+    echo "⚠️  Found vitest processes:"
+    echo "$VITEST_PROCESSES"
+    echo "🔥 Killing vitest processes..."
+    pkill -f vitest
+    echo "✅ Vitest processes cleaned up"
+else
+    echo "✅ No vitest processes found"
+fi
+
+# Node test process check
+NODE_TEST_PROCESSES=$(ps aux | grep "node.*test" | grep -v grep || true)
+if [ -n "$NODE_TEST_PROCESSES" ]; then
+    echo "⚠️  Found node test processes:"
+    echo "$NODE_TEST_PROCESSES"
+    echo "🔥 Killing node test processes..."
+    pkill -f "node.*test"
+    echo "✅ Node test processes cleaned up"
+else
+    echo "✅ No node test processes found"
+fi
+
+echo "🧹 Process cleanup completed!"

package/scripts/post-setup.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+/**
+ * Initialize git repository
+ */
+function initGit() {
+  try {
+    console.log('🔧 Initializing git repository...');
+    execSync('git init', { stdio: 'inherit' });
+    
+    console.log('📝 Creating initial commit...');
+    execSync('git add -A', { stdio: 'inherit' });
+    execSync('git commit -m "Initial commit from AI Coding Project Boilerplate"', { stdio: 'inherit' });
+    
+    return true;
+  } catch (error) {
+    console.warn('⚠️  Git initialization skipped (git might not be installed)');
+    return false;
+  }
+}
+
+/**
+ * Clean up files that shouldn't be in the user's project
+ */
+function cleanupFiles() {
+  console.log('🧹 Cleaning up setup files...');
+  
+  const filesToRemove = [
+    'bin/create-project.js',
+    'templates/.gitignore.template',
+    'scripts/setup-project.js',
+    'scripts/post-setup.js'
+  ];
+  
+  const dirsToRemove = [
+    'bin',
+    'templates'
+  ];
+  
+  // Remove files
+  for (const file of filesToRemove) {
+    const filePath = path.join(process.cwd(), file);
+    if (fs.existsSync(filePath)) {
+      fs.unlinkSync(filePath);
+    }
+  }
+  
+  // Remove empty directories
+  for (const dir of dirsToRemove) {
+    const dirPath = path.join(process.cwd(), dir);
+    if (fs.existsSync(dirPath)) {
+      try {
+        fs.rmdirSync(dirPath);
+      } catch (e) {
+        // Directory might not be empty, ignore
+      }
+    }
+  }
+}
+
+/**
+ * Show next steps to the user
+ */
+function showNextSteps() {
+  const packageJson = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+  const projectName = packageJson.name;
+  
+  console.log('\n🎉 Project setup completed successfully!\n');
+  console.log('📋 Next steps:\n');
+  console.log(`   cd ${projectName}`);
+  console.log('   npm install');
+  console.log('   npm run dev\n');
+  console.log('🌐 Language switching:\n');
+  console.log('   npm run lang:ja   # Switch to Japanese');
+  console.log('   npm run lang:en   # Switch to English\n');
+  console.log('📖 Available commands:\n');
+  console.log('   npm run dev         # Start development');
+  console.log('   npm run build       # Build for production');
+  console.log('   npm run test        # Run tests');
+  console.log('   npm run check:all   # Run all quality checks\n');
+  console.log('Happy coding! 🚀\n');
+}
+
+/**
+ * Main post-setup process
+ */
+function main() {
+  try {
+    // Initialize git repository
+    initGit();
+    
+    // Clean up setup-specific files
+    cleanupFiles();
+    
+    // Show next steps
+    showNextSteps();
+  } catch (error) {
+    console.error(`❌ Post-setup failed: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+// Run post-setup
+if (require.main === module) {
+  main();
+}