user-story-review
現在のブランチと main・master などの統合先との差分、要件定義、実装から、人間が画面で試せるユーザーストーリーの確認用 HTML を生成する。実画面のキャプチャ、確認用ダミーデータの作成スクリプト、そのデータを片付ける手順を揃えたいときに使う。
- License 许可
- MIT
- 最近更新
- 2026-11-12
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- user-story-review
- description
- 現在のブランチと main・master などの統合先との差分、要件定義、実装から、人間が画面で試せるユーザーストーリーの確認用 HTML を生成する。実画面のキャプチャ、確認用ダミーデータの作成スクリプト、そのデータを片付ける手順を揃えたいときに使う。
02 资源文件 19
- 参考文档sanko/check-story-issue45412-2026-10-09.adoc12.3 KB
- 参考文档sanko/check-story-issue45412-2026-10-09.html2.0 MB
- 资产文件sanko/screenshots/01-index.png143.0 KB
- 资产文件sanko/screenshots/02-k7-failed.png112.4 KB
- 资产文件sanko/screenshots/03-k1-multiple-matches.png215.6 KB
- 资产文件sanko/screenshots/04-k1-not-fetched.png150.5 KB
- 资产文件sanko/screenshots/05-index-after-k1-relink.png132.1 KB
- 资产文件sanko/screenshots/06-k1-after-relink.png142.1 KB
- 资产文件sanko/screenshots/07-k5-referenced.png128.2 KB
- 资产文件sanko/screenshots/08-index-after-k4-dismiss.png122.8 KB
- 资产文件sanko/screenshots/09-k4-after-dismiss.png109.4 KB
- 资产文件sanko/screenshots/10-k2-input-invalid-host.png116.0 KB
- 资产文件sanko/screenshots/11-k2-input-fetch-failed.png114.3 KB
- 资产文件sanko/screenshots/12-index-after-k2-input-relink.png111.4 KB
- 资产文件sanko/screenshots/13-k2-after-input-relink.png110.5 KB
- 资产文件sanko/screenshots/14-k2-restaurant-google-map-link.png107.4 KB
- 资产文件sanko/screenshots/15-k7-after-batch-run.png112.7 KB
- 资产文件sanko/screenshots/16-index-after-batch-run.png109.9 KB
- 脚本sanko/seed-check-data.rb7.9 KB
03 SKILL.md 正文
User story review
変更された機能を、人間が自分で操作して確かめられる日本語の HTML にする。 読み手はコードを読まない利用者や動作確認の担当者である。 操作する画面、使うデータ、期待する表示、確認後の片付けまでを一続きにする。
入力と成果物
通常は $user-story-review と引数なしで呼び出す。
作業中のリポジトリと現在のブランチを対象にする。
ユーザーが比較先や確認範囲を指定した場合は、その指定を優先する。
既存の確認資料の保存場所があれば、その規約に合わせる。
なければリポジトリ直下の check/user-story-review-<branch>-<YYYY-MM-DD-HHMMSS>/ に次を作る。
branch はパス区切りや特殊文字を除いた名前にし、既存の成果物を上書きしない。
check-story.html。確認手順、画像、データの準備と削除方法を含む。screenshots/。実画面の画像を手順番号と内容が分かる名前で保存する。- データ作成と削除のスクリプト。同じスクリプトの明示的なモードで兼ねてもよい。
data-manifest.json。作成したデータの識別子、対象環境、ストーリーとの対応を記録する。
スクリプトは対象プロジェクトの言語と実行方法に合わせる。 確認資料の作成を理由に、アプリケーションの実装変更、依存追加、コミット、push、PR 作成を行わない。
1. 比較範囲と要件を確定する
リポジトリのルートで次を確認する。
git rev-parse --show-toplevel
git status --short --branch
git branch --show-current
git rev-parse HEAD
git symbolic-ref --quiet --short refs/remotes/origin/HEAD
git for-each-ref --format='%(refname:short)' refs/heads refs/remotes
比較先は、ユーザーの指定、リポジトリが定める統合先、origin/HEAD の順に探す。
それでも決まらなければ、存在する origin/main、main、origin/master、master、origin/develop、develop から祖先関係と開発規約を確認して選ぶ。
候補が一つに絞れない場合だけ、比較先をユーザーに確認する。
リモート参照はローカルにある時点の情報として扱い、勝手に fetch やブランチの切り替えをしない。
選んだ参照名をシェル変数 STORY_BASE に設定し、分岐点から現在の HEAD までを調べる。
git rev-parse "$STORY_BASE"
git merge-base --all "$STORY_BASE" HEAD
git diff --name-status "$STORY_BASE"...HEAD
git diff "$STORY_BASE"...HEAD
git diff --cached
git diff
git ls-files --others --exclude-standard
共通祖先がない場合や複数ある場合は、比較範囲を確定するまでストーリーを断定しない。 ステージ済み・未ステージの変更と、関連する未追跡のソースや要件も読む。 生成物、秘密情報、無関係な未追跡ファイルは読み込まない。 HEAD の差分と未コミット変更は、別々に記録する。
変更された要件定義、設計書、issue に対応する文書、実装、既存テストを照合する。 差分から参照される既存の画面、権限、入力制約、状態遷移も必要な範囲で読む。 文書がなくても、実装とテストから利用者に見える変化を抽出する。 その場合は「コードから推定」と記す。 要件と実装が食い違う箇所は、期待結果と現在の挙動を分けて「要確認」にする。
この段階は、比較先とその SHA、分岐点と HEAD の SHA、未コミット変更の有無、対象となる利用者の操作を説明できれば完了する。 関連する差分がない場合は、その事実を報告して終了する。
2. 人間が試せるストーリーを組む
ストーリーごとに S1、S2 のような識別子を付け、次を整理する。
| 項目 | 内容 |
|---|---|
| 目的 | 誰が、何をしたいか。その結果、何ができるか。 |
| 根拠 | 対応する要件、変更ファイル、既存テスト。推定なら明示する。 |
| 開始状態 | 権限、ログイン状態、対象データ、直前の操作。 |
| 操作 | 開く URL、押すボタン、入力する値を順番に書く。 |
| 期待結果 | 表示、件数、保存結果など、読み手が確認できる変化。 |
| 使用データ | ダミーデータのキーと開始状態。 |
| 依存とやり直し | 先に必要な手順、操作後に変わる状態、戻し方。 |
正常系に加え、変更に関係する入力エラー、権限不足、空の状態、境界値、失敗後の再操作を扱う。 無関係な組み合わせでストーリーを増やさない。 すべての利用者に見える変更をいずれかのストーリーに対応させる。 内部処理だけの差分は、画面確認の対象外にした理由を記録する。
各手順は「操作する」「表示を見る」「何をもって合格とするか」が分かる文章にする。 画面に表示される名前を使い、関数名や SQL を理解しなくても進められるようにする。 バッチや API しかない変更では、実行コマンド、入力、期待する出力や管理画面の変化を示す。 画面のない処理に架空の UI を作らない。
3. ダミーデータと片付け方法を先に作る
まず既存の起動手順、factory、fixture、seed、テスト用アカウントを調べる。 ストーリーに必要な最小限のデータを、既存の仕組みで作る。 状態が変わるストーリーには別々のデータを用意するか、実行順と初期化方法を明記する。
書き込み前に、アプリの実行環境と実際の DB・API 接続先を確認する。 ローカルの使い捨て環境か、この確認専用の開発・テスト環境を使う。 共有環境への書き込みが必要で、既存の依頼から許可を確認できない場合は、スクリプトと対象を準備した後、実行前に確認する。 本番環境には確認用データを書き込まない。 通知、メール、決済、外部ジョブはテスト用の仕組みに切り替え、実利用者への副作用を防ぐ。 変更された機能の処理は実装を通し、外部への副作用だけを置き換える。 外部 API を stub した部分は、確認した範囲として HTML に明示する。
作成スクリプトと manifest は次を満たす。
- 実行ごとの
run_idを使い、ストーリーのデータキーと作成済みの ID を対応させる。 - manifest に対象環境、DB などの接続先の識別情報、作成した親子データ、再実行方法を記録する。認証情報は保存しない。
- 同じ run の再実行では、所有を確認できたデータだけを初期状態に戻す。既存データとの衝突時は停止する。
- DB を使う場合はトランザクション内で manifest を保存し、保存失敗時は作成をロールバックする。ファイルや外部のテスト用リソースは作成直後に記録し、途中失敗時の回収方法も用意する。
- 借用した既存アカウントや参照データは作成物と区別し、変更・削除しない。
片付けは、準備したデータだけを対象にする。 削除前に対象と件数を表示する dry-run を用意する。 実行時も環境と manifest の一致を確認し、記録された ID と所有情報を照合する。 manifest がない、環境が違う、所有を確認できない場合は削除を停止する。 名前の前方一致だけによる一括削除、全件削除、DB の初期化を片付けに使わない。
画面操作で値や状態が変わっても、作成時の ID を使って片付けられるようにする。 操作で追加される履歴、関連レコード、ファイルも追跡し、外部キーとコールバックに合う順序で片付ける。 今回作成したデータは削除する。プロジェクトの規約上、物理削除できない作成物は、非公開化などの処置と残るデータを明記する。 繰り返し実行しても、片付け済みの対象を理由に他のデータへ範囲を広げない。
HTML に、作業ディレクトリ、作成・初期化・dry-run・削除の正確なコマンドを載せる。 データ一覧には、データキー、表示名、開始状態、開く URL、対応ストーリーを載せる。
4. 実際に操作してキャプチャを撮る
既存の検証手順に沿ってアプリを起動し、対象 worktree のコードが動いていることを確認する。
この段階で行うデータの作成と片付けは、HTML に載せるコマンドをそのまま fish で実行する(fish -c '<コマンド>')。
データ作成を同じ run で二度行い、件数が増えず、ストーリーの開始状態に戻ることを確かめる。
ブラウザ操作には、利用可能な agent-browser、Playwright などを使い、そのツールの手順に従う。
ブラウザ操作が必要なら、説明だけで終えず、各ストーリーを実際に流す。
開始画面、主要な操作後、変更に関係するエラー表示を撮影する。 スクロール、待機、通知の表示時間を調整し、入力値と結果を読み取れる画像にする。 各画像に、ストーリー・手順番号、確認してほしい箇所、撮影時の状態を対応させる。 機密情報が写り込む場合はテスト用の値に置き換えて撮り直すか、画像をマスクし、その処置を記す。
キャプチャは対象アプリの実画面から取得する。 参考資料の画像の流用や、画像生成による成功画面の代用をしない。 画面のない処理では、実行ログと観測した結果を証拠にする。 起動、認証、必要な接続先の不足で確認できない項目には「未実施」と理由を記す。 未撮影の画像枠や、未実施の操作を成功したように書かない。
片付けは独立した使い捨てのデータで、dry-run、削除、もう一度削除の順に実行する。 dry-run と実際の対象が一致し、二度目は片付け済みとなり、対象外のデータが残ることを確認する。 対象外のデータがない環境では、別 run のテスト用データを用意して削除範囲を確かめ、そのデータも検証後に片付ける。 借用したデータがあれば、残っていることも確認する。 最後に人間が試すデータを開始状態へ戻し、最新の ID と URL を manifest と HTML に反映する。 人間の確認前に、そのデータを片付けない。
5. HTML を生成する
HTML は、準備から操作、やり直し、片付けまでを上から順に読める構成にする。 次の情報を含める。
- 確認する機能と、操作すると何ができるか。
- 現在のブランチ、比較先とその SHA、分岐点と HEAD の SHA、作成日時、未コミット変更、確認環境。
- 起動・ログインの前提と、ダミーデータの作成方法・一覧。
- 各ストーリーの開始状態、番号付きの操作、期待結果、対応キャプチャ、合否の記入欄。
- ストーリー間の依存、やり直す方法、削除の dry-run と実行方法、残るデータ。
- エージェントが実施した確認と結果、未実施・要確認の項目、根拠ファイル。
期待結果と実際に観測した結果を分ける。 人間の合否記入欄は空欄で渡し、エージェントの確認結果を代わりに記入しない。 要件が明示された結果と、コードから推定した結果も区別する。
CSS と画像は HTML に埋め込み、単体で開けるようにする。
画像ファイルも screenshots/ に残し、撮影元を確認できるようにする。
外部 CDN、フォント、アプリへの接続がなくても本文と画像を読めるようにする。
見出しと目次で移動でき、画像には説明文と代替テキストを付ける。
横幅に応じて画像を縮め、文字と背景のコントラストを確保し、印刷時も手順と画像を読めるようにする。
コード、入力値、動的な表示名は HTML エスケープする。
HTML に載せるコマンドは、人間が fish shell で実行する前提で書き、コードブロックの言語を fish にする。
実運用の認証情報や個人情報を HTML に含めない。
構成を確認したい場合は 参考 HTML と その元文書 を読む。 参考 HTML には画像の base64 があるので、構造を調べるときは画像データを出力しない。 参考資料のアプリ名、URL、認証情報、DB 名、固定 ID、データを残す片付け方式は、今回の対象に引き継がない。
6. 成果物を検証して渡す
確認中に対象コードが変わっていないか、HEAD と関連する未コミット変更を再確認する。
変わっていた場合は、影響するストーリーを確認し直し、キャプチャと比較情報を更新する。
生成した HTML をブラウザで開き、画像、目次、コマンド、ストーリーの順序を確認する。
HTML だけを別の場所にコピーして開き、本文と画像が欠けないことも確認する。
相対リンクで渡すスクリプトは、必要な成果物一式と一緒に渡す方法を載せる。
単体 HTML に載せるコマンドにも、スクリプトの所在と実行する作業ディレクトリを明記する。
HTML に載せたコマンドをすべて fish --no-execute -c '<コマンド>' に通し、構文エラーがないことを確認する。
完了には、次が揃っていることを確認する。
- 利用者に見える変更がストーリーに対応し、実際の表示で合否を判断できる。
- 必要な実画面キャプチャが本文に対応し、人間が使うデータが開始状態にある。
- 作成と片付けのスクリプトが HTML のコマンドのまま fish で実行でき、削除範囲と残るデータが分かる。
- manifest、画面のリンク、実際のデータが一致している。
- HTML を単体で開いて読める。
満たせない項目があれば、HTML 冒頭に「草案」と不足内容を示し、完了したと報告しない。 最終回答には HTML とスクリプトのパス、対象ブランチと比較先、実施結果、人間が最初に行う操作、未実施の理由を簡潔に書く。
04 同仓库更多 Skills
why
「なぜ X はこの動きなのか」「なぜ Y を選んだのか」、設計の根拠説明、リグレッション、ポストモーテム、データに裏付けられたしきい値に使う。利用可能な MCP を発見し、各証拠カテゴリ(ソース管理、issue トラッカー、長文ドキュメント、リアルタイムチャット、インフラ可観測性、エラートラッキング、プロダクト分析ウェアハウス)を並列で問い合わせ、決定とトレードオフについて引用付きの読み解きを返す。実行時の振る舞いには how を使う。
what-did-i-get-done
ユーザーが指定した期間に自分が作成したコミットを、簡潔な状況報告に要約する
unslop
あらゆる文章から AI の痕跡を削る。常に適用しなければならない。
typescript-best-practices
TypeScript のベストプラクティス。.ts または .tsx ファイルを読むか編集するときに使う。
thermo-nuclear-code-quality-review
抽象化の質、巨大ファイル、スパゲッティ条件分岐の増殖について、極めて厳格な保守性レビューを行う。thermo-nuclear なコード品質レビュー、thermonuclear レビュー、深いコード品質監査、または特に厳しい保守性レビューに使う。
technical-writing
階層化されたテクニカルライティング標準。Diátaxis の構造、Google developer style の文、STE の指示ルール、Global English の構文。/technical-writing、またはドキュメント、RFC、readme、PR の説明、コミットメッセージを書いたりレビューしたりするときに使う。