prd-update-progress

vfarcic/dot-ai の shared-prompts/prd-update-progress.md からベンダー提供されたものです（MIT、Copyright (c) 2025 Viktor Farcic）。原著者：Viktor Farcic。

PRD 更新進捗 Slash Command

手順

実装作業の完了状況に基づいて、既存のプロダクト要件ドキュメント（PRD）を更新する作業を支援します。このコマンドは、会話のコンテキストを活用しながら Git のコミットとコード変更を分析して、PRD の完了状況を追跡し、根拠に基づく更新案を提示します。

プロセスの概要

1. 対象 PRD の特定 - 更新する PRD を決定します
2. コンテキスト優先の進捗分析 - まず会話のコンテキストを使用し、次にフォールバックとして Git を分析します
3. 変更内容と PRD 項目の対応付け - 作業内容を要件にインテリジェントに結び付けます
4. 更新案の提示 - チェックボックスの完了や要件の変更を提案します
5. ユーザーによる確認 - 提案を確認し、例外的なケースに対応します
6. PRD の更新 - チェックボックスとステータスに変更を適用します
7. 相違点の指摘 - 実際の作業が計画と異なる場合に通知します
8. 進捗の更新をコミット - 進捗のチェックポイントを保持します
9. 次のタスクへ進む - /prd-next の実行をユーザーに促します

ステップ 1：PRD をスマートに特定する

会話のコンテキストを使用して、対象 PRD を自動的に検出します。

1. 現在の作業コンテキスト：特定の PRD、機能、または問題に関する直近の会話を確認します
2. Git ブランチの分析：現在の Git ブランチに PRD を示す情報（feature/prd-*、課題番号）が含まれているか確認します
3. 最近のファイル操作：prds/ ディレクトリ内で最近変更された PRD ファイルを特定します
4. Todo リストのコンテキスト：TodoWrite ツールに PRD 固有の進行中タスクが表示されているか確認します

検出の優先順位：

• 会話で「PRD #X」または特定の PRD ファイルが明示されている場合 → その PRD を使用します
• Git ブランチに PRD への参照（例：「feature/prd-12-*」）が含まれている場合 → PRD #12 を使用します
• TodoWrite に PRD 固有のタスクが表示されている場合 → その PRD のコンテキストを使用します
• 最近変更された PRD ファイルが 1 つだけの場合 → その PRD を使用します
• 複数の PRD が候補となる場合 → ユーザーに確認します

ステップ 2：コンテキスト優先の進捗分析

優先事項：Git 分析の前に、まず会話のコンテキストを使用します

会話コンテキストの分析（高速 - 先に使用）

直近の会話から作業の完了が明確に分かる場合：

• 最近話し合った実装：「X を完了しました」「Y を実装しました」「Z を構築しました」
• Todo リストのコンテキスト：TodoWrite ツールで完了済み／進行中の項目を確認します
• ファイル作成に関する言及：「ファイル X を作成しました」「機能 Y を追加しました」
• テスト完了に関する言及：「テストに合格しました」「X 個のテストがすべて完了しました」
• ユーザーによる確認：「うまく動作します」「実装が完了しました」「次のステップに進む準備ができました」

会話のコンテキストを利用できる場合は、それを使用します。Git の解析よりも高速で正確です

Git 変更の分析（フォールバック - コンテキストが不明瞭な場合のみ使用）

会話のコンテキストが不十分な場合に限り、Git ツールを使用します。

コミットの分析

# Get recent commits (last 10-20 commits)
git log --oneline -n 20

# Get detailed changes since last PRD update
git log --since="1 week ago" --pretty=format:"%h %an %ad %s" --date=short

ファイル変更の分析

# See what files were modified recently
git diff --name-status HEAD~10..HEAD

# Get specific changes in key directories
git diff --stat HEAD~10..HEAD

変更の分類

変更の種類を特定します。

• 新規ファイル：新しい機能やコンポーネントを示します
• 変更されたファイル：既存機能の更新を示します
• テストファイル：実装のテストを示す証拠です
• ドキュメントファイル：ドキュメントの更新を示します
• 設定ファイル：セットアップまたはデプロイの変更を示します

ステップ 3：PRD の構造を包括的に分析する

重大：チェックボックスの体系的な確認

要件を見落とさないよう、この手順を必ず実行してください：

1. grep または検索を使って、PRD 内の未チェック項目をすべて確認します

