feature-vision

ビジョンドキュメント

概要

焦点を絞った発見フェーズを通じて案内し、確立された機能開発プロセスに沿って各セクションを体系的に作成するための構造化されたコマンドです。

確立された機能開発プロセスに沿ってビジョンドキュメントを作成します。まず、@~/.local/share/dotfiles/ai/guides/feature-development-process.md にある機能開発ガイドを読み、ビジョンドキュメントの構成とアプローチを確認してください。

注：プロジェクトにガイドのローカルコピー（@project/guides/feature-development-process.md）がある場合は、プロジェクト固有の変更を反映したそのファイルを参照してもかまいません。

重要：まず、ビジョンドキュメント作成の5つのフェーズを追跡する TODO リストを作成してください。最初のフェーズを「in_progress」、残りのフェーズを「pending」にしてください。

ビジョンドキュメントの構成

ビジョンドキュメントは簡潔で焦点が明確です。通常は100～150行で、200行を超えることはありません。全般的な内容から具体的な内容へと展開します。

必須セクション：

• 明確なビジョンの表明（1文）
• 目次（主要なすべてのセクションへのリンク付き）
• 問題（何が問題なのか、誰に影響するのか、なぜ重要なのか）
• ソリューション（どのように解決するのか、中核となる理念、主要な機能）
• ユーザーニーズ（役割ごとに、達成する必要があることを簡潔な箇条書きで記載）
• 将来の可能性（概要を簡潔に記載し、別ファイルの future.md を参照）
• スコープ（v1 で提供するものと、対象外のものの具体的な一覧）

ビジョンに含めないもの：

• 詳細なビジネス上の正当性や ROI 計算
• デプロイの詳細（実行場所や方法。これは仕様書の対象です）
• 技術的な実装の詳細（API、スキーマ、アーキテクチャ。これは仕様書の対象です）
• 詳細なユーザーストーリーや受け入れ基準（これは要件の対象です）
• 手順ごとのワークフローやプロセスフロー（これは要件の対象です）
• 同じ情報を繰り返す冗長なセクション

プロセス：次の5つのフェーズを順番に進める

フェーズ1：問題の発見

以下を理解するため、焦点を絞った質問をしてください。

• 具体的にどのような問題を解決するのか。
• 誰がこの問題を経験し、どのような影響を受けるのか。
• 現在の苦痛を伴う手作業のプロセスはどのようなものか。
• 解決しなかった場合、どのような結果になるのか。

質問は1つずつにしてください。回答を待ってから次に進みます。 企業的な言い回しは避けてください。会話のような率直な表現にします。

フェーズ2：ソリューションの検討

以下について質問してください。

• 大まかには、どのように解決するのか。
• 中核となる理念やアプローチは何か。
• 必要な主要機能は何か（3～5個）。
• このソリューションのどこが異なり、優れているのか。

フェーズ3：ユーザーニーズの分析

ビジョンレベルでは、ユーザーの役割を統合して扱います。

• エンドユーザー（すべてのユーザー種別）
• 管理スタッフ（スタッフ、管理者、組織管理者をすべて統合）
• プロダクトチーム（関連する場合）

細かな役割の区別は避けてください。詳細な役割の分類は要件ドキュメントに記載します。

統合した役割ごとに、質問するのは次のことだけです。

• この機能を使って何を達成する必要があるか。

それ以上は質問しないでください。「現在の課題」や「成功によって何が変わるか」は尋ねないでください。問題セクションと重複し、要件に含めるべき内容です。

フェーズ4：将来とスコープの発見

以下について質問してください。

• 将来のフェーズで検討すべき、あると便利な機能は何か。
• v1 に明確に含めるスコープは何か（具体的な内容を確認）。
• v1 に明確に含めないスコープは何か。

重要：v1 で実際に提供するものについて、詳細かつ具体的な情報を確認します。これは要件定義への橋渡しになります。

フェーズ 5：ドキュメントの作成

