🦔
【AI駆動開発】個人開発でも爆速リリースを続けられる理由〜企画からリリース後運用まで〜

2026/02/01に公開
本記事では、実際に私がFlutterで作成したAIチャットアプリ（Sodalio）を題材に、企画 → プロジェクト初期化 → 開発 → レビュー → テスト → リリース → 運用の各フェーズにおけるAI駆動開発の実践方法をお届けします。
個人開発者の中には、複数のプロダクトを同時に開発・運用している方も少なくないと思います。

かく言う私も、Web/モバイル合わせて現在10以上のプロダクトを開発・運用していますが、個人開発において、以下の課題は避けられないと思っています。
限られた時間で、どう品質を担保するか
一人でやるリスク（レビュー不足、テスト漏れ）をどう補うか
運用フェーズで疲弊せず、どう次のプロダクト開発を進めていくか。
このフローは、そうした課題に対して「AIを各フェーズに統合する」ことで解決し、個人開発でもスタートアップ規模の開発体制に近い成果を出すことを目指しています。

もし、こういった使い方もおすすめなどありましたらコメントまでお願いします。
!この記事は長編です。 まず TL;DR と全体像を読み、その後必要なフェーズだけを読むことをおすすめします。

 目次この記事の前提
題材にしたアプリ
TL;DR
全体像（ざっくり）

フェーズ詳細
フェーズ1：企画（Planning）
フェーズ2：プロジェクト初期化（Project Setup）
フェーズ3：cc-sdd 開発（Spec-Driven Development）
フェーズ4：コードレビュー（Code Review）
フェーズ5：E2E & Visual Regression
フェーズ6：CI/CD & リリース
フェーズ7：運用/改善

まとめ（全体）

 この記事の前提
 対象読者個人開発または小規模チームでモバイルアプリを作っている
AI を開発フローに組み込みたい

 前提Flutter / GitHub の基本が分かる
Claude などのAIエージェントについての知識がある
運用フェーズ編は GitHub Actions / GoogleAnalytics / Crashlytics などの知識があると理解しやすい

 この記事で得られること企画→運用までの AI 開発パイプラインの全体像
cc-sdd をベースにした仕様駆動フローの実践例
E2E / VRT / 運用自動化の具体例

 読み方ガイドまず TL;DR と全体像を読む
自分のボトルネックのフェーズだけ読む
実装・設定は折りたたみ内のコード例を参照する
読了目安: 全体で 30〜45 分（必要フェーズだけなら 5〜10 分）

 題材にしたアプリhttps://apps.apple.com/jp/app/sodalio-aiチャット記録アプリ/id6757146846

https://play.google.com/store/apps/details?id=com.mysterylog.sodalio

 TL;DRAI に作業を寄せ、人は判断だけに集中するパイプライン
企画→初期化→開発→レビュー→テスト→リリース→運用までを一気通貫で回す
cc-sdd + TDD + E2E / VRT + 運用自動化で品質と速度を両立
まずは自分のボトルネックのフェーズから部分導入する

 全体像（ざっくり）まずは全体の流れを一枚で把握できるように、工程をざっくりまとめます。

 各フェーズの概要

フェーズ
概要


企画
市場/ユーザー/収益を整理して方向性を固める。
「何を作るか」を決めたい人はここ。

初期化
開発基盤とプロジェクト記憶（steering）を整える。
初期の手順や構成を知りたい人はここ。

開発
仕様→設計→タスク→実装を順に進める。
cc-sdd の具体的な回し方を知りたい人はここ。

レビュー
ローカル＋PRで品質を二重チェックする。
レビュー手順やAIの使い分けを知りたい人はここ。

テスト
E2E と VRT で UI の挙動/見た目を担保する。
自動テストの作り方を知りたい人はここ。

リリース
ストア文言と配布を自動化する。
CI/CDや配布フローを知りたい人はここ。

運用
監視・分析・学びで改善ループを回す。
運用自動化や改善の流れを知りたい人はここ。


 フェーズ詳細ここからはフェーズごとに詳しく解説します。必要な箇所だけ読んでもらえればOKです。

 フェーズ1：企画（Planning）!目的: 市場・ペルソナ・収益戦略を整理し、製品ビジョンとブランド要素を固める。

主な成果物: 製品ビジョン(product.md) / アプリ名 / アイコン

判断ポイント: サービス方針・サービス命名/アイコンの最終確認

 はじめにアプリ開発は企画から始まります。このフェーズでは Claude を活用しながら、市場調査・ペルソナ・収益戦略を一括で整理し、product.md（製品ビジョン）のドキュメントを生成します。

このドキュメントは後の開発フェーズにおいて仕様検討、設計書作成もどのベースとなります。
このフェーズのゴール:
市場調査に基づいた製品コンセプトの確立
ターゲットユーザーと収益モデルの明確化

product.md（製品ビジョン）の生成
アプリ名とアイコンの決定

 題材：AI チャットアプリ今回企画編で題材にするのは、カスタマイズ可能な AI キャラクターと会話を楽しめるチャットアプリです。

 Claude.ai でプロジェクトを作成まず、Claude.ai でプロジェクトを作成します。
プロジェクトを作成することで、毎回同じ前提条件を伝える必要がなくなり、また同一プロジェクト内の関連するやり取りを参照しやすくなります。

 Skills の作成毎回「市場調査をして」「ペルソナを設計して」などと依頼するたびに、出力フォーマットや分析の深さがバラバラになることがあります。

そこで、Skills というものを作成しておくことで下記を実現することが可能です。

出力フォーマットの統一: 常に同じ構造でレポートが生成される

分析の観点を固定: 漏れなく必要な項目を分析
!Agent Skills とは
Skills = Claude に追加できる「マニュアル」や「テンプレート」 です。
一度作っておけば、「市場調査して」などと伝えるだけで毎回同じフォーマット・同じ観点で分析してくれます。毎回プロンプトで「こういう形式で出して」と指示する必要がなくなります。

また、必要な文脈の時だけ読み込まれるため、コンテキストを節約しながら適切なガイダンスを提供できます。
企画フェーズ用に作成するSkillsの例

Skill
用途
出力形式


market-research
市場調査・競合分析
市場規模、競合比較表、差別化ポイント

user-persona
ペルソナ・JTBD 設計
ペルソナプロフィール、JTBD、利用シーン

monetization-strategy
収益戦略・KPI 設計
収益モデル、価格設定、KPI 目標値

kiro-product-md
product.md 生成（統合）
Kiro/cc-sdd 形式の product.md

各 Skill の設計意図実際のskillsの内容詳細は割愛しますが、どのような内容が成果物として作成されるかだけ記載いたします。
market-research目的: アプリのアイデアに対して、市場機会とリスクを明確化する
#### 出力に含まれる項目

- 市場概要（TAM/SAM/SOM、成長率）
- 競合分析（3-5 個のアプリを比較表で）
- 差別化ポイント（未充足ニーズ、狙うべきニッチ）
- まとめ: product.md 用の要約（Market Context）
user-persona目的: ターゲットユーザーを具体化し、「誰のために作るか」を明確にする
#### 出力に含まれる項目

- メインペルソナ（名前、年齢、職業、ライフスタイル）
- JTBD（Functional / Emotional / Social の 3 観点）
- 利用シナリオ（いつ、どこで、どのように）
- まとめ: product.md 用の要約（Primary Persona, Use Cases）
monetization-strategy目的: 収益モデルと KPI を設計し、ビジネスの方向性を固める
#### 出力に含まれる項目

- 推奨収益モデル（フリーミアム、サブスク等）
- 価格設定と競合比較
- KPI 設計（North Star Metric、Primary/Secondary KPIs）
- まとめ: product.md 用の要約（Revenue Model）
kiro-product-md目的: 上記 3 つの分析結果を統合し、開発に使える ドキュメント(product.md) を生成
#### 生成ルール（Steering Principles 準拠）

- 100-200 行以内に収める
- パターンと目的に焦点（詳細な機能リストは避ける）
- 「なぜこのアプリを作るか」が伝わる内容
Skills の作成、インストールClaudeの「設定」>「機能」からSkillの追加を選択するとこのようなダイアログが出ます。

Claudeと一緒にスキルを作成することもできるため、会話を通じて作成していくのがおすすめです。

作成したスキルはスキル一覧に表示されます。

!活用パターン: Skills をインストールしておくと、「市場調査をお願いします」と伝えるだけで market-research Skill が自動で使用されます。

 市場調査 → ペルソナ → 収益戦略 → product.md（製品ビジョン）生成今回はSkills を個別に実行するのではなく、Claude.ai に一括で依頼し、対話形式で進めていきます。
プロンプト例AIチャットアプリを開発したいです。
サービス内容としては自分専用にカスタマイズしたAIのキャラクターと会話し、
その会話内容を記録としてAIで要約して保存しておけるアプリにします。
「市場調査」「ペルソナ」「収益戦略」を一緒に考えてください。
対話形式で方向性を確認私の場合、Claude の個人設定に下記を記載することで、Claude が詳細な分析を始める前に、選択式の質問で方向性を確認してくれるようにしています。
曖昧な部分がある場合は回答の前に確認の質問を行うこと。
確認の際はなるべく番号をつけて、ユーザーが番号で応答可能にすること。
Claude からの確認質問の例:


#
質問
選択肢の例


1
ターゲット市場について
A) 日本市場 / B) グローバル展開 / C) まだ決めていない

2
想定しているメインの用途は
A) 日記・セルフリフレクション / B) メンタルヘルス / C) 学習

3
カスタマイズの範囲
A) アバター+性格+口調 / B) 性格+口調のみ / C) 最小限

4
開発体制について
A) 個人開発 / B) 小規模チーム / C) それ以上の規模

5
収益化の優先度は
A) 最初から重視 / B) ユーザー獲得優先 / C) サイドプロジェクト

回答方法選択肢を「1-B,2-A,3-A,4-A,5-A」のように番号と記号で回答するだけで OK です。
Claude が追加で確認したい点があれば、さらに質問が続きます（アウトプット形式、分析の深さなど）。
分析結果と product.md（製品ビジョン） の生成回答を元に、Claude が 市場調査 → ペルソナ → 収益戦略 の順で分析を行い、最終的に product.md を生成します。
生成された product.md（製品ビジョン）Claude が分析結果を統合した product.md を生成します

このファイルは後ほど開発工程でも使うものとなります。

修正したい部分があれば、チャットをしながら調整していきます。
!ポイント: 一括で依頼することで、Claude が文脈を理解した上で一貫性のある分析を行ってくれます。市場調査・ペルソナ・収益戦略が相互に整合した product.md が生成されます。

 アプリ名の決定（Claude との壁打ち）product.md でコンセプトが固まったら、アプリ名を決定します。
プロンプト例以下のコンセプトに合うアプリ名を10個提案してください：
- AI キャラクターと会話できる
- キャラをカスタマイズできる
- 日常の相棒
名前の重複チェックアプリ名がある程度決まったら、以下の点を確認します。

ここも Claude を使って調査を行います。

App Store / Google Play での重複: 同名のアプリが既に存在しないか検索

ドメイン取得可否: appname.com や appname.io が取得できるか確認

商標登録: 同様の名前で商標登録されていないか確認
!ポイント: 名前の由来や意味も一緒に提案してもらうと、ストア説明文やブランディングに活かせます。コンセプトが固まった後に名前を決めることで、アプリの本質を反映した命名ができます。

 アプリアイコン作成（ChatGPT + Canva）アプリアイコンは ChatGPT で背景透過の素材を生成し、Canva で仕上げています。

今後のカスタマイズ性などを考えると、メイン素材を背景透過で作成しておくのがベストです。
!なぜ ChatGPT なのか

Gemini なども試しましたが、アプリアイコンのメイン素材は背景透過した素材が欲しく、Gemini は背景透過画像の生成が苦手だったため、ChatGPT を採用しています。
なぜこの組み合わせか

ツール
得意なこと
苦手なこと


ChatGPT
0→1 のデザイン生成
細かい調整、複数サイズ書き出し

Canva
細かい調整、サイズ調整、書き出し
0→1 のデザイン生成

ワークフロー1. ChatGPT で背景透過の素材を生成
   ↓
2. 気に入った素材を Canva にインポート
   ↓
3. Canva でサイズ調整、背景色の微調整
   ↓
4. アプリストア用の各サイズに書き出し

 このフェーズの成果物

成果物
説明


product.md
製品ビジョン（目的、ペルソナ、機能、ビジネス目標）

