以下は/Nota/なぜpull request概要欄を丁寧に書いているのか (shokai)からのほぼコピペです

3つのaccountabilityのためです

機能の意義をユーザーや、社内のビジネスサイドに説明するaccountability

実装の正しさを他の開発者に説明するaccountability

障害発生時に対応する、未来の自分へのaccountability

既ににはScrapboxのシステム構成を見る会 2023冬で話したけど、改めて文書化しておきます

プルリク概要欄は障害対応時に使う

revertする時に見る

原因究明のために読む

障害時はscrapbox本体がダウンしている場合がある

もしpull request概要欄が空で、scrapboxのURLだけが貼ってあったら？

終わりです

ぜんぶコード読むしかない

Scrapboxに書いたのとほぼ同じ内容を、markdownで書き直している時に整理される

漏れ・抜けが見つかる

マジでわりとよくある

より良い説明が見つかる事がある

概要欄でユーザーに説明する練習をしている

何に困っているか、この機能でこんな良い事がある、仕組みはこうだ

（あれば）これまでの取り組みとの関係性、採用しなかった他の方法

頭の中で人格を分割して対話しながら書いている

より良い名前が浮かぶ事がある

設計がさらに改善される

Scrapbox側に書いてあるテキストも整理しなおそう

時系列ベースで並び替えた方が良い場合もあるし

コンポーネントや環境ごとに分類しなおした方が読みやすい場合もある

知見は別ページに切り出して再利用可能にする

おすすめフォーマット

問題 - (原因) - 解決 - (変更の詳細) - 動作確認方法

bug修正の時に使うフォーマット

現状 - 修正 - 動作確認方法

ちょっとしたUIの調整など

新機能名と概要と動画 - 実装 - 工夫した所 - 動作確認方法

新しい機能を作った時

プレゼンテーションするつもりで、魅力的に書く