人間は意図、AIは実装：Codexが導く「要件を伝えるだけ」のAI駆動開発ワークフロー

はじめに

特に、OpenAIのCodexに代表される「大規模なコードコンテキストを理解するAIモデル」のポテンシャルを最大限に引き出すため、各フェーズで使用するプロンプト、AIの予想出力、そしてコンテキスト管理の方法を具体的に紹介します。

この記事で学べること

• Codex等のコード生成モデルを「単なる補完」ではなく「開発パートナー」にするプロンプト術
• AI駆動開発の各フェーズにおける具体的なプロンプトの書き方
• UIワイヤーフレームをAIに生成させる方法
• コードベースだけでなくJSONを用いたプロジェクト進捗・コンテキスト管理
• 小規模Webアプリ開発に最適化されたワークフロー

---

目次

1. プロジェクト概要
2. Phase 0: プロジェクト構想
3. Phase 1: プロジェクト初期化
4. Phase 2: 要件定義・ドメインモデリング
5. Phase 3: アーキテクチャ設計・技術スタック選定
6. Phase 4: 開発環境セットアップ
7. Phase 5: 機能実装とcontext.json管理
8. まとめ
   まずは全体像です。以降の各Phaseは、この流れに沿って具体例とプロンプトを紹介します。
   

---

1. AI駆動開発概要

AI駆動開発とは

私が捉えるAI駆動開発のフローは、Google Mapsの体験に近いものです。

人は目的地（Why）を伝え、AI（Codex）が最適ルート（How）を提案し、到達すべき成果物（What）へ導く。

つまり、人間が「何を実現したいか」を定義し、AIが「どう進めるか」の最適な選択肢を提示する関係です。

プロジェクト概要

本記事で構築するサンプルプロジェクトの全体像です。シンプルな機能セットを持つWebアプリを題材に、AI駆動開発の各フェーズを実践的に学べます。

Feature Request 投票ボードサイトとは

ユーザーが新機能のリクエストを投稿し、他のユーザーが投票できるWebアプリケーションです。プロダクトチームはユーザーの声を可視化し、優先度を決定するために活用します。

主な機能

• 機能リクエストの投稿・閲覧
• リクエストへの投票（賛成票）
• ステータス管理（検討中・開発中・完了・却下）
• カテゴリ別フィルタリング
• 人気順・新着順ソート

---

2. Phase 0: プロジェクト構想

コードを書く前に「なぜ作るのか」「誰のために作るのか」を明確にするフェーズです。AIにビジネス観点の質問に答えてもらい、プロジェクトの方向性を固めます。技術的な議論はこの段階では行いません。

2.1 プロジェクトビジョン策定（入力プロンプトの例）

**あなたの役割**
あなたは経験豊富なプロダクトストラテジストです。
新規プロジェクトの構想段階において、ビジョン策定を支援する任務を担っています。

**重要な制約**
- **ソースコードやコードスニペットは一切出力しないでください**
- **技術選定やアーキテクチャの議論は行わないでください**
- この段階では概念レベルの議論に集中してください

**プロセス**

以下の質問に回答してください（回答は私が記入します）

**ビジネス観点**
- [Question] このプロジェクトで解決したい課題は何ですか？
  [Answer] ユーザーの機能要望を効率的に収集・管理し、開発優先度の決定を支援したい

- [Question] 想定するユーザー（ペルソナ）は誰ですか？
  [Answer] SaaSプロダクトのエンドユーザー、およびプロダクトマネージャー

- [Question] 競合や既存ソリューションはありますか？差別化ポイントは？
  [Answer] Canny、UserVoice等がある。差別化はシンプルさと無料で始められる点

- [Question] 成功の指標（KPI）は何ですか？
  [Answer] 月間アクティブ投稿数、投票参加率、フィードバック反映率

**スコープ観点**
- [Question] MVP（最小限の製品）として必要な機能は何ですか？
  [Answer] リクエスト投稿、投票、ステータス管理、一覧表示

- [Question] 将来的に追加したい機能はありますか？
  [Answer] コメント機能、ロードマップ表示、Slack連携

- [Question] 予算やリソースの制約はありますか？
  [Answer] 個人開発、無料〜低コストのインフラを使用

回答をもとに、プロジェクトビジョンドキュメントの草案を作成してください。

**成果物と保存先**
- `docs/stories/story-000-setup/vision.md` : プロジェクトビジョンドキュメント

**プロジェクト概要**
Feature Request投票ボードサイト - ユーザーの機能要望を収集・投票で優先度を可視化するWebアプリ

予想出力: vision.md

# プロジェクトビジョン

## ビジョンステートメント

「ユーザーの声を、プロダクトの力に変える」

ユーザーと開発チームをつなぐシンプルな機能要望プラットフォームを提供し、
本当に求められている機能を優先的に開発できる環境を実現します。

## ターゲットユーザー

### プライマリユーザー: エンドユーザー
– SaaSプロダクトの利用者
– 新機能や改善を要望したいが、適切な伝達手段がない
– 他のユーザーの要望も知りたい

### セカンダリユーザー: プロダクトマネージャー
– 開発優先度の判断材料が欲しい
– ユーザーの生の声を効率的に収集したい
– 対応状況を透明性高く共有したい

## 主要機能リスト（優先度付き）

| 優先度 | 機能 | 説明 |
|——–|——|——|
| Must | リクエスト投稿 | タイトル・詳細を入力して投稿 |
| Must | 投票機能 | リクエストに賛成票を投じる |
| Must | 一覧表示 | リクエストをソート・フィルタ表示 |
| Must | ステータス管理 | 検討中→開発中→完了/却下 |
| Should | カテゴリ分類 | リクエストをカテゴリで整理 |
| Should | ユーザー認証 | ログインによる投稿・投票管理 |
| Could | コメント機能 | リクエストへのディスカッション |
| Won’t (MVP外) | Slack連携 | 新規投稿の通知 |

## 成功指標（KPI）

1. **月間アクティブ投稿数**: 50件以上
2. **投票参加率**: 閲覧ユーザーの30%以上が投票
3. **フィードバック反映率**: 投稿の20%以上が開発着手

## 制約事項

– 個人開発のため、シンプルな技術構成を優先
– 無料〜低コストのインフラ（Vercel、Supabase等）を使用
– MVP開発期間: 2週間以内

---

3. Phase 1: プロジェクト初期化

プロジェクトの骨格を作るフェーズです。AI駆動開発に最適化されたフォルダ構造と、AIが参照するメモリファイル（AGENTS.md）を生成します。ここで定義した構造が、後続フェーズでの自動生成の基盤となります。

3.1 フォルダ構造生成（入力プロンプトの例）

**あなたの役割**
あなたは経験豊富なソフトウェアエンジニアです。
AI駆動開発ワークフローに準拠したプロジェクトフォルダ構造を生成する任務を担っています。

**生成するフォルダ構造**

