導入

記事やブログを書く方にはわりかし共感してもらえると思うんですが、下書きの文章全体を何度も読み返して
「ここに何か一文入れられたら全体のリズムがまとまるんだけどなぁ……」
とか
「もしかしてこの一節はそもそも消したほうがいいんじゃないか？」
とか考えてたらいつまで経っても記事が完成しないよ～みたいな経験をしたことがある人、多いんじゃないでしょうか。

この文章をブラッシュアップするための行為は「推敲」と言って、他人様に見せるための文章では基本的にやっておくべきものです。

近頃 Qiita や Zenn などで AI に書かせた記事ばかり投稿し続けている方々におかれましては**知らなかった概念**だと思いますので、今日はこれだけでも覚えて帰っていただければと思います。

改めて、「推敲（すいこう）」と言います。

本題

仕事でプルリク（以下 PR）を出すとき AI に書かせたコメントをポンと貼っちゃってませんか？
かくいう私も正直結構やっちゃいます。¹

これでも悪いとは言わないんですが、こと開発のボトルネックがレビューになっていると言われる現代においては、「頑張って読むためにレビュアーが労力を割く」より「読みやすく書くためにレビュイーが労力を割く」方がいい気がしています。
本当は AI のレビューで完結させられるのであればそれが一番いいんですけどね。

ということで最近は生成された PR コメントに次のような観点で軽く手を入れてから出すようにしてます。
ざっくり4つ、あまり目新しいものはないですが参考にしていただければうれしいです。

① 簡潔に書く

みなまで言うな。長いと読みたくない、ただそれだけ……という訳ではなく、長いと要点が埋もれるので本当に良くないです。

何ならグダグダ書くくらいならチケットの URL だけ貼っといた方がマシまである。

余談なんですが、この前某.com さんから年間のレンタルサーバー自動更新の請求が来ていて、適用は来月頭からだしなんとか解約できないかな～と思って問い合わせしたんですね。そしたら「期限前に複数回メールにてご案内を送付しております。」って言われてしまって。
確かに開いてみたらメールは何回か来てるんですけど、あなたたち普段からセールスメールばっか送ってくるじゃないですか……とそのとき思ったんですよね。
まあ契約書にサインしたのは自分なんでどう考えても自分の責任だし、埋もれているとはいえちゃんとメールボックスを見ていなかったことの勉強代だと思って払いはするんですけど……。²

とまあ話は戻って、無駄に長いコメントの中に指摘すべき事項が埋もれていたとして、それがすり抜けてしまったのをレビュアーの見落としにするのはいささか酷ではないでしょうか。
必要な情報かどうかの判断まですべてレビュアーに任せるのは責任を押し付けすぎです。

レビューのプレッシャーを軽減するためにも大事なことだけ書いたほうがいい。これができないのなら変更への理解度が足りてないので差分をもう一回自分で見返してください。

あとそもそも長いとコメントを修正する作業も面倒なんで、最初から「めっちゃ簡潔にコメント書いてください」的なプロンプトで渡すのがオススメ。

② 自分のスタンスが伝わるように書く

これは PR より技術記事³とかで顕著な気がするんですけど、AI のお出しする文章って立ち位置がフワフワしすぎて何言いたいかよくわかんないみたいなことってないですか？

この問題って、書いてる側が無意識に自分の立場から読むせいで問題の構造に気づきにくいのが原因なのかなと思っていて、やはり何も知らないニュートラルな視点の読み手が書き手のスタンスにたどり着くまでの動線というのは意識して作るべきだと感じます。

ちょっと抽象的な表現になったので具体例をば。

たとえば機能追加に合わせてデッドコードが発生し、それを削除したとします。このとき、

## 変更内容
- `hoge` の追加
- `fuga` の分岐を削除

ではなく

## 変更内容
- `hoge` の追加
- デッドコードが発生したため削除: `fuga` の分岐を削除

のように書いた方が読みやすいです。（書き方はほかにもいろいろあると思う）

なぜならば、レビュアーは機能の仕様については知っていてもデッドコードが発生したことは知らないから、そしてその背景を伝える必要があるからですね。前者だと経緯を知っている自分は「書いてあるからヨシ！」となっていても、レビューする側にとっては調べる手間が出てしまうわけです。

基本的には読み手がストレスなく書き手の思考をトレースできる状態が望ましいです。で、そのために書き手は自分がどういう目線で文章を書こうとしているのかというのを客観視する必要があるんですが、如何せんこれが結構難しい。でも意識するだけでもだいぶ違うんじゃないかなと思います。

ポエムだってそう。何言ってるかわかんないくらいなら、いっそ特定の DB を使うと会社が潰れるみたいなめちゃくちゃな誇張表現でも書いてたほうが分かりやすくていいと思う。

③ ☑ 動作確認の項目をチェックボックスで書く

PR の承認において、結局は要求されるふるまい（機能）を担保できていることが一番重要です。対象になる feature ブランチって機能のブランチですしね。
ということで、そのことを目で見てわかる形で書いておきましょう。チェックボックスならざっくりでもテストしたんだな～ってわかるのと、要件に対して明確に検証項目の漏れがあったら指摘か確認してもらえる（はずな）ので。

それと軽くでいいのでスクショを貼っておくのも Good です。
ただこれについてはスクショがあるとレビュアーは手元で動作確認とかしなくなりがちなんで、そういう意味では諸刃の剣ではあります。チームの運用とレビュイーの理解度次第。⁴

④ 特に触るところがなくても語尾とかを適当に弄っとく

AI 特有の文章の臭い消しをするだけでも意外と読みやすくなるもんです。
せっかくなのでやっときましょう。

これって日本語特有なんかなぁ……

最後に

きっかけは最近の Qiita や Zenn に読みにくい記事が多すぎて辟易したことだったんですが、そんなんここで言ったところで読むべき人には届かないことなんてわかりきっているのでこういう形の記事を書くことにしました。

PR に限らず、誰かに見せる文章は文の上手下手よりも前に「あなたが読みやすいように書きました」という心遣い、もしくは嘘でもそういうアピールが大事だと思ってます。⁵⁶

キミが読みやすいと思う文章を投げつけて読み手の心理的負担を減らしてあげよう！

え、そもそもこの記事がグダグダ書いてるじゃないかって？
……これはポエムだからいいの！

そもそも PR 自体を AI に作らせることの方が多いかもしれない ↩
そうやって解約逃させる狙いもあるんじゃないかと勘繰っちゃう ↩
これは中身スカスカのしょうもない記事ではなく、一応中身のあるものを発信しようとしてるけど投稿者がブログ慣れしてなくて生成された文章が読みにくいパターンの記事のことです ↩
仕様に詳しい人が動かしてみることで見つかるバグとかありますからね ↩
そもそも上手な文章を書くのってあまりにも難しいですし ↩
あとはブログなんかはバイブスに任せた文章もそれはそれで味があって良いですね、これは AI に書かせた時点で根底が崩壊しますが ↩