# Cursor / AI エージェント向け 作業依頼プロンプトテンプレート

> このファイルをコピーして Cursor に貼り付けてください。
> タスクを1つずつ渡すことで、確実に実装が進みます。

---

## 【必須】全タスク共通の前置き

```
まず AI_MASTER_ROADMAP.md を読んでください。
特に「4. 開発ルール」のハードコード色の例外一覧を必ず確認してから作業を開始してください。

作業完了後は必ず以下を実行・報告してください:
1. flutter analyze を実行してエラーが0件であることを確認
2. 変更したファイルの一覧と変更概要を報告
```

---

## タスク別プロンプト

### 🟥 v1.0.16-A: onboarding_dialog.dart のハードコード色修正

```
まず AI_MASTER_ROADMAP.md を読んでください。

【タスク】
lib/widgets/onboarding_dialog.dart の以下2箇所を修正してください:
- 113行目付近: Colors.grey → appColors.textSecondary
- 136行目付近: Colors.grey[300] → appColors.textSecondary

【注意】
- 同ファイル内の Colors.black.withValues(alpha:...) はシャドウのため変更禁止
- AppColors は Theme.of(context).extension<AppColors>()! で取得すること

【完了条件】
flutter analyze でエラー0件
```

---

### 🟥 v1.0.16-B: pending_analysis_screen.dart のハードコード色修正

```
まず AI_MASTER_ROADMAP.md を読んでください。

【タスク】
lib/screens/pending_analysis_screen.dart の色を以下の方針で修正してください:

変更対象（appColorsに置換）:
- Colors.red (エラーテキスト・アイコン) → appColors.error
- Colors.green.shade400 (成功アイコン) → appColors.success

変更禁止（意図的なハードコード・AI_MASTER_ROADMAP.mdの例外一覧参照）:
- Colors.grey.shade400 (disabledBackgroundColor) → Material Design標準のため維持
- Colors.grey.shade300 (プレースホルダー背景) → プレースホルダー標準色のため維持
- Colors.white (画像オーバーレイ) → カメラUI要件のため維持
- Colors.black.withValues(alpha:...) → シャドウのため維持

【完了条件】
flutter analyze でエラー0件
```

---

### 🟧 v1.0.16-C: sake_detail_screen.dart から _PhotoEditModal を分離

```
まず AI_MASTER_ROADMAP.md と FILE_SPLIT_RECOMMENDATIONS_v1.0.16.md を読んでください。

【タスク】
lib/screens/sake_detail_screen.dart の末尾にある _PhotoEditModal クラス（約266行）を
新規ファイル lib/screens/sake_detail/widgets/sake_photo_edit_modal.dart に切り出してください。

方針:
- StatefulWidget として独立させる
- 元の sake_detail_screen.dart からは import して呼び出す形にする
- Widget のシグネチャ（引数）は変えない
- ディレクトリ lib/screens/sake_detail/widgets/ を新規作成する

【完了条件】
- flutter analyze でエラー0件
- アプリの挙動が変わらないこと（写真編集モーダルが正常に開くこと）
```

---

### 🟧 v1.0.16-D: sake_detail_screen.dart から SakeMBTIStampSection を分離

```
まず AI_MASTER_ROADMAP.md と FILE_SPLIT_RECOMMENDATIONS_v1.0.16.md を読んでください。

【タスク】
lib/screens/sake_detail_screen.dart 内の MBTI スタンプセクション（約187行）を
新規ファイル lib/screens/sake_detail/sections/sake_mbti_stamp_section.dart に切り出してください。

方針:
- ConsumerWidget として独立させる
- 必要な引数（SakeItem など）はコンストラクタで受け取る
- 元ファイルは import して使用する形にする

【完了条件】
flutter analyze でエラー0件
```

---

### 🟨 v1.0.16-E: 基本テストの追加

```
まず AI_MASTER_ROADMAP.md を読んでください。

【タスク】
以下の2つのテストファイルを新規作成してください:

1. test/models/sake_item_test.dart
   - SakeItem の toJson() / fromJson() ラウンドトリップテスト
   - name, brewery, tasteStats フィールドの正確性確認

2. test/services/analysis_cache_service_test.dart
   - computeImageHash() が同じ入力に対して同じハッシュを返すこと
   - _normalizeBrandName() のスペース除去・小文字化の確認

【完了条件】
flutter test でテストがすべてパスすること
flutter analyze でエラー0件
```

---

### 🟩 v1.1.0-A: チャート手動編集機能

```
まず AI_MASTER_ROADMAP.md を読んでください。

【タスク】
sake_detail_screen.dart の五味チャートセクションに、
ユーザーが AI 生成値を手動で微調整できる機能を追加してください。

仕様:
- 編集ボタン（鉛筆アイコン）をチャートの右上に配置
- タップするとスライダー付きの編集モーダルが開く
- 5軸（香り/甘み/酸味/キレ/コク）それぞれを 0〜5 の範囲で調整可能
- 保存時は SakeItem.tasteStats を更新し Hive に永続化
- キャンセルで元の値に戻る
- UI は AppColors を使用すること（ハードコード色禁止・例外一覧参照）

【完了条件】
flutter analyze でエラー0件
チャートの値が実際に変わりアプリ再起動後も保持されること
```

---

### 🔵 Synology Proxy 構築（SSH全自動）