アプリ名
ブランディングの軸

アプリアイコン
ストア用各サイズ

これらは次の「プロジェクト初期化」フェーズで配置・設定します。

 👤 人の判断ポイントこのフェーズで人が判断すべきポイント：


#
判断内容
詳細


1
対話形式での方向性確認
Claude からの選択式質問に回答し、分析の方向性を決定

2
product.md の内容確認
生成された製品ビジョンが意図通りか確認、必要に応じて修正

3
アプリ名・アイコンの最終確認
ブランディングの軸となるため慎重に


 参考リンクClaude.ai
Jobs to be Done（JTBD）フレームワーク
Canva

 フェーズ2：プロジェクト初期化（Project Setup）!目的: 開発基盤を整え、steeringでプロジェクト記憶を作る。

主な成果物: Flutter雛形 / .kiro/steering（tech.md / structure.md）

判断ポイント: tech.md / structure.md が実態と一致しているか

 はじめに企画が固まったら、ローカル環境でプロジェクトを作成します。このフェーズでは cc-sdd をセットアップし、企画情報をプロジェクトに統合します。
このフェーズのゴール:
Flutter プロジェクトの作成
cc-sdd のインストールと設定
ステアリング（開発方針）の配置と生成

 Flutter プロジェクト生成通常の flutter create コマンドでも良いですが、私は自作の GUI ツール「YokoFlu」を使っています。

このツールは Flutter アプリを作成する際に毎回実施する定型作業を自動化するために作成しました。
YokoFlu の機能:
アプリ名、Bundle ID、アプリアイコンなどを GUI で設定
設定内容から Flutter プロジェクトを自動生成
Firebase 設定なども CLI 経由で自動化
普段使うディレクトリ構成・ライブラリ構成を反映
詳しく知りたい方は下記を参照してください。
https://zenn.dev/yokkomystery/articles/c2bf78234efc65

 cc-sdd とはcc-sdd は、AWS の AI IDE「Kiro」が提唱する Spec-Driven Development（仕様駆動開発） のワークフローを Claude Code などのAIエージェントで実現するためのツールです。

仕駆動開発は実装前に要件・設計・実装計画をすべて承認し、手戻りを防止する開発手法です。
!Kiro とは: AWS が 2025 年に発表した AI ネイティブ IDE です。「仕様書 → 設計 → タスク → 実装」という構造化されたワークフローで、AI と人間が協調しながら開発を進められます。cc-sdd はこのワークフローを Claude Code に持ち込むことで、Kiro を使わなくても同様の開発体験を得られるようにしたものです。
なぜ cc-sdd を使うのか従来の AI コーディングでは「コードを書いて」と指示すると、AI が即座に実装を始めます。所謂バイブコーディングです。しかしこのアプローチには問題があります。


問題
詳細


要件の曖昧さ
何を作るか明確でないまま実装が始まる

設計の欠如
アーキテクチャを考慮せずにコードが生成される

手戻りの多さ
「思ってたのと違う」が頻発

コンテキストの分断
会話が長くなると AI が文脈を見失う

仕様駆動開発では 「仕様を先に固める」 アプローチでこれらを解決します。
cc-sdd の特徴

特徴
説明


3 フェーズ承認
要件 → 設計 → タスクの各段階で人間がレビュー

ステアリング
プロジェクトの「記憶」を保持し、AI が全体像を理解

サブエージェント
仕様策定・設計・実装を専門のエージェントが担当

TDD 実装
テストファーストで品質を担保

仕様の永続化

.kiro/specs/というディレクトリに仕様が残り、後から参照・修正可能

cc-sdd のインストールClaude Code のサブエージェント機能を活用した仕様駆動開発を行いたいため、下記コマンドで cc-sdd をインストールします。
npx cc-sdd@latest --claude-agent --lang ja


オプション
説明


--claude-agent
Claude Code 用の 12 コマンドと 9 サブエージェントを生成

--lang ja
日本語で仕様書を生成

利用可能なコマンドcc-sdd を --claude-agent オプションでインストールすると、12 個のスラッシュコマンドと9 つのサブエージェントが利用可能になります。

（--claude オプションの場合は 11 コマンドのみ）
作成されるファイル・ディレクトリ

作成されるもの
説明


.claude/agents/kiro/
サブエージェント定義（spec-design.md, spec-impl.md など）

.claude/commands/kiro/
スラッシュコマンド定義（/kiro:spec-* コマンド）

.kiro/settings/
ルールとテンプレート


CLAUDE.md への追記
AI 駆動開発ライフサイクル（AI-DLC）のセクションが追加される


 サブエージェントとはClaude Code は複雑なタスクを専門のサブエージェントに委譲できます。cc-sdd では、インストール時に以下の 9 つのサブエージェント が定義されます。
仕様策定系（Spec）

サブエージェント
役割


spec-requirements
EARS 記法で要件定義を生成

spec-design
技術設計書を生成

spec-tasks
実装タスクリストを生成

spec-impl
TDD で実装（テストファースト）

検証系（Validate）

サブエージェント
役割


validate-gap
要件と既存コードの差分分析

validate-design
設計の品質チェック（インタラクティブ）

validate-impl
実装が仕様を満たすか検証

ステアリング系（Steering）

サブエージェント
役割


steering

.kiro/steering/ の初期化・同期（プロジェクト記憶）

steering-custom
カスタムステアリング作成（独自の開発方針を追加）

!ステアリング系とは: steering はプロジェクトの「記憶」を管理するエージェントです。product.md、tech.md、structure.md などを生成・同期します。steering-custom は API 規約やテスト方針など、プロジェクト固有のルールを追加したいときに使います。

 product.md の配置企画フェーズで生成した product.md を .kiro/steering/ に配置します。
product.md の内容例（抜粋）※以下は抜粋です（主要セクションのみ）。
ドキュメント例#### Product Overview

**Sodalio** は、自分専用にカスタマイズした AI キャラクターとの対話を通じて日々の振り返り（セルフリフレクション）を行い、会話内容を要約・保存できるモバイルアプリです。

「日記を書きたいけど何を書けばいいかわからない」「一人で考えを整理するのが苦手」というユーザーに、AI キャラクターとの自然な会話で内省をサポートします。

#### Core Capabilities

- **カスタマイズ可能な AI キャラクター**: 見た目・口調を自分好みに設定
- **対話型セルフリフレクション**: 会話で自然に日々の出来事や感情を振り返る
- **会話要約・保存機能**: AI が要約しタイムラインに保存
- **クロスプラットフォーム**: iOS・Android 対応

（中略）

#### Target User

##### Primary Persona

- **年齢層**: 20〜35 歳の若年社会人・学生
- **特徴**: 自己成長への関心が高い、テクノロジーに親和性あり、日記を書きたいが続かない
- **ニーズ**: 気軽に内省したいが人に話すのは抵抗がある

#### Success Metrics

- **North Star Metric**: 週間アクティブ会話ユーザー数
- **Primary KPIs**: DAU/MAU、Day7 継続率、無料→有料転換率

（中略）
!ポイント: 企画で整理したペルソナ、市場調査の要点、収益戦略、ビジョンを product.md に含めることで、AI が仕様策定時に「なぜこの機能が必要か」「どこに向かっているか」を理解できます。

 tech.md と structure.md の生成product.md を配置したら、ローカルの Claude Code で /kiro:steering コマンドを実行します。
/kiro:steering
Sync Modeproduct.md が既に存在する場合、このコマンドは Sync Mode で動作し、コードベースを解析して以下を自動生成します。


ファイル
内容


tech.md
技術スタック、アーキテクチャパターン

structure.md
ディレクトリ構成、コーディング規約

tech.md の内容例ドキュメント例#### Technical Stack

#### Framework

- Flutter 3.x
- Dart 3.x

#### State Management

- Riverpod

#### Backend

- Firebase (Authentication, Firestore, Functions)
- Vertex AI

#### Architecture

- Repository Pattern
- Provider Pattern (via Riverpod)
structure.md の内容例ドキュメント例#### Project Structure

#### Directory Layout

lib/
├── screens/ # UI 画面
├── models/ # データモデル
├── services/ # ビジネスロジック
├── providers/ # Riverpod プロバイダー
├── widgets/ # 共通ウィジェット
└── utils/ # ユーティリティ

#### Coding Conventions

- ファイル名: snake_case
- クラス名: PascalCase
- 変数名: camelCase

 最終的なディレクトリ構成cc-sdd を使うと、仕様策定時に必要なディレクトリが自動で作成されます。
!モノレポ構造: このプロジェクトは Sodalio/（Flutter アプリ）と Sodalio-backend/（Firebase Functions）を含むモノレポ構成にしていす。cc-sdd 関連ファイルはルートに配置されます。
最終的には以下のような構成になります：
構成例your_project/                    # モノレポルート
├── .claude/                     # Claude Code 設定（cc-sdd自動生成）
│   ├── agents/                  # サブエージェント定義（9個）
│   │   └── kiro/
│   │       ├── spec-design.md
│   │       ├── spec-impl.md
│   │       ├── spec-requirements.md
│   │       ├── spec-tasks.md
│   │       ├── steering.md
│   │       ├── steering-custom.md
│   │       ├── validate-design.md
│   │       ├── validate-gap.md
│   │       └── validate-impl.md
│   ├── commands/                # スラッシュコマンド定義（12個）
│   │   └── kiro/
│   │       ├── spec-design.md
│   │       ├── spec-impl.md
│   │       ├── spec-init.md
│   │       ├── spec-quick.md
│   │       ├── spec-requirements.md
│   │       ├── spec-status.md
│   │       ├── spec-tasks.md
│   │       ├── steering.md
│   │       ├── steering-custom.md
│   │       ├── validate-design.md
│   │       ├── validate-gap.md
│   │       └── validate-impl.md
│   └── settings.local.json      # ローカル設定
├── .kiro/
│   ├── steering/                # プロジェクト全体の方針（Project Memory）
│   │   ├── product.md           # 製品ビジョン・ペルソナ・収益戦略
│   │   ├── tech.md              # 技術スタック・アーキテクチャ
│   │   └── structure.md         # ディレクトリ構成・コーディング規約
│   ├── specs/                   # 機能ごとの仕様（cc-sdd自動生成）
│   │   └── {feature-name}/
│   │       ├── requirements.md  # 要件定義
│   │       ├── design.md        # 技術設計書
│   │       └── tasks.md         # 実装タスクリスト
│   └── settings/                # ルールとテンプレート
│       ├── rules/               # 仕様策定ルール
│       └── templates/           # テンプレート
├── CLAUDE.md                    # プロジェクトの憲法
├── Sodalio/                     # Flutterアプリ
│   ├── lib/                     # ソースコード
│   └── test/                    # テストコード
└── Sodalio-backend/             # Firebase Functions

 .kiro/ 配下の役割

ディレクトリ
役割
作成タイミング


steering/
開発方針 + 企画情報（なぜ・どう作るか）
企画: product.md（Claude.ai）、初期化: tech.md, structure.md（ローカル）

specs/
機能仕様（何を作るか）
開発フェーズで自動生成

steering（ステアリング）とはステアリングは「プロジェクトの記憶」として機能します。

product.md: なぜこのアプリを作るのか（企画意図）

tech.md: どんな技術で作るのか（技術スタック）

structure.md: どう構成するのか（ディレクトリ、規約）
これにより AI は「全体像を理解した上で」仕様策定・実装ができます。
specs（仕様）とはspecs は機能ごとの詳細仕様を保存します：
構成例.kiro/specs/
├── user-authentication/
│   ├── requirements.md   # 認証機能の要件
│   ├── design.md         # 認証機能の設計
│   └── tasks.md          # 認証機能の実装タスク
├── character-chat/
│   ├── requirements.md
│   ├── design.md
│   └── tasks.md
└── ai-image-generation/
    ├── requirements.md
    ├── design.md
    └── tasks.md

 CLAUDE.md についてCLAUDE.md はプロジェクトの「憲法」として機能します。cc-sdd インストール時に AI-DLC セクションが追記されます。
追記される内容ドキュメント例#### AI-DLC and Spec-Driven Development

Kiro-style Spec Driven Development implementation on AI-DLC (AI Development Life Cycle)

#### Project Context

##### Paths

- Steering: `.kiro/steering/`
- Specs: `.kiro/specs/`

##### Steering vs Specification

**Steering** (`.kiro/steering/`) - Guide AI with project-wide rules and context
**Specs** (`.kiro/specs/`) - Formalize development process for individual features

