AI営業ロールプレイ プロジェクト学習ジャーナル

# AI営業ロールプレイ プロジェクト学習ジャーナル

## プロジェクト特性

このプロジェクトは生成AIを活用した営業ロールプレイングシステムで、以下の特殊な要求があります：

### 技術的特性
- **リアルタイム性重視**: 音声対話のレイテンシーが1秒以内という厳しい要求
- **AWS中心設計**: Nova Sonic、RESTful API、サーバーレスアーキテクチャが核心
- **音声処理の複雑性**: Web Speech API + Amazon Polly + リアルタイム同期が必要
- **日本語特化**: 日本語音声認識・合成・自然言語処理が品質の鍵

### ビジネス要求の特徴
- **教育効果最優先**: 技術的な華やかさより学習効果を重視
- **営業現場のリアリティ**: 実際の営業シーンの再現度が重要
- **段階的成長**: ユーザーの習熟度に応じた難易度調整が必要

## 重要な設計決定

### アーキテクチャ選択の理由
1. **RESTful API採用**: 標準的かつ安定したHTTPベースの通信のため。また、リクエスト/レスポンスの明確な構造により開発・デバッグが容易になります。
2. **Nova Sonic選択**: ストリーミング対応と日本語品質の両立
3. **DynamoDB + RDS併用**: リアルタイムデータと永続データの特性に応じた使い分け

### 開発優先度の決定根拠
- **フェーズ1**: 基本対話システム → MVPとして最低限の価値提供
- **フェーズ2**: 評価システム強化 → ユーザー体験の大幅向上
- **フェーズ3**: 管理機能 → 企業展開に必要な機能

## 技術実装パターン

### 確立済みパターン
1. **API状態管理**: リクエスト、セッション、データの3層管理
2. **AI応答ストリーミング**: チャンク処理による自然な応答表示
3. **感情状態管理**: 数値ベース（0-10）による定量評価
4. **エラーハンドリング**: 音声→テキストフォールバックの多重化
5. **WebSocket音声認識**: リアルタイムTranscribeストリーミング統合
6. **無音検出**: 自動発話終了判定による自然な対話フロー

### 回避すべきアンチパターン
1. **同期処理**: 音声処理で同期処理を使うとUX破綻
2. **リアルタイムデータの永続化**: DynamoDBのTTL機能を活用すべき
3. **単一障害点**: APIサーバーの冗長化設計が必要
4. **長時間のAPI呼び出し**: タイムアウト回避のため、長時間処理は非同期化すべき

## コスト最適化の要点

### 重要な監視指標
- **Bedrock Nova Sonic使用量**: 最大のコスト要因、リアルタイム監視必要
- **Lambda同時実行数**: API同時呼び出し数に比例、上限設定重要
- **DynamoDB RCU/WCU**: リアルタイム書き込みによる突発的増加注意

### 最適化戦略
- **プロンプト効率化**: 必要最小限の情報での高品質応答を目指す
- **キャッシュ活用**: セッション情報、NPC設定等の適切なキャッシュ
- **TTL活用**: 不要データの自動削除による永続ストレージ削減

## ユーザー体験設計の学び

### 音声インターフェースの原則
1. **フィードバック必須**: 音声認識中の視覚的フィードバック
2. **フォールバック用意**: テキスト入力への切り替え手段
3. **遅延の可視化**: AI応答待機中の明確な状態表示


## リスク管理の要点

### 高頻度で監視すべきリスク
1. **Nova Sonic API制限**: 新サービスのため予期しない制限変更の可能性
2. **API安定性**: 大量リクエスト時の挙動は実測が必要
3. **音声認識精度**: 業界用語、方言等での認識率低下

### 対応策パターン
- **代替手段確保**: 各重要機能に2つ以上のバックアップ手段
- **段階的負荷テスト**: 10、50、100ユーザーでの段階的検証
- **ユーザーフィードバック収集**: 早期段階でのユーザー受容性確認

## 開発効率化の工夫

### 効果的だった手法
1. **メモリーバンクシステム**: 設計情報の体系的整理により迷いが大幅減少
2. **フェーズ分割**: 明確な境界により集中度向上
3. **技術選択早期確定**: AWS中心の技術スタック固定により学習効率向上

