無料GitHub で公開

github

GitHubでpull requestを作り、文章を書く時の心得。PRのタイトルと概要欄の書き方、リンクが壊れない書き方、親子PRの組み方を定める。 pull requestを作成・更新する時、GitHubに載る文章を書く時に読み込む。

含まれるファイル（1）

インストールする前に、エージェントに与えられる指示の中身を確認できます。

pull requestを作成・更新する時、GitHubに載る文章を書く時は、以下の基準に従う。repoのドキュメントやPRテンプレートに別の定めがあれば、そちらに従う。文体はkuden:writing skillの基準に従う。

タイトルは、なぜ変えるのかと、この変更で何がどう変わるのかを、1文で書く。理由と、挙動がどう変わるかが書いてあれば、レビュアーはタイトルだけで妥当性の見当が付く。

実装の手順をなぞらない。そのPRで新しく作った関数名やファイルパスを並べたタイトルは、diffを読むまで意味が分からない
症状を消すとだけ書かない。「warningを消す」は握り潰しとも読め、変更の性質が伝わらない。「findOneAndUpdateのnew: trueはdeprecatedなのでreturnDocument: afterを使う」のように、理由と置き換えの中身を書く
ユーザーに見えるbugの修正は、「<再現条件>で<症状>が起きる問題を修正」の形で書く。どう直したかは、概要欄の冒頭に置く
画面に関わる変更は、実装の語ではなく、影響する画面の名前で範囲を示す
既存のtoolに出力を1つ足すような小さな変更は、理由を付けず、既存のファイル名やfield名で短く書く。理由を付けて長くなるなら、理由は概要欄に回す
commit messageの1行目も、ここまでの基準で書く
文末の時制や区切り方は、そのrepoのmerge済みのPRやcommitに合わせる

概要欄、コメント、commit message等、GitHubで表示される文章の全てに当てはまる。

#1234 やURLの前後には、半角スペースを入れる。#1234で直した はリンクにならない。(https://example.com/日本語のページ)。 は、)。 までがURLに含まれる
#数字 は、issueとPRの番号にだけ使う。Dependabot alertのように別の番号体系を持つ物は、フルURLで書く。#数字 で書くと、同じ番号の無関係なissueやPRへのリンクになる
URLの日本語の部分は、percent-encodeせずに書く。encodeしたURLは、どのページへのリンクかを人間が読み取れない

親PRの概要欄に ## 子PR の節を置き、子PRを作る度に - #1234 の形で足す
子PRの概要欄の1行目に、#1234 の子PRです と書く
親branchは、default branchに空のcommitを1つ積んで作り、親PRにする。default branchに無いcommitが1つも無いと、PRを作れない
子PRは親branchに向け、子PR同士は兄弟にする。ある子PRのbranchから次の子PRを作ると、先のPRのcommitがdiffに混ざる
PRをどこに向けるかをユーザーに訊く時は、branch名ではなくPRの関係で訊く。「feature-x からbranchを切るか」ではなく、「#1234 の子PRにするか、mainに向けたPRにするか」と訊き、本番に載る時期のような帰結を添える

まだレビューはありません。使ってみた感想をお寄せください。

概要と使いどころ

無料日本語概要

Agent Skillを書く時の心得。SKILL.mdに何を書き、何を書かないかの判断基準と、レビュー指摘の採否の基準を定める。 Agent Skillを作成する時、編集する時、レビュー指摘の採否を決める時に読み込む。