##### Active Specifications

- Check `.kiro/specs/` for active specifications
- Use `/kiro:spec-status [feature-name]` to check progress

#### Development Guidelines

- 回答は日本語で行う。requirements.md、design.md、tasks.md、research.md、validation reports などの仕様関連 Markdown は spec.json.language に従う。

#### Minimal Workflow

- Phase 0 (optional): `/kiro:steering`, `/kiro:steering-custom`
- Phase 1 (Specification):
  - `/kiro:spec-init "description"`
  - `/kiro:spec-requirements {feature}`
  - `/kiro:validate-gap {feature}` (optional: for existing codebase)
  - `/kiro:spec-design {feature} [-y]`
  - `/kiro:validate-design {feature}` (optional: design review)
  - `/kiro:spec-tasks {feature} [-y]`
- Phase 2 (Implementation): `/kiro:spec-impl {feature} [tasks]`
  - `/kiro:validate-impl {feature}` (optional: after implementation)
- Progress check: `/kiro:spec-status {feature}` (use anytime)

#### Development Rules

- 3-phase approval workflow: Requirements → Design → Tasks → Implementation
- Human review required each phase; use `-y` only for intentional fast-track
- Keep steering current and verify alignment with `/kiro:spec-status`
- Follow the user's instructions precisely, and within that scope act autonomously: gather the necessary context and complete the requested work end-to-end in this run, asking questions only when essential information is missing or the instructions are critically ambiguous.

#### Steering Configuration

- Load entire `.kiro/steering/` as project memory
- Default files: `product.md`, `tech.md`, `structure.md`
- Custom files are supported (managed via `/kiro:steering-custom`)
これにより Claude Code がプロジェクトの開発フローを理解できます。

 このフェーズの成果物

成果物
説明


Flutter プロジェクト
基本的なプロジェクト構造

.claude/
サブエージェント、コマンド定義

.kiro/steering/
product.md, tech.md, structure.md

CLAUDE.md
AI-DLC セクション追記済み


 👤 人の判断ポイントこのフェーズで人が判断すべきポイント：


#
判断内容
詳細


1
ステアリングの最終確認
tech.md, structure.md が実態と合っているか


 参考リンクcc-sdd（Spec-Driven Development）
Kiro の仕様書駆動開発プロセスを Claude Code で徹底的に再現した
Claude Code サブエージェント

 フェーズ3：cc-sdd 開発（Spec-Driven Development）!目的: 要件→設計→タスク→実装を順に固め、品質を担保する。

主な成果物: requirements.md / design.md / tasks.md / 実装コード

判断ポイント: 要件・設計・タスクの承認

 はじめに開発フェーズでは、仕様駆動開発（Spec-Driven Development） という手法を使います。これは「仕様を策定してから実装する」アプローチで、3 段階の承認プロセスを経て品質を担保します。
このフェーズのゴール:
要件定義 → 技術設計 → タスク生成 → TDD 実装の流れを理解
各段階での人の判断ポイントを明確化
実際の機能追加を通じたワークフローの習得

 cc-sdd とはcc-sdd は「仕様駆動開発」のフレームワークです。
核心：各段階で人が「OK」を出さないと次に進めないこれにより
無駄な実装を防げる
設計段階で問題を発見できる
AI の暴走を防げる

 利用可能なコマンドcc-sdd をインストールすると、12 個のスラッシュコマンドが利用可能になります。
仕様策定コマンド（Spec）

コマンド
役割


/kiro:spec-init
仕様ディレクトリ作成

/kiro:spec-requirements
EARS 記法で要件定義

/kiro:spec-design
技術設計書生成

/kiro:spec-tasks
実装タスクリスト生成

/kiro:spec-impl
TDD で実装

/kiro:spec-status
進捗確認

/kiro:spec-quick
クイック仕様生成（対話なしで一気に生成）

検証コマンド（Validate）

コマンド
用途
使いどころ


/kiro:validate-gap
要件と既存コードの差分分析
既存アプリへの機能追加

/kiro:validate-design
設計の品質チェック
複雑な機能の設計レビュー

/kiro:validate-impl
実装が仕様を満たすか検証
実装完了後の最終確認

ステアリングコマンド（Steering）

コマンド
用途


/kiro:steering
ステアリングの初期化・同期

/kiro:steering-custom
カスタムステアリング作成（独自ルール）

!ステアリングコマンドの使い分け: /kiro:steering は product.md、tech.md、structure.md などコアファイルの管理に使います。/kiro:steering-custom は API 規約やテスト方針など、プロジェクト固有のルールを追加したいときに使います。

 実践：カスタムキャラクター画像の自動生成機能ここからは cc-sdd を用いた実際の機能追加の流れを記載していきます。
追加する機能今回追加する機能は AI のカスタムキャラクター作成時に、入力した設定内容（名前・性格・口調など）をもとに AI がアバター画像を自動生成する機能です。
↓ この画面に生成ボタンを配置し、キャラクター画像を自動生成するようにする。

↓ 機能追加後のイメージ


 Step 1: 仕様初期化/kiro:spec-init カスタムキャラクター作成時に設定内容からAIでキャラクターの画像を自動生成する機能を作成する
実行結果.kiro/specs/ai-character-image-generation/ ディレクトリが作成され、spec.json と初期の requirements.md が生成されます。
.kiro/specs/
└── ai-character-image-generation/
    ├── spec.json        ← フェーズと承認状態を管理
    └── requirements.md  ← 初期の要件（簡潔な内容）
spec.json によるフェーズ管理spec.json は仕様の進捗と承認状態を管理するファイルです。

要件定義 → 技術設計 → タスク生成の各フェーズで approved: true になると次のフェーズに進めます。

前のフェーズが承認されていない場合は cc-sdd はコマンドを打っても実行を拒否します。

全ての承認が完了すると ready_for_implementation: true となり、/kiro:spec-impl で TDD 実装を開始できます。


フィールド
説明


phase
現在のフェーズ（initialized → requirements → design → tasks）

approvals.*.generated
ドキュメントが生成されたか

approvals.*.approved
人が承認したか

ready_for_implementation
全承認後に true になり、実装可能になる


 Step 2: 要件定義/kiro:spec-requirements ai-character-image-generation
EARS（Easy Approach to Requirements Syntax） 記法で要件が生成されます。


パターン
構文
例


普遍的
The [system] shall [action]
The system shall display error messages in red

イベント駆動
When [event], the [system] shall [action]
When user taps generate, the system shall call AI API

状態依存
While [state], the [system] shall [action]
While generating, the system shall show progress

オプション
Where [condition], the [system] shall [action]
Where premium user, the system shall allow unlimited

生成される requirements.md の例以下は実際のプロジェクトで生成された requirements.md の抜粋です。
ドキュメント例#### Requirements Document

#### Introduction

本ドキュメントは、Sodalio アプリにおける「AI キャラクター画像自動生成機能」の要件を定義する。

#### Requirements

##### Requirement 1: AI 画像生成の起動

**Objective:** As a ユーザー, I want カスタムキャラクター作成画面で AI 画像生成を起動できること, so that 手動で画像を用意しなくてもキャラクター画像を作成できる

###### Acceptance Criteria

1. When ユーザーがカスタムキャラクター編集画面で AI 画像生成ボタンをタップする, the アプリ shall AI 画像生成フローを開始する
2. While AI 画像生成に必要な設定項目が未入力である, the アプリ shall 生成ボタンを無効化し、必要項目を示すツールチップを表示する
3. When AI 画像生成ボタンが有効な状態でタップされる, the アプリ shall 現在の設定内容から画像生成用プロンプトを構築する

##### Requirement 3: 画像スタイル選択

**Objective:** As a ユーザー, I want 生成する画像のスタイルを選択できること, so that 自分の好みに合ったキャラクター画像を作成できる

###### Acceptance Criteria

1. When AI 画像生成フローが開始される, the アプリ shall 画像スタイル選択 UI を表示する
2. The アプリ shall 既存の ImageStyle から選択可能なスタイル（アニメ、写実、ピクセルアート等）を提供する
3. When ユーザーがスタイルを選択する, the アプリ shall 選択されたスタイルをプロンプトに適用する

##### Requirement 7: 使用制限とクォータ管理

**Objective:** As a システム, I want AI 画像生成の使用回数を管理すること, so that サービスコストを適切に管理できる

###### Acceptance Criteria

1. The アプリ shall ユーザーのサブスクリプションレベルに応じた画像生成回数制限を適用する
2. When ユーザーが画像生成制限に達している, the アプリ shall 制限到達メッセージを表示し、プレミアムアップグレードを案内する
3. While 無料ユーザーの場合, the アプリ shall 画像生成機能をプレミアム限定機能として表示する
!実際の requirements.md: 完全版は .kiro/specs/ai-character-image-generation/requirements.md に 10 個の Requirement として定義されています。各 Requirement には Objective（User Story 形式）と Acceptance Criteria（EARS 記法）が含まれます。
!👤 人の判断ポイント

要件に漏れがないか、既存機能との整合性があるかを確認して承認します。
確認観点：
機能要件の網羅性
非機能要件（性能、セキュリティ）
既存機能との整合性
受け入れ基準の妥当性

 Step 3: 技術設計要件が承認されたら、技術設計に進みます。
/kiro:spec-design ai-character-image-generation
生成される design.md の例ドキュメント例#### 技術設計書

#### 概要

**目的**: カスタムキャラクター作成時にユーザーが入力した設定内容から
AI 画像を自動生成し、手動での画像選択を不要にする。

**影響**: 既存の CustomCharacterEditorScreen に AI 画像生成ボタンを追加し、
既存の generateImage Cloud Function および ImageStyle enum を再利用する拡張実装。

#### アーキテクチャ

┌─────────────────┐
│ CustomCharacter │
│ EditorScreen │──┬─▶ ImageStyleSelectorDialog
└──────────────────────┘  
│ └─▶ ImagePreviewDialog
▼
┌──────────────────────┐
│ CharacterPrompt │
│ Builder         │
└─────────────────┘
│
▼
┌───────────────────────────────────────┐
│ AIService │───▶│ Cloud Function │
│ (既存) 　 │ │ (generateImage)       │
└───────────────────────────────────────┘
│
▼
┌──────────────────┐
│ Vertex AI Gemini │
└──────────────────┘

#### コンポーネント

| コンポーネント 　        | 役割 　　　　                      |
| ------------------------ | ---------------------------------- |
| CharacterPromptBuilder   | キャラクター属性からプロンプト構築 |
| ImageStyleSelectorDialog | 画像スタイル選択 UI                |
| ImagePreviewDialog       | 生成画像のプレビュー・採用・再生成 |
| AIService（既存） 　     | Cloud Function 呼び出し            |
| FirestoreService（既存） | 画像圧縮・Storage 保存             |

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

| エラー                    | 対応 　                                |
| ------------------------- | -------------------------------------- |
| クォータ超過              | 制限到達メッセージ + プレミアム案内 　 |
| コンテンツポリシー違反 　 | プロンプト修正を促すメッセージ         |
| タイムアウト              | 再試行オプション表示 　                |
| ネットワークエラー        | リトライボタン表示                     |
!実際の design.md: 完全版には Mermaid 図、要件トレーサビリティ表、インターフェース定義（Dart コード）、テスト戦略、多言語対応キー一覧なども含まれます。
!👤 人の判断ポイント

既存の Service/Provider との整合性、パフォーマンスへの影響を確認します。
確認観点：
アーキテクチャの一貫性
既存コンポーネントとの統合（AIService、FirestoreService）
エラーハンドリングの網羅性
パフォーマンスへの影響

 Step 4: タスク生成設計が承認されたら、実装タスクを生成します。
/kiro:spec-tasks ai-character-image-generation
生成される tasks.md の例ドキュメント例#### Implementation Plan

#### Tasks

- [ ] 1. プロンプト構築ユーティリティの実装

  - [ ] 1.1 キャラクター属性からプロンプトを構築するクラス作成
  - [ ] 1.2 プロンプト構築ロジックのユニットテスト
  - _Requirements: 2.1, 2.2, 2.3, 2.4, 2.5_

- [ ] 2. 画像スタイル選択ダイアログの実装

  - [ ] 2.1 スタイル選択 UI をガラス風デザインで構築
  - _Requirements: 3.1, 3.2, 3.3, 3.4_