```
以下の手順でSynology NAS上にGemini APIプロキシサーバーを構築してください。
Agentとして自律的に進め、不明な情報は最初にまとめて質問してください。

【事前確認】作業開始前に以下を私に確認してください:
1. SynologyのSSHユーザー名 (例: admin, maita など)
2. SynologyのTailscale IP (NASのターミナルで `tailscale ip -4` を実行すると確認できます)
3. Gemini APIキー (lib/secrets.local.dart の geminiApiKey の値)

【タスク】
上記の情報が揃ったら、以下を順番に実行してください:

Step 1: SSH接続確認
  ターミナルで以下を実行し、接続できることを確認する:
  ssh [ユーザー名]@[TailscaleIP] "echo 'SSH OK'"

Step 2: プロキシ用ディレクトリ作成
  ssh [ユーザー名]@[TailscaleIP] "mkdir -p /docker/ponshu_proxy"

Step 3: ファイル転送
  以下の3ファイルをSCPでNASに転送する:
  scp tools/proxy/server.js [ユーザー名]@[TailscaleIP]:/docker/ponshu_proxy/
  scp tools/proxy/package.json [ユーザー名]@[TailscaleIP]:/docker/ponshu_proxy/
  scp tools/proxy/Dockerfile [ユーザー名]@[TailscaleIP]:/docker/ponshu_proxy/

Step 4: Dockerイメージのビルド
  ssh [ユーザー名]@[TailscaleIP] "cd /docker/ponshu_proxy && docker build -t ponshu-proxy:latest ."

Step 5: 既存コンテナの停止・削除（再構築時のみ）
  ssh [ユーザー名]@[TailscaleIP] "docker rm -f ponshu-proxy-server 2>/dev/null || true"

Step 6: コンテナ起動
  ssh [ユーザー名]@[TailscaleIP] "docker run -d \
    --name ponshu-proxy-server \
    --restart unless-stopped \
    -p 8080:8080 \
    -e GEMINI_API_KEY='[APIキー]' \
    -e DAILY_LIMIT=50 \
    -e PORT=8080 \
    ponshu-proxy:latest"

Step 7: 動作確認
  curl http://[TailscaleIP]:8080/health
  → "OK" が返れば成功

Step 8: Flutter側の設定更新
  lib/secrets.local.dart を以下のように更新する:
  - aiProxyBaseUrl を "http://[TailscaleIP]:8080" に変更
  - useProxy を true に変更

Step 9: 完了報告
  以下を報告してください:
  - 各Stepの実行結果
  - コンテナが正常起動しているか (docker ps の出力)
  - healthチェックの結果
  - secrets.local.dart の変更内容

【注意事項】
- Tailscale経由のためVPN（Tailscale）が接続中でないとアクセスできない
- DAILY_LIMIT=50 は後から変更可能（コンテナ再起動で反映）
- APIキーはStep 6実行前にCursorのターミナルには表示されない形で入力すること

【完了条件】
- curl http://[TailscaleIP]:8080/health → "OK"
- flutter analyze でエラー0件
```

---

### 🔵 Synology Proxy 動作確認・再起動（構築済みの場合）

```
Synology上のponshu-proxyコンテナの状態を確認・必要なら再起動してください。

【事前確認】
1. SynologyのSSHユーザー名
2. SynologyのTailscale IP

【タスク】
Step 1: コンテナ状態確認
  ssh [ユーザー名]@[TailscaleIP] "docker ps -a | grep ponshu-proxy"

Step 2: ヘルスチェック
  curl http://[TailscaleIP]:8080/health

Step 3: ログ確認（問題がある場合）
  ssh [ユーザー名]@[TailscaleIP] "docker logs ponshu-proxy-server --tail 50"

Step 4: 再起動（必要な場合）
  ssh [ユーザー名]@[TailscaleIP] "docker restart ponshu-proxy-server"

結果を報告してください。
```

---

## カラー使用ルール（クイックリファレンス）

### ✅ 使用すべきもの

```dart
final appColors = Theme.of(context).extension<AppColors>()!;

appColors.textPrimary       // メインテキスト
appColors.textSecondary     // サブテキスト・ヒント
appColors.textTertiary      // 薄いテキスト
appColors.brandPrimary      // ブランドカラー（ボタン等）
appColors.brandAccent       // アクセントカラー
appColors.error             // エラー表示（Colors.red の代替）
appColors.success           // 成功表示（Colors.green の代替）
appColors.warning           // 警告表示
appColors.surfaceElevated   // カード背景
appColors.surfaceSubtle     // 薄い背景
appColors.divider           // 区切り線
```

### ❌ 変更禁止のハードコード色

```
camera_screen.dart 全体
  → Colors.white / black / white54 / transparent
  → 理由: カメラUIはテーマ非依存で視認性確保が必須

pending_analysis_screen.dart:387
  → Colors.grey.shade400 (disabledBackgroundColor)
  → 理由: Material Design の disabled ボタン標準

pending_analysis_screen.dart:341
  → Colors.grey.shade300 (プレースホルダー背景)
  → 理由: 画像未選択状態の標準色

main_screen.dart:65
  → Colors.grey.shade400 (Pro機能ロックアイコン)
  → 理由: 無効化状態の意図的な灰色表現

各所の boxShadow
  → Colors.black.withValues(alpha: ...)
  → 理由: シャドウは黒固定が自然
```

---

## トラブルシューティング

### flutter analyze でエラーが出た場合

```
AI_MASTER_ROADMAP.md を再度確認し、以下をチェックしてください:
1. AppColors のプロパティ名が正しいか（lib/theme/app_colors.dart を参照）
2. ConsumerWidget を使っているか
3. ハードコード色の例外一覧に該当していないか
エラーメッセージを貼り付けて修正してください。
```

### 巨大ファイル (sake_detail_screen.dart) を編集する場合

```
1872行あるため、一度に全体を把握しようとしないこと。
対象のクラス・メソッドの範囲だけをピンポイントで読み込み編集すること。
```

---

**最終更新**: 2026-02-13