feature-request-board/
├── docs/
│   ├── specs/                  # 【SSOT】仕様書
│   │   ├── domain-model.md     # ドメインモデル定義
│   │   ├── api-specs.md        # API仕様
│   │   ├── db-schema.md        # DBスキーマ
│   │   ├── glossary.md         # 用語集
│   │   ├── project-rules.md    # プロジェクトルール
│   │   └── adrs/               # アーキテクチャ決定記録
│   │
│   ├── stories/                # ストーリー単位の作業
│   │   ├── story-000-setup/    # 初期セットアップ
│   │   │   └── vision.md
│   │   └── story-XXX-name/     # 各機能ストーリー
│   │       ├── requirement.md
│   │       ├── plan.md
│   │       ├── design.md
│   │       ├── wireframes.md   # UIワイヤーフレーム
│   │       └── context.json    # コンテキスト管理
│   │
│   └── guidelines/             # 開発ガイドライン
│       └── test-guidelines.md
│
├── src/                        # ソースコード
│   ├── app/                    # Next.js App Router
│   ├── components/             # UIコンポーネント
│   ├── lib/                    # ユーティリティ
│   └── types/                  # 型定義
│
├── tests/                      # テストコード
├── .env.example
├── README.md
└── AGENTS.md                   # AIアシスタント用メモリ

**プロセス**
1. 上記のフォルダ構造を作成
2. 各ファイルに最小限のテンプレートを配置
3. 構造確認後に報告

**入力**
- `docs/stories/story-000-setup/vision.md` : プロジェクトビジョン

**成果物**
- プロジェクトルートにフォルダ構造を生成

3.2 AGENTS.md 生成（入力プロンプトの例）

AGENTS.mdはAIの「長期記憶」として機能します。プロジェクトルール、参照すべきドキュメント、現在のステータスを記載することで、AIが一貫した判断を下せるようになります。

**あなたの役割**
あなたは経験豊富なソフトウェアエンジニアです。
プロジェクト専用のAIメモリファイル（AGENTS.md）を生成する任務を担っています。

**テンプレート**

# Feature Request Board - AIアシスタント用メモリ

## プロジェクト概要
Feature Request投票ボードサイト - ユーザーの機能要望を収集・投票で可視化

## フォルダ構成
[上記のフォルダ構造を記載]

## 参照必須ドキュメント
- `docs/specs/glossary.md` : プロジェクト用語
- `docs/specs/project-rules.md` : 命名規則、コーディング規約
- `docs/guidelines/test-guidelines.md` : テスト方針

## 作業ルール
1. **計画先行**: 作業前に計画を立て、承認後に実行
2. **3案提示**: 計画・提案時は3つの選択肢を提示
3. **仕様書優先**: 実装前に関連仕様書を確認・更新
4. **context.json更新**: 機能実装完了時にcontext.jsonを更新

## 現在のステータス
- フェーズ: Phase 1 - プロジェクト初期化
- 進行中ストーリー: story-000-setup

**成果物**
- `AGENTS.md` : プロジェクトルートに配置

---

4. Phase 2: 要件定義・ドメインモデリング

「何を作るか」を詳細に定義するフェーズです。ユーザーストーリー、UIワイヤーフレーム、ドメインモデルの3つを作成し、実装の土台を固めます。技術に依存しない設計を心がけることで、後から技術選定を変更しても影響を最小限に抑えられます。

4.1 ユーザーストーリー自動生成（入力プロンプトの例）

人間は「ビジョンを読んでストーリーを生成して」と伝えるだけ。AIがビジョンを分析し、必要なストーリーを特定して、自動的にフォルダ分けとファイル生成を行います。

人間が入力する（入力プロンプトの例）

vision.md を読み込んで、MVPに必要なユーザーストーリーを自動生成してください。
ストーリー毎にフォルダを分けて、requirement.md を作成してください。

AIが参照する詳細指示（AGENTS.md に事前設定）

## ユーザーストーリー自動生成ルール

### トリガー
「ユーザーストーリーを生成」「ストーリーを作成」等のリクエストを受けた場合、
以下のプロセスを自動実行します。

### 自動実行プロセス

**Step 1: ビジョン分析**
1. `docs/stories/story-000-setup/vision.md` を読み込む
2. MVP機能リストを抽出
3. 各機能をユーザーストーリー単位に分割
4. 優先度（Must/Should/Could）を判定
5. ストーリー間の依存関係を特定

**Step 2: ストーリー分割案の提示**
分析結果を以下の形式で提示し、人間の承認を得る：

【ストーリー分割案】

| # | ストーリー名 | 優先度 | 依存先 |
|---|-------------|--------|--------|
| 001 | {機能名} | Must | なし |
| 002 | {機能名} | Must | 001 |
| ... | ... | ... | ... |

この分割案でよろしいですか？（承認/修正）

**Step 3: フォルダ・ファイル自動生成（承認後）**
承認を受けたら、以下を自動生成：

docs/stories/
├── story-000-setup/
│   └── user-stories-overview.md  ← 全体サマリ（自動生成）
│
├── story-001-{name}/             ← 自動作成
│   ├── requirement.md            ← 自動生成
│   └── context.json              ← 初期状態で生成
│
├── story-002-{name}/
│   ├── requirement.md
│   └── context.json
│
└── ...（ストーリー数だけ繰り返し）

自動生成ファイルの内容

requirement.md テンプレート

# Story-{NNN}: {ストーリー名}

## 概要
{ビジョンから抽出した機能説明}

## ユーザーストーリー
「{ペルソナ}として、{目的}したい。なぜなら{理由}だからだ。」

## 受け入れ基準
### AC-1: {基準名}
- Given: {前提条件}
- When: {操作}
- Then: {期待結果}

### AC-2: {基準名}
- Given: ...

## 優先度・見積もり
- 優先度: {Must/Should/Could}
- 見積もり: {S/M/L}

## 依存関係
- 依存先: {story-XXX または なし}
- 依存元: {story-XXX または なし}

## 備考
{補足事項があれば記載}

context.json 初期状態

{
  "feature_id": "{NNN}-{name}",
  "user_story_path": "docs/stories/story-{NNN}-{name}/requirement.md",
  "related_user_stories": [],
  "related_code": {},
  "new_files": [],
  "modified_files": [],
  "status": "not_started",
  "started_at": null,
  "completed_at": null
}

命名規則

• ストーリー番号: 3桁ゼロ埋め（001, 002, …）
• フォルダ名: story-{NNN}-{機能名のkebab-case}
• 例: story-001-request-posting, story-002-voting

追加ファイル生成の判断

ストーリーの性質	追加で生成するファイル
UI・画面を含む	wireframes.md（後続プロンプトで生成）
外部API連携あり	context.json に external_apis を記載

実行例

人間の入力（入力プロンプトの例）

vision.md を読んでユーザーストーリーを自動生成して。

AIの動作フロー

**AIの応答 Step 1（分析結果の提示）:**

vision.md を分析しました。以下のストーリー分割を提案します。

【ストーリー分割案】

| # | ストーリー名 | 概要 | 優先度 | 依存先 |
|---|-------------|------|--------|--------|
| 001 | リクエスト投稿 | 新規リクエストを投稿 | Must | なし |
| 002 | 投票機能 | リクエストに投票 | Must | 001 |
| 003 | 一覧表示 | リクエスト一覧とフィルタ | Must | 001 |
| 004 | ステータス管理 | 管理者によるステータス変更 | Must | 003 |
| 005 | ユーザー認証 | ログイン・ユーザー管理 | Should | なし |

この分割案で進めてよろしいですか？
- 承認 → フォルダ・ファイルを自動生成します
- 修正 → 変更点を教えてください

**人間の応答**
承認

**AIの応答 Step 2（自動生成実行）**

ストーリーフォルダとファイルを自動生成しました。