- [ ] 3. 画像プレビューダイアログの実装

  - [ ] 3.1 生成画像のプレビュー表示と操作 UI を構築
  - _Requirements: 5.1, 5.2, 5.3, 5.4_

- [ ] 4. 多言語対応のローカライゼーション追加

  - [ ] 4.1 AI 画像生成機能の UI 文字列を 16 言語でローカライズ
  - _Requirements: 10.1, 10.2_

- [ ] 5. キャラクター編集画面への AI 画像生成機能統合

  - [ ] 5.1 AI 画像生成ボタンを編集画面に追加
  - [ ] 5.2 AI 画像生成フローの実装
  - [ ] 5.3 生成画像の採用・保存処理を実装
  - [ ] 5.4 再生成機能の実装
  - _Requirements: 1.1, 1.2, 1.3, 6.1, 6.2, 6.3, 8.1, 8.4_

- [ ] 6. エラーハンドリングとクォータ管理の実装

  - [ ] 6.1 画像生成エラーの処理とユーザーフィードバック
  - _Requirements: 7.1, 7.2, 9.1, 9.2, 9.3, 9.4_

- [ ] 7. 統合テストの実装
  - [ ] 7.1 AI 画像生成フロー全体の統合テスト
  - [ ] 7.2 エラーケースとクォータ制限の統合テスト
  - _Requirements: 全要件_
!ポイント: 各タスクには _Requirements:_ で対応する要件番号が紐付けられます。これにより「どの要件を満たすための実装か」が明確になり、トレーサビリティが確保されます。
!👤 人の判断ポイント

タスクの粒度が適切か、漏れがないかを確認します。
確認観点：
タスクの粒度（大きすぎ/小さすぎ）
依存関係の順序
テストタスクの有無

 Step 4.5: 設計検証（オプション）複雑な機能や既存コードへの影響が大きい場合、設計を検証できます。
#### 設計の品質チェック（対話形式）
/kiro:validate-design ai-character-image-generation
validate-gap について既存コードベースがある場合、/kiro:validate-gap で要件と既存実装の差分を分析できます。
/kiro:validate-gap ai-character-image-generation
これにより：
既存コードで再利用できる部分
新規に実装が必要な部分
既存コードへの影響範囲
が明確になります。
タスクまでを承認すると"ready_for_implementation"が true になり、実装着手可能になります。


 Step 5: TDD 実装実装準備ができたので、テスト駆動開発（TDD） で実装していきます。
/kiro:spec-impl ai-character-image-generation
TDD サイクルcc-sdd では、以下の TDD サイクルを厳密に守りながら実装を進めていきます。
AI の実装フローAI が各タスクについて以下を繰り返します。

テスト作成（期待する入出力に基づく）

テスト実行（失敗することを確認 → テストが正しい証拠）

最小限の実装（テストを通すためだけのコード）

リファクタ（テストを壊さずに改善）
実装が完了していくと、順次 Tasks のチェックボックスにチェックがついていきます。

重要なルール!重要: 実装中にテストを変更するのは NG です。テストは「仕様書」であり、実装の都合で変えてはいけません。テストが通らない場合は実装を修正します。

 Step 6: 実装検証（オプション）実装が完了したら、仕様を満たしているか検証できます。
/kiro:validate-impl ai-character-image-generation
検証内容要件（requirements.md）を全て満たしているか
設計（design.md）に従っているか
タスク（tasks.md）を全て完了しているか
テストが全てパスするか

 進捗確認いつでも進捗を確認できます。
/kiro:spec-status ai-character-image-generation
出力例#### ai-character-image-generation

| Phase | Status | File |
|-------|--------|------|
| Requirements | ✅ Approved | requirements.md |
| Design | ✅ Approved | design.md |
| Tasks | ✅ Approved | tasks.md |
| Implementation | 🔄 In Progress | 3/5 tasks |
全てのタスクが完了するとこのように結果が表示されます。


 👤 人の判断ポイント（まとめ）

#
判断内容
タイミング


1
要件定義の承認

/kiro:spec-requirements 後

2
技術設計の承認

/kiro:spec-design 後

3
実装タスクの承認

/kiro:spec-tasks 後


 参考リンクcc-sdd（Spec-Driven Development）
EARS 記法（要件定義）
Kiro の仕様書駆動開発プロセスを Claude Code で徹底的に再現した

 フェーズ4：コードレビュー（Code Review）!目的: ローカルとPR後のGitHub上でのレビューで品質を二重チェックする。

主な成果物: レビュー指摘 / 修正コミット / PR

判断ポイント: 指摘の妥当性とマージ可否

 はじめにTDD 実装が完了したら、コードレビューを行います。このフェーズでは PR 作成前のローカルレビュー と PR 後の GitHub上でのAI レビュー を組み合わせて、多層的なレビュー体制を構築します。
このフェーズのゴール:
ローカルでの AI コードレビューの実行
複数の AI レビューツールの使い分け
レビュー指摘の効率的な修正

 使用するツールの説明Claude Code（ローカル）ターミナルから直接 Claude と対話し、コードの読み書き、実行、レビューができます。
特徴:
ローカルのファイルシステムにアクセス可能
カスタムスキル（~/.claude/commands/）を定義可能
📖 詳細: Claude Code ドキュメント
Claude Code Action（GitHub）Claude Code Action は GitHub Actions として動作し、Issue/PR で @claude とメンションすることで Claude を呼び出せます。
特徴:
GitHub 上で @claude と書くだけで起動
リポジトリのコードベースを理解した上で回答
PR のレビュー、Issue の分析、コード修正が可能
📖 詳細: Claude Code Action 公式リポジトリ
Codex（GitHub App）Codex は OpenAI が提供する AIエージェントで GitHub App で、PR の差分を自動でレビューします。
特徴:
PR 作成時に自動でレビューコメント
実装の妥当性、抜け漏れの指摘
Claude とは異なる観点でのチェック
📖 詳細: Codex GitHub App
BugBot（Cursor）BugBot は Cursor 製の AI レビューツールで、バグやセキュリティ問題の検出に特化しています。
特徴:
バグ・セキュリティに特化
「Fix in Cursor」ボタンで即修正可能
Cursor IDE との連携
📖 詳細: Cursor Bugbot

 レビューの全体像
 ローカルコードレビュー（PR 作成前）なぜローカルでレビューするのか
早期発見: PR を出す前に問題を発見・修正できる

効率化: PR 後のレビュー指摘を減らせる

品質向上: Critical な問題を事前に潰せる
カスタムスキルの作成コードレビュー用のカスタムスキルを作成しておくと便利です。
コマンド定義（スキルのトリガー）：
~/.claude/commands/code-quality/code-reviewer.md
---
agent: code-reviewer
description: Automated Flutter/Dart code review
---

Review code changes for best practices, security, performance, and maintainability with detailed feedback.
エージェント定義（レビューの実行方法）：
定義例~/.claude/agents/code-quality/code-reviewer.md
---
name: code-reviewer
description: Automated code review agent for Flutter/Dart projects
model: sonnet
color: blue
---

You are an expert Flutter/Dart code reviewer with deep knowledge of
best practices, security, performance, and maintainability.

#### Review Dimensions
1. Functionality & Correctness ✅
2. Performance ⚡
3. Security 🔒
4. Maintainability 🛠️
5. Flutter Best Practices 📱
6. Riverpod Specific 🔄
7. Code Style 🎨
8. Testing 🧪

#### Categorize Findings
- Critical (🔴 Must Fix): セキュリティ脆弱性、機能バグ、メモリリーク
- Important (🟡 Should Fix): パフォーマンス問題、テスト不足
- Minor (🔵 Consider): スタイル改善、リファクタリング提案
- Positive (✅ Great!): 良いパターン、よくテストされたコード
レビューの実行/code-quality:code-reviewer
このスキルを呼び出すと、master ブランチとの差分を自動で検出し、以下の観点でレビューします：
バグ・ロジックエラー
セキュリティ脆弱性
パフォーマンス問題
コード品質・可読性
Flutter/Dart ベストプラクティス
Riverpod の適切な使用
プロジェクト規約（CLAUDE.md）への準拠
また、セキュリティ観点でレビューしたい場合は下記のコマンドでレビューしてもらうことも可能です。
/security-review  

 レビュー結果の例実際のレビュー結果では、問題を重要度別に分類して報告されます：
#### 【Critical】重大な問題

##### 1. メモリリークの可能性 - `_acceptGeneratedImage`メソッド (信頼度: 95)

**問題点:** 非同期処理中に dispose される可能性があるが、setState の前に mounted チェックがない

**改善提案:**

```dart
if (mounted) {
  setState(() {
    _pickedImage = Uint8List.fromList(imageBytes);
  });
}
```

 指摘事項の修正レビューで指摘された問題を修正します。Claude Code に「修正をお願いします」と伝えると、自動で修正を行います。
修正後のテスト実行修正が完了したら、テストを再実行して問題がないことを確認します。
flutter test

 PR 作成（@claude によるタイトル・説明文自動生成）ローカルレビューが完了したら、PR を作成します。このとき @claude を使って PR のタイトルと説明文を自動生成できます。
ワークフローフロー例ローカルレビュー完了
    │
    ▼
git push（ブランチをリモートに push）
    │
    ▼
PR を Draft で作成
    │
    ▼
@claude にタイトル・説明文の生成を依頼
    │
    ▼
生成された内容を確認・微調整
    │
    ▼
PR を Ready for Review に変更
@claude への依頼例PR の Draft を作成したら、コメントで以下のように依頼します：
@claude この PR のタイトルと説明文を作成してください。
!ポイント

Draft PR で @claude を呼び出すことで、コードの差分を理解した上で適切なタイトル・説明文を生成してくれます。手動で書くよりも網羅的で、レビュアーにとって分かりやすい PR になります。

 PR 後の AI レビューツールの使い分け

ツール
得意分野
特徴


Claude Code Action
設計・ロジック・アーキテクチャ
俯瞰的なレビュー

Codex
実装の妥当性・抜け漏れ確認
追加の観点チェック

BugBot
バグ・セキュリティ
「Fix in Cursor」ボタンで即修正可能

Claude Code ActionClaude Code Action は 2 つのトリガー で起動できます：
PR 作成時（自動）
PR での @claude メンション（手動）
なぜ @claude で Claude のワークフローを起動できるのか.github/workflows/claude.yml で @claude メンションを検知するように設定されているためです。GitHub Webhook がコメントイベントを検知し、Claude Code Action ワークフローが起動します。
コード例on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    # ...
@claude メンションの活用例「@claude PR のタイトルと説明文を作成して」
「@claude この変更でメモリリークの可能性はある？」
「@claude このロジックをもっとシンプルに書ける？」
「@claude Riverpod の使い方これで合ってる？」
「@claude BugBot/Codex の指摘を Issue 化して、修正 PR を作って」
Fix ボタンでの修正Claude からのレビューはコメント内に出る [Fix this →]ボタンをタップすることでそのまま修正して PR を出すことが可能です。
CodexCodex（OpenAI 製の GitHub App）でも PR 差分をレビューします。Claude とは異なるモデルのため、別の観点からの指摘が得られます。
特徴:
PR 作成時に自動でコメント
実装の妥当性・抜け漏れを指摘
Claude とは異なる視点でのダブルチェック
BugBotBugBot は Cursor 製の AI レビューツールで、バグやセキュリティ問題の検出に特化しています。
特徴:
バグ・セキュリティに特化
「Fix in Cursor」ボタンで即修正可能
Cursor IDE との連携

 レビュー指摘への対応フローフロー例指摘を受ける
    │
    ▼
重要度を確認
    │
    ├─ Critical/Important → すぐに修正
    │
    └─ Minor → 以下のいずれか
         │
         ├─ すぐに修正（簡単な場合）
         │
         └─ @claude で Issue 化 + 修正 PR 作成を依頼
!ポイント

レビュー指摘については重要なものはすぐに修正し、軽微なものは @claude で Issue 化と修正 PR 作成を依頼することが多いです（BugBot/Codex の指摘も同様）。

 👤 人の判断ポイント

#
判断内容
タイミング


1
ローカルレビューの指摘確認
TDD 実装完了後、PR 作成前

2
PR のマージ
AI レビュー通過後


 参考リンクClaude Code Action
Codex GitHub App
BugBot（Cursor）
Claude Code カスタムスキル

 フェーズ5：E2E & Visual Regression!目的: UIの操作と見た目をE2E/VRTで保証する。

主な成果物: Maestroフロー / ベースライン画像 / レポート

