infer-intent

civicship-api 設計意図推論

Git履歴・コミットメッセージから設計の意図や歴史的文脈を推論します。なぜこのコードがこう書かれているのか、過去の変更理由を理解することで、安全な変更を支援します。

使用方法

# 特定ファイルの設計意図を推論
/infer-intent src/application/domain/account/wallet/service.ts

# ドメイン全体の歴史を分析
/infer-intent wallet

# 特定の実装パターンの理由を調査
/infer-intent "なぜWalletServiceはトランザクションを必須にしているのか"

引数:

• $ARGUMENTS: ファイルパス、ドメイン名、または質問

---

意図推論プロセス

ステップ1: Git履歴の取得

対象ファイル・ドメインのコミット履歴を取得:

# ファイルの全履歴
git log --follow --oneline src/application/domain/account/wallet/service.ts

# 詳細な変更履歴
git log -p --follow src/application/domain/account/wallet/service.ts

# 特定期間のコミット
git log --since="1 year ago" --oneline -- src/application/domain/account/wallet

# コミット統計
git log --stat --oneline -- src/application/domain/account/wallet

履歴レポート:

## Git履歴の概要

### 変更統計

| 項目 | 値 |
|------|-----|
| 総コミット数 | 45件 |
| 最初のコミット | 2023-06-20 |
| 最新のコミット | 2026-01-10 |
| 期間 | 2年7ヶ月 |
| 主要コントリビューター | 3名 |

---

### コミット頻度

| 期間 | コミット数 |
|------|-----------|
| 2023年 | 12件 |
| 2024年 | 20件 |
| 2025年 | 10件 |
| 2026年 | 3件 |

**トレンド:** 2024年にピーク（機能追加が活発）

---

### 主要なコミット

#### 1. 初期実装（2023-06-20）

commit a1b2c3d feat: Add wallet domain with basic CRUD operations

**変更内容:**
- WalletService, WalletRepository の初期実装
- 基本的なCRUD操作のみ

---

#### 2. トランザクション対応（2023-08-15）

commit e4f5g6h fix: Add transaction support to wallet operations

**変更内容:**
- すべてのメソッドに `tx` パラメータ追加
- トランザクション内での操作を保証

**理由（コミットメッセージから推論）:**
- ポイント送受信で不整合が発生したバグ修正
- トランザクションなしでは残高計算にレースコンディション

---

#### 3. バリデーション強化（2024-02-10）

commit i7j8k9l feat: Add strict validation for negative balance

**変更内容:**
- 残高がマイナスにならないチェック追加

**理由:**
- 本番環境でマイナス残高が発生
- ビジネスルール違反を防ぐため

---

#### 4. パフォーマンス最適化（2024-06-20）

commit m1n2o3p perf: Optimize wallet balance calculation with cache

**変更内容:**
- 残高計算にキャッシュ導入
- クエリ回数を削減

**理由:**
- ユーザー増加によりレスポンスタイム劣化
- 100ms → 30ms に改善

---

#### 5. セキュリティ修正（2025-03-15）

commit q4r5s6t security: Add RLS to all wallet queries

**変更内容:**
- すべてのクエリに `ctx.issuer` を適用

**理由:**
- 他ユーザーのウォレット情報が見えるバグ
- セキュリティ監査で指摘

---

ステップ2: コミットメッセージの分析

コミットメッセージから設計判断を推論:

## コミットメッセージ分析

### カテゴリ別の分類

| カテゴリ | 件数 | 割合 |
|---------|------|------|
| feat (機能追加) | 18件 | 40% |
| fix (バグ修正) | 12件 | 27% |
| perf (パフォーマンス) | 5件 | 11% |
| security (セキュリティ) | 3件 | 7% |
| refactor (リファクタリング) | 4件 | 9% |
| test (テスト) | 3件 | 7% |

**傾向:** 機能追加が多いが、バグ修正も頻繁

---

### 頻出キーワード分析

| キーワード | 出現回数 | 文脈 |
|-----------|---------|------|
| transaction | 8回 | トランザクション対応 |
| validation | 6回 | バリデーション強化 |
| balance | 10回 | 残高計算ロジック |
| security | 5回 | セキュリティ修正 |
| performance | 4回 | パフォーマンス改善 |

