format-post

読み手の手間を減らすために使う。 飾りとして足すと、本当に見てほしいものが埋もれます。量が増えるのは構いません。判定は読み手が「何を・なぜ・何がリスクか・どう検証したか」を拾うまでに、読み返し・探索・組み立て直しが要るかです（ /update-pr-description の references/body.md の「読み手が拾う4点を軸にする」）。

量と流れ（過不足なく書く・概要から詳細へ流す・読み手の想定・表と図で畳む）と、投稿前に拾うもの（指す先が決まらない語・読点・1文の長さ・否定）は references/writing.md が持つ。 書き始める前と投稿の直前に開く。下の節はどの手段で畳むかを選ぶためのもの。

描画されるかどうかは、記憶ではなく一次情報で確かめる。

資料	持っているもの
GitHub Flavored Markdown の仕様	表・取り消し線・自動リンク・生の HTML（ <details> ）など、記法の描画規則
基本的な書き方とフォーマットの構文	Alert・脚注・見出しへのリンク・メンションなど、仕様の外にある GitHub の拡張と、その使い方の注意

手段の選び方

手段	使う場面	詳細
表	同じ観点の項目が3件以上	concise_first_then_detail.md
Mermaid	列挙から読み取れない構造・関係・流れ	同上
Alert	読み飛ばすと事故になる1〜2点	下記
<details>	その場で開ける形で長い実体を置く	下記
脚注	本筋から外れる1行の補足	下記
パーマリンク	コードの特定の行を指す	下記
見出しへのリンク	本文の別の節を指す（「詳しくは下のテスト内容」を探させない）	下記
引用（ > ）	課題票・仕様・レビュー指摘の原文をそのまま示す	言い換えると、読み手は原文と食い違っていないかを確かめに行く
別コメント	本文と独立に参照される情報のかたまり	/create-pr / /update-pr-description

既存の対応と、この PR で足した分を表で分ける

複数の対象と複数の経路にまたがる PR で、既に対応済みの部分とこの PR で足した部分が混ざるなら、本文の冒頭に表を置く。行に対象、列に経路を取り、各セルを「既存」「この PR」「対象外」で書き分ける。既存のセルには対応したマージ済みの PR 番号を添える。

散文で「〜は既存、〜はこの PR」と並べると、読み手が境界を頭の中で組み立てることになる。対象か経路が1つしかないなら表は1行になるので、置かない。

本文の別の節は、見出しへのリンクで指す

