create-ai-project 1.11.2

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

@@ -0,0 +1,86 @@
+# Technical Design Rules
+
+## Basic Technology Stack Policy
+TypeScript-based application implementation. Architecture patterns should be selected according to project requirements and scale.
+
+## Environment Variable Management and Security
+
+### Environment Variable Management
+- Centrally manage environment variables and build mechanisms to ensure type safety
+- Avoid direct references to `process.env`, obtain through configuration management layer
+- Properly implement default value settings and mandatory checks
+
+### Security
+- Do not include `.env` files in Git
+- Always manage API keys and secrets as environment variables
+- Prohibit logging of sensitive information
+- Do not include sensitive information in error messages
+
+## Architecture Design
+
+### Architecture Design Principles
+Select appropriate architecture for each project and define clearly:
+
+- **Clear Definition**: Project architecture is defined in dedicated files under `docs/rules/architecture/`
+- **Separation of Responsibilities**: Clearly define responsibilities for each layer and module, and maintain boundaries
+
+## Pattern Application Consistency
+
+Strictly follow selected architecture patterns. See `docs/rules/architecture/` for project-specific details.
+
+## Unified Data Flow Principles
+
+#### Basic Principles
+1. **Single Data Source**: Store the same information in only one place
+2. **Structured Data Priority**: Use parsed objects rather than JSON strings
+3. **Clear Responsibility Separation**: Clearly define responsibilities for each layer
+
+#### Data Flow Best Practices
+- **Validation at Input**: Validate data at input layer and pass internally in type-safe form
+- **Centralized Transformation**: Consolidate data transformation logic in dedicated utilities
+- **Structured Logging**: Output structured logs at each stage of data flow
+
+## Build and Testing
+Use the appropriate run command based on the `packageManager` field in package.json.
+
+### Build Commands
+- `build` - TypeScript build
+- `type-check` - Type check (no emit)
+
+### Testing Commands
+- `test` - Run tests
+- `test:coverage` - Run tests with coverage
+- `test:coverage:fresh` - Run tests with coverage (fresh cache)
+- `test:safe` - Safe test execution (with auto cleanup)
+- `cleanup:processes` - Cleanup Vitest processes
+
+### Quality Check Requirements
+
+Quality checks are mandatory upon implementation completion:
+
+**Phase 1-3: Code Quality Checks**
+- `check` - Biome (lint + format)
+- `check:unused` - Detect unused exports
+- `check:deps` - Detect circular dependencies
+- `build` - TypeScript build
+
+**Phase 4: Tests**
+- `test` - Test execution
+
+**Phase 5: Code Quality Re-verification**
+- `check:code` - Re-verify code quality (clean up side effects from test fixes in Phase 4)
+
+### Auxiliary Commands
+- `check:all` - Overall integrated check (check:code + test) *for manual batch verification
+- `open coverage/index.html` - Check coverage report
+- `format` - Format fixes
+- `lint:fix` - Lint fixes
+
+### Troubleshooting
+- **Port in use error**: Run the `cleanup:processes` script
+- **Cache issues**: Run the `test:coverage:fresh` script
+- **Dependency errors**: Clean reinstall dependencies
+
+### Coverage Requirements
+- **MANDATORY**: Unit test coverage MUST be 70% or higher
+- **Metrics**: Statements, Branches, Functions, Lines

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

