issue / PR コメントの書き方
issue や PR のコメントは、開発者だけでなくお客さんやチームの非エンジニアが読む。彼らが読んで困らない・誤解しないことを第一にする。技術的に正確でも、相手に伝わらなければ価値がない。
守ること
- 平易な日本語で短く。専門用語を避け、動詞と場所で言い換える（例:「バックエンド」→「データを作るところ」）
- 結論だけ書く。調べた過程・試したことの羅列・言い訳は載せない。聞かれてから出す
- 見出しを盛らない。
# ご相談 のようなメタ見出しは付けない。本文だけで十分伝わるなら見出し自体いらない
- 不明点があるときも、「どこを・どうすれば直るか」の要点だけを平易に書く。長い背景説明にしない
トーン：言い切らない、盛らない、守りに入らない
結論や事実（取れた件数など）は言い切ってよい。だが見立て・提案・おすすめの方向は、相手（レビュアーやお客さん）が決める余地を残す書き方にする。
- 見立ては打診調にする。「〜です」「〜が正解」と言い切らず、「〜なのかなと」「〜ありそうな感じですね」のように相談する調子で書く。これは最後の質問だけでなく本文の提案部分すべてに効かせる
- 盛らない。「すでに」「まず」「丸ごと」のような強調語は無くても意味が通る。落とす
- 先回りして守りに入らない。「新しく作るのではなく〜」のように、来るかもしれない反論を予想して潰す説明は入れない。素直な道筋だけを書く
- 段落は短く、空行で区切る。1段落に詰め込まず、1つの話につき1段落にして読みやすくする
直す前（言い切り・盛り・防御）:
今の検索はすでに全文検索の仕組みを使っています。なので新しい仕組みを丸ごと足すのではなく、同じ仕組みに絞り込みを足すのが素直です。
直した後（打診・素直）:
今の検索は全文検索の仕組みを使っていて、そこに絞り込みを足すのが素直なのかなと。
書かないもの
これらは必要がある場合の例外を除き記載しない。
- スキル名（issue-loop など）。相手は知らない情報
- 技術用語（frontend / backend / API / agent / view box / margin など）
- ファイルパス・関数名・行番号（
src/server/handler.py:702 など）
- コード構造の説明（「xlim と ylim が…」「settings から margin_x を…」）。読み手はイメージしづらい
- 言い訳（「枠を超えるので別タスク」「想定範囲を超える」など）。やる / やらないだけ書く
主語と目的語を省かない
「誰が」「何を」が抜けると、読み手は何の話か分からない。書いた本人には分かっていても、読み手には伝わらない。
- 直す前: 確認しました。問題なさそうです。
- 直した後: 出典ページの件数を確認しました。画面の件数と一致しています。
比喩を使わない
「〜の穴」「〜の壁」「パズルのピース」「銀の弾丸」のような比喩は使わない。比喩は書いた本人しか意味が分からず、読み手には暗号になる。何が起きているかをそのまま書く。
- 直す前: 検索に穴があります。
- 直した後: 検索で、カタカナの商品名が見つかりません。
AI っぽい書き癖をやめる
AI が書いた文章に出やすい癖がある。コメントに出ていたら消す。
- 前置きの導入を書かない。 「〜について見ていきます」「〜を整理します」から始めず、いきなり本題を書く
- 「第一に」「第二に」「最後に」で区切らない。 並べたいときは普通の箇条書きにする
- 事実をぼかさない。 「〜と言えるでしょう」「〜と考えられます」「〜という側面もあります」で濁さない。確かめた事実と結果は言い切る。打診調にするのは見立てと提案だけ（上の「トーン」の節）
- 気遣いや共感を盛らない。 「お気持ちよく分かります」「ご苦労をお察しします」のような文は書かない
- 見出し・太字・箇条書きを詰め込まない。 短いコメントは普通の文で書く
- 頼まれていない注意書きを足さない。 「ただし〜は保証できません」のような決まり文句を入れない
- 最後にまとめを付けない。 「まとめ」「結論として」で同じことを言い直さない
- 前向きで大きな締めを書かない。 「より良いものにしていきましょう」「いかがでしたか」で終えず、事実を書いたところで終える
検証結果は「直った証拠」を見せる
修正できたことを報告するときが一番大事。「直った証拠」を具体的に見せる。次の2つをセットにする。
UI の場合は画面のスクリーンショットを撮影して見せる。
- 実データが入った状態を見せる（表の中身・画面）。数値や中身そのものを出す
- その数字が正しいか裏を取る。出典ページの URL と突き合わせ、一致していることを示す
「空欄が消えた」「取得不可 0 件」のような "無かった数" だけで終えない。それだと「取れなかったのが 0」とも読めて、何が良くなったのか伝わらない。
悪い例:
取得不可 0 件になりました。
（"無かった数"だけ。直った実感がない）
良い例:
直りました。表に実データが入り、空欄は無くなりました。
| 商品 | レビュー件数 |
| --- | --- |
| 商品A | 13 件 |
| 商品B | 18 件 |
件数が正しいか出典ページを開いて確認しました。表示と一致しています。
| 商品 | 出典ページ | 件数 | 判定 |
| --- | --- | --- | --- |
| 商品A | https://example.com/item-a | 13 件 | 一致 |
| 商品B | https://example.com/item-b | 18 件 | 一致 |
（実データ＋裏取りがセット。何がどう良くなったか一目で分かる）
UI・画面の話は「絵」で見せる
画面の見た目や「こう変わる」という話を文章だけで説明しない。読み手（お客さん・非エンジニア）は文章からは画面を想像できず、「で、どうなるの？」となる。
- 1枚の絵を添える。今の画面と、変わった後のイメージを並べた図を作って画像で貼る。文章は絵の補足に留める
- **「既存の○○を流用して、こんなふうにできそうです」**という形にする。ゼロから作る話より、今ある画面を使い回す形で見せた方が伝わるし安心される
- 相手の意図に沿った案にする。相手が「A と比べたい」と言っているのに別の基準（B）を持ち出さない。まず相手の言ったとおりに作れるかを調べ、その線で見せる
- 「既存の○○を流用できる」は出どころまで書く。「もう出しています」「すでにあります」だけだと、読み手はどの画面の・どう作られたデータか分からない。「○○の機能で、△△として作られて画面の□□に出ている。それを使い回す」まで具体的に書く。書く前に自分でその出どころ（どの処理が作り、どこに表示されているか）を確認しておく
- 内部の仕組みは書かない／不要な確認を足さない。「どう計算しているか」のような中身は読み手を混乱させるだけ。画面に見えている呼び名だけで書く。相手が既に決めたことを蒸し返す確認も付けない
質問・相談コメントのとき
- 1〜2 行で、本文だけ。見出しなし
- A か B か丸投げしない。自分のたたき台を1つ出して「〜で良さそう？」と確認をもらう形にする
- 例: 「グラフの外側に少し余白を作るイメージで良さそうですか？」