判断ポイント: 差分が意図した変更かどうか

 はじめにリリースをする前に単体テストに加えて、E2E テストと Visual Regression Testing で品質を担保します。
このフェーズのゴール:
Maestro による E2E テストの作成と実行
Visual Regression Testing によるスクリーンショット差分検出
テスト失敗時のデバッグ方法の習得

 E2E テスト（Maestro）Maestro とはMaestro は宣言的な YAML 形式でモバイルアプリの E2E テストを記述できるツールです。
特徴:
YAML で直感的に記述
iOS / Android 両対応
スクリーンショット取得
待機処理の柔軟な制御
📖 公式ドキュメント: Maestro
!cc-sdd と E2E の関係

E2E テストは cc-sdd のフロー（要件 → 設計 → タスク → TDD 実装）とは 別フロー で実行するようにしています。TDD はユニット/統合テスト向きですが、E2E は UI が完成してから書く方が効率的だからです。
ただし、requirements.md の受け入れ基準を E2E シナリオのインプットにすることで、仕様との紐付けを維持します。

 E2E テストの自動生成私は requirements.md から E2E テストを生成する Claude Code カスタムコマンド を作成しています。
!カスタムコマンドとは

Claude Code では ~/.claude/commands/ にコマンド定義ファイルを配置することで、独自のコマンド（スキル）を追加できます。/e2e:create はこの仕組みを使って作成した私のカスタムコマンドです。
#### 機能のE2Eテストを生成（カスタムコマンド）
/e2e:create {feature-name}

#### 例: AI画像生成機能のE2E
/e2e:create ai-image-generation
このコマンドは .kiro/specs/{feature}/requirements.md を読み込み、受け入れ基準に基づいた Maestro YAML を自動生成するように作成しています。

 E2E テストの構造E2E テストは 1 ファイルで完結 するように設計します。未ログイン状態でも自動でログイン処理を行う runFlow を活用します。
実際のテスト例以下は実際のプロジェクトで使用している AI キャラクター画像生成の E2E テストです：
コード例Sodalio/maestro/flows/ai-character-image-generation.yaml
#### AIキャラクター画像生成 E2E Test
#### カスタムキャラクター作成時のAI画像生成機能をテスト
#
#### Prerequisites:
#### - ログイン済み（未ログインの場合は自動ログイン）
#### - プレミアムプラン（手動で設定済みと仮定）
#
#### Test Coverage:
#### - Req 1: AI画像生成の起動（必須フィールド入力後にボタン有効化）
#### - Req 3: 画像スタイル選択
#### - Req 5: 生成画像のプレビューと確認

appId: com.mysterylog.sodalio.staging
---
#### ===== Launch App =====
- launchApp

#### ===== Setup: Login =====
- runFlow: setup/login-if-needed.yaml

#### ===== Initial State =====
- extendedWaitUntil:
    visible: "記録|カレンダー|マイページ|設定"
    timeout: 15000
- takeScreenshot: "01_home_screen"

#### ===== Navigate to Settings =====
- tapOn: "設定"
- waitForAnimationToEnd
- tapOn:
    text: "後で|Later|閉じる|Close"
    optional: true
- waitForAnimationToEnd
- takeScreenshot: "02_settings_screen"

#### ===== Navigate to Custom Character Editor =====
- tapOn:
    text: "カスタムキャラクターを作成"
- waitForAnimationToEnd
- takeScreenshot: "04_character_editor_empty"

#### ===== Fill Required Fields =====
- tapOn:
    text: "名前"
- inputText: "テストキャラ太郎"
- hideKeyboard

- tapOn:
    text: "説明"
- inputText: "白い毛並みと青い目を持つ猫のキャラクター"
- hideKeyboard

- tapOn:
    text: "性格"
- inputText: "優しくて穏やか"
- hideKeyboard

- tapOn:
    text: "種別/タイプ"
- inputText: "白い猫"
- hideKeyboard
- takeScreenshot: "05_character_editor_filled"

#### ===== Trigger AI Image Generation =====
- tapOn:
    text: "AIで生成"
- waitForAnimationToEnd

#### ===== Image Style Selection =====
- extendedWaitUntil:
    visible: "スタイルの選択|アニメ/イラスト|生成する"
    timeout: 15000
- takeScreenshot: "07_style_selection_dialog"

- tapOn:
    text: "生成する"
- waitForAnimationToEnd

#### ===== Wait for Generation & Preview =====
- extendedWaitUntil:
    visible: "採用する|再生成"
    timeout: 120000
- takeScreenshot: "09_preview_dialog"

#### ===== Accept Generated Image =====
- tapOn:
    text: "採用する"
- waitForAnimationToEnd
- takeScreenshot: "11_editor_with_image"

#### ===== Final Verification =====
- assertVisible: "画像を選択|AIで生成|保存"

 E2E テストの重要なパターン

パターン
用途
例


runFlow: setup/login-if-needed.yaml
ログイン処理を共通化
全テストの先頭で使用

optional: true
条件付き実行
タイミングや条件次第でダイアログが出るかもしれない箇所

visible: "A|B|C"
正規表現マッチ
複数パターンを許容

extendedWaitUntil
タイムアウト付き待機
非同期処理の完了待ち

スクリーンショット命名規則!ポイント

takeScreenshot コマンドで意味のある名前をつけることで、後述の Visual Regression Testing でベースラインとの比較が容易になります。スクリーンショット名は {NN}_{screen_name} 形式（例: 01_home_screen）で統一するようにしています。

 E2E テスト失敗時のデバッグテストが失敗した場合、ClaudeがMaestro が保存するスクリーンショットを適宜確認して自動修正します。
デバッグの流れコード例#### 1. テスト実行（失敗）
maestro test maestro/flows/ai-image-generation.yaml

#### 2. スクリーンショットを確認
#### 結果は ~/.maestro/tests/{timestamp}/ に保存される
open ~/.maestro/tests/  # 最新のディレクトリを開く

#### 3. 失敗時のスクリーンショット（❌マーク付き）で実際のUIを確認

#### 4. テストのセレクタを修正して再実行
Claude Code でのデバッグClaude Code を使えば、スクリーンショットを見せて「この UI に合わせてテストを修正して」と指示するだけで、AI が自動でセレクタを修正してくれます。

 Visual Regression TestingE2E テストで撮影したスクリーンショットを、ベースラインと比較して UI の意図しない変更を検出します。
なお、ここで使うvisual-regression.sh は 独自のカスタムスクリプトです（Maestro 標準の機能ではありません）。
Visual Regression の仕組み処理内容
run 実行時は Maestro を --test-output-dir で走らせ、maestro/screenshots に保存
比較は maestro/screenshots または最新の ~/.maestro/tests を参照
ImageMagick で差分ピクセル数を算出（THRESHOLD のデフォルトは 0.1 = 10%）
ステータスバー/ホームインジケーターをクロップして誤検出を軽減（CROP_TOP / CROP_BOTTOM）
差分画像と HTML レポートを maestro/diff-results/{year}/{timestamp} に出力
差分が検出された場合、意図した変更かバグかを判断します。


状況
対応



意図的な UI 変更（仕様変更）

save-baseline {flow} でベースラインを更新


意図しない UI 変更（バグ）
コードを修正してベースラインに合わせる

!👤 人の判断ポイント

Visual Regression の差分が検出された場合、それが意図した変更かバグかを判断します。意図した変更ならベースラインを更新し、バグならコードを修正します。

 ディレクトリ構成!モノレポ構造: maestro ディレクトリは Flutter アプリ配下（Sodalio/maestro/）に配置するようにしています。
構成例Sodalio/maestro/
├── config.yaml               # Maestro設定
├── flows/                    # E2Eテストシナリオ
│   ├── setup/
│   │   ├── login-if-needed.yaml
│   │   ├── full-reset.yaml
│   │   └── set-plan-*.yaml   # プラン別セットアップ
│   ├── suites/               # テストスイート
│   │   ├── suite-all-plans.yaml
│   │   ├── suite-free.yaml
│   │   └── suite-standard.yaml
│   ├── tests/                # プラン別テスト
│   │   ├── plan-free/
│   │   ├── plan-light/
│   │   └── plan-standard/
│   ├── ai-character-image-generation.yaml
│   ├── ai-chat.yaml
│   ├── calendar.yaml
│   └── ...
├── baseline/                 # ベースライン画像
│   └── {flow-name}/
│       ├── 01_home_screen.png
│       └── ...
└── reports/                  # テストレポート

 テスト実行コマンドコード例#### Sodalioディレクトリに移動
cd Sodalio

#### 単一テスト実行
maestro test maestro/flows/ai-character-image-generation.yaml

#### スイート実行（全プラン）
maestro test maestro/flows/suites/suite-all-plans.yaml

#### プラン別テスト実行
maestro test maestro/flows/suites/suite-free.yaml
maestro test maestro/flows/suites/suite-standard.yaml

#### Visual Regression 実行（テスト→比較→レポート生成）
./maestro/scripts/visual-regression.sh run ai-character-image-generation

#### ベースライン更新
./maestro/scripts/visual-regression.sh save-baseline ai-character-image-generation
Visual Regression スクリプトの説明詳細は割愛しますが、maestro/scripts/visual-regression.sh は複数のサブコマンドを持つスクリプトとして作成しています。
主なサブコマンド

コマンド
説明


run [flow]
テスト実行 → 比較 → レポート生成を一括実行

save-baseline
現在のスクリーンショットをベースラインとして保存

compare [flow]
既存のテスト結果とベースラインを比較

report [flow]
HTML レポートを生成

list
利用可能なフローとベースライン状態を表示

cleanup
古いテスト結果を削除（既定は最新5件を保持）

下記は定義しているコマンドの内容抜粋です。

run コマンドE2E テストを実行し、スクリーンショット比較とレポート生成まで行うメインコマンドです。
処理内容:

maestro/screenshots をクリアしてから Maestro を実行
flow 指定がない場合は full-flow.yaml を実行
比較はベースラインと差分率を算出（閾値超過は FAIL）
失敗してもレポートは生成（diff-results/{year}/{timestamp}）

diff-results/latest に最新結果へのリンクを作成
#### 単一フローの Visual Regression
./maestro/scripts/visual-regression.sh run ai-character-image-generation

#### 全フローの Visual Regression（full-flow.yaml を実行）
./maestro/scripts/visual-regression.sh run

save-baseline コマンド現在のスクリーンショットをベースラインとして保存します。UI を意図的に変更した場合に使用します。
処理内容:
最新のテスト結果（または maestro/screenshots）から取得
スクリーンショット名を正規化して maestro/baseline/{flow-name}/ にコピー
#### ベースラインを更新
./maestro/scripts/visual-regression.sh save-baseline ai-character-image-generation

 参考リンクMaestro（E2E テスト）
ImageMagick（Visual Regression）
Maestro Docs - Commands

 フェーズ6：CI/CD & リリース!目的: CIで品質を担保し、ステージング配布とストアアップロードを半自動化する。

主な成果物: CI結果 / ステージング配布 / ストア文言 / バイナリ / デプロイログ

判断ポイント: ステージング配布の実行判断 / ストア文言の最終確認 / store-upload 実行

 はじめに開発が完了したら、GitHub にプッシュして CI・レビュー・リリースを行います。
このフェーズのゴール:
GitHub Actions による CI の設定
PR ラベルによるステージング配布（Firebase App Distribution）
CHANGELOG からストア文言の自動生成
store-upload.yml + Fastlane によるストアアップロード

 CIPR 作成と push（master/main/develop/release ブランチ）で CI が自動実行されます。

モノレポのため変更検知を挟み、Sodalio/ に変更がある時だけ Flutter CI を走らせます。

また develop ブランチのみ、フォーマット差分があれば自動コミットする運用です。
ワークフロー例!モノレポ対応: このプロジェクトはモノレポ構造のため、Sodalio/ 配下の変更のみを検出して CI を実行します。カスタムアクション（.github/actions/）を使用して Flutter セットアップや変更検出を共通化しています。
コード例.github/workflows/ci-flutter.yml
name: Flutter CI

on:
  push:
    branches:
      - master
      - main
      - develop
      - 'release/**'
    paths:
      - "Sodalio/**"
      - ".github/actions/**"
      - ".github/workflows/ci-flutter.yml"
  pull_request:
    branches:
      - master
      - main
      - develop
      - 'release/**'
    paths:
      - "Sodalio/**"
      - ".github/actions/**"
      - ".github/workflows/ci-flutter.yml"