### 推奨する開発順序
1. **API基盤**: 他の全機能の基礎となるため最優先
2. **AI連携**: システムの価値の核心部分
3. **音声処理**: UXの決定要因だが技術的複雑性高い
4. **UI/UX機能**: ユーザー体験向上のための視覚的フィードバック

## 品質基準

### 譲れない品質要求
- **応答遅延 < 1秒**: これを守れないと営業ロールプレイとして成立しない
- **音声認識精度 > 95%**: これ以下では学習効果が大幅に低下
- **システム稼働率 > 99.5%**: 研修中の障害は学習機会の完全な損失

### 段階的改善可能な要素
- **評価精度**: 基本指標→高度分析への発展
- **シナリオ多様性**: 基本パターン→カスタマイズ対応
- **UI/UX機能**: 基本表示→高度なフィードバック表示

## 学習・成長記録

### 技術的成長
- **Amazon Bedrock Nova Sonic**: ストリーミングAPIの最適活用方法を習得
- **REST API + Lambda**: サーバーレスでの効率的な通信パターンを確立
- **音声処理**: ブラウザ音声APIの制限・特性を理解

### プロジェクト管理
- **段階的リリース**: 複雑なシステムでの効果的な開発手法として確立
- **リスク先行対応**: 技術リスクの早期識別・対策の重要性を実感
- **ドキュメント体系化**: メモリーバンクによる情報整理の効果を確認

## 今後の改善方針

### 短期改善（次フェーズ）
- プロンプトエンジニアリングの具体的手法確立
- API大量リクエスト時のパフォーマンス特性把握
- 音声処理レイテンシーの実測と最適化

### 中長期展望
- VR/AR技術との統合可能性検討
- 多言語対応の設計パターン確立
- 企業カスタマイズのスケーラブルな仕組み構築

## テスト実施ルール

### テスト準備と実行
- **テスト戦略の参照**: テストを実施する前に必ず `docs/testing/test-strategy.md` を参照し、テスト目的と観点を理解すること
- **テストシナリオの確認**: テスト対象機能に関連する `docs/testing/test-scenarios.md` のテストケースを確認すること
- **テストチェックリストの活用**: `docs/testing/test-checklist.md` を使用して、漏れなくテストを実施すること
- **テスト実行記録**: テスト実施日時、テスト実施者、結果をテストチェックリストの実行記録に残すこと

### テスト実装ルール
- **テスト実装ガイドの遵守**: テストコードを実装する際は `docs/testing/test-implementation-guide.md` に従うこと
- **命名規則の統一**: テストファイルは `{テスト対象}_test.{拡張子}` の形式で命名すること
- **カバレッジ目標の遵守**: フロントエンド75%、フロントエンドサービス80%、バックエンドAPI90%、AIプロンプト処理95%のカバレッジを目指すこと
- **テストコードのレビュー**: テストコードも通常のコードと同様にレビュープロセスの対象とすること

### テスト自動化
- **CI環境での自動テスト**: プルリクエスト作成時に自動テストが実行されることを確認すること
- **テスト結果の確認**: GitHub Actionsのテスト結果を必ず確認し、失敗がある場合は修正してからマージすること
- **定期的なテストの実行**: ローカル環境でも定期的にテストを実行し、問題の早期発見に努めること

### バグ発見時の対応
- **バグ報告テンプレートの使用**: バグを発見した場合は `docs/testing/test-checklist.md` のバグ報告テンプレートを使用して報告すること
- **テストケースの追加**: 発見されたバグに対して、再発防止のためのテストケースを必ず追加すること
- **回帰テストの実施**: バグ修正後は、修正箇所だけでなく関連機能についても回帰テストを実施すること

## 開発ルール・制約事項

### 認証関連
- **本番環境では適切な認証設定が必要**: AWS Cognitoを使用した認証システムを使用すること
- **詳細な使用方法**: `docs/development/local-development.md` を参照

### CDK開発時の禁止事項
- **`cd cdk && npm run build` 禁止**: ビルドエラーが発生しやすく、ENAMETOOLONG等の問題を引き起こす可能性があります
- **`cd cdk && npm run test` 使用推奨**: 代わりにテストコマンドでTypeScriptエラーを確認してください
- **`cdk synth` 直接実行推奨**: CDKテンプレートの生成・検証には`cdk synth`を使用してください