2. 未チェックの各要件を種類ごとに分類します：

   • 実装（コード、機能、技術的なタスク）
   • ドキュメント（ガイド、例、相互参照）
   • 検証（例が動作することのテスト、ユーザージャーニー）
   • ユーザー受け入れ（実際の利用、複数クライアントでのテスト）
   • リリース活動（トレーニング、デプロイ、ロールアウト）
   • 成功指標（導入状況、分析、サポートへの影響）

   現在の prd-create が作成する PRD では、実運用での受け入れ項目は PRD のチェックボックスではなく、リンクされた acceptance issue で管理します。PRD は、実装のマイルストーンがマージされた時点で完了です。実運用での受け入れに関するチェックボックスが残っている古い PRD では、完了を判定する前に、該当項目をリンクされた acceptance issue に移してください（sweep ラベルは決して使用しないでください）。これにより、/prd-full と /prd-done がそれらの完了を待たずに済みます。項目は、そこで追跡されるものとしてユーザー受け入れの下に記載してください。

3. git の変更を適切なカテゴリにのみ対応付けます

4. 慎重に判断します。直接的な証拠がある場合にのみ、項目を完了としてマークします

証拠に基づく完了基準

実装要件 — 次の場合に完了としてマークします：

• コードファイル：機能が実装されていることを示している
• テストファイル：包括的なテストを示している
• 統合：コンポーネントが適切に接続されている

ドキュメント要件 — 次の場合に完了としてマークします：

• ファイルの作成：ドキュメントファイルが存在する
• 例の検証：コマンドや例がテスト済みである
• 相互参照の動作：内部リンクが検証済みである

検証要件 — 次の場合に完了としてマークします：

• 手動テストの実施：ワークフローがエンドツーエンドでテスト済みである
• 例の確認：ドキュメントに記載されたすべての例が動作する
• ユーザージャーニーの確認：一連のワークフローが検証済みである

リリース活動 — 次の場合に完了としてマークします：

• トレーニングの実施：チームがトレーニングを受けている
• デプロイの完了：機能が公開され、利用可能になっている
• ロールアウトの完了：ユーザーが実際に機能を利用している

慎重な完了ポリシー

直接的な証拠がない限り、完了としてマークしないでください：

• ❌ 検証せずに、ドキュメントが「十分に良い」と決めつけないでください
• ❌ 実際にテストした証拠なしに、テスト完了とマークしないでください
• ❌ ロールアウトの証拠なしに、リリース項目を完了とマークしないでください
• ❌ 指標なしに、成功基準を完了とマークしないでください

ギャップ分析

次の項目を体系的に特定します：

• 証拠のない要件（まだ対応が必要なこと）
• 要件に対応しない証拠（スコープ外で実施された作業）
• 検証の不足（実装済みだがテストされていないもの）
• ロールアウトの不足（準備はできているが、デプロイまたは導入されていないもの）

ステップ 4：包括的な進捗レポート

必須：ステータスの完全な分析

包括的な内訳を提示します：

## PRD Progress Analysis: [PRD Name]

### ✅ COMPLETED (with evidence):
**Implementation** (X/Y items):
- [x] Item name - Evidence: specific files/changes
- [x] Item name - Evidence: specific files/changes

**Documentation** (X/Y items):
- [x] Item name - Evidence: docs created, examples tested
- [x] Item name - Evidence: cross-references verified

### ⏳ REMAINING WORK:
**Validation** (X items unchecked):
- [ ] Item name - Reason: needs manual testing/validation
- [ ] Item name - Reason: examples not tested

**User Acceptance** (X items unchecked):
- [ ] Item name - Reason: no cross-client testing done
- [ ] Item name - Reason: no user feedback collected

**Launch Activities** (X items unchecked):
- [ ] Item name - Reason: team not trained
- [ ] Item name - Reason: not deployed to production

**Success Metrics** (X items unchecked):
- [ ] Item name - Reason: no usage data available
- [ ] Item name - Reason: adoption not measured