【生成されたフォルダ構造】
docs/stories/
├── story-000-setup/
│   ├── vision.md（既存）
│   └── user-stories-overview.md ✅ 新規作成
│
├── story-001-request-posting/ ✅ 新規作成
│   ├── requirement.md
│   └── context.json
│
├── story-002-voting/ ✅ 新規作成
│   ├── requirement.md
│   └── context.json
│
├── story-003-list-view/ ✅ 新規作成
│   ├── requirement.md
│   └── context.json
│
├── story-004-status-management/ ✅ 新規作成
│   ├── requirement.md
│   └── context.json
│
└── story-005-user-auth/ ✅ 新規作成
    ├── requirement.md
    └── context.json

【次のステップ】
1. 各 requirement.md の内容を確認・修正
2. UI関連ストーリー（001, 003）の wireframes.md を生成
3. ドメインモデル設計へ進む

予想出力: user-stories-overview.md

# ユーザーストーリー概要

## ストーリー一覧

| ID | ストーリー名 | 優先度 | 見積もり |
|—-|————-|——–|———|
| 001 | リクエスト投稿機能 | Must | M |
| 002 | 投票機能 | Must | S |
| 003 | 一覧表示・フィルタ | Must | M |
| 004 | ステータス管理 | Must | S |
| 005 | ユーザー認証 | Should | M |

## 依存関係図mermaid
graph TD
A[story-001: リクエスト投稿] –> B[story-002: 投票機能]
A –> C[story-003: 一覧表示]
B –> C
C –> D[story-004: ステータス管理]
E[story-005: ユーザー認証] –> A
E –> B

style A fill:#ff9999
style B fill:#ff9999
style C fill:#ff9999
style D fill:#ff9999
style E fill:#ffcc99
## MVP開発順序

1. **Phase 1**: story-001（投稿）→ story-003（一覧）
2. **Phase 2**: story-002（投票）→ story-004（ステータス）
3. **Phase 3**: story-005（認証）※オプション

予想出力: story-001-request-posting/requirement.md

# Story-001: リクエスト投稿機能

## 概要
ユーザーが新しい機能リクエストを投稿できる機能。タイトル、詳細説明、カテゴリを入力して送信する。

## ユーザーストーリー
「SaaSプロダクトのユーザーとして、欲しい機能をリクエストしたい。なぜなら自分の要望を開発チームに伝え、プロダクト改善に貢献したいからだ。」

## 受け入れ基準

### AC-1: 新規リクエストの投稿
– Given: ユーザーがトップページにアクセスしている
– When: 「新規リクエスト」ボタンをクリックし、タイトル・詳細を入力して「投稿」を押す
– Then: リクエストが保存され、一覧に表示される

### AC-2: 入力バリデーション
– Given: ユーザーが投稿フォームを開いている
– When: タイトルを空欄のまま「投稿」を押す
– Then: エラーメッセージが表示され、投稿されない

### AC-3: カテゴリ選択
– Given: ユーザーが投稿フォームを開いている
– When: カテゴリドロップダウンをクリックする
– Then: 定義済みカテゴリ一覧が表示され、選択できる

## 優先度・見積もり
– 優先度: Must
– 見積もり: M（3-5日）

## 依存関係
– 依存先: なし（最初に実装するストーリー）
– 依存元: story-002-voting, story-003-list-view

## 備考
– MVP段階では認証なしで投稿可能とする
– 画像添付機能は将来対応

予想出力: story-001-request-posting/context.json（初期状態）

json
{
"feature_id": "001-request-posting",
"user_story_path": "docs/stories/story-001-request-posting/requirement.md",
"related_user_stories": [],
"related_code": {},
"new_files": [],
"modified_files": [],
"status": "not_started",
"started_at": null,
"completed_at": null
}

4.2 UIワイヤーフレーム生成（入力プロンプトの例）

UIの構成をAIに生成させる際は、アスキーアートとMermaid図を組み合わせると効果的です。成果物パスは指定せず、AIがルールに従って自動配置します。

**あなたの役割**
あなたはUI/UXデザイナーです。
Feature Request投票ボードのUIワイヤーフレームを作成してください。

**重要な制約**
- **ソースコードは出力しないでください**
- アスキーアート形式でワイヤーフレームを表現してください
- 画面遷移はMermaid図で表現してください

**プロジェクトルールの参照**
- `AGENTS.md` : ファイル配置ルール
- `docs/specs/project-rules.md` : 命名規則

**要件**

作成する画面:
1. トップページ（リクエスト一覧）
2. リクエスト詳細ページ
3. 新規リクエスト投稿フォーム
4. 管理者用ステータス管理画面

各画面で表現する要素:
- ヘッダー/ナビゲーション
- メインコンテンツエリア
- 主要なUI要素（ボタン、入力欄、カード等）
- レスポンシブ時の変化点（Desktop/Mobile）

**入力**
- `docs/stories/story-000-setup/vision.md`
- `docs/stories/story-000-setup/user-stories-overview.md`

**生成指示**
UI関連のストーリーフォルダ内に wireframes.md を自動生成してください。

予想出力: wireframes.md

# UIワイヤーフレーム: リクエスト一覧・投稿

## 1. トップページ（リクエスト一覧）

### Desktop版 (1024px以上)
┌─────────────────────────────────────────────────────────────────┐
│ 🗳️ Feature Request Board [ログイン] [新規リクエスト] │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 🔍 キーワード検索… │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ [すべて] [検討中] [開発中] [完了] ソート: [人気順 ▼] │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ┌───┐ │ │
│ │ │ 42│ ダークモード対応をお願いします │ │
│ │ │ ▲ │ 目が疲れるので夜間モードが欲しいです… │ │
│ │ └───┘ 🏷️ UI改善 📅 2日前 💬 5件 │ │
│ │ [検討中] │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ┌───┐ │ │
│ │ │ 28│ Slack連携機能 │ │
│ │ │ ▲ │ 新着通知をSlackで受け取りたい… │ │
│ │ └───┘ 🏷️ 連携 📅 1週間前 💬 3件 │ │
│ │ [開発中] │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ┌───┐ │ │
│ │ │ 15│ CSVエクスポート │ │
│ │ │ ▲ │ データをダウンロードしたい… │ │
│ │ └───┘ 🏷️ データ管理 📅 2週間前 💬 1件 │ │
│ │ [完了] ✅ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ [< 前へ] 1 / 5 [次へ >] │
│ │
└─────────────────────────────────────────────────────────────────┘
### Mobile版 (375px)
┌─────────────────────────┐
│ 🗳️ FR Board [≡] │
├─────────────────────────┤
│ 🔍 検索… │
├─────────────────────────┤
│ [すべて][検討中][開発中]│
│ ソート: [人気順 ▼] │
├─────────────────────────┤
│ ┌─────────────────────┐ │
│ │ ▲ 42 ダークモード │ │
│ │ 対応をお願い │ │
│ │ 🏷️UI 📅2日前 [検討中]│ │
│ └─────────────────────┘ │
│ ┌─────────────────────┐ │
│ │ ▲ 28 Slack連携機能 │ │
│ │ │ │
│ │ 🏷️連携 📅1週間前 │ │
│ │ [開発中] │ │
│ └─────────────────────┘ │
│ … │
├─────────────────────────┤
│ [➕ 新規リクエスト] │
└─────────────────────────┘
## 2. 新規リクエスト投稿モーダル
┌─────────────────────────────────────────────────┐
│ 新規リクエスト投稿 [✕] │
├─────────────────────────────────────────────────┤
│ │
│ タイトル │
│ ┌─────────────────────────────────────────┐ │
│ │ 機能リクエストのタイトルを入力… │ │
│ └─────────────────────────────────────────┘ │
│ │
│ 詳細説明 │
│ ┌─────────────────────────────────────────┐ │
│ │ │ │
│ │ どのような機能が欲しいですか？ │ │
│ │ なぜその機能が必要ですか？ │ │
│ │ │ │
│ │ │ │
│ └─────────────────────────────────────────┘ │
│ │
│ カテゴリ │
│ ┌─────────────────────────────────────────┐ │
│ │ UI改善 ▼ │ │
│ └─────────────────────────────────────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────────┐ │
│ │ キャンセル │ │ 投稿する │ │
│ └─────────────────┘ └─────────────────────┘ │
│ │
└─────────────────────────────────────────────────┘
## 3. 画面遷移図mermaid
stateDiagram-v2
[] –> トップページ