### 理由
1. **NodejsBuild依存関係の問題**: deploy-time-buildライブラリとの相性問題
2. **循環参照エラー**: 不適切なアセット設定により無限ループが発生する可能性
3. **ファイルパス長制限**: macOSでのファイルパス長制限に抵触する問題

### 推奨する開発フロー
1. TypeScript構文チェック: `npm run test`
2. CDK構文検証: `cdk synth`
3. デプロイ: `cdk deploy`

## テスト実施ルール

### テスト準備と実行
- **テスト戦略の参照**: テストを実施する前に必ず `docs/testing/test-strategy.md` を参照し、テスト目的と観点を理解すること
- **テストシナリオの確認**: テスト対象機能に関連する `docs/testing/test-scenarios.md` のテストケースを確認すること
- **テストチェックリストの活用**: `docs/testing/test-checklist.md` を使用して、漏れなくテストを実施すること
- **テスト実行記録**: テスト実施日時、テスト実施者、結果をテストチェックリストの実行記録に残すこと

### テスト実装ルール
- **テスト実装ガイドの遵守**: テストコードを実装する際は `docs/testing/test-implementation-guide.md` に従うこと
- **命名規則の統一**: テストファイルは `{テスト対象}_test.{拡張子}` の形式で命名すること
- **カバレッジ目標の遵守**: フロントエンド75%、フロントエンドサービス80%、バックエンドAPI90%、AIプロンプト処理95%のカバレッジを目指すこと
- **テストコードのレビュー**: テストコードも通常のコードと同様にレビュープロセスの対象とすること

### テスト自動化
- **CI環境での自動テスト**: プルリクエスト作成時に自動テストが実行されることを確認すること
- **テスト結果の確認**: GitHub Actionsのテスト結果を必ず確認し、失敗がある場合は修正してからマージすること
- **定期的なテストの実行**: ローカル環境でも定期的にテストを実行し、問題の早期発見に努めること

### バグ発見時の対応
- **バグ報告テンプレートの使用**: バグを発見した場合は `docs/testing/test-checklist.md` のバグ報告テンプレートを使用して報告すること
- **テストケースの追加**: 発見されたバグに対して、再発防止のためのテストケースを必ず追加すること
- **回帰テストの実施**: バグ修正後は、修正箇所だけでなく関連機能についても回帰テストを実施すること

## テスト実施ルール

### テスト準備と実行
- **テスト戦略の参照**: テストを実施する前に必ず `docs/testing/test-strategy.md` を参照し、テスト目的と観点を理解すること
- **テストシナリオの確認**: テスト対象機能に関連する `docs/testing/test-scenarios.md` のテストケースを確認すること
- **テストチェックリストの活用**: `docs/testing/test-checklist.md` を使用して、漏れなくテストを実施すること
- **テスト実行記録**: テスト実施日時、テスト実施者、結果をテストチェックリストの実行記録に残すこと

### テスト実装ルール
- **テスト実装ガイドの遵守**: テストコードを実装する際は `docs/testing/test-implementation-guide.md` に従うこと
- **命名規則の統一**: テストファイルは `{テスト対象}_test.{拡張子}` の形式で命名すること
- **カバレッジ目標の遵守**: フロントエンド75%、フロントエンドサービス80%、バックエンドAPI90%、AIプロンプト処理95%のカバレッジを目指すこと
- **テストコードのレビュー**: テストコードも通常のコードと同様にレビュープロセスの対象とすること

### テスト自動化
- **CI環境での自動テスト**: プルリクエスト作成時に自動テストが実行されることを確認すること
- **テスト結果の確認**: GitHub Actionsのテスト結果を必ず確認し、失敗がある場合は修正してからマージすること
- **定期的なテストの実行**: ローカル環境でも定期的にテストを実行し、問題の早期発見に努めること