### 🎯 COMPLETION STATUS:
- **Overall Progress**: X% complete (Y of Z total items)
- **Implementation Phase**: 100% complete ✅
- **Validation Phase**: X% complete (what's missing)
- **Launch Phase**: X% complete (what's missing)

慎重な推奨ポリシー

直接的な証拠がある場合にのみ、項目を完了としてマークすることを提案してください。 今後対応が必要な項目を明確に列挙してください。 すべての項目が本当に完了していない限り、「すべて完了」と主張しないでください。

ステップ 5：実装と計画の分析

差異の検出

実際の実装が計画されたアプローチと異なる場合は、その内容を明示します：

• アーキテクチャの変更：当初の計画とは異なる技術的なアプローチ
• スコープの変更：実装中に追加または削除された機能
• 要件の変化：開発中に明確になったユーザーニーズ
• 技術的な発見：コーディング中に判明した制約や機会

更新の推奨

差異が見つかった場合は、PRD の更新を提案します：

• 意思決定ログの更新：実装アプローチを変更した理由を記録する
• 要件の修正：実際の機能に合わせて要件を更新する
• アーキテクチャの更新：技術的なアプローチのドキュメントを改訂する
• スコープの調整：項目をフェーズ間で移動するか、機能定義を更新する

ステップ 6：ユーザー確認プロセス

提案する変更を、完全な透明性をもって明確に提示します。

1. 証拠の概要：検出した作業内容を示します
2. 完了として提案する項目：証拠とともに、完了にする具体的なチェックボックス項目を列挙します
3. 残作業の分析：未チェックの項目とその理由を明確に示します
4. 差異の警告：計画と実際の状況の違いを強調します
5. 誠実な進捗評価：現実的な完了率を提示します

重要な要件：

• 文字どおりすべてのチェックボックスが完了していない限り、「すべて完了」とは決して言わないでください（リンクされた acceptance イシューで管理されるライブ受け入れ項目は、PRD のチェックボックスではありません）
• Git に基づく分析の制約を明示してください
• 機能が動作することを検証できない場合は、検証の不足を認めてください
• 実装と検証／ロールアウトを分けて扱ってください

変更を加える前にユーザーの確認を待ち、以下に対応します。

• 一部承認：ユーザーが提案の一部には同意し、残りには同意しない場合
• 追加のコンテキスト：ユーザーが Git 履歴からは確認できない情報を提供した場合
• スコープの明確化：ユーザーが、対象外に見える作業について説明した場合
• 今後の計画：ユーザーが現在の進捗に基づいて、今後の作業を調整したい場合

ステップ 7：体系的な更新の適用

更新を適用する際は、以下を行います。

1. 確認済みの項目のみ更新する — 推測で判断しないでください
2. ステータスのセクションを更新する — 現在のフェーズが反映されるようにします
3. 引き続き作業が必要な未チェック項目を保持する
4. 完了率を現実的に更新する

ステップ 7.5：コード例の検証

実装の進捗に基づいて PRD を更新する際：

重要：PRD 内のコード例が現在の実装と一致しているか、必ず確認してください

例への影響の検出

1. インターフェースの変更：関数シグネチャ、パラメーター型、戻り値の形式
2. API の進化：メソッド名、クラス構造、データモデル
3. ワークフローの更新：ユーザー操作のパターン、手順
4. 統合の変更：コンポーネントの接続方法と通信方法

コード例の更新プロセス

1. PRD をスキャンする：すべてのコードスニペットと例を特定します
2. 実装と照合する：例を実際のコードと比較します
3. 古くなった例に印を付ける：現状と一致しない例を明示します
4. 優先度を評価する：すぐに更新が必要な例を判断します
5. 例を更新する：コードスニペットを現在の実装に合わせて修正します
6. 例を検証する：更新した例をテストし、動作することを確認します

確認する例のカテゴリ

• 関数呼び出し：パラメーターの順序、型、名前
• インターフェース定義：TypeScript のインターフェース、クラス構造
• API レスポンス：データ形式、フィールド名、レスポンス構造
• ワークフローの手順：ユーザー操作の順序、ツールの使用パターン
• 設定：セットアップ例、環境変数、設定ファイル

例を更新するタイミング

• 直ちに：インターフェースの変更によって既存の例が機能しなくなった場合
• 完了前：実装のマイルストーンを完了としてマークする場合
• レビュー中：PRD の正確性を検証する場合
• ユーザーフィードバックを受けたとき：例が動作しないという報告を受けた場合

ステップ 8：進捗更新のコミット

PRD の更新が正常に完了したら、進捗のチェックポイントを保持するために、すべての変更をコミットします。

実装作業をコミットする

# MANDATORY: Stage ALL files - implementation work AND PRD updates together
# DO NOT selectively add only PRD files - commit everything as one atomic unit
git add .

# Verify what will be committed
git status

# Create comprehensive commit with PRD reference
git commit -m "feat(prd-X): implement [brief description of completed work]

- [Brief list of key implementation achievements]
- Updated PRD checkboxes for completed items

Progress: X% complete - [next major milestone]"

コミットメッセージのガイドライン

• PRD 番号を記載する：コミットメッセージには必ず prd-X を含めます
• 内容を簡潔に記述する：実装した内容を短く明確に説明します
• 進捗を示す：完了状況と次のステップを含めます
• 証拠に基づく：実際に実装が進捗した場合にのみコミットします

注記：ユーザーから明示的に求められない限り、コミットをプッシュしないでください。コミットはリモートブランチに影響を与えずに、ローカルの進捗チェックポイントを保持します。

ステップ 9：PRD のステータスに応じた次のステップ

PRD の更新と変更のコミットが完了したら、完了状況に応じてユーザーに案内します。

PRD に未完了のタスクが残っている場合

---

PRD の進捗が更新され、コミットされました。

この PRD の作業を続けるには、次の手順を実行してください。

1. 会話コンテキストをクリア／リセットします
2. /prd-next を実行して、次のタスクを取得します

---

PRD が 100% 完了している場合

---

PRD #X が完了しました！

完了処理を行うには、次の手順を実行してください。

1. 会話コンテキストをクリア／リセットします
2. /prd-done を実行して、PRD を完了フォルダーに移動し、GitHub の issue をクローズします

---