human-review

人によるレビュー

人が作業を独力で確認できるよう、内容を十分に理解しやすくしてください。 コンテキストを思い出す手間、証拠を探す手間、変更を関連づける手間を減らし、人が理解と判断に集中できるようにしてください。

作業のコンテキストを再確認する

依頼、適用されるプロジェクト上の決定事項、仕様があればその仕様、現在の差分、確認可能なレビュー履歴を読みます。作業の目的と、人が実際に決定した選択肢を確認します。コードからわかるのは実装内容であり、人がその結果すべてを意図していたことの証明にはなりません。

最初に、目的、実現した変更、確認を始める場所を説明します。以前のレビューのコンテキストがある場合は、人が最後に確認したリビジョンから何が変わったかを明らかにします。そうでない場合は、新たに確認を始める場所を説明します。人の知識レベルは会話からのみ推測し、人が求めたり理解が不足している様子を示したりしたら、説明の詳しさを調整します。

変更を簡潔にまとめる前に、変更された各動作、アクセスルール、データへの影響、外部とのやり取り、エラー処理について把握します。それぞれについて、説明が必要な内容、プロダクト上の判断が必要な内容、確認済みの不具合を区別し、さらに、観察されたこと、ソースから推測したこと、未検証のことを分けて記録します。こうすることで、説明を簡潔にする際に変更の一部が黙って省かれるのを防げます。全項目を確認できる状態にして、阻害要因や重大な不明点は冒頭近くに記載します。

動作の変化を示す

一度に一つの一貫した動作を説明し、そのきっかけ、変更前後の結果、仕組み、影響を関連づけます。変更全体の中での位置づけをわかるようにし、人が、AI によって決着済みと見なされている選択肢を含め、別の部分を選んで確認できるようにします。ファイルや実装レイヤーではなく、実際に起きることを軸に整理します。

関係性を確認しやすくするため、実際の UI キャプチャ、リクエストとレスポンスの値、短いソースコードの比較、アクセス表、フロー図など、必要最小限の形式を使います。関連する証拠は主張の近くに示すか、隣接する開閉可能なセクションに配置します。結果がどのように導かれるかを人が確認するうえで役立つ技術的な詳細は説明し、より深いソースの説明は必要に応じて確認できるようにします。

実際のプロダクトを確認し、説明を裏づけるのに必要な範囲で最小限かつ安全なチェックを実行します。観察した結果には、対象のリビジョンまたは未コミットの差分、ルートまたはコマンド、環境を明記します。提供された観察結果はその旨を示し、出所を保持します。以前の AI による要約は主張であり、証拠ではありません。ソースから導いた結論と、観察できていない内容を正確にラベル付けします。モックや提案中の画面を、観察した結果として扱ってはいけません。レビューの準備中は、秘密情報や個人情報を伏せ、プロダクトを保持します。

人が使う言葉で、具体的な操作と結果を示して書きます。「未解決のコミットメント」「レビューの扱い」「証拠への経路」のような抽象的なプロセスのラベルではなく、実際の問い、変更された動作、証拠を確認できる場所を明示します。必要な技術用語はそのまま使い、馴染みのない用語は文脈の中で説明します。動作を確認するうえで役立たない所要時間の見積もり、重大度コード、スコア、ファイル数、テスト数は省きます。

判断を代替せず、判断を支援する

説明のたびに確認を求めるのではなく、重要な前提や境界で検討を促してください。質問では、実際に選択できる内容と、それぞれの回答によって何が変わるのかを明らかにします。根拠が不足している、大きな差分がある、または確認済みの不具合を修正する必要があるという理由で、製品上の決定を勝手に作り出してはいけません。

未解決の製品上の決定は最大3件までとし、保留中の決定はすべて明示して、先行する決定が確定した後に引き継げるようにします。影響が大きい、または覆すのが難しい選択から始めてください。この上限が適用されるのは決定の数であり、人間が確認できる作業の範囲ではありません。未解決の製品上の決定がない場合でも、動作を説明し、その根拠を確認できるようにしてください。欠陥や観察不足によって準備完了と判断できないかどうかは、別途伝えてください。

人間が会話で明示的に述べた場合に限り、選択を確定済みとして扱います。セクションを開くこと、読むこと、沈黙、一般的な了承は、承認ではありません。再利用可能な確定済みの決定は、プロジェクト既存の決定プロセスを通じて保持してください。一時的なレビュー用ページやメモは、その記録には該当しません。

再開しやすい地点を残す

レビューを中断するときや、人間が別の作業に移るときは、会話内、または持ち運び可能な引き継ぎが役立つ場合は一時的なレビュー成果物のそばに、簡潔なメモを残してください。元のリビジョンと未コミットの変更があれば記録し、その変更が元の状態に含まれる場合は、関連する差分またはスナップショットを保持します。実際に確認した箇所、人間が表明した決定や疑問、未解決の点、次に行うと有用な作業を記録してください。別のセッションで引き継げるよう、メモと根拠をリンクしてください。観察された操作と、表明された理解や承認は区別します。不明な場合は、その旨を記してください。

再開時には、以前の観察を再利用する前に、現在の作業を記録された元の状態と比較してください。どの箇所を再確認する必要があるか、その理由とともに指摘し、影響を受けない議論は保持して、未解決の質問から再開します。以前の元の状態を復元できない場合は、レビューが最新であると主張するのではなく、どの比較ができないのかを伝えてください。レビューを引き継ぐ前に、人間がすでに確認したかのように扱わず、次に着手する地点を示してください。

人間が活用できるレビューを提供する

簡単な説明は会話内で行います。比較、ナビゲーション、継続的なレビューに HTML が役立つ場合は、リポジトリの外で assets/review.html を必要に応じて調整してください。このテンプレートには、背景情報、動作の一覧、変更前と変更後のセクション、関連する根拠、任意の再開メモが用意されています。ラベルを翻訳し、プレースホルダーを置き換え、使わないセクションを削除してください。このテンプレートは出発点であり、変更のたびに必須の画面を用意するものではありません。

HTML については、ブラウザーでナビゲーション、比較、開閉表示、狭いビューポートを確認してください。内容が不完全であったり、操作部品が壊れていたりする場合は、レビュー画面を準備完了とする前に修正してください。ブラウザーで検証できない場合は、その制約を明示してください。完成した HTML は、現在のハーネスでサポートされる方法で実行し、ユーザーが開けるアドレスを、対応していればプレビューとともに共有してください。レビュー中はサーバーを利用可能な状態に保ちます。ブラウザーでの検証によって確認できるのはレビュー画面が機能することまでであり、基盤となる製品が正しいことや承認済みであることではありません。

適切な引き継ぎでは、動作を説明できること、AI が指摘しなかった前提を確認できること、作業を切り替えた後に再開できることを支援します。ページが表示されたことや人間が承認したことだけを理由に、人間の理解が深まったと主張してはいけません。