「下記」「上の表」では、読み手が探しに行きます。 GitHub は見出しごとにアンカーを作るので、[テスト内容](#テスト内容) と書けば1クリックで着きます。

アンカーは見出しを小文字にし、空白をハイフンへ置き換え、句読点を除いて作られます。同じ見出しが2つあると、2つ目以降に番号が付きます。見出しを変えたらリンクも直す。 投稿したら描画された本文でリンクを1つずつ押して確かめる。

投稿先で変わるのは量、判断軸は同じ

本文だけの話ではありません。 補足コメントもレビュー返信も、散文だと長くなるなら畳む。

投稿先	向いている手段	注意
PR 本文	全部	Alert は1〜2個
補足コメント	<details>・表・パーマリンク	長い実体を置く場所なので <details> が最も向いている
レビュー返信（非対応の理由）	表・Mermaid・パーマリンク	観点が3つ（指摘 / 現状 / 判断）並ぶなら表
ハッシュだけの返信	何も足さない	1行目からハッシュを機械抽出できる形を壊さない
コマンドコメント	何も足さない	本文がコマンド1行でないと起動しない

返信でこそパーマリンクが役に立ちます。 「その行は今こうなっている」を示すのに path:line を書くと、相手が開いたときには差分が動いていることがあります。

Alert の1〜2個は本文の話。 コメントや返信は短いので、そもそも1個で足ります。返信に2個並ぶなら、それは返信ではなく別コメントか本文の役目です。

短さは免罪符になりません。 返信3行に表を付けるのは過剰で、散文のままが正解です。

Backlog の図は、本文は素の Mermaid、コメントは画像にする

Backlog は課題の本文では Mermaid を図として描き、コメントでは描きません。 置き場で書き方を分けます。

置き場	書き方	理由
課題の本文	```mermaid のコードブロック	本文では描かれ、後から図を直しやすい
課題へのコメント	Mermaid を PNG にして添付し、![image][<ファイル名>] で埋める	コメントでは描かれず、ソースのまま出る

• PNG は bunx -p @mermaid-js/mermaid-cli@latest mmdc -i x.mmd -o x.png -s 2 -b white で描く。@latest を外すと、bunx は以前に取ってきた古いバージョンを使い続け、バージョンによっては図が崩れる。描いたら投稿の前に開いて、崩れていないかを見る
• 添付は API の POST /api/v2/space/attachment へ上げて返った ID を、bee issue comment の --attachment に渡す。bee にはアップロードが無い
• 図を直すときに使う .mmd は手元に残す。コメントには PNG しか残らないので、捨てると図を描き直すことになる
• コメントの添付はコメントの編集では差し替えられない。 図を直すなら、まだ読まれていないコメントは消して投稿し直し、読まれたコメントには新しいコメントで足す（ keep_records_current.md ）

Alert は3種だけ使う

GitHub には5種ありますが、使うのは3種に絞ります。選択肢が多いと毎回迷い、迷った末に強い方を選びがちになります。

種類	使う場面
NOTE	生成者表示に占有されている（ github_note_generated_by_claude.md ）。他の用途に使わない
IMPORTANT	知らないと動かせない・順序を誤ると壊れる（マージ順、DB の再生成、前提の設定）
WARNING	既存の挙動が壊れうる（この経路だけ並行更新に弱い、この条件で値が落ちる）

TIP は PR に書く場面が無く、CAUTION は WARNING と役割が重なるので使いません。

本文には1〜2個。生成者表示の NOTE は数えません。 GitHub 自身が「1記事あたり1〜2個」としており、生成者表示は末尾の固定節よりさらに後ろにあるので、本文の Alert と注意を奪い合っていません。連続して置かないのは GitHub の指示どおり守ります。

順序を逆にしないでください。 先に 「読み飛ばすと事故になるか」で選び、その結果が2個を超えたときに畳み方を見直す。上限から逆算して落とすと、大事なほうが散文へ戻ります。実際に「手元で DB を初期化しないとテストが落ちる」と「この経路はロックを取るので後から来た更新が待つ」の2点が競合し、後者を落とす判断をして戻した例があります。

3つ目の候補が出たら、それを信号として扱う。 たいてい次のどちらかです。

• 3つ目は警告ではなく説明（読み飛ばしても事故にならない）
• 本文が構造化できていない。同じ主題の危険が分かれているなら1つに束ねるか、表に畳む

Alert は他の要素の中へネストできません。 表のセル・箇条書きの中には置けないので、置くなら独立した位置に。

<details> と別コメントを使い分ける

どちらも「本文を汚さずに詳細を置く」手段なので、基準を持たないと毎回迷います。

	<details>	別コメント
置く場所	その情報が要る節の直下	本文の外
読み手	その節を読んでいる人が、その場で開く	必要になった人が探して開く
例	検算の件数表、テスト出力の抜粋、失敗したときのログ、SQL の全文、全件の列挙	API 契約の全文、調査ログ、他リポジトリ向けの申し送り

<summary> には中身が分かる名前を付ける。 「詳細」では開くまで判断できません。

畳んだ中身にも本文と同じ基準を当てる。 畳めば何を書いてもよいことにはなりません。

何を畳み、何を見せたままにするか

使えるところでは使う。判定は「読んで判断が変わるか」。 変わるものは見せたまま、それを支える根拠の実体（上の表の <details> の例）は畳む。

見せたまま	畳む
結論・症状・影響範囲・注意点・修正前後の画像	結論を支える実体（件数表・ログ・SQL・列挙）

畳んだら、外に結論を1行置く。 実装を戻したときに落ちるテストの表なら、「6箇所のどれを戻しても1〜2件落ちる」を外に出して表を畳む。<summary> は中身の名前で、結論の代わりにはなりません。開かない読み手に結論が届かないためです。

開かないと筋が追えなくなるなら畳みすぎ。 判断に使うものまで隠すと、短くした分だけ分かりにくくなります。上の「畳んだ中身にも本文と同じ基準を当てる」とは向きが逆で、両側から量を決める。

コードの行を指すときはパーマリンクを使う

path:line は行がずれた瞬間に別の行を指します。レビュー中は差分が動くので、書いた側が正しくても読む側には違う行が見えます。

パーマリンクはコミットに固定されるので、別の行を指すようになりません。 GitHub 上でファイルを開き、行番号をクリックして y を押すと、コミットハッシュを含む URL になります。

https://github.com/OWNER/REPO/blob/<commit>/path/to/file.go#L42-L48

同一リポジトリのパーマリンクは、GitHub がコード片として展開して表示します。引用を貼らずに済むので、その場で読める。

path:line を書いてよいのは、差分の中で位置が自明なとき（インラインコメントの中で同じファイルを指す等）だけ。

自動クローズのキーワードを書かない

Closes #123 / Fixes #123 / Resolves #123 は、マージした時点で対象を閉じます。

閉じる時機は自分で決める。 依存する変更が別 PR に残っている、リリースまで開けておきたい、複数 PR で1つの課題を分けている。いずれもマージしたら完了、ではありません。

参照するだけなら #123 と書けば足ります（ github_writing.md ）。リンクは張られ、閉じません。

脚注は着地位置に注意する

GitHub は脚注を描画結果の末尾へ集めます。 PR 本文では生成者表示より後ろに出るので、テンプレの節構成とは無関係の位置に着地します。

そのため、節の中で読まれる必要がある補足には使わない。使うのは、読み飛ばしても本筋が通る1行だけです。

括弧書きで済むなら括弧書きにする。脚注は読み手に往復させるので、1行の補足に見合わないことが多い。

やってはいけないこと

• Closes / Fixes / Resolves を書くこと。マージした時点で対象が閉じる。閉じる時機は自分で決める
• 本文に Alert を3つ以上置くこと。GitHub 自身が1〜2個に制限している（生成者表示の NOTE は数えない）
• 上限から逆算して落とすこと。先に「読み飛ばすと事故になるか」で選ぶ。数を守って大事なほうを散文へ戻すのは逆
• Alert を表のセルや箇条書きの中へ入れること。ネストできず、記法として壊れる
• <summary> を「詳細」で済ませること。開くまで中身が判断できない
• 判断に使うもの（結論・症状・影響・画像）を <details> へ畳むこと。開かない読み手に届かない
• 畳んだのに、結論を外に置かないこと。<summary> は中身の名前で、結論の代わりにならない
• 差分が動く箇所を path:line で指すこと。行がずれると別の行を指す

関連

• github_writing.md （常駐のルール）: アノテーションと、フックもスキルも通らない経路の注意はあちらが持つ。本スキルは PR 本文・コメントを書く場面に限った手段の選び方
• concise_first_then_detail.md （簡潔に）: 表と Mermaid の使い分けはあちら。本スキルは GitHub でしか使えない手段を足す
• github_note_generated_by_claude.md （生成者表示）: NOTE を占有している。他の Alert と混ざらないよう用途を分ける
• github_writing.md （他リポジトリの参照）: #123 は参照するだけで閉じない
• github_writing.md （1文ごとに改行）: あちらは文の表記、本スキルは構造の選び方
• /create-pr / /update-pr-description / /review-pr / /resolve-ai-reviews / /resolve-human-reviews: 本スキルが土台で、各スキルは投稿先固有の事情を上乗せする