**解釈:**
- トランザクションが重要な関心事
- 残高計算は複雑で頻繁に修正
- セキュリティ問題が過去に複数回発生

---

### 重要な設計決定

#### 決定1: トランザクション必須化

**コミット:** e4f5g6h (2023-08-15)

**メッセージ:**

fix: Add transaction support to wallet operations

ポイント送受信でレースコンディションが発生し、 残高の不整合が発生した。 今後すべてのウォレット操作はトランザクション内で 実行することを必須とする。

**推論される意図:**
- データ整合性が最優先
- 並行アクセスでのレースコンディションを防ぐ
- パフォーマンスよりも正確性を重視

---

#### 決定2: マイナス残高の禁止

**コミット:** i7j8k9l (2024-02-10)

**メッセージ:**

feat: Add strict validation for negative balance

本番環境でマイナス残高が発生したため、 厳密なバリデーションを追加。 ポイント使用時に残高不足の場合はエラーを返す。

**推論される意図:**
- ビジネスルール: ポイントは借金できない
- 既存のバリデーションが不十分だった
- 信頼性向上のための防御的プログラミング

---

#### 決定3: キャッシュ導入

**コミット:** m1n2o3p (2024-06-20)

**メッセージ:**

perf: Optimize wallet balance calculation with cache

ユーザー増加によりウォレットクエリが ボトルネックになっていた。 残高計算に10秒のキャッシュを導入し、 レスポンスタイムを100ms→30msに改善。

**推論される意図:**
- スケーラビリティへの対応
- リアルタイム性よりパフォーマンスを優先（10秒は許容）
- 将来的なユーザー増加を見越した設計

---

#### 決定4: RLS（Row-Level Security）の徹底

**コミット:** q4r5s6t (2025-03-15)

**メッセージ:**

security: Add RLS to all wallet queries

セキュリティ監査で、一部のクエリでRLSが 適用されていないことが判明。 全てのクエリで ctx.issuer を使用するよう修正。

**推論される意図:**
- セキュリティが最重要課題
- 一度でも情報漏洩があった（またはリスクがあった）
- 再発防止のための徹底的な対策

---

ステップ3: コード変更パターンの分析

コード変更の傾向から設計思想を推論:

# ファイルパスを引数から取得
FILE_PATH="${ARGUMENTS}"

# 追加された行数と削除された行数
git log --stat --oneline -- "${FILE_PATH}" | \
  grep "$(basename "${FILE_PATH}")" | awk '{sum+=$4} END {print sum}'

# 特定関数の変更履歴（例: createWallet関数）
git log -L :createWallet:"${FILE_PATH}"

変更パターンレポート:

## コード変更パターン

### メソッド別の変更頻度

| メソッド | 変更回数 | 最終変更日 |
|---------|---------|-----------|
| createWallet | 8回 | 2025-01-10 |
| findByUserId | 12回 | 2024-11-20 |
| transferPoints | 15回 | 2025-12-05 |
| calculateBalance | 10回 | 2024-06-20 |

**解釈:**
- `transferPoints` が最も変更が多い（複雑なロジック）
- `findByUserId` も頻繁に変更（セキュリティ、パフォーマンス改善）

---

### createWallet メソッドの進化

