review-product-flow

製品フローをレビューする

製品ウォークスルーとは、人が実際のアプリを操作して、ユーザー向けのすべての機能を確認し、目にする内容を評価することです。成果物はランファイル、レンダリングされた人間向けガイド、および vet-product-flow レポートです。これらはアプリ独自のレンダリングに基づき、機能ケースごとに1行を設け、要件 ID とケース種別を付与します。ケースと判定結果は同じファイルに記載するため、エージェントが検証した内容をそのまま人が読むことになります。成果物を作成してください。チャットメッセージは成果物ではありません。正常系だけのガイドでは不十分です。検証レポートができるまでは、作成完了ではありません。

ケースの分類（すべてのガイドで以下の種別を使用）

kind	意味	典型的な情報源
happy	機能が本来の目的どおりに動作する	要件の主要なストーリー
edge	境界値／空／重複／最大長／空白	同じ ID または関連する基準にあるエッジ条件
error	ユーザーに表示される失敗経路（検証チップ、4xx メッセージ、入力値の保持）	要件にあるエラー条件
nonbehavior	起きてはならないこと	対象範囲外、否定形の SHALL
persist	再読み込み／再オープン／クライアントの再起動後も保持される	「保持される」と記載された条件、またはストアが管理する状態
visual	レイアウト、色、空状態の文言、使用感 — 人の目で確認	表示に関する要件。サーバーへの書き込みなし
journey	複数のステップからなるワークフローで、個別ケースをつなぐもの（任意、ガイドごとに最大2件）	複数ストーリーにまたがるユーザーパス

ここでは、カオス、負荷、競合、セキュリティファジングのテストスイートを作らないでください。こうしたテストは、1人のユーザーによる一巡確認には該当しません。権限／ロールのケースは、UI に表示される場合に含めます（ロールに対する setup と、edge または error）。

Todos — ゲート

§1 の前に、TodoWrite を使ってセクションごとに1件（1〜4）の todo を作成し、さらに末尾の todo 製品フローを検証（ランファイルに対する vet-product-flow）も作成してください。後回しにせず、今作成します。実行するランファイルについて .skills/<CODE>/vet-product-flow.md が存在する場合にのみ、検証用 todo を完了にしてください。 完了条件：スコープ決定前にリストが作成され、検証用 todo が含まれていること。

1. すべての機能をスコープに含める — カバレッジゲート

対象機能の requirements.md、design.md、tasks.md を読みます。ユーザーが確認できる機能をすべて列挙してください。新機能だけでなく、同じユーザーワークフローに隣接する機能も含めます。

カバレッジルール（§4 の完了前に、すべて満たす必要があります）：

1. ユーザー向けのすべての要件 IDに、1件以上のケースがあること。
2. すべての機能領域（ガイドの各セクション）に、1件以上の happy と、edge | error | nonbehavior | persist のいずれかの非正常系ケースが1件以上あること。
3. ユーザーが試す可能性のあるすべての対象範囲外／意図的に動作しない仕様に、nonbehavior ケースがあること（または引き継ぎ事項に「これを試すユーザー向けの方法はない — スキップ」と明記すること）。
4. 永続性を主張するすべての条件に、persist ケースがあること（または Expect と backend によって再読み込み／ストアを検証する happy／edge ケースがあること。専用の persist 行を設ければスキップされないため、そちらを推奨します）。
5. 仕様にその領域のエッジ、エラー、非動作、永続性に関する記述がない場合は、そのセクションに次の1行を記載します：カバレッジ例外：仕様にエッジ／エラー／非動作／永続性の記述なし — 製品の動作を作り出してはいけません。この例外は、検索可能な形で正直に記録するためのものであり、仕様にエッジ条件がある場合に見逃しを正当化するものではありません。

ID に対する正常系ケースが1件あっても、その ID または関連する ID にエッジ条件が記載されている場合は不十分です。

完了条件：上記のカバレッジルールを満たしているか、すべての例外をガイドに記載していること。

2. 各ケースを実際のコードに基づいて作成する