トップページ –> リクエスト詳細: カードクリック
トップページ –> 投稿モーダル: 新規投稿ボタン
トップページ –> ログイン: ログインボタン

投稿モーダル –> トップページ: 投稿完了/キャンセル

リクエスト詳細 –> トップページ: 戻る
リクエスト詳細 –> 投票完了: 投票ボタン
投票完了 –> リクエスト詳細: 自動

ログイン –> トップページ: 認証成功

state 管理者フロー {
[] –> 管理画面
管理画面 –> ステータス変更
ステータス変更 –> 管理画面
}

トップページ –> 管理画面: 管理者メニュー
## 4. コンポーネント構成図mermaid
graph TD
subgraph Layout
A[Header]
B[Footer]
end

subgraph Pages
C[TopPage]
D[RequestDetailPage]
E[AdminPage]
end

subgraph Components
F[RequestCard]
G[VoteButton]
H[StatusBadge]
I[CategoryFilter]
J[SortSelector]
K[SearchBar]
L[RequestForm]
M[Pagination]
end

C –> F
C –> I
C –> J
C –> K
C –> M

F –> G
F –> H

D –> G
D –> H

E –> H
## 5. UIコンポーネント仕様

### RequestCard コンポーネント

| 要素 | 説明 | インタラクション |
|——|——|—————–|
| 投票数 | 現在の投票数を表示 | – |
| 投票ボタン | ▲アイコン | クリックで投票/取消 |
| タイトル | リクエストのタイトル | クリックで詳細へ |
| 説明（抜粋） | 最大100文字 | – |
| カテゴリタグ | カテゴリ名 | クリックでフィルタ |
| 投稿日 | 相対時間表示 | – |
| ステータスバッジ | 色分け表示 | – |

### ステータスバッジの色定義

| ステータス | 背景色 | 文字色 |
|———–|——–|——–|
| 検討中 | #FEF3C7 | #92400E |
| 開発中 | #DBEAFE | #1E40AF |
| 完了 | #D1FAE5 | #065F46 |
| 却下 | #FEE2E2 | #991B1B |

4.3 ドメインモデル設計（入力プロンプトの例）

ドメインモデルは「ビジネスロジックの設計図」です。RDBやNoSQLといった具体的な技術に依存せず、エンティティ、値オブジェクト、集約といった概念レベルで設計することで、技術選定の自由度を保ちます。

**あなたの役割**
あなたは経験豊富なソフトウェアアーキテクトであり、DDD実践者です。
技術に依存しないドメインモデル（理想の設計図）を作成する任務を担っています。

**重要な制約**
- **ソースコードは一切出力しないでください**
- **特定の技術（RDB/NoSQL等）を前提としないでください**
- Mermaid記法でクラス図・関係図を作成してください

**設計項目**

1. **エンティティ（Entity）**
   - FeatureRequest（機能リクエスト）
   - Vote（投票）
   - User（ユーザー）
   - Category（カテゴリ）

2. **値オブジェクト（Value Object）**
   - RequestStatus（ステータス）
   - VoteCount（投票数）

3. **集約（Aggregate）**
   - FeatureRequest集約（ルート: FeatureRequest）
   - User集約（ルート: User）

4. **ドメインイベント**
   - RequestCreated
   - VoteCast
   - StatusChanged

**入力**
- `docs/stories/story-000-setup/user-stories-overview.md`
- `docs/specs/glossary.md`

**成果物**
- `docs/specs/domain-model.md` : ドメインモデル定義

予想出力: domain-model.md

# ドメインモデル定義

## 1. エンティティ・値オブジェクト一覧

### エンティティ

| エンティティ名 | 説明 | 識別子 |
|—————|——|——–|
| FeatureRequest | 機能リクエスト | requestId |
| User | システム利用者 | userId |
| Category | リクエストの分類 | categoryId |

### 値オブジェクト

| 値オブジェクト名 | 説明 | 属性 |
|—————–|——|——|
| RequestStatus | リクエストの状態 | status: enum |
| VoteCount | 投票数の集計 | count: number |
| Vote | 投票情報 | requestId, voterId, createdAt |

## 2. クラス図mermaid
classDiagram
class FeatureRequest {
+RequestId id
+String title
+String description
+CategoryId categoryId
+UserId authorId
+RequestStatus status
+VoteCount voteCount
+DateTime createdAt
+DateTime updatedAt
+castVote(userId)
+cancelVote(userId)
+changeStatus(newStatus)
}

class User {
+UserId id
+String email
+String displayName
+UserRole role
+DateTime createdAt
+createRequest(title, description, categoryId)
+vote(requestId)
}

class Category {
+CategoryId id
+String name
+String color
+Int sortOrder
}

class Vote {
<>
+RequestId requestId
+UserId voterId
+DateTime createdAt
}

class RequestStatus {
<>
+StatusType status
+isTransitionAllowed(newStatus)
}

class VoteCount {
<>
+Int count
+increment()
+decrement()
}

FeatureRequest “1” –> “” Vote : has
FeatureRequest “1” –> “1” RequestStatus : has
FeatureRequest “1” –> “1” VoteCount : has
FeatureRequest “” –> “1” Category : belongs to
FeatureRequest “” –> “1” User : authored by
Vote “” –> “1” User : cast by
## 3. 集約境界図mermaid
graph TB
subgraph FeatureRequest集約
FR[FeatureRequest
集約ルート]
V[Vote]
RS[RequestStatus]
VC[VoteCount]
FR –> V
FR –> RS
FR –> VC
end

subgraph User集約
U[User
集約ルート]
end

subgraph Category集約
C[Category
集約ルート]
end

FR -.-> U
FR -.-> C
V -.-> U

style FR fill:#f9f,stroke:#333
style U fill:#f9f,stroke:#333
style C fill:#f9f,stroke:#333
## 4. ステータス遷移図mermaid
stateDiagram-v2
[] –> 検討中: 投稿時
検討中 –> 開発中: 開発決定
検討中 –> 却下: 却下
開発中 –> 完了: リリース
開発中 –> 検討中: 差し戻し
完了 –> []
却下 –> [*]
## 5. ドメインイベント

| イベント名 | トリガー | ペイロード |
|———–|———|———–|
| RequestCreated | 新規リクエスト投稿時 | requestId, title, authorId |
| VoteCast | 投票時 | requestId, voterId |
| VoteCanceled | 投票取消時 | requestId, voterId |
| StatusChanged | ステータス変更時 | requestId, oldStatus, newStatus |

## 6. ビジネスルール

### 投票ルール
– 1ユーザーは1リクエストに対して1票のみ投票可能
– 自分が投稿したリクエストにも投票可能
– 投票は取り消し可能