作成する前に、重複を徹底的に取り除いてください。

• このセクションは、別のセクションの情報を繰り返していませんか？
• このセクションは、問題からすでに明らかなことを正当化しているだけではありませんか？
• これは仕様レベルの詳細（デプロイ、技術アーキテクチャ）ではありませんか？
• これは要件レベルの詳細（詳細なワークフロー、受け入れ基準）ではありませんか？

そのうえで、3つのドキュメントを作成してください。

1. vision.md - 簡潔で焦点の定まったビジョンドキュメント：

• 明確な1文のビジョンステートメントを作成する
• 主要なすべてのセクションへのリンクを含む目次を作成する
• 具体的なスコープのセクションを含めてビジョンドキュメントをまとめる
• 一般的な内容（問題、解決策）から具体的な内容（詳細なスコープ）へと展開する
• 全体を通じて「企業用語を使わない」という原則に従う
• 将来の可能性についての簡潔なセクションから future.md を参照する
• 全体を150行未満に抑える - 徹底的に簡潔にする

2. future.md - 将来の拡張機能の詳細：

• 将来の機能をすべて含む、詳細な future.md ドキュメントを別途作成する
• フェーズごと（フェーズ 2、フェーズ 3 など）に整理する
• 戦略的な将来のビジョン（該当する場合）を含める

3. discussion-summary.md - 継続して更新するディスカッションの要約ドキュメント：

• すべてのフェーズを通じて内容を蓄積していく、統合されたディスカッションの要約を作成する
• ビジョンに関するすべてのディスカッションを含む「Vision Phase」セクションを設ける
• Requirements、Spec、Plan フェーズ用のプレースホルダーセクションを設ける
• 「Key Decisions Log」に、行ったアーキテクチャ上の決定とその理由を記録する
• 技術的な実現可能性に関する議論と実装案を記録する
• 特定された技術的な制約や課題を記録する
• 要件や仕様で取り上げるべき未解決の質問を含める
• 参照したファイルと関連機能を「Technical Context」セクションに追加する
• 明確なセクションと目次で整理する
• このドキュメントは、機能のライフサイクル全体を通じて組織の知見を記録するためのものです

主な原則

一般的な内容から具体的な内容へと展開する： 大まかな問題と解決策から始め、要件へと自然につながる具体的なスコープの詳細で締めくくります。

スコープセクションは重要です： ここには、v1 で提供する内容を具体的なリストとして記載します。機能、ツール、特徴を箇条書きにするイメージです。これがビジョンと要件をつなぎます。

ただし、以下は含めないでください。

• デプロイ方法（ステージングか本番かなど） - これは仕様の領域です
• 技術アーキテクチャの詳細 - これは仕様の領域です
• 含めない項目の理由 - 対象外の項目を挙げるだけにし、説明は不要です

将来の内容を分ける： 将来の機能はすべて、詳細な future.md ドキュメントにまとめます。ビジョンには将来の概要だけを簡潔に記載します。

企業用語を使わない： まず人に伝わることを意識します。明確で簡潔な言葉を使い、専門用語や不必要に複雑な表現は避けます。

ユーザーの役割を集約する： ユーザーの役割はビジョンの段階でまとめます。詳細な役割の内訳は要件に記載します。

重複を取り除く（重要）： 私たちは小規模なチームであり、簡潔で読みやすいドキュメントを大切にしています。各セクションには、新しい情報を必ず含めてください。セクションを追加する前に、「すでに述べた内容を繰り返していないか」と確認します。繰り返している場合は、削除してください。

避けるべき、よくある重複のパターン：

• 問題を企業用語で言い換えただけの「Business Case」
• 問題セクションですでに挙げた課題を繰り返す「Consequences」セクション
• 問題セクションを見れば明らかな場合の「Who This Affects」セクション
• 異なる表現でメリットや価値を列挙する複数のセクション
• ユーザーニーズにおける詳細な「現在の課題」と「成功した状態」の両方の記述（問題セクションですでに説明しています）