#### Version 1（2023-06-20）
```typescript
async createWallet(userId: string) {
  return this.repo.create({ userId, balance: 0 });
}

特徴: シンプル、トランザクションなし

---

Version 2（2023-08-15）

async createWallet(userId: string, tx: Prisma.TransactionClient) {
  return this.repo.create({ userId, balance: 0 }, tx);
}

変更: トランザクション対応

---

Version 3（2024-02-10）

async createWallet(ctx: IContext, userId: string, tx: Prisma.TransactionClient) {
  // バリデーション追加
  const existing = await this.repo.findByUserId(ctx, userId, tx);
  if (existing) {
    throw new Error("WALLET_ALREADY_EXISTS");
  }
  return this.repo.create({ userId, balance: 0 }, tx);
}

変更: 重複チェック追加

---

Version 4（現在）

async createWallet(
  ctx: IContext,
  input: GqlWalletCreateInput,
  communityId: string,
  tx: Prisma.TransactionClient
): Promise<PrismaWallet> {
  // バリデーション
  const existing = await this.repo.findByUserId(ctx, input.userId, tx);
  if (existing) {
    throw new Error("WALLET_ALREADY_EXISTS");
  }

  // 入力変換
  const data = this.converter.toCreateData(input, communityId);

  // 作成
  return await this.repo.create(ctx, data, tx);
}

変更: Clean Architecture パターンに準拠、Converter導入

推論:

• 段階的にアーキテクチャを改善
• 最初はシンプルだったが、バグを経験して厳格化
• 最終的にDDDパターンに完全準拠

---

### ステップ4: 関連IssueとPRの調査

GitHubのIssue/PRから背景を調査:

```bash
# 関連PRを検索
gh pr list --search "wallet" --state all --limit 20

# 特定PRの詳細（PR番号を引数から取得）
PR_NUMBER="${ARGUMENTS}"
gh pr view "$PR_NUMBER"

# PRのコメントを確認
gh api repos/Hopin-inc/civicship-api/pulls/"$PR_NUMBER"/comments

Issue/PR分析:

## 関連Issue/PRの分析

### 重要なPR

#### PR #45: トランザクション対応
**タイトル:** Add transaction support to wallet operations
**作成日:** 2023-08-15
**状態:** Merged

**説明:**

問題

ポイント送受信で以下のバグが発生:

1. ユーザーAが100ptをユーザーBに送信
2. 同時にユーザーBが100ptをユーザーAに送信
3. 両者のポイントが増加（残高の不整合）

原因

トランザクション管理がなく、レースコンディション

対策

すべてのウォレット操作をトランザクション内で実行

**レビューコメント:**
- "トランザクションを必須にするのは良い判断"
- "パフォーマンスへの影響は？" → "問題なし、10ms以下"

**推論:**
- 実際に本番でバグが発生していた
- データ整合性を最優先する文化
- パフォーマンスよりも正確性

---

#### PR #78: セキュリティ修正
**タイトル:** Add RLS to all wallet queries
**作成日:** 2025-03-15
**状態:** Merged

**説明:**

問題

セキュリティ監査で指摘: ユーザーAが他ユーザーのウォレット情報を取得可能

原因

一部のクエリで ctx.issuer を使用していない

対策

全てのRepositoryメソッドでRLSを適用

**レビューコメント:**
- "Critical なセキュリティバグ、即座にマージすべき"
- "テストカバレッジを100%にして"

**推論:**
- セキュリティインシデントが発生した可能性
- 監査プロセスが機能している
- セキュリティを非常に重視

---

ステップ5: コードレビューコメントの分析

過去のコードレビューから設計思想を推論:

# PRのレビューコメントを取得
gh api repos/Hopin-inc/civicship-api/pulls/45/reviews

レビューコメント分析:

## コードレビューから見える設計思想

### 頻出するレビュー指摘

#### 1. トランザクション管理

**コメント例:**

このメソッドはトランザクション内で呼ばれる可能性があるので、 tx パラメータを追加してください。

**頻度:** 10回以上

**推論される原則:**
- トランザクション管理は必須
- 全てのメソッドで tx を伝播すべき
- データ整合性への強いこだわり

---

#### 2. エラーハンドリング

**コメント例:**

バリデーションエラーは Error ではなく、 ビジネス例外クラスを使ってください。

**頻度:** 5回以上

**推論される原則:**
- エラーを適切に分類
- クライアントに意味のあるエラーメッセージ
- デバッグしやすいコード

---

#### 3. テストカバレッジ

**コメント例:**

このメソッドのテストが不足しています。 エッジケースもカバーしてください。

**頻度:** 8回以上

**推論される原則:**
- テストを重視
- カバレッジ目標: 90%以上
- エッジケースを見逃さない

---

#### 4. パフォーマンス

**コメント例:**

このクエリはN+1問題を引き起こします。 DataLoaderを使用してください。

**頻度:** 3回以上

**推論される原則:**
- パフォーマンスを意識
- N+1問題は許容しない
- スケーラビリティを考慮