### ステータス遷移ルール
– 「検討中」→「開発中」「却下」のみ遷移可能
– 「開発中」→「完了」「検討中（差し戻し）」のみ遷移可能
– 「完了」「却下」からの遷移は不可

### 投稿ルール
– タイトルは必須、3〜100文字
– 説明は必須、10〜2000文字
– カテゴリは任意（未指定時は「その他」）

---

5. Phase 3: アーキテクチャ設計・技術スタック選定

Phase 2で設計したドメインモデルを「どう実現するか」を決めるフェーズです。アーキテクチャパターンと技術スタックを選定し、ADR（アーキテクチャ決定記録）として残すことで、将来の判断材料にします。

5.1 アーキテクチャ設計（入力プロンプトの例）

小規模Webアプリでは、複雑なアーキテクチャは過剰になりがちです。ドメインモデルを歪めない範囲で、最もシンプルな構成を選ぶことが重要です。

**あなたの役割**
あなたは経験豊富なソフトウェアアーキテクトです。
ドメインモデルを実現するための最適なアーキテクチャを設計する任務を担っています。

**重要な制約**
- **ソースコードは一切出力しないでください**
- **ドメインモデルを歪めないアーキテクチャを設計してください**
- 小規模Webアプリに適したシンプルな構成を優先してください

**入力**
- `docs/specs/domain-model.md`
- `docs/stories/story-000-setup/vision.md`（制約: 個人開発、低コスト）

**検討項目**
1. アーキテクチャパターン（レイヤード/クリーン/シンプルMVC）
2. システム構成（モノリス推奨）
3. フロントエンド/バックエンドの分離方針

**成果物**
- `docs/specs/architecture.md`

予想出力: architecture.md（抜粋）

# アーキテクチャ設計書

## 1. アーキテクチャパターン選定

### 選定: シンプルレイヤードアーキテクチャ

小規模Webアプリのため、過度に複雑なアーキテクチャは採用せず、
実用的なレイヤー分離を行います。mermaid
graph TB
subgraph Presentation Layer
UI[React Components]
Pages[Next.js Pages/App Router]
end

subgraph Application Layer
API[API Routes]
Actions[Server Actions]
end

subgraph Domain Layer
Entities[Entities]
Services[Domain Services]
end

subgraph Infrastructure Layer
DB[Database Client]
Auth[Auth Provider]
end

UI –> Pages
Pages –> API
Pages –> Actions
API –> Services
Actions –> Services
Services –> Entities
Services –> DB
Services –> Auth
## 2. システム構成

### Full-Stack Next.js モノリスmermaid
graph LR
subgraph Vercel
A[Next.js App]
B[API Routes]
C[Server Actions]
end

subgraph Supabase
D[(PostgreSQL)]
E[Auth]
F[Storage]
end

User –> A
A –> B
A –> C
B –> D
C –> D
B –> E
C –> E
### 選定理由
- 個人開発に適したシンプルな構成
- Vercel + Supabase で無料枠内運用可能
- デプロイ・運用の手間を最小化

5.2 技術スタック選定（入力プロンプトの例）

技術選定では「なぜその技術を選んだか」を比較表形式で整理します。コスト、学習曲線、エコシステムの成熟度などを考慮し、プロジェクトの制約に最も適した選択を行います。

**あなたの役割**
あなたは経験豊富なソリューションアーキテクトです。
設計したアーキテクチャを実現するための最適な技術スタックを選定する任務を担っています。

**重要な制約**
- **ソースコードは一切出力しないでください**
- 個人開発・低コストの制約を考慮してください
- 比較表形式で整理してください

**入力**
- `docs/specs/architecture.md`
- 制約: 個人開発、無料〜低コスト、モダンな技術

**成果物**
- `docs/specs/tech-stack.md`
- `docs/specs/adrs/adr-001-tech-stack.md`

予想出力: tech-stack.md

# 技術スタック定義

## 推奨構成

| カテゴリ | 技術 | 理由 |
|———|——|——|
| フレームワーク | Next.js 14 (App Router) | フルスタック、Server Actions対応 |
| 言語 | TypeScript | 型安全性、開発効率 |
| スタイリング | Tailwind CSS | 迅速なUI構築 |
| UIコンポーネント | shadcn/ui | 高品質、カスタマイズ可能 |
| データベース | Supabase (PostgreSQL) | 無料枠充実、Auth統合 |
| ORM | Prisma | 型安全、マイグレーション管理 |
| 認証 | Supabase Auth | DB統合、ソーシャルログイン |
| ホスティング | Vercel | 無料枠、Next.js最適化 |
| テスト | Vitest + Playwright | 高速、モダン |

## インフラ構成図mermaid
graph TB
subgraph Client
Browser[Browser/Mobile]
end

subgraph Vercel[“Vercel (Free Tier)”]
Edge[Edge Network]
App[Next.js App]
end

subgraph Supabase[“Supabase (Free Tier)”]
Auth[Auth Service]
DB[(PostgreSQL)]
Realtime[Realtime]
end

Browser –> Edge
Edge –> App
App –> Auth
App –> DB
DB –> Realtime
Realtime –> Browser
## コスト見積もり

| サービス | 無料枠 | 想定使用量 | 月額コスト |
|———|——–|———–|———–|
| Vercel | 100GB帯域 | 〜10GB | $0 |
| Supabase | 500MB DB, 50K Auth | 〜100MB, 〜1K | $0 |
| **合計** | – | – | **$0** |

---

6. Phase 4: 開発環境セットアップ

Phase 3で選定した技術スタックを実際にインストールし、開発を始められる状態にするフェーズです。人間は「インストールして」と伝えるだけで、AIがtech-stack.mdを読み取り、必要なパッケージと設定を自動で構築します。

6.1 技術スタックインストール（入力プロンプトの例）

人間が入力するプロンプト

tech-stack.md に基づいて、プロジェクトの初期セットアップとパッケージインストールを実行してください。

AIが参照する詳細指示（AGENTS.md に事前設定）

## 技術スタックインストールルール

### トリガー
「インストール」「セットアップ」「環境構築」等のリクエストを受けた場合、
以下のプロセスを自動実行します。

### 自動実行プロセス

**Step 1: tech-stack.md 読み込み・分析**
1. `docs/specs/tech-stack.md` を読み込む
2. インストールが必要なパッケージを抽出
3. インストール順序を決定（依存関係考慮）

**Step 2: インストール計画の提示**
以下の形式で計画を提示し、人間の承認を得る：

【インストール計画】

1. プロジェクト初期化
   - Next.js プロジェクト作成（TypeScript）

2. 主要パッケージ
   - Tailwind CSS
   - Prisma
   - その他...

3. 開発ツール
   - ESLint
   - Prettier
   - その他...

4. 設定ファイル生成
   - .env.example
   - .gitignore
   - tsconfig.json（カスタマイズ）

この計画で進めてよろしいですか？（承認/修正）

**Step 3: インストール実行（承認後）**
承認を受けたら、以下を順次実行：
1. プロジェクト初期化コマンド
2. パッケージインストール
3. 設定ファイル生成・カスタマイズ
4. 動作確認（dev server起動テスト）

実行例

**人間の入力（入力プロンプトの例）**
tech-stack.md を読んで環境構築して。

AIの動作フロー

**AIの応答 Step 1（インストール計画の提示）**
tech-stack.md を分析しました。以下のインストール計画を提案します。

