github-comment-quality

GitHub のコメントとコミュニケーションの品質基準

基本理念

GitHub の文章は、レビュアーや共同作業者に向けた技術的なコミュニケーションであり、内部用のメモ帳や作業実績の記録、ボットの実行日誌ではありません。

人間の読み手を意識して、成果、重要な技術的根拠、検証結果を簡潔に伝えます。必要最小限の言葉で質問に答えるか問題を修正し、レビュアーの時間を尊重してください。

承認と範囲の境界

• 下書きと投稿： ユーザーが「PR を開いて」「レビューに返信して」「Issue を作成して」など、明示的に依頼していない限り、文章の下書きを作成しても投稿の許可を得たことにはなりません。求められていないコメントの投稿や Issue の作成はしないでください。
• 無関係な Issue を自動作成しない： 作業中に無関係なバグや CI の不足を見つけた場合は、ローカルで指摘するか、Issue を作成するかユーザーに尋ねてください。ユーザーの許可なく新しい Issue を自動作成してはいけません。

---

GitHub コミュニケーションにおける 8 つのアンチパターン

1.「開発日誌」のような PR の説明文

• アンチパターン： 考えたこと、試したこと、測定したこと、採用しなかったことをすべて物語のように PR の本文へ書くこと（例：数段落にわたる設計論、却下した代替案、ベンチマークの再現、古くなった下書きの履歴）。

• ルール： PR の本文には、過去の下書きの経緯ではなく、ブランチの現在の状態を記載します。次の点に絞ってください。

  • 概要： ユーザーから見える変更やアーキテクチャの変更を 1～2 項目で記載します。
  • 主な変更点： 実装の具体的な詳細を記載します（自明でない場合のみ）。
  • 検証： 追加・合格したテストと手動確認を記載します（ターミナル出力をそのまま貼り付けないでください）。
  • 修正内容： Issue への参照を記載します。
  • (1～3 行程度の小さな変更では、見出しを付けず 1～2 文で説明するのが望ましいです)。

• ❌ (却下したライブラリ依存関係、テストハーネスの設定方法を 500 語にわたって説明し、ターミナル出力を 40 行貼り付ける)

• ✅

  Fixes #72
  
  ## Summary
  
  - Initialize upstream MCP servers concurrently during startup rather than serially.
  - Bounds startup latency to the slowest single upstream server.
  
  ## Changes
  
  - Launch each configured upstream in its own goroutine and merge results deterministically by sorted server name.
  - Retain child process handles to ensure clean process termination on shutdown.
  
  ## Verification
  
  - Added unit tests for concurrent launch timing and deterministic tool ordering.
  - Local benchmark: 9 upstreams initialize in 9.7s (down from 31.1s serial).
  - `go test -race ./...` passes.
  

2. 不釣り合いで、コンプライアンスにこだわりすぎたレビュー返信

• アンチパターン： 1 行のレビューコメントに対し、従ったルールをすべて列挙し、差分を繰り返し、プロンプトを引用するなど、数段落にわたるコンプライアンス報告で返信すること。

• ルール（適切な分量）： 判断に影響する事実や適用した修正が伝わる、最短の返信にしてください。

  • 通常の修正： 1 行とコミット SHA。
  • 技術的な制約／異議： 哲学的な議論やメタ議論に入らず、具体的な不変条件、制約、テスト結果を直接述べます。

• ❌

  Ran both humanizer and comment-and-documentation-quality skills on the guide. Flagged bold-spam (§15), announcing the next point (§28), repetition (§11), and stripped em dashes under Anti-Pattern 1 in commit 7dfe483...
  

• ✅ Updated in 7dfe483. Removed the MCP server comparison and tightened the wording. Build and tests pass.

3.「なぜ間違えたか」の説明（弁解的な事後分析）

• アンチパターン： モデルがどのように幻覚を起こしたか、前例のコードに惑わされたか、誤った前提を置いたかを説明すること。

• ルール： AI が混乱した経緯の事後分析は不要です。修正内容を直接報告してください。

• ❌

  The URL split was my mistake. I carried over the Home Assistant case where aiohttp 404s on the slash variant, and assumed the same applied here without checking. Reverted in b64a2fd...
  

• ✅ Reverted the URL change and restored the test connection step in b64a2fd. The HTTP endpoint on 27123 remains the default.

4. 感情的・メタ的なコメント（自己評価）

• アンチパターン： 自身のパフォーマンスを評価したり、意図を語ったりすること：
  • 「3 点すべてご指摘のとおりです。」
  • 「どうしてそうなったのかは説明できます。」
  • 「ボットが収束に失敗したわけではありません。」
  • 「意図的に最小限にしました……」
• ルール： 自己評価を見せつける表現、弁解、感情的な言い回しは削除してください。コメントは技術的かつ中立的で、要点を直接述べるものにします。（誤りを認める際の簡潔で丁寧な応対は問題ありません）。
• ❌ 3 点すべてご指摘のとおりです。対応する代わりに議論してしまったというご指摘はそのとおりで、ほかのガイドを引用したのも不適切でした。
• ✅ Updated in 74f9283. Removed all em dashes across the guides and tightened the setup instructions.