各ケースについてコードを読み、ユーザーが実際に目にする内容を確認します。正確な用語（キーワード、コマンド名、ラベル）、キーボードショートカット、実際の表示（バッジの色、チップのスタイル、アイコン）をソース（テーマトークン、CSS）から確認し、推測で記載しないでください。コードから正直に伝えるべき注意点（区切り文字が削除されず暗く表示される、ステータス用の UI がまだないなど）がわかった場合は、ケースにも記載します。

3. 実際のアプリを起動し、正直な観察ポイントを見つける

docs/agents/project.md の Run locally (dev) コマンドでアプリを起動します （記載がなければ見つけて記録します — validate-ui を参照）。劣化している 領域があれば、最初に明示します。たとえば、キーが必要な機能や、まだ実装されて いないサブ機能です。UI から操作できない動作にもケースを用意し、実際の観察方法 （devtools の invoke(...)、読み取り専用の DB 確認など）を記載します。存在しない 画面をでっち上げてはいけません。完了条件：アプリが実行中で、まだ UI から見えない すべての動作に観察方法があること。

4. ケースを作成し、シェルをレンダリングする（CSS を作り込まない）

作成時の SSOT は実行ファイルであり、手作業で作成した HTML ではありません。

1. .skills/<CODE>/review-product-flow.json を作成します（スキーマに迷った場合は、 同階層の references/cases-schema.md を読み込みます）。すべてのケースに必須項目を すべて記入します。id、req、kind、title、setup、try、expect、 backend（backend はサーバー側のアサーション、または文字列 presentational）。 実行状態（run、human）はこちらで入力するため、作成するのは 8 項目です。

2. チェックイン済みのシェルから人間向けガイドをレンダリングします — ユーザーがカスタム作成を明示的に求めない限り、craft-page を読み込んだり、 配色やレイアウトを作り込んだりしてはいけません。

   python3 <skill-root>/scripts/review-product-flow render .skills/<CODE>/review-product-flow.json \
     -o .skills/<CODE>/review-product-flow.html
   

   <skill-root> をこのスキルのインストール先に解決します（このモノレポでは skills/acceptance/review-product-flow）。シェルは shell/guide.html です — テーマ対応の CSS/JS、種類別チップ、判定バッジ、data-* 属性を備えています。 レンダリングされたページには、レンダリング時点の判定が表示され、その旨も 記載されるため、何も実行していない状態でダブルクリックしても正しい内容が 表示されます。

3. カバレッジのセルフチェック： セクションごとに kind 別のケース数を 数えます。いずれかの機能領域にハッピーパス以外の種類がなく、 Coverage exception の行もない場合は、引き渡し前に不足しているケースを 追加します。

任意：journey の行は最大 2 つまでです。これらは個別ケースのカバレッジの 代わりにはなりません。

チャットだけのチェックリストを納品してはいけません。 デフォルトの手順として、 カスタム HTML ページ全体を再生成してはいけません — ケースを作成して render を 実行するのが正しい手順です。

完了条件：実行ファイルとレンダリング済み HTML が既知のパスに保存され、 カバレッジが満たされ、すべてのケースに必須項目がそろっていること。

5. 引き渡す

順序：成果物 → 実行ファイルの vet → 任意の serve → vet がクリーンになってから dogfood。

1. 成果物 — 両方のパス（実行ファイル + HTML）、最も手早く開始できる方法 — 機能を有効にする約 30 秒の初回テスト（通常は最初の happy 行）— その後、 機能の劣化に関する注記とカバレッジの例外を伝えます。

2. 直ちに vet を実行します。 実行ファイルとレンダリング済み HTML が保存され、 §4 のカバレッジが満たされたら、直ちに 必須サブスキルとして vet-product-flow を実行ファイルに対して使用します — serve、dogfood、 または「作成完了」と伝えるより前に実施します。.skills/<CODE>/vet-product-flow.md が存在する場合にのみ、Vet product flow の todo を完了にします。§1 / §4 の カバレッジのセルフチェックは、作成時の基本事項であり、このレポートの代わりには なりません。