permissions:
  contents: write # develop の自動フォーマットコミット用
  pull-requests: read

env:
  FLUTTER_VERSION: "3.32.4"

jobs:
  flutter:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Check changes
        id: changes
        uses: ./.github/actions/check-file-changes
        with:
          directory: Sodalio

      - name: Setup Flutter
        if: steps.changes.outputs.changed == 'true'
        uses: ./.github/actions/setup-flutter
        with:
          flutter-version: ${{ env.FLUTTER_VERSION }}

      - name: Install dependencies
        if: steps.changes.outputs.changed == 'true'
        working-directory: Sodalio
        run: flutter pub get

      - name: Format
        if: steps.changes.outputs.changed == 'true'
        working-directory: Sodalio
        run: dart format lib test

      - name: Commit formatted code (develop only)
        if: |
          github.event_name == 'push' &&
          steps.changes.outputs.changed == 'true' &&
          github.ref == 'refs/heads/develop'
        working-directory: Sodalio
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add -A
          git diff --staged --quiet || (git commit -m "chore: auto-format code [skip ci]" && git push)

      - name: Format check
        if: steps.changes.outputs.changed == 'true'
        working-directory: Sodalio
        run: dart format --set-exit-if-changed lib test

      - name: Analyze
        if: steps.changes.outputs.changed == 'true'
        working-directory: Sodalio
        run: flutter analyze --no-fatal-infos --no-fatal-warnings

      - name: Test with coverage
        if: steps.changes.outputs.changed == 'true'
        working-directory: Sodalio
        run: flutter test --coverage
CI 高速化のポイント

設定
効果


paths
変更があったディレクトリのみ CI を実行

カスタムアクション
Flutter セットアップ、変更検出を共通化

--no-fatal-infos --no-fatal-warnings
情報・警告レベルはブロックしない

timeout-minutes: 30
長時間実行を防止


 ステージング配布（Firebase App Distribution）本番リリース前に、必要なときだけ ステージングビルド を作って配布します。
Android: .github/workflows/staging-android.yml
iOS: .github/workflows/staging-ios.yml
どちらも pull_request で起動しますが、実ビルドはラベル付与時のみです（コスト削減）。

手動実行（workflow_dispatch）も可能です。
使用ラベル:
run-staging-build-android
run-staging-build-ios
ワークフローの起動条件まとめ

ワークフロー
トリガー
補足


ci-flutter.yml
push / pull_request
master/main/develop/release のみ

staging-android.yml
pull_request / workflow_dispatch
ラベルがないとビルドはスキップ

staging-ios.yml
pull_request / workflow_dispatch
ラベルがないとビルドはスキップ

store-upload.yml
workflow_dispatch
iOS / Android を個別に選択

e2e-maestro.yml
workflow_dispatch
手動実行のみ（macOS）


 リリースブランチの作成開発が完了したら、リリースブランチを作成します（main / master どちらでも運用可）。

このリリースブランチに開発した内容をマージし、release→mainブランチへのPRを作成して、後続の作業を実施する運用にしています。
コード例#### リリースブランチを作成
git checkout -b release/1.1.0

#### 開発内容をマージ
git merge feature/ai-image-generation

#### main へ PR を作成（master 運用の場合は --base master）
gh pr create --base main --title "Release 1.1.0"

 CHANGELOG → ストア文言生成@claude への依頼この工程は PR 上の @claude コメントで依頼し、CHANGELOG 更新とストア文言生成の 作業 PR を切り出してもらう運用にしています。
コメント例💬 PR コメント（@claude）：
「CHANGELOG.md の更新と、App Store 用のリリースノートを多言語で生成してください。
リリースノートにはユーザーに見える変更のみを記載（新機能/改善/不具合修正）。
内部実装・リファクタ・CI/依存更新・テスト追加・開発向け変更は記載しないでください。
対象言語: ja, en, ko, th, vi, id, es-419
配置先: Store/whats_new/{version}/{lang}.md」
CHANGELOG.md の例ドキュメント例CHANGELOG.md
#### Changelog

#### [1.1.0] - 2025-01-15

##### Added
- AI によるキャラクター画像自動生成機能
- 画像の再生成機能

##### Fixed
- 会話履歴のスクロールが重い問題を改善
- 一部端末での画像表示の不具合を修正

##### Changed
- キャラクター作成画面のUIを改善
↓ 作成されたブランチ

生成されるストア文言の例ドキュメント例Store/whats_new/1.2.0/ja.md
【新機能】
・AIがキャラクターの画像を自動生成！設定内容から自分だけのアバターを作れます
・気に入らなかったら再生成も可能

【改善】
・会話履歴のスクロールがスムーズになりました
・キャラクター作成画面がより使いやすくなりました

【修正】
・一部端末での画像表示の問題を修正しました

 リリース前の E2E 検証自動デプロイ前に release ブランチで ローカルの E2E テストを全実行し、スクリーンショット差分を確認します。

また、e2e-maestro.yml は コスト削減のため手動実行のみにしており、必要なタイミングで Actions から起動します（macOS runner）。
私は Claude に E2E 用のカスタムコマンドを作成しており、そこから実行可能にしています。

 自動デプロイ（Fastlane + GitHub Actions）App Store / Google Play への画像・文言・バイナリのアップロードは、store-upload.yml を workflow_dispatch で手動実行する運用です。

（リリース PR で最終確認 → Actions から実行、という流れにしています）
ワークフロー概要コード例.github/workflows/store-upload.yml
name: Upload Store Metadata

on:
  workflow_dispatch:
    inputs:
      version:
        description: "Store version (x.y.z). Optional; defaults to pubspec.yaml."
        required: false
      version_code:
        description: "Android versionCode. Optional; defaults to pubspec.yaml."
        required: false
      # Platform selection
      upload_ios:
        description: "Upload to App Store Connect"
        type: boolean
        required: false
        default: true
      upload_android:
        description: "Upload to Google Play"
        type: boolean
        required: false
        default: true
      # Upload targets
      upload_binary:
        description: "Build and upload binary (IPA/AAB)"
        type: boolean
        required: false
        default: true
      upload_description:
        description: "Upload app description (概要文言)"
        type: boolean
        required: false
        default: true
      upload_whats_new:
        description: "Upload release notes (アップデート文言)"
        type: boolean
        required: false
        default: true
      upload_screenshots:
        description: "Upload screenshots"
        type: boolean
        required: false
        default: true
実行オプション

オプション
説明


version
バージョン番号（未指定時は pubspec.yaml から取得）

version_code
ビルド番号（未指定時は pubspec.yaml から取得）

upload_ios
App Store Connect へのアップロード有無

upload_android
Google Play へのアップロード有無

upload_binary
バイナリ（IPA/AAB）のビルド＆アップロード

upload_description
アプリ概要文言のアップロード

upload_whats_new
リリースノート（アップデート文言）のアップロード

upload_screenshots
スクリーンショットのアップロード

補足:
iOS は macOS runner でビルド・署名（upload_binary: true のとき）
Android は Ubuntu runner で AAB ビルド（upload_binary: true のとき）

upload_* のフラグは内部で skip_* に変換され、Sodalio/scripts/sync_store_metadata.sh と fastlane に渡します
Google Play は production トラックに draft でアップロード（公開は手動）
必要な Secrets は Sodalio/docs/ci-secrets.md に整理しています。
アップロード対象ストアへのアップロード対象は以下の 4 種類です：


対象
説明
iOS
Android


バイナリ
アプリ本体
IPA
AAB

概要文言
アプリの説明文
description.txt
full_description.txt

アップデート文言
今回の更新内容
release_notes.txt
changelogs/{version_code}.txt

スクリーンショット
ストア掲載画像
screenshots/
images/phoneScreenshots/

実用的なユースケース

やりたいこと
設定


文言だけ先に準備

upload_binary: false, upload_screenshots: false


スクショだけ更新

upload_binary: false, upload_description: false, upload_whats_new: false


バイナリだけ更新

upload_description: false, upload_whats_new: false, upload_screenshots: false


バイナリビルドはローカルでGitHub Actions でもビルド可能ですが、iOS は時間がかかるため ローカルでビルド → fastlane で直接アップロード することも多いです。
バージョン指定
version / version_code の入力が優先
未指定時は pubspec.yaml の version: x.y.z+code から抽出
メタデータの管理ストアメタデータは Store/ ディレクトリで一元管理し、アップロード時に fastlane 形式に変換します：
構成例Store/
├── description/
│   └── current/
│       ├── ja.md    # 概要文言（日本語）
│       ├── en.md    # 概要文言（英語）
│       └── ...
├── whats_new/
│   ├── 1.0.0/
│   │   └── ja.md, en.md, ...
│   └── 1.1.0/       # アップデート文言（バージョンごと）
│       └── ja.md, en.md, ...
└── assets/
    └── screenshots/ # スクリーンショット
        └── ja/current/
            ├── ios/
            └── android/
アップロード時は Sodalio/scripts/sync_store_metadata.sh が Store/ の Markdown を fastlane 形式（Sodalio/ios/fastlane/metadata / Sodalio/android/fastlane/metadata/android など）に同期します。
メリット:
Markdown で管理できる
Git で変更履歴を追跡
バージョンごとのアップデート文言を保存
※ ios/ / android/ がない場合は ja/current/ 直下を共通画像として使用します。

 デプロイフロー
 👤 人の判断ポイント

#
判断内容
タイミング


1
ストア文言の最終確認
リリースノート生成後

2
ストアアップロードの実行判断
workflow_dispatch 実行前


 参考リンクGitHub Actions
Fastlane
Keep a Changelog

 フェーズ7：運用/改善!目的: クラッシュ・分析・学びを自動化し、改善ループを回す。

主な成果物: 監視Issue / 週次レポート / LEARNINGS.md

判断ポイント: 対応優先度と改善施策の実行

 はじめにリリース後は運用フェーズに入ります。ここでも AI を活用して、継続的な改善を行います。
このフェーズのゴール:
Crashlytics によるクラッシュ監視と自動 Issue 化
GA 分析による改善提案
学びの蓄積と活用

 運用フローの全体像スケジュール一覧

ジョブ
スケジュール
説明


Crashlytics 日次
毎日 JST 0:30
新規クラッシュの早期発見

GA 週次レポート
月曜 JST 9:00
週間 KPI レポート

Crash 週次サマリー
月曜 JST 9:00
クラッシュ傾向まとめ

Learnings
月曜 JST 11:00
学び分析

!なぜ GA は日次ではなく週次？

日次データはノイズが多く、有意な傾向が見えにくいです。週次にすることで：
トレンドが明確になる
通知疲れを防げる
アクションにつながりやすい

 @claude メンションの仕組み（Claude Code Action）運用フェーズの自動化において重要な役割を果たすのが Claude Code Action です。
Claude Code Action とはClaude Code Action は、GitHub の Issue や PR で @claude とメンションすることで Claude を呼び出せる GitHub Actions です。
特徴:
Issue/PR のコメントで @claude と書くだけで起動
リポジトリのコードベースを理解した上で回答
コードの分析、修正提案、Issue 化などが可能
なぜ @claude で Claude が起動するのか!認証方式: Claude Code Action では anthropic_api_key（API キー）または claude_code_oauth_token（OAuth トークン）のいずれかを使用できます。OAuth トークンを使用すると、より安全な認証が可能です。
📖 詳細: Claude Code Action 公式リポジトリ

 GA 分析 → 週次レポート → Claude 分析
仕組み毎週月曜（JST 9:00）に GA 週次レポートを GitHub Issue に投稿し、@claude をコメント内に記載することで分析・改善提案までを自動化しています。
週次レポート方式GA レポートは 週ごとの Issue に週次レポートを投稿します。日次ではなく週次にすることで、ノイズを減らしトレンドを見やすくしています。
[GA] 週次レポート 2025-W03
├─ 📊 週間サマリー（1週間分の集計）
├─ 📈 日別トレンド（ミニチャート）
├─ 📱 プラットフォーム別
└─ 🎯 イベント別（変化が大きい順）
レポート内容

セクション
内容


💡 今週のハイライト
30%以上変化した指標を自動検出・強調

📈 日別推移
ミニバーチャートで 1 週間の推移を可視化

KPI サマリー
アクティブユーザー、新規ユーザー、セッション、エンゲージメント率（前週比較）

プラットフォーム別
iOS / Android 別の KPI

イベント別
主要イベントの発生回数（変化が大きい順にソート）

レポート出力例レポート例#### 📊 GA週次レポート