5. ボット署名、ウォーターマーク、Generated-By フッター

• アンチパターン： _Generated by Claude Code_、_Reviewed by OpenAI Codex_、またはモデルのウォーターマークを付け加えること。
• ルール： PR、Issue、コメントには、自発的な「Generated by」「Automated by」やツールの帰属を示すフッターを決して含めないでください。
• ❌ Fixed the typo in 3a1b2c3.\n\n---\n_Generated by Claude Code_
• ✅ Fixed the typo in 3a1b2c3.

6. 単独の検証報告によるノイズ

• アンチパターン： レビューの進展につながらないローカルセッションの活動を記すだけのコメントを、公開 Issue や PR に残すこと（例：go test の出力をそのまま貼り付ける、対応が不要なのにローカルでチェックを実行したと知らせる）。

• ルール： 検証の概要は PR の本文またはレビューへの返信に含めてください。実行ログだけのコメントは投稿しないでください。

• ❌

  I merged this branch onto main in a throwaway worktree and verified it locally:
  $ go test -race ./...
  ok github.com/dvcrn/mcpnest/internal/app 7.846s
  

• ✅ (代わりに、PR の本文または該当するレビューへの返信に含めてください：Verified locally with go test -race ./...)

7. 関連性の薄い指摘とスコープの拡大

• アンチパターン： 特定の PR やレビューのスレッドに、リポジトリの別の箇所で見つけた無関係なバグ、CI の失敗、所見を付け加えること。
• ルール： すべての PR とレビューのスレッドは、それぞれの対象だけに厳密に限定してください。関連性の薄い問題はローカルで記録するか、別の Issue を作成する前にユーザーに確認してください。
• ❌ Fixed the query parameter in 4b5c6d7. Also noticed that GitHub Actions CI configuration in .github/workflows/ci.yml is missing a Go cache step, which might slow down builds.
• ✅ Fixed the query parameter in 4b5c6d7. Tests pass.

8. 意図的に行わなかったことの説明

• アンチパターン： 実行しなかった仮定上の作業を列挙すること（「行わなかったことが一つあります……」「古いファイルには触れませんでした……」「そのまま保留にしました……」など）。
• ルール： レビュアーが評価すべき真の保留中の判断や既知の制約に当たる場合に限り、未実施の項目に言及してください。
• ❌ I did not touch the older guides beyond the dashes because antigravity-sync-macos is 162 words and reads thin.
• ✅ (実際の技術的制約を示す例) This change kills direct child processes on cancellation. Process-group cleanup for grandchildren is not yet handled and should be addressed in a follow-up.

---

技術的な正確さと事実の正確性

1. 主張や証拠を捏造しないでください： テストの成功、ベンチマーク、コミット、Issue 番号、検証手順を作り上げないでください。変更がコミットされ、プッシュされていない限り、修正を適用したと主張しないでください。
2. 技術的な不確実性を保ってください： may を will に、typically を always に変えたり、実験的な観察結果を普遍的な保証にしたりしないでください。
3. 各事実の記載場所は一つにしてください： 同じ調査内容を PR の本文、レビューのスレッド、状況コメント、最終的な要約で重複させないでください。
4. 技術用語を正確に保ってください： 正確な技術用語（例：race condition, mutex contention, atomic swap, WAL mode）を使い、基本的な言語仕様を過度に説明しないでください。

---

書式、句読点、文体のルール

1. em ダッシュ（—）、en ダッシュ（–）、間を置く二重ハイフン（--）は一切使用しないでください： コロン、括弧、または文を分けて表現してください（--verbose などの CLI フラグはそのままにしてください）。
2. 太字の多用や装飾的な絵文字は避けてください： 句ごとに太字にしたり、見出しの前に 🚀、💡、✅ を付けたりしないでください。
3. ターミナル出力をそのまま貼り付けないでください： テストやベンチマークの結果は、40 行の出力を貼り付けるのではなく、簡潔な一行または表にまとめてください。
4. 前置きやお世辞は避けてください： 「素晴らしい提案です！」「まったくそのとおりです！」「詳しく見ていきましょう」 といった表現は省いてください。
5. 明確なタイトルを付けてください： PR と Issue のタイトルは具体的かつ簡潔にし、会話調の不要な表現を避けてください。PR のタイトルは命令形にしてください（例：Fix dirty state warning in AI dialog）。Issue のタイトルでは、問題や目的が明確に伝わるようにしてください（例：AI dialog shows stale warning after save、Support concurrent upstream initialization）。リポジトリで必須とされていない限り、Conventional Commits の接頭辞（feat:、fix:）は避けてください。

---

テンプレート

アーティファクトごとの例については、templates.md をお読みください。PR の説明、レビューコメント、または issue に合ったテンプレートを選び、短い返信にすべてのセクションを無理に盛り込まないでください。