【インストール計画】
## 1. プロジェクト初期化
npx create-next-app@latest feature-request-board \
  --typescript \
  --tailwind \
  --eslint \
  --app \
  --src-dir \
  --import-alias "@/*"
## 2. 主要パッケージ

| パッケージ | バージョン | 用途 |
|-----------|-----------|------|
| @prisma/client | latest | DBクライアント |
| prisma | latest (dev) | ORM・マイグレーション |
| @supabase/supabase-js | latest | Supabase連携 |
| zod | latest | バリデーション |
| react-hook-form | latest | フォーム管理 |

npm install @prisma/client @supabase/supabase-js zod react-hook-form
npm install -D prisma

## 3. UIコンポーネント（shadcn/ui）
npx shadcn-ui@latest init
npx shadcn-ui@latest add button card input textarea select badge

## 4. 開発ツール

| ツール | 用途 |
|--------|------|
| prettier | コードフォーマット |
| prettier-plugin-tailwindcss | Tailwindクラス整列 |
| @testing-library/react | コンポーネントテスト |
| vitest | テストランナー |
| playwright | E2Eテスト |

npm install -D prettier prettier-plugin-tailwindcss
npm install -D vitest @testing-library/react @vitejs/plugin-react jsdom
npm install -D @playwright/test

## 5. 設定ファイル生成

| ファイル | 内容 |
|---------|------|
| .env.example | 環境変数テンプレート |
| .prettierrc | Prettier設定 |
| vitest.config.ts | Vitest設定 |
| prisma/schema.prisma | DB スキーマ初期化 |

この計画で進めてよろしいですか？
- 承認 → インストールを実行します
- 修正 → 変更点を教えてください

**人間の応答**
承認

**AIの応答 Step 2（インストール実行）**

インストールを実行しています...

### 1/5 プロジェクト初期化 ✅
npx create-next-app@latest feature-request-board --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"
→ 完了

### 2/5 主要パッケージインストール ✅
npm install @prisma/client @supabase/supabase-js zod react-hook-form
npm install -D prisma
→ 完了

### 3/5 shadcn/ui セットアップ ✅
npx shadcn-ui@latest init
# 選択: Default style, Slate color, CSS variables: Yes
npx shadcn-ui@latest add button card input textarea select badge dialog form label
→ 完了

### 4/5 開発ツールインストール ✅
npm install -D prettier prettier-plugin-tailwindcss
npm install -D vitest @testing-library/react @vitejs/plugin-react jsdom
npm install -D @playwright/test
npx playwright install
→ 完了

### 5/5 設定ファイル生成 ✅

**生成されたファイル**

`.env.example`:
# Database (Supabase)
DATABASE_URL="postgresql://user:password@host:5432/dbname"
DIRECT_URL="postgresql://user:password@host:5432/dbname"

# Supabase
NEXT_PUBLIC_SUPABASE_URL="https://xxx.supabase.co"
NEXT_PUBLIC_SUPABASE_ANON_KEY="your-anon-key"
SUPABASE_SERVICE_ROLE_KEY="your-service-role-key"

# App
NEXT_PUBLIC_APP_URL="http://localhost:3000"

