# v7: Vertex AI 재무 분석 프롬프트 작성 및 테스트

## 프롬프트 엔지니어링이란?

프롬프트 엔지니어링은 AI 모델로부터 원하는 결과를 얻기 위해 입력(프롬프트)을 최적화하는 기술입니다. 좋은 프롬프트는 명확하고, 구조화되어 있으며, 구체적인 지시사항을 포함합니다.

### 좋은 재무 분석 프롬프트의 조건

1. **명확한 역할 지정**: "당신은 재무 분석가입니다"
2. **구체적인 요청**: "총 수입, 총 지출, 순자산 변동을 분석하세요"
3. **출력 형식 지정**: "다음 형식으로 답변하세요: ..."
4. **컨텍스트 제공**: 거래 데이터, 날짜 범위 등

## 프롬프트 템플릿 작성

### src/utils/prompt.ts

```typescript
import { MFTransaction } from '../types';
import { Formatter } from './formatter';
import { TransactionAnalyzer } from './transaction-analyzer';

export class PromptBuilder {
  /**
   * 기본 재무 요약 프롬프트
   */
  static buildSummaryPrompt(
    transactions: MFTransaction[],
    fromDate: string,
    toDate: string
  ): string {
    const stats = TransactionAnalyzer.getBasicStats(transactions);
    const categoryStats = TransactionAnalyzer.groupByCategory(
      transactions.filter((t) => !t.is_income)
    );

    const prompt = `
あなたは優秀な個人ファイナンシャルアドバイザーです。
以下の期間の家計データを分析し、わかりやすく日本語で説明してください。

## 分析期間
${fromDate} ~ ${toDate}

## 基本統計
- 総収入: ¥${stats.totalIncome.toLocaleString()}
- 総支出: ¥${stats.totalExpense.toLocaleString()}
- 純資産変動: ¥${stats.netChange.toLocaleString()}
- 取引件数: ${stats.transactionCount}件

## 支出カテゴリ TOP 5
${categoryStats.slice(0, 5).map((c, i) => `${i + 1}. ${c.name}: ¥${c.amount.toLocaleString()}`).join('\n')}

## 最近の取引履歴 (10件)
${Formatter.transactionsToText(transactions.slice(0, 10))}

## 依頼内容
以下の項目について、簡潔に分析してください:

1. **概要**: この期間の収支を一言で要約
2. **主要インサイト**: 特筆すべき3つのポイント
3. **支出パターン**: どのカテゴリに多く使っているか
4. **改善提案**: 節約や改善のための具体的なアドバイス

**出力形式**:
簡潔で読みやすい箇条書き形式で答えてください。
絵文字を適度に使用して、わかりやすくしてください。
    `.trim();

    return prompt;
  }

  /**
   * 詳細 分析 프롬프트
   */
  static buildDetailedAnalysisPrompt(
    transactions: MFTransaction[],
    fromDate: string,
    toDate: string
  ): string {
    const stats = TransactionAnalyzer.getBasicStats(transactions);
    const { income, expense } = TransactionAnalyzer.splitIncomeExpense(transactions);
    const categoryStats = TransactionAnalyzer.groupByCategory(expense);
    const topExpenses = TransactionAnalyzer.getTopExpenses(transactions, 5);

    const prompt = `
あなたはデータアナリストとファイナンシャルプランナーの専門知識を持つAIアシスタントです。
以下の家計データを徹底的に分析し、プロフェッショナルなレポートを作成してください。

## 分析期間
${fromDate} ~ ${toDate} (${transactions.length}件の取引)

## 基本指標
- 総収入: ¥${stats.totalIncome.toLocaleString()} (${stats.incomeCount}件)
- 総支出: ¥${stats.totalExpense.toLocaleString()} (${stats.expenseCount}件)
- 純資産変動: ¥${stats.netChange.toLocaleString()}
- 平均収入額: ¥${Math.round(stats.avgIncome).toLocaleString()}
- 平均支出額: ¥${Math.round(stats.avgExpense).toLocaleString()}