@@ -0,0 +1,149 @@
+# TypeScript Testing Rules
+
+## Test Framework
+
+- **Vitest**: This project uses Vitest
+- Test imports: `import { describe, it, expect, beforeEach, vi } from 'vitest'`
+- Mock creation: Use `vi.mock()`
+
+## Basic Testing Policy
+
+### Quality Requirements
+- **Coverage**: Unit test coverage must be 70% or higher
+- **Independence**: Each test can run independently without depending on other tests
+- **Reproducibility**: Tests are environment-independent and always return the same results
+- **Readability**: Test code maintains the same quality as production code
+
+### Coverage Requirements
+**Mandatory**: Unit test coverage must be 70% or higher
+**Metrics**: Statements, Branches, Functions, Lines
+
+### Test Types and Scope
+1. **Unit Tests**
+   - Verify behavior of individual functions or classes
+   - Mock all external dependencies
+   - Most numerous, implemented with fine granularity
+
+2. **Integration Tests**
+   - Verify coordination between multiple components
+   - Use actual dependencies (DB, API, etc.)
+   - Verify major functional flows
+
+3. **Cross-functional Verification in E2E Tests**
+   - Mandatory verification of impact on existing features when adding new features
+   - Cover integration points with "High" and "Medium" impact levels from Design Doc's "Integration Point Map"
+   - Verification pattern: Existing feature operation → Enable new feature → Verify continuity of existing features
+   - Success criteria: No change in response content, processing time within 5 seconds
+   - Designed for automatic execution in CI/CD pipelines
+
+## Test Implementation Conventions
+
+### Directory Structure
+```
+src/
+└── application/
+    └── services/
+        ├── __tests__/
+        │   ├── service.test.ts      # Unit tests
+        │   └── service.int.test.ts  # Integration tests
+        └── service.ts
+```
+
+### Naming Conventions
+- Test files: `{target-file-name}.test.ts`
+- Integration test files: `{target-file-name}.int.test.ts`
+- Test suites: Names describing target features or situations
+- Test cases: Names describing expected behavior
+
+### Test Code Quality Rules
+
+✅ **Recommended: Keep all tests always active**
+- Merit: Guarantees test suite completeness
+- Practice: Fix problematic tests and activate them
+
+❌ **Avoid: test.skip() or commenting out**
+- Reason: Creates test gaps and incomplete quality checks
+- Solution: Completely delete unnecessary tests
+
+## Test Quality Criteria
+
+### Boundary and Error Case Coverage
+Include boundary values and error cases alongside happy paths.
+```typescript
+it('returns 0 for empty array', () => expect(calc([])).toBe(0))
+it('throws on negative price', () => expect(() => calc([{price: -1}])).toThrow())
+```
+
+### Literal Expected Values
+Use literal values for assertions. Do not replicate implementation logic.
+```typescript
+expect(calcTax(100)).toBe(10)  // not: 100 * TAX_RATE
+```
+
+### Result-Based Verification
+Verify results, not invocation order or count.
+```typescript
+expect(mock).toHaveBeenCalledWith('a')  // not: toHaveBeenNthCalledWith
+```
+
+### Meaningful Assertions
+Each test must include at least one verification.
+```typescript
+it('creates user', async () => {
+  const user = await createUser({name: 'test'})
+  expect(user.id).toBeDefined()
+})
+```
+
+### Appropriate Mock Scope
+Mock only direct external I/O dependencies. Use real implementations for indirect dependencies.
+```typescript
+vi.mock('./database')  // external I/O only
+```
+
+### Property-based Testing (fast-check)
+Use fast-check when verifying invariants or properties.
+```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)
+  }))
+})
+```
+
+**Usage condition**: Use when Property annotations are assigned to ACs in Design Doc.
+
+## Mock Type Safety Enforcement
+
+### Minimal Type Definition Requirements
+```typescript
+// ✅ Only required parts
+type TestRepo = Pick<Repository, 'find' | 'save'>
+const mock: TestRepo = { find: vi.fn(), save: vi.fn() }
+
+// Only when absolutely necessary, with clear justification
+const sdkMock = {
+  call: vi.fn()
+} as unknown as ExternalSDK // Complex external SDK type structure
+```
+
+## Basic Vitest Example
+
+```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-en/typescript.md

@@ -0,0 +1,116 @@
+# TypeScript Development Rules
+
+## Type Safety in Backend Implementation
+
+**Type Safety in Data Flow**
+Input Layer (`unknown`) → Type Guard → Business Layer (Type Guaranteed) → Output Layer (Serialization)
+
+**Backend-Specific Type Scenarios**:
+- **API Communication**: Always receive responses as `unknown`, validate with type guards
+- **Form Input**: External input as `unknown`, type determined after validation
+- **Legacy Integration**: Stepwise assertion like `window as unknown as LegacyWindow`
+- **Test Code**: Always define types for mocks, utilize `Partial<T>` and `vi.fn<[Args], Return>()`
+
+## Coding Conventions
+
+**Class Usage Criteria**
+- **Recommended: Implementation with Functions and Interfaces**
+  - Rationale: Improves testability and flexibility of function composition
+- **Classes Allowed**:
+  - Framework requirements (NestJS Controller/Service, TypeORM Entity, etc.)
+  - Custom error class definitions
+  - When state and business logic are tightly coupled (e.g., ShoppingCart, Session, StateMachine)
+- **Decision Criterion**: If "Does this data have behavior?" is Yes, consider using a class
+  ```typescript
+  // ✅ Functions and interfaces
+  interface UserService { create(data: UserData): User }
+  const userService: UserService = { create: (data) => {...} }
+  ```
+
+**Function Design**
+- **0-2 parameters maximum**: Use object for 3+ parameters
+  ```typescript
+  // ✅ Object parameter
+  function createUser({ name, email, role }: CreateUserParams) {}
+  ```
+
+**Dependency Injection**
+- **Inject external dependencies as parameters**: Ensure testability and modularity
+  ```typescript
+  // ✅ Receive dependency as parameter
+  function createService(repository: Repository) { return {...} }
+  ```
+
+**Asynchronous Processing**
+- Promise Handling: Always use `async/await`
+- Error Handling: Always handle with `try-catch`
+- Type Definition: Explicitly define return value types (e.g., `Promise<Result>`)
+
+**Format Rules**
+- Semicolon omission (follow Biome settings)
+- Types in `PascalCase`, variables/functions in `camelCase`
+- Imports use absolute paths (`src/`)
+
+**Clean Code Principles**
+- ✅ Delete unused code immediately
+- ✅ Delete debug `console.log()`
+- ❌ Commented-out code (manage history with version control)
+- ✅ Comments explain "why" (not "what")
+
+## Error Handling
+
+**Absolute Rule**: Error suppression prohibited. All errors must have log output and appropriate handling.
+
+**Fail-Fast Principle**: Fail quickly on errors to prevent continued processing in invalid states
+```typescript
+// ❌ Prohibited: Unconditional fallback
+catch (error) {
+  return defaultValue // Hides error
+}
+
+// ✅ Required: Explicit failure
+catch (error) {
+  logger.error('Processing failed', error)
+  throw error // Handle appropriately at higher layer
+}
+```
+
+**Result Type Pattern**: Express errors with types for explicit handling
+```typescript
+type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }
+
+// Example: Express error possibility with types
+function parseUser(data: unknown): Result<User, ValidationError> {
+  if (!isValid(data)) return { ok: false, error: new ValidationError() }
+  return { ok: true, value: data as User }
+}
+```
+
+**Custom Error Classes**
+```typescript
+export class AppError extends Error {
+  constructor(message: string, public readonly code: string, public readonly statusCode = 500) {
+    super(message)
+    this.name = this.constructor.name
+  }
+}
+// Purpose-specific: ValidationError(400), BusinessRuleError(400), DatabaseError(500), ExternalServiceError(502)
+```
+
+**Layer-Specific Error Handling (Backend)**
+- API Layer: Convert to HTTP response, log output excluding sensitive information
+- Service Layer: Detect business rule violations, propagate AppError as-is
+- Repository Layer: Convert technical errors to domain errors
+
+**Structured Logging and Sensitive Information Protection**
+Never include sensitive information (password, token, apiKey, secret, creditCard) in logs
+
+**Asynchronous Error Handling**
+- Global handler setup mandatory: `unhandledRejection`, `uncaughtException`
+- Use try-catch with all async/await
+- Always log and re-throw errors
+
+## Performance Optimization
+
+- Streaming Processing: Process large datasets with streams
+- Memory Leak Prevention: Explicitly release unnecessary objects

package/docs/rules-ja/architecture/implementation-approach.md

@@ -0,0 +1,136 @@
+# 実装戦略選択フレームワーク（メタ認知的アプローチ）
+
+## メタ認知的戦略選択プロセス
+
+### Phase 1: 現状の包括的分析
+
+**核心質問**: 「既存の実装はどうなっているのか？」
+
+#### 分析フレームワーク
+```yaml
+アーキテクチャ分析: 責務分離、データフロー、依存関係、技術的負債
+実装品質評価: コード品質、テストカバレッジ、パフォーマンス、セキュリティ
+歴史的文脈理解: 現在の形の理由、過去判断の妥当性、制約の変化、要求の進化
+```
+
+#### メタ認知質問リスト
+- この実装の真の責務は何か？
+- どの部分がビジネス本質で、どの部分が技術的制約由来か？
+- コードから明確でない依存関係や暗黙の前提条件は何か？
+- 現在の設計がもたらしている利点と制約は？
+
+### Phase 2: 戦略探索と創造
+
+**核心質問**: 「before → after を判断する時に、参考にすべき実装パターンや戦略は何なのか？」
+
+#### 戦略発見プロセス
+```yaml
+調査・探索: 技術スタック事例（WebSearch活用）、同種プロジェクト、OSS実装、文献・ブログ
+創造的思考: 戦略組み合わせ、制約前提設計、フェーズ分け、拡張ポイント設計
+```
+
+#### 参考戦略パターン（創造的組み合わせを推奨）
+
+**レガシー対応戦略**:
+- ストラングラーパターン: 段階的置換による漸進的移行
+- ファサードパターン: 統一インターフェースによる複雑性の隠蔽
+- アダプターパターン: 既存システムとの橋渡し
+
+**新規開発戦略**:
+- 機能駆動開発: ユーザー価値重視の縦断実装
+- 基盤駆動開発: 安定性重視の基盤優先構築
+- リスク駆動開発: 最大リスク要素から優先的に対処
+
+**統合・移行戦略**:
+- プロキシパターン: 透過的な機能拡張
+- デコレーターパターン: 既存機能の段階的強化
+- ブリッジパターン: 抽象化による柔軟性確保
+
+**重要**: 最適解は各プロジェクトの文脈に応じた創造的思考により発見される。
+
+### Phase 3: リスク評価とコントロール
+
+**核心質問**: 「既存の実装にそれを当てはめた時にどういうリスクが発生し、それをどうコントロールするのが最良なのか？」
+
+#### リスク分析マトリクス
+```yaml
+技術的リスク: 既存システム影響、データ整合性、パフォーマンス劣化、統合複雑性
+運用リスク: サービス可用性、デプロイダウンタイム、運用プロセス変更、切り戻し手順
+プロジェクトリスク: スケジュール遅延、技術習得コスト、品質達成度、チーム連携
+```
+
+#### リスクコントロール戦略
+```yaml
+予防的対策: 段階的移行、並行動作検証、統合・回帰テスト追加、監視設定
+発生時対応: 切り戻し手順、ログ・メトリクス準備、連絡体制定義、サービス継続手順
+```
+
+### Phase 4: 制約適合性検証
+
+**核心質問**: 「このプロジェクトの制約は何か？」
+
+#### 制約チェックリスト
+```yaml
+技術的制約: ライブラリ互換性、リソース容量、義務要件、数値目標
+時間的制約: 期限・優先度、依存関係、マイルストーン、学習期間
+リソース制約: チーム・スキル、作業時間・体制、予算、外部契約
+ビジネス制約: 市場投入時期、顧客影響、法規制・標準
+```
+
+### Phase 5: 実装アプローチ決定
+
+基本的な実装アプローチから最適解を選択（創造的組み合わせも推奨）：
+
+#### 垂直スライス（機能駆動）
+**特徴**: 機能単位で全層を縦断実装
+**適用条件**: 機能間の依存が少ない、ユーザーが利用可能な形で出力、アーキテクチャ全層への変更が必要
+**確認方法**: 各機能完成時のエンドユーザー価値提供
+
+#### 水平スライス（基盤駆動）  
+**特徴**: アーキテクチャ層別の段階的構築
+**適用条件**: 基盤システムの安定性が重要、複数機能が共通基盤に依存、層別の段階的確認が有効
+**確認方法**: 全基盤層完成時の統合動作確認
+
+#### ハイブリッド（創造的組み合わせ）
+**特徴**: プロジェクト特性に応じた柔軟な組み合わせ
+**適用条件**: 要件が明確でない、フェーズごとにアプローチ変更が必要、プロトタイピングから本格実装への移行
+**確認方法**: 各フェーズの目標に応じてL1/L2/L3の適切なレベルで確認
+
+### Phase 6: 判断根拠の文書化
+
+**Design Docでの記載**：実装戦略の選択理由と根拠を明記する。
+
+## 確認レベル定義
+
+各タスクの完了確認における優先順位：
+
+- **L1: 機能動作確認** - エンドユーザー機能として動作（例：検索実行可能）
+- **L2: テスト動作確認** - 新規テストが追加されパス（例：型定義テスト）  
+- **L3: ビルド成功確認** - コンパイルエラーなし（例：インターフェース定義）
+
+**優先順位**: L1 > L2 > L3 の順で確認可能性を重視
+
+## 統合ポイントの定義
+
+選択した戦略に応じて統合ポイントを定義：
+- **ストラングラー系**: 各機能の新旧システム切り替え時
+- **機能駆動**: ユーザーが実際に機能を利用可能になった時
+- **基盤駆動**: 全アーキテクチャ層が揃いE2Eテストが通った時
+- **ハイブリッド**: 各フェーズで定義した個別目標達成時
+
+## アンチパターン
+
+- **パターン固執**: リスト内の戦略のみで選択し、独自の組み合わせを検討しない
+- **分析不足**: Phase 1の分析フレームワークを飛ばして戦略選択  
+- **リスク軽視**: Phase 3のリスク分析マトリクスを省略して実装着手
+- **制約無視**: Phase 4の制約チェックリストを確認せず戦略決定
+- **根拠省略**: Phase 6の文書化テンプレートを使用せず戦略選択
+
+## メタ認知的実行のための指針
+
+1. **既知パターンの活用**: 出発点として参考し、創造的組み合わせを探索
+2. **WebSearch積極活用**: 同種技術スタックの実装事例を調査  
+3. **5 Whys適用**: 根本理由を追求し本質を把握
+4. **複数観点評価**: Phase 1-4の各観点から網羅的に評価
+5. **創造的思考**: 複数戦略の順序適用やプロジェクト固有の制約を活かした設計を検討
+6. **判断根拠明示**: 設計ドキュメントでの戦略選択根拠を明示化