私たちには要点を。エージェントにはすべてを。

今、プルリクエストの説明、レビューへの返信、issueの大半はエージェントが書いています。文章は上手です。ただ、とにかく長いのです。

長いプルリクエストの説明は読まれません。レビュアーは最初の数行に目を通し、スクロールして、承認します。あるいは、本文にもう書いてあることを質問します。一方、次にそのスレッドを引き継ぐエージェントは、すべてを必要とします。何が変わったのか、なぜか、何をテストして、何をテストしていないのか。

つまり、どの投稿にも読み手が二人いるのです。そこで、一つの文章で両方に向けて書くのをやめました。

冒頭に2文、残りは折りたたむ

エージェントから投稿する文章は、今はすべて同じ形です。

1. 人向けの、1〜2文の冒頭。スキルではこれをリード（lead）と呼びます。
2. 区切り線。
3. 全文を入れた、折りたたみブロック。エージェント向けですが、すべて読みたい人も開けます。
4. 書いたスキルの名前を入れたフッター。

GitHubではブロックは<details>要素、Linear（多くの開発チームが使う課題管理ツール）では>>>ブロックです。どちらでも、レビュアーに見えるのは2文と閉じた箱だけです。

実際の例として、私が出したRaycastのHomebrew拡張機能へのプルリクエストを載せます。冒頭には何が変わったか、何をレビューしてほしいかが書いてあります。そのすぐ下にビフォー・アフターの画像があり、それ以外はすべて折りたたまれています。

ひとつ注意があります。GitHubのコマンドラインツールが画像をアップロードできるのは、リポジトリに書き込める人だけです。自分のフォークから他人のプロジェクトにプルリクエストを出すときは、たいてい書き込めません。そこでスキルは、画像の欄に目印を入れた表を投稿し、どのファイルをどこに入れるかを伝えます。画像はブラウザで貼り付けます。ブラウザなら、どの貢献者でも画像を追加できます。

変更前	変更後
📎 ここにdia-before.pngを貼り付け	📎 ここにdia-after.pngを貼り付け
diaでAirMediaが先頭。Diaは3ページほど下。	diaでDiaが先頭。その後に「dia」で始まる名前が続く。

とても短い投稿では、折りたたみブロックを付けても同じことの繰り返しになります。レビューコメントへの返信なら、「b72e019で修正しました。もう一度レビューをお願いします。」の1行で足ります。そのときエージェントはその1行だけを投稿し、区切り線も、折りたたみブロックも、フッターも付けません。

冒頭で、やってほしいことを伝える

冒頭には二つのことを書きます。何が変わったかと、読み手に何をしてほしいかです。「待ち時間の値を確認してください。」「ダークモードでのエラーの色を確認してください。」やることがなければ、何が変わったかを書きます。

エージェントは冒頭を最後に、詳細を書き終えてから書きます。先に書くと「このPRでは…」で始まる前置きになりがちです。最後に書けば、すでにある内容の要約になり、やってほしいことがひと目で分かります。

次にやることから書くという考え方は、i-have-adhdというスキルから来ています。ADHDがあってもなくても役に立ちます。忙しいレビュアーも同じ問題を抱えているからです。

詳細は省かない

折りたたみブロックは要約ではありません。リポジトリにプルリクエストのテンプレートがあれば、ブロックはその見出しに一つずつ従います。テンプレートはメンテナーが丁寧なレビューのために用意したものなので、そのまま残します。邪魔にならない場所に移すだけです。テンプレートがなければ、スキル自身の見出しを使います。概要、なぜ、変更点、確かめたこと、確かめていないこと・理由です。

つまり、レビュアーには入り口が二つあります。ざっと見るなら、冒頭とスクリーンショットで十分です。何が変わったか、どう見えるか、何を確認すればいいかが分かります。丁寧にレビューするなら、コードとブロックを開けば、自分たちが求めたテンプレートが埋まった状態で見つかります。

いちばん大事なのは「確かめていないこと」です。CIが通っても、証明されるのはCIで動かした部分だけです。何を確かめていないかを書くエージェントは、レビュアーに見るべき具体的な場所を渡してくれます。テンプレートに項目がなくても、スキルはこのセクションを加えます。

ブロックは普段は開かれないので、必要なだけ長くできます。短い投稿か、完全な投稿か、どちらかを選ぶ必要はありません。

Homebrewのプルリクエストのブロックを開くと、Raycastのテンプレートどおり、DescriptionとScreencast、最後にチェックリストが並んでいます。その間に、スキルがHow it was tested(実行したコマンドとその結果)とNot tested (and why)を加えています。

あなたの言語を、あなたの順番で

チームの全員が英語を楽に読めるとは限らず、全員が英語で書くわけでもありません。そこでスキルは、あなたの言語で書きます。先頭に来る言語と、その下に続くほかの言語です。

初めて使うとき、スキルはあなたがエージェントに書いている言語で二つ質問し、答えを既定として保存します。

投稿はどの言語から始めますか？

英語

その下にほかの言語も加えますか？

はい：日本語

その後は、投稿ごとに普通の言葉で変えます。「英語だけ」「日本語を先に」「ポルトガル語だけ」などです。日本語が先頭のときは、英語の原文が原文:の後に来るので、どれが元の文か読み手に分かります。

前に出したHomebrewの修正で試しました。本物のプルリクエストは英語のままにして、貢献しているオープンソースのプロジェクトを乱さないようにしました。自分のフォークで同じ変更を英語と日本語で出し、同じようにLinearのissueも作りました。

自分の言語の文を先に書き、ほかの言語はすべて仕上がった文から訳します。下書きから訳すと、最終版とずれていくからです。

投稿の前に、小さなスクリプトが文章をチェックします。どの言語でも、文の長さを制限します。30語まで、日本語のように単語の間にスペースがない言語は80文字までです。英語では、エムダッシュ、短縮形、「should」のようなあいまいな語も探し、冒頭、区切り線、ブロック、フッターといった形式の各部分もチェックします。意味まではチェックできないので、スキルはエージェントに冒頭だけを読み直すようにも指示します。英語のルールはsimple-englishとunslopをもとにしています。

一つのスキルに、一つの役割

スキルは4つあり、それぞれが一つのことを受け持ちます。

• postは文章を受け持ちます。形式、言語、文体、チェックです。
• githubとlinearはプラットフォームを受け持ちます。記法とコマンドです。
• create-prはプルリクエストの流れを受け持ちます。正確なコミット範囲、チェック、タイトル、そして冒頭のすぐ下に置くビフォー・アフターの画像です。文章にはpostを使います。

GitHubの表示が変わったら、変えるのはgithubだけです。冒頭を良くしたいときは、postだけを変えます。あとでgitlabスキルをgithubの隣に、jiraスキルをlinearの隣に加えても、ほかのスキルには手を入れずに済みます。

フッターには実行したスキルの名前が入ります。たとえばclins:create-prです。結果が気に入った人は、何を実行すれば同じものが得られるか分かります。

試してみる

デモでは、各スキルが書く文章を、GitHubとLinearでの架空の例で見られます。一つのプルリクエストを、4つの言語の組み合わせで切り替えて見られる例もあります。

スキルはオープンソースです。どのコーディングエージェントにも、次のコマンドでインストールできます。

npx skills add clins1994/skills

issueやプルリクエストは歓迎です。コントリビューションガイドに、取りかかりやすいアイデアをいくつか挙げています。