AGENT SKILL

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

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 は、準備から操作、やり直し、片付けまでを上から順に読める構成にする。 次の情報を含める。

  1. 確認する機能と、操作すると何ができるか。
  2. 現在のブランチ、比較先とその SHA、分岐点と HEAD の SHA、作成日時、未コミット変更、確認環境。
  3. 起動・ログインの前提と、ダミーデータの作成方法・一覧。
  4. 各ストーリーの開始状態、番号付きの操作、期待結果、対応キャプチャ、合否の記入欄。
  5. ストーリー間の依存、やり直す方法、削除の dry-run と実行方法、残るデータ。
  6. エージェントが実施した確認と結果、未実施・要確認の項目、根拠ファイル。

期待結果と実際に観測した結果を分ける。 人間の合否記入欄は空欄で渡し、エージェントの確認結果を代わりに記入しない。 要件が明示された結果と、コードから推定した結果も区別する。

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

seiei-sogen
seiei-sogen/agent-skills

why

「なぜ X はこの動きなのか」「なぜ Y を選んだのか」、設計の根拠説明、リグレッション、ポストモーテム、データに裏付けられたしきい値に使う。利用可能な MCP を発見し、各証拠カテゴリ(ソース管理、issue トラッカー、長文ドキュメント、リアルタイムチャット、インフラ可観測性、エラートラッキング、プロダクト分析ウェアハウス)を並列で問い合わせ、決定とトレードオフについて引用付きの読み解きを返す。実行時の振る舞いには how を使う。

★ 0
seiei-sogen
seiei-sogen/agent-skills

what-did-i-get-done

ユーザーが指定した期間に自分が作成したコミットを、簡潔な状況報告に要約する

★ 0
seiei-sogen
seiei-sogen/agent-skills

unslop

あらゆる文章から AI の痕跡を削る。常に適用しなければならない。

★ 0
seiei-sogen
seiei-sogen/agent-skills

typescript-best-practices

TypeScript のベストプラクティス。.ts または .tsx ファイルを読むか編集するときに使う。

★ 0
seiei-sogen
seiei-sogen/agent-skills

thermo-nuclear-code-quality-review

抽象化の質、巨大ファイル、スパゲッティ条件分岐の増殖について、極めて厳格な保守性レビューを行う。thermo-nuclear なコード品質レビュー、thermonuclear レビュー、深いコード品質監査、または特に厳しい保守性レビューに使う。

★ 0
seiei-sogen
seiei-sogen/agent-skills

technical-writing

階層化されたテクニカルライティング標準。Diátaxis の構造、Google developer style の文、STE の指示ルール、Global English の構文。/technical-writing、またはドキュメント、RFC、readme、PR の説明、コミットメッセージを書いたりレビューしたりするときに使う。

★ 0