### バグ発見時の対応
- **バグ報告テンプレートの使用**: バグを発見した場合は `docs/testing/test-checklist.md` のバグ報告テンプレートを使用して報告すること
- **テストケースの追加**: 発見されたバグに対して、再発防止のためのテストケースを必ず追加すること
- **回帰テストの実施**: バグ修正後は、修正箇所だけでなく関連機能についても回帰テストを実施すること

## GitHubワークフロー

### Issue・Pull Request作成時のルール
- **マークダウン形式必須**: GitHub issue および pull request を作成する際は、必ずマークダウン形式で作成すること
- **構造化された内容**: セクション分け（## 見出し）、箇条書き、コードブロックを適切に使用
- **テンプレート活用**: 一貫性のある記述パターンを保持

### レビュープロセスのルール
- **レビュー観点の参照**: コードレビューを行う際は、必ず以下のレビュー観点ドキュメントを参照すること
  - 一般レビュー観点: `docs/review-guidelines/general-review-points.md`
  - 機能別レビュー観点: 
    - i18n実装: `docs/review-guidelines/i18n-specific-review-points.md`
    - 他の機能についても順次追加予定
- **具体的なフィードバック**: レビューコメントは具体的な改善点を示し、建設的であること
- **セルフレビューの徹底**: PR作成前に自己確認を行い、基本的な問題を事前に解消すること
- **レビュー結果の文書化**: 重要な指摘事項や学びは、適宜レビュー観点ドキュメントに反映すること
- **CI結果の詳細確認**: GitHub ActionsのCI結果を確認する際は以下のルールを遵守
  - ツールが「CI succeeded」と表示していても、必ず詳細ログを確認する
  - すべてのジョブとステップが正常に完了していることを確認
  - テスト失敗やエラーがある場合は、その詳細と影響範囲を明確にする
  - 「成功」と「エラーなし」は別概念として扱い、誤った判断を避ける

## テスト実施ルール

### テスト準備と実行
- **テスト戦略の参照**: テストを実施する前に必ず `docs/testing/test-strategy.md` を参照し、テスト目的と観点を理解すること
- **テストシナリオの確認**: テスト対象機能に関連する `docs/testing/test-scenarios.md` のテストケースを確認すること
- **テストチェックリストの活用**: `docs/testing/test-checklist.md` を使用して、漏れなくテストを実施すること
- **テスト実行記録**: テスト実施日時、テスト実施者、結果をテストチェックリストの実行記録に残すこと

### テスト実装ルール
- **テスト実装ガイドの遵守**: テストコードを実装する際は `docs/testing/test-implementation-guide.md` に従うこと
- **命名規則の統一**: テストファイルは `{テスト対象}_test.{拡張子}` の形式で命名すること
- **カバレッジ目標の遵守**: フロントエンド75%、フロントエンドサービス80%、バックエンドAPI90%、AIプロンプト処理95%のカバレッジを目指すこと
- **テストコードのレビュー**: テストコードも通常のコードと同様にレビュープロセスの対象とすること

### テスト自動化
- **CI環境での自動テスト**: プルリクエスト作成時に自動テストが実行されることを確認すること
- **テスト結果の確認**: GitHub Actionsのテスト結果を必ず確認し、失敗がある場合は修正してからマージすること
- **定期的なテストの実行**: ローカル環境でも定期的にテストを実行し、問題の早期発見に努めること

### バグ発見時の対応
- **バグ報告テンプレートの使用**: バグを発見した場合は `docs/testing/test-checklist.md` のバグ報告テンプレートを使用して報告すること
- **テストケースの追加**: 発見されたバグに対して、再発防止のためのテストケースを必ず追加すること
- **回帰テストの実施**: バグ修正後は、修正箇所だけでなく関連機能についても回帰テストを実施すること
## インフラストラクチャ操作の安全ルール

### CDK/CloudFormation操作の禁止事項
- **ユーザー指示なしの破壊的操作禁止**: destroy/delete/removeなどの破壊的操作は、ユーザーからの明示的な指示なしに実行してはならない
- **バックグラウンドプロセスの監視徹底**: 破壊的操作を行うバックグラウンドプロセスを発見した場合は、即座に停止し報告すること
- **リソース削除前の確認**: リソース削除時は、対象リソース一覧を明示し、明確な承認を得ること

