write-acceptance

作業を人に引き継いで、受け入れてもらう

何かを作り終えたら、それが実際に機能するところを人に見てもらう必要があります。その人は、セッションの内容を何も把握していません。あなたが何を決めたか、すでに何を確認したか、画面にある5つのボタンのどれが新しいものかも知りません。

docs/<feature>/ACCEPTANCE.md（別の場所を使っているプロジェクトでなければ、プロジェクトの計画フォルダーにあります）は、その情報の隔たりを埋めるためのページです。ここに書くのは、相手に期待することを順番に並べたチェックリストだけです。相手が質問を一つもせずに上から順に作業できるか、そして各手順の最後に、実際に確認できる観察結果があるかで評価されます。

読む人を把握しましょう。 通常は製品を知っているユーザーですが、今週の作業内容は知りません。機能を見たことがなく、どこに何があるかも知らないテスターが読む場合もあります。後者を想定して書きましょう。「いつもの場所」ではなく、画面、メニュー、ボタンの名前を示してください。ユーザーなら推測できる手順でも、テスターからは作業が進められないと報告されることがあります。

これはwrite-handoffではありません。 こちらは、未完成の作業を次のエージェントに引き継ぐものです。ブランチの状態、マージするもの、作業を再開する場所などを伝えます。こちらは、完成した作業を人に引き継ぎ、受け入れてもらうものです。実行時に両方が必要になる場合もありますが、読む人も目的も異なり、共有する内容はありません。

含めること、そして決して含めないこと

機械ではできないことだけにします。 それだけを基準にしましょう。誰かが実行するチェックリストと、ざっと目を通して放置されるチェックリストを分ける基準です。

• 認証情報がなく、アクセスできないコンソールやアカウント。ホスティングのダッシュボード、DNS、アプリストア、リポジトリのシークレットなど。
• 物理環境や複数デバイスが関係するケース。異なるネットワークにつながった2台のマシン、ホットスポットを使うスマートフォン、2人目のユーザー、再起動など。
• 人の目でしか判断できないこと。新しいUIが周囲のUIと調和しているか、アニメーションが遅く感じられるか、文言が適切かなど。
• ここでは実行できなかったこと。ビルドできないプラットフォーム、ハードウェアが必要なテストスイート、インストールされていないアセットなど。そのことを明記し、確認によって何が証明されるのかも記載してください。
• テストで確認済みでも、機能が実際に存在することを証明するためのデモンストレーションを1つ。相手は、実際に動作するところを一度見たいと思っています。

すでに自分で行ったことを、相手に求めてはいけません。 テストスイート、フォーマッター、EXECUTION.mdで成功している項目は、あなたの担当であり、すでに完了しています。これらを再び記載すると、本当に人の手が必要な3つの手順が埋もれてしまいます。何かに失敗した場合も、それを受け入れ手順にしてはいけません。修正するか、未解決事項を質問ログ（プロジェクトで未解決の質問を管理している場所。決まりがなければ、計画のそばに質問セクションまたはファイルを用意します）に延期事項として記録してください。

書き方

まず、すでに構築して検証済みの内容を述べ、EXECUTION.md を参照してもらいます。次に、残っている作業と、なぜ人の手が必要なのか（コンソール、別のデバイス、その人自身の目が必要なため）を説明します。その後にチェックリストを示します。

• 途中で区切れる順序付きのセクションに分け、それぞれにおおよその所要時間を記載します。たとえば、## A. プロビジョニング（コンソール作業、約30分とDNSの反映時間） のようにします。20分しかない人でも、どこまで進められるかがわかるようにします。
• すべてのコマンドをコピーして貼り付けられる形にし、実行場所を明記します。どのマシン、どのコンソール、どのシェルを使うのかを書きます。コードブロックを使い、本人しか用意できない値以外は、プレースホルダーではなく実際の値を使います。本人しか用意できない値については、何の値で、どこで確認できるかを説明します。
• 証拠となる観測可能な結果を記載し、感覚的な表現は避けます。「同期が完了することは証拠ではありません。中継経路が証拠です。」「systemctl is-enabled docker は enabled を出力する必要があります。」成功条件が「動くはずです」になっている手順は、完了報告できません。
• 壊れているように見えても問題のない点を明記します。フェイルクローズするゲート、意図的に設定していない復旧用メールアドレス、初回実行に10分かかることなどは、注記に隠さず、該当する箇所で「これは設計どおりであり、故障ではありません」と説明します。
• 詳しい手順を繰り返すのではなく、運用手順書を参照させます。このページには期待される作業を順番に並べ、運用ドキュメントやユーザーガイドには実際の手順を記載します。同じ手順を二か所に書くと、内容に食い違いが生じます。
• 何を報告してほしいのかを明記します。どの手順について報告が必要か、どのファイルをコミットするのか、回答を待っている未解決の質問は何かを具体的に示します。該当する場合は、未解決の質問がチェックリストの実行を妨げないことも明確にします。
• 目覚めたばかりの人にもわかるように書きます。平易な文章を使い、プロダクトの用語を使い、実行時のフェーズIDや略記は避けます。相手が不在の間に行った判断が理由で手順が必要になった場合は、その理由を一節で説明します。

正直さを保てる範囲で、できるだけ短くします。実際に確認だけで済むなら、その旨を3行で書き、開くべきものを一つだけ示します。実態のない儀式を作るより、短いページのほうが適切です。

受け入れセクション

最後に番号付きの確認項目を記載します。計画にあるユーザー自身のユースケースを、確認事項ではなく実際に行う操作として書き直します。それぞれに、準備するもの、実行すること、完了を示す正確な観測結果を記載します。これらによって作業の完了を判断するため、ページの最後に置き、番号を付けます。そうすれば、読者は「D.2 は合格、D.3 では X が表示された」と回答できます。

後続の作業で以前の受け入れ項目に追加する場合は、既存のセクションを書き換えず、新しいセクションを追加します。すでに以前の項目を確認した人がいる可能性があるためです。

配置場所

• docs/<feature>/ACCEPTANCE.md に記載し、最後のフェーズでコミットします。
• EXECUTION.md（「残りの受け入れ確認項目は ACCEPTANCE.md のチェックリストです」）と、完了報告からリンクします。完了報告は要約にとどめます。チェックリストはこのファイルに置き、スクロールして消えてしまうチャットメッセージには置きません。
• 後続の実行で手順が追加または完了した場合は、このファイルをその場で更新します。 close-roadmap と close-plan は、作業を完了扱いにする前に、項目ごとにレビューし、その後このファイルを廃止します。再実行する価値のある項目は、機能の現行テスト計画に引き継ぎます。報告されていない確認項目が一つでもあれば、クローズできません。そのため、最後まで実施できる程度にリストを短く保ちます。