`.prettierrc`:
```json
{
  "semi": false,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "plugins": ["prettier-plugin-tailwindcss"]
}

`vitest.config.ts`:
import { defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom',
    globals: true,
    setupFiles: ['./tests/setup.ts'],
  },
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
})

`prisma/schema.prisma`:
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider  = "postgresql"
  url       = env("DATABASE_URL")
  directUrl = env("DIRECT_URL")
}

// モデルは Phase 5 で追加

---

## 環境構築完了

【生成されたプロジェクト構造】
feature-request-board/
├── src/
│   ├── app/
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   └── globals.css
│   ├── components/
│   │   └── ui/          # shadcn/ui
│   └── lib/
│       └── utils.ts
├── prisma/
│   └── schema.prisma
├── tests/
│   └── setup.ts
├── .env.example
├── .prettierrc
├── vitest.config.ts
├── tailwind.config.ts
├── tsconfig.json
├── package.json
└── README.md

【動作確認】
npm run dev
# → http://localhost:3000 でアクセス可能

【次のステップ】
1. `.env.example` をコピーして `.env.local` を作成
2. Supabase プロジェクトを作成し、環境変数を設定
3. `docs/specs/project-rules.md` を生成（次のプロンプト）

予想出力: package.json（主要部分）

json
{
"name": "feature-request-board",
"version": "0.1.0",
"private": true,
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"lint": "next lint",
"format": "prettier --write .",
"test": "vitest",
"test:e2e": "playwright test",
"db:generate": "prisma generate",
"db:push": "prisma db push",
"db:migrate": "prisma migrate dev",
"db:studio": "prisma studio"
},
"dependencies": {
"@prisma/client": "^5.x.x",
"@supabase/supabase-js": "^2.x.x",
"next": "14.x.x",
"react": "^18.x.x",
"react-dom": "^18.x.x",
"react-hook-form": "^7.x.x",
"zod": "^3.x.x"
},
"devDependencies": {
"@playwright/test": "^1.x.x",
"@testing-library/react": "^14.x.x",
"@types/node": "^20.x.x",
"@types/react": "^18.x.x",
"@vitejs/plugin-react": "^4.x.x",
"eslint": "^8.x.x",
"prettier": "^3.x.x",
"prettier-plugin-tailwindcss": "^0.5.x",
"prisma": "^5.x.x",
"tailwindcss": "^3.x.x",
"typescript": "^5.x.x",
"vitest": "^1.x.x"
}
}

---

6.2 プロジェクトルール・ガイドライン生成（入力プロンプトの例）

project-rules.mdは「AIへの具体的な指示書」です。命名規則、ディレクトリ構造、Git運用ルールを明文化することで、AIが一貫したコードを生成できるようになります。このファイルが充実しているほど、Phase 5での自動生成の精度が向上します。

**あなたの役割**
あなたは経験豊富なテックリードです。
プロジェクト固有のルールとガイドラインを定義する任務を担っています。

**入力**
- `docs/specs/tech-stack.md`
- `docs/specs/architecture.md`

**成果物**
- `docs/specs/project-rules.md` : 命名規則、ディレクトリ構造
- `docs/specs/glossary.md` : 用語集
- `docs/guidelines/test-guidelines.md` : テスト方針

予想出力: project-rules.md（抜粋）

# プロジェクト固有ルール

## 1. ディレクトリ構造
src/
├── app/ # Next.js App Router
│ ├── (auth)/ # 認証が必要なルート
│ ├── (public)/ # 公開ルート
│ ├── api/ # API Routes
│ └── layout.tsx
├── components/
│ ├── ui/ # shadcn/ui コンポーネント
│ ├── features/ # 機能別コンポーネント
│ │ ├── request/ # リクエスト関連
│ │ └── vote/ # 投票関連
│ └── layouts/ # レイアウト
├── lib/
│ ├── db/ # Prisma client
│ ├── auth/ # 認証ユーティリティ
│ └── utils/ # 汎用ユーティリティ
├── types/
│ └── index.ts # 型定義
└── actions/ # Server Actions
## 2. 命名規則

| 対象 | 規則 | 例 |
|——|——|—–|
| コンポーネント | PascalCase | `RequestCard.tsx` |
| ユーティリティ | camelCase | `formatDate.ts` |
| 型定義 | PascalCase | `FeatureRequest` |
| API Route | kebab-case | `api/feature-requests/route.ts` |
| Server Action | camelCase + Action | `createRequestAction.ts` |

## 3. Git運用ルール

### ブランチ戦略: GitHub Flow
main (本番)
└── feature/issue-001-request-posting
└── feature/issue-002-voting
└── fix/issue-010-vote-count-bug
### コミットメッセージ
():

例:
feat(request): リクエスト投稿機能を追加
fix(vote): 投票カウントの不整合を修正
docs(readme): セットアップ手順を追記



---

7. Phase 5: 機能実装とcontext.json管理

いよいよコードを書くフェーズです。人間は「要件」だけを伝え、AIがAGENTS.mdとproject-rules.mdを参照して、適切な場所に適切な命名でファイルを自動生成します。context.jsonで進捗と依存関係を管理することで、複数ストーリーの並行開発も可能になります。

7.1 context.json の役割と構造

context.jsonは各ストーリーの「実装履歴」です。どのファイルを作成・変更したか、どのストーリーに依存しているかを記録することで、AIが過去の実装を正確に把握できます。

context.json は、AI駆動開発において以下の目的で使用します：

1. 進捗追跡: どのユーザーストーリーがどこまで進んでいるか
2. コンテキスト管理: AIが参照すべきファイルの一覧
3. 依存関係の可視化: 関連するストーリーやコードの把握

7.2 機能実装（入力プロンプトの例）

成果物のパスを羅列せず、要件と参照ドキュメントのみ伝えます。AIがルールに従ってファイルを自動生成し、context.jsonで追跡します。これが「要件ベースプロンプト」の核心であり、プロンプトの簡潔さと出力の一貫性を両立させます。

**あなたの役割**
あなたは経験豊富なソフトウェアエンジニアです。
ユーザーストーリー「リクエスト投稿機能」を実装してください。

**プロジェクトルールの参照**
実装前に以下を必ず確認し、ルールに従ってください：
- `AGENTS.md` : フォルダ構成、作業ルール、技術スタック
- `docs/specs/project-rules.md` : 命名規則、ディレクトリ構造
- `docs/guidelines/test-guidelines.md` : テスト方針
- `docs/specs/glossary.md` : 用語集

**参照ドキュメント**
- `docs/specs/domain-model.md` : ドメインモデル
- `docs/specs/architecture.md` : アーキテクチャ設計
- `docs/specs/tech-stack.md` : 技術スタック
- `docs/stories/story-001-request-posting/requirement.md` : 要件定義
- `docs/stories/story-001-request-posting/wireframes.md` : UIワイヤーフレーム

**要件**
1. requirement.md の受け入れ基準を満たす実装を行う
2. wireframes.md に基づいてUIコンポーネントを作成
3. TDDで実装（テストファースト）
4. 実装完了後、context.json を生成
5. 関連する仕様書（api-specs.md, db-schema.md）を更新

**生成指示**
プロジェクトルールに従い、必要なソースコード・テストコード・ドキュメントを自動生成してください。
生成したファイルは context.json に記録してください。

補足: AIが自動生成するためのAGENTS.md追記内容

この内容をAGENTS.mdに追記することで、AIは「実装時にどこに何を配置すべきか」を自動判断できるようになります。ファイル種別ごとの配置ルール、テストコードの配置、context.jsonの自動生成形式を明示しています。

## 機能実装時の自動生成ルール

### ソースコード配置ルール

src/
├── app/                         # Next.js App Router
│   ├── (auth)/                  # 認証必要ルート
│   ├── (public)/                # 公開ルート
│   │   └── {feature}/           # 機能別ページ
│   └── api/
│       └── {resource}/          # リソース別API（kebab-case）
│           └── route.ts
├── components/
│   ├── ui/                      # 汎用UIコンポーネント
│   └── features/
│       └── {feature}/           # 機能別コンポーネント（kebab-case）
│           └── {ComponentName}.tsx  # PascalCase
├── actions/
│   └── {actionName}Action.ts    # camelCase + Action
├── lib/
│   └── db/
│       └── schema.prisma
└── types/
    └── {domain}.ts              # ドメイン別型定義

### テストコード配置ルール
tests/
├── components/
│   └── {ComponentName}.test.tsx  # コンポーネント名と対応
├── actions/
│   └── {actionName}Action.test.ts
└── e2e/
    └── {feature}.spec.ts

### 実装完了時の自動処理
1. **context.json 生成**: ストーリーフォルダ内に作成
2. **仕様書更新**: 新規API → api-specs.md、DB変更 → db-schema.md
3. **AGENTS.md更新**: 現在のステータスを更新

### context.json の自動生成形式
実装完了時、以下の形式で自動生成：
{
  "feature_id": "{NNN}-{feature-name}",
  "user_story_path": "docs/stories/story-{NNN}-{name}/requirement.md",
  "related_user_stories": [/* 依存ストーリーのパス */],
  "related_code": {
    "presentation": { "components": [], "pages": [] },
    "application": { "actions": [], "api_routes": [] },
    "domain": { "types": [] },
    "infrastructure": { "db": [] }
  },
  "new_files": [/* 新規作成ファイル */],
  "modified_files": [/* 変更ファイル */],
  "external_apis": [],
  "status": "completed",
  "started_at": "{ISO8601}",
  "completed_at": "{ISO8601}"
}

7.3 context.json 更新プロンプト（実装完了時）

実装が完了したら必ずcontext.jsonを更新します。ステータスを「completed」に変更し、作成・変更したファイルを記録することで、次のストーリー実装時にAIが正確なコンテキストを把握できます。

**あなたの役割**
あなたは経験豊富なソフトウェアエンジニアです。
ユーザーストーリーの実装が完了したため、context.json を更新する任務を担っています。

**入力**
- `docs/stories/story-001-request-posting/context.json` : 既存のcontext.json
- 実装完了した全ファイルのリスト

**更新内容**
1. `status` を `"completed"` に変更
2. `completed_at` に完了日時を設定
3. `new_files` と `modified_files` を最終確認・更新
4. `related_user_stories` に依存関係を追加（あれば）

**成果物**
- `docs/stories/story-001-request-posting/context.json` : 更新版

**更新後のcontext.json**
```json
{
  "feature_id": "001-request-posting",
  "user_story_path": "docs/stories/story-001-request-posting/requirement.md",
  "related_user_stories": [
    "docs/stories/story-003-list-view/requirement.md"
  ],
  "related_code": {
    "presentation": {
      "components": [
        "src/components/features/request/RequestForm.tsx",
        "src/components/features/request/RequestCard.tsx",
        "src/components/features/request/RequestList.tsx"
      ],
      "pages": [
        "src/app/(public)/page.tsx",
        "src/app/(public)/requests/[id]/page.tsx"
      ]
    },
    "application": {
      "actions": [
        "src/actions/createRequestAction.ts",
        "src/actions/getRequestsAction.ts"
      ],
      "api_routes": [
        "src/app/api/feature-requests/route.ts",
        "src/app/api/feature-requests/[id]/route.ts"
      ]
    },
    "domain": {
      "types": [
        "src/types/index.ts",
        "src/types/request.ts"
      ]
    },
    "infrastructure": {
      "db": [
        "src/lib/db/schema.prisma",
        "prisma/migrations/001_create_requests/"
      ]
    }
  },
  "new_files": [
    "src/components/features/request/RequestForm.tsx",
    "src/components/features/request/RequestCard.tsx",
    "src/components/features/request/RequestList.tsx",
    "src/actions/createRequestAction.ts",
    "src/actions/getRequestsAction.ts",
    "src/app/api/feature-requests/route.ts",
    "src/app/api/feature-requests/[id]/route.ts",
    "src/app/(public)/requests/[id]/page.tsx",
    "src/types/request.ts",
    "prisma/migrations/001_create_requests/",
    "tests/components/RequestForm.test.tsx",
    "tests/components/RequestCard.test.tsx",
    "tests/actions/createRequestAction.test.ts"
  ],
  "modified_files": [
    "src/lib/db/schema.prisma",
    "src/types/index.ts",
    "src/app/(public)/page.tsx",
    "docs/specs/api-specs.md",
    "docs/specs/db-schema.md"
  ],
  "external_apis": [],
  "status": "completed",
  "started_at": "2024-01-15T10:00:00Z",
  "completed_at": "2024-01-16T18:30:00Z"
}