## カテゴリ別支出
${categoryStats.map((c, i) => {
  const percentage = (c.amount / stats.totalExpense * 100).toFixed(1);
  return `${i + 1}. ${c.name}: ¥${c.amount.toLocaleString()} (${percentage}%)`;
}).join('\n')}

## 高額支出 TOP 5
${topExpenses.map((t, i) => `${i + 1}. ${t.date} - ${t.content}: ¥${t.amount.toLocaleString()} (${t.category.name})`).join('\n')}

## 全取引履歴
${Formatter.transactionsToText(transactions)}

## レポート要件
以下の項目について、詳細に分析してください:

### 1. エグゼクティブサマリー
- この期間の財務状況を3-4文で要約

### 2. 収入分析
- 収入源と金額
- 前月比の変化(推測可能な場合)

### 3. 支出分析
- カテゴリ別の詳細分析
- 支出パターンの特徴
- 注目すべき支出項目

### 4. トレンドと洞察
- 発見された傾向
- 異常な支出や特異点
- ポジティブな点とネガティブな点

### 5. アクションプラン
- 具体的な節約アドバイス
- 支出最適化の提案
- 次月の目標設定

**出力形式**:
マークダウン形式で、見出しと箇条書きを使用してください。
数値は具体的に示し、パーセンテージも併記してください。
絵文字を適度に使用して、読みやすくしてください。
    `.trim();

    return prompt;
  }

  /**
   * 比較 분석 프롬프트 (전월 대비)
   */
  static buildComparisonPrompt(
    currentTransactions: MFTransaction[],
    previousTransactions: MFTransaction[],
    currentPeriod: { from: string; to: string },
    previousPeriod: { from: string; to: string }
  ): string {
    const currentStats = TransactionAnalyzer.getBasicStats(currentTransactions);
    const previousStats = TransactionAnalyzer.getBasicStats(previousTransactions);

    const incomeChange = currentStats.totalIncome - previousStats.totalIncome;
    const expenseChange = currentStats.totalExpense - previousStats.totalExpense;

    const prompt = `
あなたは家計管理の専門家です。
2つの期間の家計データを比較分析し、変化と傾向を報告してください。

## 今月 (${currentPeriod.from} ~ ${currentPeriod.to})
- 総収入: ¥${currentStats.totalIncome.toLocaleString()}
- 総支出: ¥${currentStats.totalExpense.toLocaleString()}
- 純資産変動: ¥${currentStats.netChange.toLocaleString()}
- 取引件数: ${currentStats.transactionCount}件

## 先月 (${previousPeriod.from} ~ ${previousPeriod.to})
- 総収入: ¥${previousStats.totalIncome.toLocaleString()}
- 総支出: ¥${previousStats.totalExpense.toLocaleString()}
- 純資産変動: ¥${previousStats.netChange.toLocaleString()}
- 取引件数: ${previousStats.transactionCount}件

## 変化
- 収入変化: ${incomeChange >= 0 ? '+' : ''}¥${incomeChange.toLocaleString()}
- 支出変化: ${expenseChange >= 0 ? '+' : ''}¥${expenseChange.toLocaleString()}

## 依頼内容
以下の項目について分析してください:

1. **月次比較**: 収入と支出の変化を評価
2. **改善点**: 良くなった点
3. **懸念点**: 悪化した点
4. **推奨事項**: 次月に向けたアドバイス

簡潔で具体的に答えてください。
    `.trim();

    return prompt;
  }

  /**
   * 간단한 질문 응답 프롬프트
   */
  static buildQuestionPrompt(
    transactions: MFTransaction[],
    question: string
  ): string {
    const stats = TransactionAnalyzer.getBasicStats(transactions);

    const prompt = `
あなたは個人の家計データを分析するAIアシスタントです。
以下のデータに基づいて、ユーザーの質問に答えてください。

## データサマリー
- 総収入: ¥${stats.totalIncome.toLocaleString()}
- 総支出: ¥${stats.totalExpense.toLocaleString()}
- 取引件数: ${stats.transactionCount}件

## 取引履歴
${Formatter.transactionsToText(transactions.slice(0, 50))}

## ユーザーの質問
${question}