**期間**: 2025-01-13 〜 2025-01-19（前週: 2025-01-06 〜 2025-01-12）

##### 💡 今週のハイライト

- 📈 **アクティブユーザー** が前週比 +35% と大幅増加
- 🎯 イベント「**send_message**」が前週比 +52% と急増

##### 📈 日別推移

**アクティブユーザー**: ▁▃▅▇█▇▅ (120〜450)
**セッション**: ▃▅▇█▇▅▃ (200〜680)

##### KPIサマリー

| 指標 | 今週 | 前週 | 変化 | トレンド |
| --- | ---: | ---: | ---: | :---: |
| アクティブユーザー | 2,450 | 1,815 | +35% | 📈 |
| 新規ユーザー | 320 | 280 | +14% | ↗️ |
| セッション | 4,200 | 3,800 | +11% | ↗️ |
| エンゲージメント率 | 68.5% | 65.2% | +3.3% | ➖ |
必要な設定Google Analytics Data API の有効化（GCP）
サービスアカウントを GA プロパティに 閲覧者 で追加（GA のアクセス管理）
GA の権限は IAM ではなく、GA 側のアクセス管理で付与


GA_PROPERTY_ID を GitHub Actions Variables に設定
ラベルはスクリプトが自動作成（type/ga-report, env/prod）
Claude への分析依頼レポートコメントの末尾に @claude と分析指示を含めることで、レポート投稿と同時に Claude Code Action が起動します。
---

@claude このレポートを分析して以下を教えてください：
1. **注目すべきトレンド**: 数値の変化から読み取れる傾向
2. **ユーザー行動の変化**: イベントデータから推測できること
3. **改善アクション**: 来週に向けて検討すべきこと

 クラッシュ監視 → 自動 Issue → Claude 分析仕組みGitHub Actions で毎日 Crashlytics をチェックし、新しいクラッシュを GitHub Issue として自動作成します。閾値フィルタと優先度自動付与により、ノイズを減らし対応優先度を明確にしています。
改善ポイント

機能
説明


🚦 優先度自動計算
影響ユーザー数と発生回数から Critical/High/Medium/Low を自動判定

🔢 閾値フィルタ
指定した閾値未満のクラッシュはスキップ（ノイズ削減）

📋 テーブル形式
Issue ボディを見やすく整形

優先度の自動計算ロジックスコア = (影響ユーザー数 × 10) + 発生回数

Critical (🔴): スコア >= 100 または ユーザー >= 10
High (🟠):     スコア >= 30 または ユーザー >= 5
Medium (🟡):   スコア >= 10 または ユーザー >= 2
Low (🟢):      それ以外
Crashlytics データの取得方法Firebase Crashlytics のデータは BigQuery API で取得します。Crashlytics → BigQuery エクスポートを事前に設定しておく必要があります。
必要な設定:
Firebase サービスアカウント JSON（GitHub Secrets に設定）

Crashlytics → BigQuery エクスポート の有効化（Firebase Console）
サービスアカウントに BigQuery データ閲覧者 の権限を付与（GCP IAM）
対象アプリの設定（FIREBASE_PROJECT_ID / CRASHLYTICS_APPS_JSON）