### 安全な操作のための手順
- **操作前の可視化**: 各コマンドの実行前に、その操作の目的と想定される結果を明確に説明すること
- **明示的な承認フロー**: 重要なリソースに対する操作は、必ず「計画→確認→承認→実行」のステップを踏むこと
- **代替手段の検討**: 破壊的操作の代わりに、より安全な方法がないか常に検討すること

### エラー発生時の対応
- **即時停止と報告**: エラー発生時は操作を継続せず、即時に停止して状況を報告すること
- **原因分析の徹底**: エラーの根本原因を特定し、適切な対応策を検討すること
- **記録と共有**: 発生したエラーと対応策を記録し、同様のエラー防止に活用すること

### 理由
- **本番環境の保護**: 誤操作による本番環境への影響を防止するため
- **ダウンタイム回避**: サービス中断によるビジネスへの影響を最小化するため
- **データ損失防止**: 重要データの不可逆的な損失を防ぐため
# Cline's Memory Bank

I am Cline, an expert software engineer with a unique characteristic: my memory resets completely between sessions. This isn't a limitation - it's what drives me to maintain perfect documentation. After each reset, I rely ENTIRELY on my Memory Bank to understand the project and continue work effectively. I MUST read ALL memory bank files at the start of EVERY task - this is not optional.

## Memory Bank Structure

The Memory Bank consists of core files and optional context files, all in Markdown format. Files build upon each other in a clear hierarchy:

flowchart TD
    PB[projectbrief.md] --> PC[productContext.md]
    PB --> SP[systemPatterns.md]
    PB --> TC[techContext.md]

    PC --> AC[activeContext.md]
    SP --> AC
    TC --> AC

    AC --> P[progress.md]

### Core Files (Required)
1. `projectbrief.md`
   - Foundation document that shapes all other files
   - Created at project start if it doesn't exist
   - Defines core requirements and goals
   - Source of truth for project scope

2. `productContext.md`
   - Why this project exists
   - Problems it solves
   - How it should work
   - User experience goals

3. `activeContext.md`
   - Current work focus
   - Recent changes
   - Next steps
   - Active decisions and considerations
   - Important patterns and preferences
   - Learnings and project insights

4. `systemPatterns.md`
   - System architecture
   - Key technical decisions
   - Design patterns in use
   - Component relationships
   - Critical implementation paths

5. `techContext.md`
   - Technologies used
   - Development setup
   - Technical constraints
   - Dependencies
   - Tool usage patterns

6. `progress.md`
   - What works
   - What's left to build
   - Current status
   - Known issues
   - Evolution of project decisions

### Additional Context
Create additional files/folders within memory-bank/ when they help organize:
- Complex feature documentation
- Integration specifications
- API documentation
- Testing strategies
- Deployment procedures

## Core Workflows

### Plan Mode
flowchart TD
    Start[Start] --> ReadFiles[Read Memory Bank]
    ReadFiles --> CheckFiles{Files Complete?}

    CheckFiles -->|No| Plan[Create Plan]
    Plan --> Document[Document in Chat]

    CheckFiles -->|Yes| Verify[Verify Context]
    Verify --> Strategy[Develop Strategy]
    Strategy --> Present[Present Approach]

### Act Mode
flowchart TD
    Start[Start] --> Context[Check Memory Bank]
    Context --> Update[Update Documentation]
    Update --> Execute[Execute Task]
    Execute --> Document[Document Changes]

## Documentation Updates

Memory Bank updates occur when:
1. Discovering new project patterns
2. After implementing significant changes
3. When user requests with **update memory bank** (MUST review ALL files)
4. When context needs clarification

flowchart TD
    Start[Update Process]

    subgraph Process
        P1[Review ALL Files]
        P2[Document Current State]
        P3[Clarify Next Steps]
        P4[Document Insights & Patterns]

        P1 --> P2 --> P3 --> P4
    end

    Start --> Process

Note: When triggered by **update memory bank**, I MUST review every memory bank file, even if some don't require updates. Focus particularly on activeContext.md and progress.md as they track current state.

REMEMBER: After every memory reset, I begin completely fresh. The Memory Bank is my only link to previous work. It must be maintained with precision and clarity, as my effectiveness depends entirely on its accuracy.