## 回答要件
- 質問に対して簡潔かつ正確に答えてください
- データに基づいた具体的な情報を提供してください
- 必要に応じて数値を示してください
    `.trim();

    return prompt;
  }
}
```

## 재무 분석기 구현

### src/vertexai/analyzer.ts

```typescript
import { VertexAIClient } from './client';
import { MFTransaction } from '../types';
import { PromptBuilder } from '../utils/prompt';

export class FinancialAnalyzer {
  private aiClient: VertexAIClient;

  constructor() {
    this.aiClient = new VertexAIClient();
  }

  /**
   * 기본 재무 요약
   */
  async analyzeSummary(
    transactions: MFTransaction[],
    fromDate: string,
    toDate: string
  ): Promise<string> {
    const prompt = PromptBuilder.buildSummaryPrompt(
      transactions,
      fromDate,
      toDate
    );

    console.log('📊 재무 요약 분석 중...\n');

    const response = await this.aiClient.generateText({
      prompt,
      temperature: 0.3, // 사실 기반이므로 낮은 temperature
      maxOutputTokens: 2048,
    });

    return response.text;
  }

  /**
   * 상세 분석
   */
  async analyzeDetailed(
    transactions: MFTransaction[],
    fromDate: string,
    toDate: string
  ): Promise<string> {
    const prompt = PromptBuilder.buildDetailedAnalysisPrompt(
      transactions,
      fromDate,
      toDate
    );

    console.log('📈 상세 재무 분석 중...\n');

    const response = await this.aiClient.generateText({
      prompt,
      temperature: 0.4,
      maxOutputTokens: 4096, // 더 긴 출력
    });

    return response.text;
  }

  /**
   * 비교 분석 (전월 대비)
   */
  async analyzeComparison(
    currentTransactions: MFTransaction[],
    previousTransactions: MFTransaction[],
    currentPeriod: { from: string; to: string },
    previousPeriod: { from: string; to: string }
  ): Promise<string> {
    const prompt = PromptBuilder.buildComparisonPrompt(
      currentTransactions,
      previousTransactions,
      currentPeriod,
      previousPeriod
    );

    console.log('🔄 전월 대비 분석 중...\n');

    const response = await this.aiClient.generateText({
      prompt,
      temperature: 0.3,
      maxOutputTokens: 2048,
    });

    return response.text;
  }

  /**
   * 사용자 질문 응답
   */
  async answerQuestion(
    transactions: MFTransaction[],
    question: string
  ): Promise<string> {
    const prompt = PromptBuilder.buildQuestionPrompt(transactions, question);

    console.log(`💬 질문 분석 중: "${question}"\n`);

    const response = await this.aiClient.generateText({
      prompt,
      temperature: 0.2,
      maxOutputTokens: 1024,
    });

    return response.text;
  }
}
```

## 분석 테스트 스크립트

### src/cli-analyze.ts

```typescript
import 'dotenv/config';
import { MoneyForwardClient } from './moneyforward/client';
import { FinancialAnalyzer } from './vertexai/analyzer';
import { format, subMonths } from 'date-fns';

async function main() {
  console.log('💰 Money Forward + Vertex AI 재무 분석\n');
  console.log('='.repeat(60) + '\n');

  try {
    // 1. Money Forward에서 데이터 조회
    const mfClient = new MoneyForwardClient();

    const toDate = format(new Date(), 'yyyy-MM-dd');
    const fromDate = format(subMonths(new Date(), 1), 'yyyy-MM-dd');

    console.log(`📅 분석 기간: ${fromDate} ~ ${toDate}\n`);

    const transactions = await mfClient.getAllTransactions(fromDate, toDate);

    if (transactions.length === 0) {
      console.log('⚠️  거래 내역이 없습니다');
      return;
    }

    console.log('='.repeat(60) + '\n');

    // 2. Vertex AI로 분석
    const analyzer = new FinancialAnalyzer();

    const analysis = await analyzer.analyzeSummary(
      transactions,
      fromDate,
      toDate
    );

    // 3. 결과 출력
    console.log('🤖 Vertex AI 분석 결과');
    console.log('='.repeat(60) + '\n');
    console.log(analysis);
    console.log('\n' + '='.repeat(60) + '\n');

    console.log('✅ 분석 완료!');
  } catch (error) {
    console.error('❌ 에러:', error);
    process.exit(1);
  }
}

main();
```