MONITORING_PAT（GitHub PAT、@claude トリガー用）
ラベルはスクリプトが自動作成（type/crash, env/prod, priority/*）
閾値設定（環境変数）:


環境変数
デフォルト
説明


CRASH_MIN_USER_COUNT
1
影響ユーザー数の最小値

CRASH_MIN_EVENT_COUNT
1
発生回数の最小値

ワークフローコード例.github/workflows/issue-monitoring.yml
name: Issue Monitoring (Crashlytics/GA)

on:
  schedule:
    # Crashlytics: 毎日 JST 0:30（新規クラッシュの早期発見）
    - cron: '30 15 * * *'
    # GA + Crash Summary: 毎週月曜 JST 9:00（週次レポート）
    - cron: '0 0 * * 1'
    # Learnings: 毎週月曜 JST 11:00（学び分析）
    - cron: '0 2 * * 1'
  workflow_dispatch:
    inputs:
      run_ga:
        description: 'Run GA Weekly Report'
        type: boolean
        default: false
      run_crash:
        description: 'Run Crashlytics Daily Issues'
        type: boolean
        default: false
      run_crash_summary:
        description: 'Run Crashlytics Weekly Summary'
        type: boolean
        default: false
      run_learnings:
        description: 'Run Weekly Learnings Analysis'
        type: boolean
        default: false

env:
  # Crashlytics 閾値設定（ノイズ削減）
  CRASH_MIN_USER_COUNT: '1'
  CRASH_MIN_EVENT_COUNT: '1'

jobs:
  crashlytics:
    name: Crashlytics Daily Issues
    if: |
      (github.event_name == 'workflow_dispatch' && github.event.inputs.run_crash == 'true') ||
      (github.event_name == 'schedule' && github.event.schedule == '30 15 * * *')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Create Crashlytics Issues
        env:
          FIREBASE_SERVICE_ACCOUNT_JSON: ${{ secrets.FIREBASE_SERVICE_ACCOUNT_JSON }}
          GITHUB_TOKEN: ${{ secrets.MONITORING_PAT }}
        run: node scripts/monitoring/crashlytics_daily_issues.js
!MONITORING_PAT について: @claude メンションで Claude Code Action をトリガーするには、GITHUB_TOKEN ではなく Personal Access Token（PAT）が必要です。GITHUB_TOKEN はワークフロー内で別のワークフローをトリガーできないためです。
↓ クラッシュ分析の CI 画面

自動作成される Issue の例Issue例#### [Crash][Prod] 🟠 NullPointerException at ChatScreen.build

Crashlytics Issue ID: abc123

#### 🟠 優先度: High

##### 概要

| 項目 | 値 |
| --- | --- |
| プラットフォーム | Android |
| 例外 | `NullPointerException` |
| サブタイトル | ChatScreen.build (line 42) |
| 影響ユーザー数 | **15** |
| 発生回数 | **42** |
| 影響バージョン | 1.2.3 |

##### タイムライン

- 初回発生: 2025-01-14 10:23:45
- 最新発生: 2025-01-15 08:15:32
- 対象期間（JST）: 2025-01-15

🔗 [Crashlyticsで詳細を確認](https://console.firebase.google.com/...)
Claude への分析依頼（Issue 本文に含める）Issue 本文の末尾に @claude と分析指示を含めることで、Issue 作成と同時に Claude Code Action が起動します。
コメント例---

@claude このクラッシュを分析してください：
**分析手順:**

1. 上記の例外名・サブタイトルからエラーの種類を特定
2. このリポジトリのコードベースを検索して関連箇所を探す
3. 影響ユーザー数と発生回数から優先度を判断

**回答フォーマット:**

- 🔍 原因推測: （エラー内容から考えられる原因）
- 📍 関連コード: （該当しそうなファイル・関数名）
- ⚡ 優先度: High/Medium/Low（理由も添えて）
- 🛠️ 修正方針: （具体的な修正アプローチ）
!Issue 本文に @claude を含める理由: Issue 作成後にコメントで @claude を付ける方式だと、2 ステップ必要になります。Issue 本文に最初から含めることで、作成と同時に分析が開始され、運用が効率化されます。
Claude の分析コメント例コメント例#### クラッシュ分析

- 🔍 **原因推測**: `ChatScreen.build`内で `messages` リストが null の状態でアクセスされている可能性が高いです。非同期でデータ取得中に build が呼ばれた場合に発生すると推測されます。

- 📍 **関連コード**: `lib/screens/chat_screen.dart:42` 付近の `ListView.builder` での `messages.length` アクセス

- ⚡ **優先度**: **High** - 15 ユーザーに影響、継続的に発生しており放置すると影響拡大の恐れあり

- 🛠️ **修正方針**:
  1. `messages` が null の場合のガード追加
  2. または `AsyncValue` パターンで loading/error/data を適切にハンドリング
  3. テスト追加: messages が null/empty の場合のテスト

 週次クラッシュサマリー毎週月曜に、1 週間のクラッシュ傾向をまとめた週次サマリーを自動生成します。

仕組みサマリー内容

セクション
内容


💡 今週のハイライト
クラッシュ傾向（増減）、解決状況

📊 統計サマリー
ユニーク Issue 数、総発生回数、影響ユーザー（前週比較）

📱 プラットフォーム別
iOS / Android 別の統計

🔝 Top クラッシュ
影響ユーザー数順の Top 5

📋 GitHub Issue 状況
今週解決済み / 現在オープン

サマリー出力例レポート例#### 🔥 クラッシュ週次サマリー

**期間**: 2025-01-13 〜 2025-01-19

##### 💡 今週のハイライト

- 📉 影響ユーザー数が前週比で減少しました
- ✅ 今週 **3件** のクラッシュIssueを解決しました
- ⏳ 現在 **5件** のクラッシュIssueが未対応です

##### 📊 統計サマリー

| 指標 | 今週 | 前週 | 変化 | トレンド |
| --- | ---: | ---: | ---: | :---: |
| ユニーク Issue | 8 | 12 | -4 (-33%) | 📉 |
| 総発生回数 | 156 | 245 | -89 (-36%) | 📉 |
| 影響ユーザー | 42 | 68 | -26 (-38%) | 📉 |

##### 🔝 Top クラッシュ（影響ユーザー数順）

###### iOS

| # | Issue | ユーザー | 発生回数 |
| --- | --- | ---: | ---: |
| 1 | `NullPointerException at ChatScreen...` | 15 | 42 |
| 2 | `IndexOutOfBoundsException in List...` | 8 | 23 |
週次レポートでも@claudeを利用して分析をしてもらいます。


 学びの蓄積（LEARNINGS.md）運用で得た学びを LEARNINGS.md に蓄積します。週次で自動更新 PR が作成される仕組みを導入しています。
自動更新の仕組みスクリプトで Issue を作成し、@claude に分析と PR 作成を任せるシンプルな設計です。
ポイント: 正規表現でコメントを解析するのではなく、Claude に自然な分析を任せることで、より柔軟で質の高い学びを抽出できます。
ワークフロー設定issue-monitoring.yml に週次ジョブを追加しています：
コード例.github/workflows/issue-monitoring.yml
learnings:
  name: Weekly Learnings Issue
  if: |
    (github.event_name == 'workflow_dispatch' && github.event.inputs.run_learnings == 'true') ||
    (github.event_name == 'schedule' && github.event.schedule == '0 2 * * 1')
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: '20'
    - name: Create Learnings Issue
      env:
        GITHUB_TOKEN: ${{ secrets.MONITORING_PAT }}
      run: node scripts/monitoring/learnings_weekly_analysis.js
自動作成される Issue の例Issue例#### 週次学び分析依頼

2025-W03 にクローズされた Crash Issue から学びを抽出し、
LEARNINGS.md を更新してください。

##### 対象 Issue（2 件）

- #42: [Crash][Prod] 🟠 NullPointerException at ChatScreen.build
- #58: [Crash][Prod] 🟡 IndexOutOfBoundsException in ListView

---

@claude 上記の Issue を分析して、LEARNINGS.md を更新する PR を作成してください。
自動生成される LEARNINGS.md のセクション例セクション例##### 2025-W03 (自動生成)

- **[#42](https://github.com/.../issues/42)**: NullPointerException at ChatScreen.build

  - 原因: 非同期処理完了前に build が呼ばれて null アクセス
  - 対策: AsyncValue パターンで loading/error/data を適切にハンドリング

- **[#58](https://github.com/.../issues/58)**: IndexOutOfBoundsException in ListView
  - 原因: リストの長さチェックが不十分
  - 対策: itemCount と実データの整合性チェックを追加
LEARNINGS.md の構成例ドキュメント例LEARNINGS.md
#### 学びの蓄積

#### クラッシュから学んだこと

##### 2025-01: Null安全でない箇所でクラッシュ多発
- **問題**: 非同期処理完了前に build が呼ばれて NullPointerException
- **対策**: Lint ルール追加、AsyncValue パターンの徹底
- **Issue**: #42

##### 2025-01: 非同期処理のエラーハンドリング不足
- **問題**: API エラー時にユーザーへのフィードバックがない
- **対策**: try-catch 必須化、エラー表示コンポーネント共通化
- **Issue**: #58

#### GA分析から学んだこと

##### チュートリアル完了率
- 3ステップ以内が最適（それ以上は離脱率上昇）
- スキップボタンは必須

##### 継続率との相関
- 初回チャット完了率が Day7 継続率に強く相関
- オンボーディングで最初のチャットまで誘導すべき

#### レビューで指摘されがちなこと

##### Riverpod の dispose 忘れ
- **対策**: テンプレートに dispose 処理を追加

##### コメント不足
- **対策**: 複雑なロジックには必須化（レビューチェックリストに追加）
CLAUDE.md への反映学びは CLAUDE.md に反映し、AI の品質向上に活かします。
CLAUDE.md（追記部分）
#### Development Guidelines から学んだこと

##### 非同期処理
- AsyncValue パターンを使用すること
- null チェックを徹底すること

##### エラーハンドリング
- try-catch は必須
- ユーザーへのフィードバックを忘れずに

 👤 人の判断ポイント

#
判断内容
タイミング


1
クラッシュ対応方法の選択
Issue 作成後（優先度ラベルを参考に）

2
改善施策をやるかどうか
GA 週次レポート確認後（月曜）

3
学びの PR をマージするか
週次 PR 作成後（月曜）

対応方法の選択肢クラッシュ対応:
🔴 Critical → 即時対応
🟠 High → 今週中に対応
🟡 Medium → 次スプリントで検討
🟢 Low → Backlog へ
@claude に修正を依頼
改善施策:
実施する → 企画フェーズへループ
保留 → Backlog へ
却下 → 理由を記録

 運用 → 企画へのループ運用で得た学びやデータは、次の機能開発（企画フェーズ）にフィードバックします。
フロー例運用
 │
 ├─ クラッシュ分析 → バグ修正（優先度に応じて）
 │
 ├─ GA週次分析 → 改善施策立案
 │
 ├─ 週次サマリー → 傾向把握・リソース配分
 │
 └─ 学びの蓄積 → CLAUDE.md 更新
          │
          ▼
       企画（次の機能開発）

 まとめ（運用フェーズ）運用フェーズでも AI と自動化を活用することで：

クラッシュの早期発見・分析: 自動 Issue 化 + 優先度自動付与 + Claude 分析

週次での傾向把握: GA 週次レポート + クラッシュ週次サマリー

データドリブンな改善: 週次レポート + Claude 提案

知識の蓄積: LEARNINGS.md → CLAUDE.md
!監視頻度の最適化
日次: クラッシュ検出（早期発見が重要）
週次: GA レポート + クラッシュサマリー（トレンド把握）
日次データはノイズが多いため、週次でまとめて確認する方が有意義です。ただしクラッシュは早期発見が重要なため日次で検出しています。
これにより、継続的な品質向上と効率的な運用が実現できます。

 参考リンク
Claude Code Action - GitHub での @claude メンション
Firebase Crashlytics

Crashlytics を BigQuery にエクスポート - BigQuery 連携の設定

BigQuery API - Crashlytics データ取得
Google Analytics Data API
GitHub Actions

 まとめ（全体）本記事では、個人開発でも「速度」と「品質」を両立するために、AIを開発パイプライン全体へ組み込む方法を紹介しました。

重要なのは、人は判断に集中し、作業はAIに任せるという役割分担を徹底することです。
最初からすべてを完璧に回す必要はありません。

まずは自分がボトルネックに感じているフェーズ（企画・レビュー・運用など）から部分的に取り入れ、少しずつ「自分に合うパイプライン」へ育てていくのが現実的です。
この流れを一度作ってしまえば、個人でも継続的に改善しながらアプリを育てていけます。

ぜひ自分の開発スタイルに合わせてカスタマイズし、次のリリースに繋げてみてください。
やりたいこと	設定
文言だけ先に準備	`upload_binary: false`, `upload_screenshots: false`
スクショだけ更新	`upload_binary: false`, `upload_description: false`, `upload_whats_new: false`
バイナリだけ更新	`upload_description: false`, `upload_whats_new: false`, `upload_screenshots: false`
フェーズ	概要
企画	市場/ユーザー/収益を整理して方向性を固める。「何を作るか」を決めたい人はここ。
初期化	開発基盤とプロジェクト記憶（steering）を整える。初期の手順や構成を知りたい人はここ。
開発	仕様→設計→タスク→実装を順に進める。 cc-sdd の具体的な回し方を知りたい人はここ。
レビュー	ローカル＋PRで品質を二重チェックする。レビュー手順やAIの使い分けを知りたい人はここ。
テスト	E2E と VRT で UI の挙動/見た目を担保する。自動テストの作り方を知りたい人はここ。
リリース	ストア文言と配布を自動化する。 CI/CDや配布フローを知りたい人はここ。
運用	監視・分析・学びで改善ループを回す。運用自動化や改善の流れを知りたい人はここ。
Skill	用途	出力形式
`market-research`	市場調査・競合分析	市場規模、競合比較表、差別化ポイント
`user-persona`	ペルソナ・JTBD 設計	ペルソナプロフィール、JTBD、利用シーン
`monetization-strategy`	収益戦略・KPI 設計	収益モデル、価格設定、KPI 目標値
`kiro-product-md`	product.md 生成（統合）	Kiro/cc-sdd 形式の product.md
#	質問	選択肢の例
1	ターゲット市場について	A) 日本市場 / B) グローバル展開 / C) まだ決めていない
2	想定しているメインの用途は	A) 日記・セルフリフレクション / B) メンタルヘルス / C) 学習
3	カスタマイズの範囲	A) アバター+性格+口調 / B) 性格+口調のみ / C) 最小限
4	開発体制について	A) 個人開発 / B) 小規模チーム / C) それ以上の規模
5	収益化の優先度は	A) 最初から重視 / B) ユーザー獲得優先 / C) サイドプロジェクト
ツール	得意なこと	苦手なこと
ChatGPT	0→1 のデザイン生成	細かい調整、複数サイズ書き出し
Canva	細かい調整、サイズ調整、書き出し	0→1 のデザイン生成
成果物	説明
`product.md`	製品ビジョン（目的、ペルソナ、機能、ビジネス目標）
アプリ名	ブランディングの軸
アプリアイコン	ストア用各サイズ
#	判断内容	詳細
1	対話形式での方向性確認	Claude からの選択式質問に回答し、分析の方向性を決定
2	product.md の内容確認	生成された製品ビジョンが意図通りか確認、必要に応じて修正
3	アプリ名・アイコンの最終確認	ブランディングの軸となるため慎重に
問題	詳細
要件の曖昧さ	何を作るか明確でないまま実装が始まる
設計の欠如	アーキテクチャを考慮せずにコードが生成される
手戻りの多さ	「思ってたのと違う」が頻発
コンテキストの分断	会話が長くなると AI が文脈を見失う
特徴	説明
3 フェーズ承認	要件 → 設計 → タスクの各段階で人間がレビュー
ステアリング	プロジェクトの「記憶」を保持し、AI が全体像を理解
サブエージェント	仕様策定・設計・実装を専門のエージェントが担当
TDD 実装	テストファーストで品質を担保
仕様の永続化	`.kiro/specs/`というディレクトリに仕様が残り、後から参照・修正可能
オプション	説明
`--claude-agent`	Claude Code 用の 12 コマンドと 9 サブエージェントを生成
`--lang ja`	日本語で仕様書を生成
作成されるもの	説明
`.claude/agents/kiro/`	サブエージェント定義（spec-design.md, spec-impl.md など）
`.claude/commands/kiro/`	スラッシュコマンド定義（/kiro:spec-* コマンド）
`.kiro/settings/`	ルールとテンプレート
`CLAUDE.md` への追記	AI 駆動開発ライフサイクル（AI-DLC）のセクションが追加される
状況	対応
意図的な UI 変更（仕様変更）	`save-baseline {flow}` でベースラインを更新
意図しない UI 変更（バグ）	コードを修正してベースラインに合わせる
サブエージェント	役割
`spec-requirements`	EARS 記法で要件定義を生成
`spec-design`	技術設計書を生成
`spec-tasks`	実装タスクリストを生成
`spec-impl`	TDD で実装（テストファースト）
サブエージェント	役割
`validate-gap`	要件と既存コードの差分分析
`validate-design`	設計の品質チェック（インタラクティブ）
`validate-impl`	実装が仕様を満たすか検証
サブエージェント	役割
`steering`	`.kiro/steering/` の初期化・同期（プロジェクト記憶）
`steering-custom`	カスタムステアリング作成（独自の開発方針を追加）
ファイル	内容
`tech.md`	技術スタック、アーキテクチャパターン
`structure.md`	ディレクトリ構成、コーディング規約
ディレクトリ	役割	作成タイミング
`steering/`	開発方針 + 企画情報（なぜ・どう作るか）	企画: product.md（Claude.ai）、初期化: tech.md, structure.md（ローカル）
`specs/`	機能仕様（何を作るか）	開発フェーズで自動生成
成果物	説明
Flutter プロジェクト	基本的なプロジェクト構造
`.claude/`	サブエージェント、コマンド定義
`.kiro/steering/`	product.md, tech.md, structure.md
`CLAUDE.md`	AI-DLC セクション追記済み
コマンド	役割
`/kiro:spec-init`	仕様ディレクトリ作成
`/kiro:spec-requirements`	EARS 記法で要件定義
`/kiro:spec-design`	技術設計書生成
`/kiro:spec-tasks`	実装タスクリスト生成
`/kiro:spec-impl`	TDD で実装
`/kiro:spec-status`	進捗確認
`/kiro:spec-quick`	クイック仕様生成（対話なしで一気に生成）
コマンド	用途	使いどころ
`/kiro:validate-gap`	要件と既存コードの差分分析	既存アプリへの機能追加
`/kiro:validate-design`	設計の品質チェック	複雑な機能の設計レビュー
`/kiro:validate-impl`	実装が仕様を満たすか検証	実装完了後の最終確認
コマンド	用途
`/kiro:steering`	ステアリングの初期化・同期
`/kiro:steering-custom`	カスタムステアリング作成（独自ルール）
フィールド	説明
`phase`	現在のフェーズ（initialized → requirements → design → tasks）
`approvals.*.generated`	ドキュメントが生成されたか
`approvals.*.approved`	人が承認したか
`ready_for_implementation`	全承認後に `true` になり、実装可能になる
目次

この記事の前提

対象読者

前提

この記事で得られること

読み方ガイド

題材にしたアプリ

TL;DR

全体像（ざっくり）

各フェーズの概要

フェーズ詳細

フェーズ1：企画（Planning）

はじめに

題材：AI チャットアプリ

Claude.ai でプロジェクトを作成

Skills の作成

企画フェーズ用に作成するSkillsの例

各 Skill の設計意図

market-research

user-persona

monetization-strategy

kiro-product-md

Skills の作成、インストール

市場調査 → ペルソナ → 収益戦略 → product.md（製品ビジョン）生成

プロンプト例

対話形式で方向性を確認

回答方法

分析結果と product.md（製品ビジョン） の生成

生成された product.md（製品ビジョン）

アプリ名の決定（Claude との壁打ち）

プロンプト例

名前の重複チェック

アプリアイコン作成（ChatGPT + Canva）

なぜこの組み合わせか

ワークフロー

このフェーズの成果物

👤 人の判断ポイント

参考リンク

フェーズ2：プロジェクト初期化（Project Setup）

はじめに

Flutter プロジェクト生成

cc-sdd とは

なぜ cc-sdd を使うのか

cc-sdd の特徴

cc-sdd のインストール

利用可能なコマンド

作成されるファイル・ディレクトリ

サブエージェントとは

仕様策定系（Spec）

検証系（Validate）

ステアリング系（Steering）

product.md の配置

product.md の内容例（抜粋）

tech.md と structure.md の生成

Sync Mode

tech.md の内容例

structure.md の内容例

最終的なディレクトリ構成

.kiro/ 配下の役割

steering（ステアリング）とは

specs（仕様）とは

CLAUDE.md について

追記される内容

このフェーズの成果物

👤 人の判断ポイント

参考リンク

フェーズ3：cc-sdd 開発（Spec-Driven Development）

はじめに

cc-sdd とは

核心：各段階で人が「OK」を出さないと次に進めない

利用可能なコマンド

仕様策定コマンド（Spec）

検証コマンド（Validate）

ステアリングコマンド（Steering）

実践：カスタムキャラクター画像の自動生成機能

追加する機能

Step 1: 仕様初期化

実行結果

spec.json によるフェーズ管理

Step 2: 要件定義

分析結果と product.md（製品ビジョン）の生成

`run` コマンド

`save-baseline` コマンド