---

ステップ6: チーム文化の推論

コミットメッセージ、PR、レビューから組織文化を推論:

## チーム文化の推論

### 開発プロセス

#### コードレビュー文化
- **全PRにレビュー必須**
- 平均レビュー数: 2-3名
- レビュー期間: 1-2日
- マージ条件: 全レビュアーの承認 + CI通過

**推論:**
- 品質を重視する文化
- チーム間のナレッジ共有
- 属人化を防ぐ仕組み

---

#### テスト文化
- **テストなしのPRはマージされない**
- カバレッジ目標: 90%
- E2Eテストも重視

**推論:**
- テスト駆動開発（TDD）に近い文化
- 品質保証を最優先

---

#### セキュリティ意識
- **セキュリティ監査を定期実施**
- RLSを徹底
- センシティブデータの取り扱いに厳格

**推論:**
- 金融系・個人情報を扱うプロダクト
- セキュリティインシデントを経験している可能性
- コンプライアンスを重視

---

### 技術的な価値観

#### 優先順位

1. **正確性 > パフォーマンス**
   - トランザクション必須化
   - 厳格なバリデーション

2. **セキュリティ > 利便性**
   - 全クエリにRLS
   - 認証・認可の徹底

3. **保守性 > 開発速度**
   - Clean Architecture準拠
   - リファクタリングを厭わない

4. **テスト > 機能追加**
   - 高いカバレッジ要求
   - エッジケースの網羅

**推論:**
- 長期的な運用を見据えた設計
- 技術的負債を許容しない文化

---

ステップ7: 設計パターンの推論

コードの進化から設計パターンを推論:

## 設計パターンの進化

### パターン1: トランザクション管理

**進化:**

V1: トランザクションなし ↓ V2: 一部のメソッドにトランザクション ↓ V3: 全メソッドでトランザクション必須 ↓ V4: UseCaseでトランザクション管理、Serviceは伝播のみ

**推論される設計思想:**
- レイヤー責任の明確化
- UseCaseがトランザクション境界
- Serviceはビジネスロジックのみ

---

### パターン2: エラーハンドリング

**進化:**

V1: 例外をそのままthrow ↓ V2: カスタムエラークラス導入 ↓ V3: エラーコードの統一 ↓ V4: GraphQLエラーとの統合

**推論される設計思想:**
- ユーザーフレンドリーなエラーメッセージ
- デバッグしやすいエラー情報
- クライアント側での適切なハンドリング

---

### パターン3: データアクセス

**進化:**

V1: Serviceが直接Prismaを呼ぶ ↓ V2: Repository層を導入 ↓ V3: Converter層を導入（入力変換） ↓ V4: Presenter層を導入（出力変換）

**推論される設計思想:**
- Clean Architectureへの段階的移行
- 各レイヤーの責任を明確化
- テストしやすい構造

---

ステップ8: 技術的決定の背景推論

なぜこの技術選択をしたのかを推論:

## 技術的決定の背景

### 決定1: Prisma ORM 採用

**推論される理由:**
1. **型安全性:** TypeScriptとの親和性
2. **マイグレーション:** スキーマ管理が容易
3. **開発効率:** 生SQLを書く必要がない
4. **コミュニティ:** 活発なエコシステム

**裏付け:**
- 初期コミットからPrisma使用
- マイグレーションファイルが整然と管理されている
- Prisma独自の機能（RLS、トランザクション）を活用

---

### 決定2: GraphQL 採用

**推論される理由:**
1. **柔軟性:** クライアントが必要なデータのみ取得
2. **型安全性:** スキーマ駆動開発
3. **フロントエンドとの親和性:** React/Apollo との統合
4. **N+1防止:** DataLoaderでパフォーマンス最適化

**裏付け:**
- DataLoaderの積極的な活用
- GraphQL Code Generatorでの型生成
- スキーマファーストな開発プロセス

---

### 決定3: tsyringe（DI） 採用

**推論される理由:**
1. **テスタビリティ:** モック化が容易
2. **疎結合:** 依存関係の明確化
3. **保守性:** インターフェースベースの設計
4. **スケーラビリテ

---

*Content truncated.*