### package.json 스크립트 추가

```json
{
  "scripts": {
    "dev": "tsx src/index.ts",
    "auth": "tsx src/cli-auth.ts",
    "fetch": "tsx src/cli-fetch-transactions.ts",
    "test:ai": "tsx src/cli-test-vertexai.ts",
    "analyze": "tsx src/cli-analyze.ts",
    "build": "tsc"
  }
}
```

## 실행 및 테스트

### 재무 분석 실행

```bash
npm run analyze
```

예상 출력:

```
💰 Money Forward + Vertex AI 재무 분석

============================================================

📅 분석 기간: 2025-10-30 ~ 2025-11-30

📥 거래 내역 조회 중... (offset: 0)
✅ 총 87건의 거래 내역 조회 완료

============================================================

📊 재무 요약 분석 중...

🤖 Vertex AI에 요청 중...
✅ Vertex AI 응답 수신 완료

🤖 Vertex AI 분석 결과
============================================================

## 📊 概要
11月は総収入50万円、総支出32万円で、18万円の黒字を達成しました。

## 💡 主要インサイト
• 🍔 食費が全支出の26.6%を占めており、前月より増加傾向
• 🚇 在宅勤務の影響で交通費が大幅に減少
• 🛒 オンラインショッピングの利用が増加

## 📈 支出パターン
1. 食費: ¥85,000 (外食が多い)
2. 日用品: ¥45,000 (Amazon中心)
3. 光熱費: ¥22,000
4. 通信費: ¥15,000
5. 交通費: ¥12,000

## 🎯 改善提案
• 週2-3回の自炊で食費を¥20,000程度削減可能
• 使用していないサブスク3件を解約(月¥2,400節約)
• 緊急資金目標達成率90% - 年末までに達成見込み

============================================================

✅ 분석 완료!
```

## 프롬프트 최적화 팁

### 1. Temperature 설정

```typescript
// 사실 기반 분석 (낮은 온도)
temperature: 0.2-0.3  // 숫자, 통계 위주

// 창의적인 제안 (높은 온도)
temperature: 0.6-0.8  // 아이디어, 조언
```

### 2. 컨텍스트 윈도우 관리

Gemini 1.5 Flash는 최대 1M 토큰까지 지원하지만, 비용과 속도를 고려하여:

```typescript
// 거래 내역이 너무 많으면 요약
if (transactions.length > 200) {
  // 최근 100건만 상세 표시, 나머지는 통계만
}
```

### 3. 출력 형식 명시

```typescript
const prompt = `
...

**출력 형식**:
# 제목
## 섹션1
- 항목1
- 항목2

구체적인 형식을 지정하면 일관된 결과를 얻을 수 있습니다.
`;
```

### 4. Few-Shot Learning

예시를 제공하면 더 나은 결과:

```typescript
const prompt = `
...

예시:
입력: 食費 ¥50,000
출력: 🍔 食費が多めです。週2-3回の自炊をお勧めします。

이제 다음 데이터를 분석하세요:
...
`;
```

## 체크리스트

v7을 완료하기 전에 다음을 확인하세요:

- [ ] `PromptBuilder` 클래스 구현 완료
- [ ] `FinancialAnalyzer` 클래스 구현 완료
- [ ] `cli-analyze.ts` 스크립트 생성
- [ ] `npm run analyze` 실행하여 분석 성공
- [ ] 분석 결과가 유용하고 이해하기 쉬운지 확인
- [ ] 다양한 프롬프트 템플릿 테스트

## 다음 단계

v8에서는 거래 데이터 전처리를 개선하고 프롬프트를 더욱 최적화합니다.

---

**작성일**: 2025-11-30
**상태**: ✅ 완료
**다음**: v8 - 데이터 전처리 및 프롬프트 최적화