# ペルソナと進めるアーキテクチャ設計

> 技術リードのジミンと、Mamma（育児アプリ）の現状把握、代替案比較、目標設計、決定文書、MCPでの実装を進めます。

コーディングエージェントと開発する技術リードが、現在の構造を把握し、次の機能を設計して実装につなげる例です。Mamma（育児アプリ）の記録保存フローから始めましょう。

## ペルソナと目標

**ジミンは開発者3人のチームの技術リードです。** チームはコーディングエージェントと育児記録サービスを開発しています。ジミンは接続状態が変わっても、利用者が記録の入力と保存結果の確認を続けられる構造を設計します。

| 項目 | 今回決めること |
| --- | --- |
| 利用体験 | 入力中の記録、保存中、完了をどう表示するか |
| 構造 | 既存の画面・保存経路で再利用する部分と追加する責任 |
| 品質基準 | 再試行、重複保存、アプリを再度開いたときの確認方法 |
| 成果物 | 現状キャンバス、目標キャンバス、設計決定文書、実装・テストのチェックリスト |

<Note>ジミンと追加要件は、活用の流れを説明する架空のシナリオです。画面は実際のMammaコードから生成した文書・キャンバスです。目標設計は現在の実装と分けて管理します。</Note>

## 資料を準備する

- [GitHub接続](/ja/guides/github)で参照できるリポジトリと基準ブランチ
- 現在の機能説明と利用者の状況を記した要件
- 維持するAPI、データ構造、権限、デプロイ・運用条件
- 完了を判断する利用シナリオとテスト基準

ジミンは「記録を入力 → 保存を要求 → 結果を確認」という一つのフローから始めます。範囲を決めると、AIが読むコードと人が判断する質問を絞れます。

## 現在の構造を一枚にまとめる

チャットでリポジトリと関連文書を指定し、現在の呼び出しと責任を説明する文書・キャンバスを依頼します。

```text
Mammaリポジトリの記録入力と保存のフローを読んでください。
画面、状態管理、保存コマンド、データアクセス層の呼び出しを
現状キャンバスにし、主要な説明にソースパスを残してください。
コードで確認した動作と、追加で確認する質問を分けてください。
現在の実装を説明する文書を別に保存してください。
```

<Screenshot name="canvas-review" alt="Mammaコードから生成した現状のアーキテクチャキャンバス" caption="既存の構造を共有すると、新しい責任を置く層を一緒に判断しやすくなります。" />

ジミンは各矢印をソースと照合します。保存を開始する場所、結果を画面に返す場所、利用者とデータのアクセス範囲を確認します。

## 下部入力欄からエージェントと設計を改善する

現在の構造を示すキャンバスを開き、下部の**キャンバスに指示する…**に変更内容を入力します。ジミンは構成要素をレイヤーごとに配置し、図形や接続線を選んで役割や改善案を質問します。AIパネルを閉じると、同じ会話を続けながら設計を広く表示できます。

<Screenshot name="canvas-command" alt="下部入力欄からMammaの構造改善を依頼する画面" caption="設計を見ながら変更対象と維持する条件を伝えます。" />

```text
選択した部分の責務と接続方向を説明して。
現在の構造を維持し、再試行の責務を置く場所を代案として提案して。
目標構造は別のキャンバスに作って。
```

直接描画、選択範囲への指示、保存の確認は[アーキテクチャ図とキャンバス](/ja/guides/canvas)で試せます。

## 代替案を比較して目標構造を描く

現状と目標は別のキャンバスで管理します。例えば、**既存の保存経路で再試行する方式**と**保存待ちキューを追加する方式**を比較します。どちらも今回の追加要件に対する設計候補です。

```text
現在の構造と記録保存の要件から、二つの設計案を比較してください。
Aは既存の保存経路を活用し、Bは保存待ちキューを追加します。
変更するモジュール、記録ID、保存順序、重複処理、権限、
利用者に示す状態、テスト範囲を表にしてください。
前提と検証する質問を残し、目標構造の草案を描いてください。
現状キャンバスを維持し、目標キャンバスを新たに保存してください。
```

| 比較基準 | レビューする質問 |
| --- | --- |
| 責任の位置 | 保存状態と再試行をどの層が管理するか？ |
| データの一貫性 | 同じ記録を再送するとき、どの識別子と処理規則を使うか？ |
| 利用体験 | 保存中と完了をどの根拠で区別するか？ |
| アクセス権限 | 既存の利用者・家族のアクセス範囲をどう維持するか？ |
| 実装と運用 | 追加ストレージ、デプロイ、観測項目、テストに何が必要か？ |

## レビューを設計決定文書に残す

ジミンが案を選んだら、チャットで理由と変更範囲を文書にまとめます。**選択した案、比較した案、維持するインターフェース、データフロー、受け入れ条件、残る質問**を含めます。

<Screenshot name="chat-review" alt="Mamma文書から記録フローとレビュー項目を整理したチャット" caption="人が判断する質問を絞り、合意内容を設計文書につなげます。" />

例えば「同じ記録を再保存しても一つの記録として確認できる」「アプリを再度開くと保存状態が分かる」を受け入れ条件にします。合意した条件を、成功・再試行・権限・再接続のテストに展開します。

## エージェントが設計を読んで実装する

[Specify MCP](/ja/mcp/connect)を接続したコーディングエージェントに、設計決定文書と目標キャンバスを読むよう依頼します。接続先が提供する文書・キャンバスの読み取りツールで同じ文脈を確認できます。

```text
Specify MCPでMammaの記録保存の設計決定文書と目標キャンバスを読んでください。
現在のコードと照合し、変更するモジュールと実装順序を整理してください。
受け入れ条件を実装し、成功・再試行・権限・再接続をテストしてください。
追加の判断が必要な方針は質問としてまとめてください。
```

## 次の変更で設計と実装を合わせる

実装後、現在の状態を示す文書・キャンバスをそれぞれリポジトリに接続します。対象ブランチのpush後に更新結果と編集履歴を確認します。目標設計の文書は合意の基準として維持し、現状資料と比較して受け入れ条件を点検します。

設定は[リポジトリ接続の管理](/ja/guides/automation-settings)、結果の確認は[自動更新の結果を確認](/ja/guides/review-proposals)を参照してください。

## 完了チェックリスト

- 現状と目標の構造の役割が分かれています。
- 新しい責任、既存インターフェース、データフローを説明できます。
- 決定理由と受け入れ条件が設計決定文書に残っています。
- エージェントが同じ文書を読み、実装・テスト結果を残しています。
- 変更後の現状構造と実際のコードを人が照合しています。