短く保つ： ビジョンドキュメントは100～150行以内にします。200行を超える場合は、同じ内容を繰り返しているか、仕様・要件レベルの詳細を含めています。

ガイドライン

• 一度に質問するのは1つだけにし、回答を待ってください
• 各フェーズを完了するたびに、TODO リストを更新してください
• 質問は堅苦しい言い回しを避け、会話調にしてください
• すぐに役立つ情報に焦点を当て、余計な内容は避けてください
• 提供された既存のメモやコンテキストを参照してください
• 実用性を重視してください。私たちは、読みやすく実行可能なドキュメントを大切にする小規模チームです
• 発見フェーズでは、技術的な実現可能性やアーキテクチャについて話し合うのが一般的です。こうした内容はすべて記録してください
• 最後に必ず3つのドキュメントを作成してください：vision.md、future.md、discussion-summary.md

開始手順

1. 5フェーズのTODOリストをただちに作成してください
2. ユーザーに質問してください：「どの機能ディレクトリで作業していますか？フルパスを入力してください（例：project/features/FT033-feature-name）」
3. ユーザーに質問してください：「既存のメモがある場合は、確認できるように @notes.md または @[filename].md の形式でタグ付けしてください」
4. ディレクトリが存在することを確認し、そこに vision.md、future.md、discussion-summary.md を作成することを確認してください
5. タグ付けされたメモファイルを確認してください
6. 最初の問題発見に関する質問をして、フェーズ1を開始してください
7. 質問は簡潔にし、次の質問に進む前に回答を待ってください
8. 会話の中で、vision.mdに直接記載しない内容も含め、技術面やアーキテクチャに関する議論を記録してください

discussion-summary.md に記録する内容

このドキュメントは、機能開発の全フェーズを通じてコンテキストを蓄積する構成にしてください。ビジョンフェーズでは、ドキュメント全体の構成を作成してください：

ドキュメント構成：

# Feature Name: Discussion Summary

Living document capturing technical discussions, research, decisions, and
context from all phases of feature development.

## Table of Contents
- [Vision Phase](#vision-phase)
- [Requirements Phase](#requirements-phase)
- [Spec Phase](#spec-phase)
- [Plan Phase](#plan-phase)
- [Key Decisions Log](#key-decisions-log)
- [Technical Context](#technical-context)

## Vision Phase
[Vision phase content goes here]

## Requirements Phase
*To be added during requirements phase.*

## Spec Phase
*To be added during spec phase.*

## Plan Phase
*To be added during plan phase.*

## Key Decisions Log
| # | Decision | Rationale | Phase |
|---|----------|-----------|-------|
[Decisions from vision phase]

## Technical Context
### Files Referenced
[Backend and frontend files referenced]

### Related Features
[Related feature references]

ビジョンフェーズに含める内容：

• 特定した中心的な問題と、議論したすべての詳細
• 解決策のアプローチと、議論を通じてどのように変化したか
• 技術的な実現可能性に関する議論
• 決定したアーキテクチャとその理由
• 検討した実装案（採用しなかった案も含む）
• 技術選定とその理由（SDK、フレームワーク、プロトコル）
• 特定した技術的制約
• 既存システムとの統合ポイント
• 要件／仕様フェーズに向けた未解決の質問

主要決定事項の記録：

• 決定事項には1から順に番号を付けてください
• 決定事項、理由、フェーズとして「ビジョン」を記載してください
• 後続フェーズでは番号を引き継いでください

技術的なコンテキスト：

• 議論中に参照したファイル（バックエンドとフロントエンドのパス）を一覧にしてください
• 影響を受ける可能性のある関連機能を記録してください

目的： このドキュメントは、機能のライフサイクル全体を通じて、組織の記憶として役立ちます。各フェーズでセクションを追加し、主要決定事項の記録と技術的なコンテキストは全フェーズを通じて蓄積します。