3. 任意の serve — エージェントと一緒に手動テストを行う場合は、ライブガイドを 提供します。

   python3 <skill-root>/scripts/review-product-flow serve .skills/<CODE>/review-product-flow.json
   

   127.0.0.1:8787 にバインドされ、エージェントが記録した判定に追従し、 ユーザーのチェックをエージェントが確認できる場所に書き戻します。チェックの 意味を明確に伝えます。チェックはユーザーが確認したことを記録するものであり、 pass になることはありません。停止するには serve --stop を実行します。 通常のファイルとして開いた場合も、ガイドにはレンダリング時の判定が表示されます — サーバーを使う利点は最新の状態が反映されることだけです。

4. エージェントによる dogfood — クリーンな vet-product-flow レポートが 得られた後（または未解決の指摘に対する明示的な例外が設定された後）に限り、 run-product-walkthrough と実行ファイルのパスを伝えます。Walkthrough では 独自のゲートも適用されます。引き渡しの順序がそのチェックの代わりになることは ありません。

完了条件：成果物が保存され、根拠が示され、§1 のカバレッジゲートが満たされ、 すべてのケースの項目がそろい、この実行ファイルに対する .skills/<CODE>/vet-product-flow.md が存在すること。

よくある正当化

考え	実情
「チャット内の Markdown チェックリストで十分です」	チェックを保存できず、実際に照合するバッジを表示できず、スクロールすると見えなくなります。成果物は実行ファイルとレンダリングされたガイドです。
「この機能専用のレイアウトを作ります」	デフォルトはチェックイン済みのシェルです。カスタム作成は、ユーザーから求められた場合に限ります。
「ブラウザーではなくネイティブのデスクトップアプリを使っているので、アーティファクトは合いません」	アーティファクトはアプリの横に開いておく補助資料です。アプリがネイティブであることは、ガイドをチャット内に埋め込む理由にはなりません。
「バッジを言葉で説明します」	ユーザーは実際に見ているものと照合します。実際の表示を再現しなければ、期待される結果を検証できません。
「要件ごとに問題なく動くケースが1つあれば十分です」	カバレッジゲートでは、問題なく動くケース以外の種類（または文書化された例外）が必要です。問題なく動くケースだけではデモであり、レビュー用プロダクトフローではありません。
「境界ケースはガイドではなくユニットテストに入れます」	Review Product Flow はユーザー向けの画面です。ユーザーが遭遇しうる境界ケースは、すべて行として記載します。
「より悪いケースとは、負荷／カオス／ファズテストのことです」	それらは別のハーネスで扱います。Review Product Flow で扱うより悪いケースは、境界ケース、エラー、動作しないケース、永続化です。
「§4 のカバレッジセルフチェックはすでに実行したので、vet は不要です」	セルフチェックは同一セッション内での作成時の確認であり、実装対象の独立した評価ではありません。vet の代わりにはなりません。
「次のステップとして vet を指定して止めれば、コントローラーが実行します」	ステップ 2 では vet-product-flow を実行します。指定するだけでは完了ではありません。
「アーティファクトはディスク上にあるので、作成は完了です」	JSON／HTML が配置された時点ではなく、vet レポートが存在する時点で完了です。

注意すべき兆候

• 実行ファイルと review-product-flow render を使わず、HTML／CSS のページ全体を手書きしている
• いずれかのケースで backend ／ setup ／ kind が欠けている
• 検索可能なカバレッジ例外がないまま、問題なく動くケースだけのセクションがある
• review-product-flow mark ではなく、ガイドのチェックで進捗を記録するようエージェントに指示している
• §4 のカバレッジセルフチェックを vet-product-flow の代わりとして扱っている
• この実行ファイルに対する .skills/<CODE>/vet-product-flow.md がないまま、このスキルが完了したと宣言している
• vet レポートが存在する前に run-product-walkthrough を指定する（または dogfood を提案する）
• レポートのパスが存在しないのに、Vet product flow の TODO にチェックを付けている