7.4 投票機能実装（入力プロンプトの例）

依存ストーリーがある場合は、そのcontext.jsonを参照するよう指示します。AIは依存先の実装を確認し、既存コンポーネントを適切に拡張・修正します。新規ファイルと変更ファイルを区別して記録することで、差分が明確になります。

**あなたの役割**
あなたは経験豊富なソフトウェアエンジニアです。
ユーザーストーリー「投票機能」を実装してください。

**プロジェクトルールの参照**
- `AGENTS.md` : フォルダ構成、作業ルール
- `docs/specs/project-rules.md` : 命名規則

**依存関係**
このストーリーは story-001 に依存しています。
- `docs/stories/story-001-request-posting/context.json` を参照し、既存実装を確認

**参照ドキュメント**
- `docs/stories/story-002-voting/requirement.md` : 要件定義
- `docs/specs/domain-model.md` : ドメインモデル（投票ルール確認）

**要件**
1. 1ユーザー1票の投票機能を実装
2. 投票の取り消し機能を実装
3. 投票数のリアルタイム表示
4. story-001 の RequestCard に VoteButton を統合

**生成指示**
プロジェクトルールに従い、必要なファイルを自動生成してください。
依存ストーリーで作成済みのファイルは modified_files として context.json に記録してください。

予想されるAIの動作

AIは以下のように自動判断してファイルを生成します：

【AIの思考プロセス】

1. AGENTS.md を確認
   → コンポーネントは src/components/features/{feature}/ に配置
   → Server Actions は src/actions/{name}Action.ts

2. story-001 の context.json を確認
   → RequestCard.tsx が既に存在
   → 投票ボタンを統合するため modified_files に追加

3. 生成ファイルを決定
   - src/components/features/vote/VoteButton.tsx (NEW)
   - src/actions/castVoteAction.ts (NEW)
   - src/actions/cancelVoteAction.ts (NEW)
   - src/app/api/votes/route.ts (NEW)
   - src/types/vote.ts (NEW)
   - tests/components/VoteButton.test.tsx (NEW)
   - src/components/features/request/RequestCard.tsx (MODIFIED)
   - src/lib/db/schema.prisma (MODIFIED)

4. context.json を生成

生成される context.json の例

{
  "feature_id": "002-voting",
  "user_story_path": "docs/stories/story-002-voting/requirement.md",
  "related_user_stories": [
    "docs/stories/story-001-request-posting/requirement.md"
  ],
  "related_code": {
    "presentation": {
      "components": [
        "src/components/features/vote/VoteButton.tsx (NEW)",
        "src/components/features/request/RequestCard.tsx (MODIFIED)"
      ]
    },
    "application": {
      "actions": [
        "src/actions/castVoteAction.ts (NEW)",
        "src/actions/cancelVoteAction.ts (NEW)"
      ],
      "api_routes": [
        "src/app/api/votes/route.ts (NEW)"
      ]
    },
    "domain": {
      "types": [
        "src/types/vote.ts (NEW)"
      ]
    },
    "infrastructure": {
      "db": [
        "src/lib/db/schema.prisma (MODIFIED)",
        "prisma/migrations/002_create_votes/ (NEW)"
      ]
    }
  },
  "new_files": [
    "src/components/features/vote/VoteButton.tsx",
    "src/actions/castVoteAction.ts",
    "src/actions/cancelVoteAction.ts",
    "src/app/api/votes/route.ts",
    "src/types/vote.ts",
    "prisma/migrations/002_create_votes/",
    "tests/components/VoteButton.test.tsx",
    "tests/actions/castVoteAction.test.ts",
    "tests/actions/cancelVoteAction.test.ts"
  ],
  "modified_files": [
    "src/lib/db/schema.prisma",
    "src/components/features/request/RequestCard.tsx",
    "docs/specs/api-specs.md",
    "docs/specs/db-schema.md"
  ],
  "external_apis": [],
  "status": "completed",
  "started_at": "2024-01-17T09:00:00Z",
  "completed_at": "2024-01-17T17:00:00Z"
}

7.5 全体コンテキスト集約プロンプト

複数のストーリーが進行すると、プロジェクト全体の進捗把握が難しくなります。各context.jsonを集約してサマリを作成することで、プロジェクトマネジメントとAIへのコンテキスト提供を両立します。

プロジェクト全体の進捗を把握するために、各ストーリーの context.json を集約します。

**あなたの役割**
あなたはプロジェクトマネージャーです。
全ストーリーの context.json を集約し、プロジェクト全体の進捗レポートを作成する任務を担っています。

**入力**
- `docs/stories/story-001-request-posting/context.json`
- `docs/stories/story-002-voting/context.json`
- `docs/stories/story-003-list-view/context.json`
- `docs/stories/story-004-status-management/context.json`

**成果物**
- `docs/stories/project-context-summary.md` : 全体進捗サマリ

**出力形式**
# プロジェクト進捗サマリ

## ストーリー別ステータス

| Story ID | 名称 | ステータス | 開始日 | 完了日 |
|----------|------|----------|--------|--------|
| 001 | リクエスト投稿 | ✅ completed | 01/15 | 01/16 |
| 002 | 投票機能 | ✅ completed | 01/17 | 01/17 |
| 003 | 一覧表示 | 🔄 in_progress | 01/18 | - |
| 004 | ステータス管理 | ⏳ not_started | - | - |

## 新規作成ファイル一覧（全ストーリー）
[各context.jsonのnew_filesを集約]

## 変更ファイル一覧（全ストーリー）
[各context.jsonのmodified_filesを集約]

8. まとめ

全フェーズを通じて一貫しているのは「人間がWhy/Whatを定義し、AIがHowを実行する」という役割分担です。ルールファイル（AGENTS.md、project-rules.md）を充実させることで、プロンプトはシンプルになり、AIの出力品質は向上します。

AI駆動開発の流れ

本記事のポイント

5つの核心を押さえることで、AI駆動開発を自分のプロジェクトに適用できます。

1. 要件ベースのプロンプト設計: 成果物パスを指定せず、AIがルールを参照して自動生成
2. AGENTS.md / project-rules.md の活用: 自動生成ルールを事前に定義
3. UIワイヤーフレームの活用: アスキーアート + Mermaid図で視覚化
4. context.jsonによるコンテキスト管理: AIが参照すべき情報を構造化
5. 小規模開発への最適化: 開発サイクルにおける不要なフェーズを効率化し、実用的な構成に

本記事が皆さんのAI駆動開発の参考になれば幸いです。