github-writing — 読み手が一読で行動できる文章を書く

GitHub 向けの文章 (PR 本文 / Issue・PR スレッドのコメント / レビューコメント) が対象。 「言いたいことは全部書いてあるが、何をすればいいか分からない」文章を防ぐ。網羅性より 可読性と行動可能性を優先する。ドキュメント全般の絵文字禁止は CLAUDE.md の Documentation Style 節を継続して守る。

4つの役割を混ぜない

事実・判断・依頼・次アクションを段落または見出しで分離する。1つの長い段落に事実と 理由と経緯を詰め込まない。

1. 事実: 観測・計測・コードから確認できたこと
2. 判断と理由: 何をどう決めたか、なぜか
3. 依頼: 相手にしてほしいこと (確認・承認・修正など)。埋もれさせず、探さなくても 見つかる位置に置く
4. 次アクション: これを読んだ人が次に何をすればいいか

依頼が無い文章 (質問への回答など) では 3 を省いてよい。ただし省いたことを意識的に 判断すること。

分離の手段 (見出し / 太字ラベル / 段落分け) は文章量に応じて選んでよく、4つ全てに 機械的に見出しを立てる必要はない。内容が薄い役割は隣接する役割の段落に含めてよい。 ただし性質の違う内容 (例: 事実と判断) を同じ文の中で混在させないこと。

用語と網羅性

• 専門用語・内部の task_id・内部でしか通じない略語は、初出で開くか、開けないなら削る。 相手が知らない語で説明しない
• 「やったこと全部」を書かない。相手の判断や行動に必要な情報だけを本文に置き、根拠・ ログ・検討経緯は <details> に畳むか報告ファイルへのポインタにする
• 冒頭で結論を書く。経緯から書き始めない。読み手は最初の数行で「何の話で、自分は何を すればいいか」を掴めること
• 1文だけの段落を空行で細かく区切って縦に間延びさせない。関連する項目は箇条書きに まとめ、連続する空行 (2行以上) は作らない
• 他リポジトリの Issue / PR を参照するときは owner/repo#番号 で書く。#番号 だけだと 投稿先リポジトリの同番号を指し、別物に誤リンクするかリンクにならない

投稿前の自己チェック

一読しただけで次の3つをそれぞれ1文で言えるか確認する。言えないなら投稿しない。

• (a) 今どうなっているのか
• (b) 我々が何をどう決めたのか、なぜか
• (c) 自分 (読み手) が何をすればいいのか

before / after

before は 2026-08-06 に作成した Issue 返信ドラフトの一段落。事実・判断・理由・社内の 検討経緯が1つの段落に混在していて、読み手が知りたい「バグか」「いつ入るか」に一読で たどり着けない。

1点目 (shelf_detached のブリッジ側実装予定について) 現時点で PR #48 (head 6d00e13) には 未実装です。これは実装漏れではなく、設計段階でスコープを phase 1 と phase 2 に分けた 意図的な判断です。phase 1 (今回配備済みの範囲) では、棚外れの実際の検知そのもの (積載 期待という状態の判定、Kachaka API の GetMovingShelfId や GetError 14606 の購読) は見送り、 検知結果が得られない間は自動解放を発動しない fail-closed の最小限のゲートだけを実装 しました。理由は大きく2点です。ひとつは、実際の棚外れ検知には起動直後の未積載や意図的な 棚下ろし運用と事故的な棚外れを区別するための状態管理が必要で、設計・検証のコストが 大きいことです。もうひとつは、現行のブリッジが常駐の非同期処理を持たない同期呼び出し 中心の周期ポーリング構成のため、新しい状態監視を追加するには相応の実装コストが伴う ことです。なお検討の初期段階では、検知結果が無い間の安全ゲートまで先送りする案も ありましたが、mode: release を設定できる一方で保護の仕組みが何も無いのは矛盾だという 指摘を受け、そのゲートだけは先行して組み込む方針に改めた経緯があります。

after は同じ内容を、相手が知りたい「バグではないか」「いつ入るか」を起点に事実・判断・ 理由・次アクションに分けたもの。社内の検討経緯 (先送り案から今の方針に変えた経緯) は 相手の行動に不要なので落とした。

1点目 (shelf_detached のブリッジ側実装予定について)

shelf_detached の検知は PR #48 (head 6d00e13) 時点で未実装です。バグではなく、phase 2 に 意図的に先送りしています。phase 1 では、検知結果が無い間は自動解放を発動しない fail-closed ゲートのみを実装済みです。

先送りの理由は2点です。

1. 実際の検知には、起動直後の未積載と事故的な棚外れを区別する状態管理が必要で、設計・ 検証コストが大きい
2. 現行ブリッジは周期ポーリング構成のため、新しい状態監視の追加コストが大きい

検知の実装は phase 2 で行う予定です。着手時期が決まり次第この Issue で共有します。

対象ごとの違い

以下は「4つの役割を混ぜない」を土台にした、対象別の追加要件。基礎原則を置き換える ものではなく、レビューコメントのように役割を簡略化する場合も「事実と依頼・判断を 混ぜない」という原則自体は保つ。

• PR 本文: 読み手はレビュアー。冒頭で「何をレビューしてほしいか」と影響範囲を示す。 実装過程のログや試行錯誤は <details> に畳む
• Issue・PR スレッドコメント: 会話の一部であることを意識する。直前の質問に対する 回答という体裁を保ち、前提の再掲は最小限にする
• レビューコメント: 指摘ごとに blocking (このままではマージ不可) か non-blocking (nit・提案) かを明示する。これが無いと著者はどこまで直せばよいか判断できない。 個別の指摘は必ず該当行の行コメント (inline review comment) として付ける。本文に file:line + コードブロック引用でまとめる書き方は使わない。行コメントなら著者が 該当箇所を探さずに diff 上で直接解決できる。レビュー本文には全体の判断・検証結果・ 依頼だけを残す。対象コードを示さない「〜が問題です」「〜を修正してください」だけの 指摘は書かない

レビューコメントの投稿手順

gh pr review --comment --body-file は本文しか送れず、行コメントは付かない。行コメントは API を直接叩く。

gh api -X POST repos/OWNER/REPO/pulls/N/reviews --input - <<'EOF'
{"commit_id": "<head SHA>", "event": "COMMENT", "body": "<全体の判断・依頼>",
 "comments": [
   {"path": "path/to/file", "line": 23, "side": "RIGHT", "body": "non-blocking / nit\n\n..."},
   {"path": "path/to/file", "start_line": 15, "line": 21, "side": "RIGHT",
    "start_side": "RIGHT", "body": "non-blocking / 提案\n\n..."}
 ]}
EOF

• 複数行にまたがる指摘は start_line + start_side を足す
• 行番号は変更後ファイルの行番号。diff に現れない行にはアンカーできない
• 提出済みレビューは削除できない (Can not delete a non-pending pull request review, HTTP 422)。本文を差し替えるときは PUT repos/OWNER/REPO/pulls/N/reviews/{review_id} で body を更新する。書き換え前に現在の body を必ず fetch する