github-contributor

GitHub コントリビューター

メンテナーが実際にマージしたいと思うプルリクエストを提出するための、フェーズ別プレイブックです。このスキルは実際の PR ライフサイクル、つまり調査 → 実装 → 品質チェック → 説明 → 提出後、に沿って構成されています。各フェーズにはそれぞれ固有の失敗パターンがあり、最もよくある間違いは、適切なことを不適切なフェーズで行うことだからです（例：規模が大きすぎる PR に完璧な説明を書く）。

フェーズ 0 — このスキルを使う場面

次のすべてに当てはまる場合に、このスキルを使ってください。

• 自分がメンテナーではないリポジトリに貢献する（メンテナーは説明なしに PR をクローズできます）。
• 作業が、ソースコード、テスト、ドキュメント、ビルド設定のいずれか 1 つ以上に関わる。
• PR を提出するだけでなく、マージしてほしい。

次の場合は使わないでください：自分のリポジトリ、共有コンテキストのある社内チームの PR、メンテナーが対応を待っている緊急修正ブランチ、またはごく単純な 1 行の変更（コメント 1 つで十分です）。

フェーズ 1 — PR 提出前の調査

PR がクローズされる最もよくある理由は、貢献者が受け入れ可能だと思い込んでいることと、メンテナーがすでに明文化している内容との食い違いです。コードを書く前に、これを解消してください。

ステップ 1.1 — CONTRIBUTING.md を厳格な契約として読む

CONTRIBUTING.md は単なるスタイル上の助言ではありません。番号付きのルールはすべて、マージの前提条件として扱ってください。特に次の点に注意してください。

• AI 支援による貢献に関する条項。 多くのプロジェクトで、AI による PR が相次いだ 2024〜2026 年に追加されました。よくある表現：「事前の相談がない AI 生成 PR はクローズする場合があります」「すべての行を説明できなければなりません」「1 つのイシューにつき 1 つの PR」。この条項がある場合、プロジェクトに対して明示的に開示する必要があり（フェーズ 4 を参照）、PR を小さく保つ必要があります。
• イシューを先に作成するルール。 機能 PR を開く前に、機能リクエストのイシューが存在していることを求めるプロジェクトもあります。
• 言語ごとのテストコマンド。 CONTRIBUTING.md に pnpm test:unit && cargo test と書かれている場合、実行するのはそれらのコマンドであり、IDE が推奨するコマンドではありません。

CONTRIBUTING.md がない場合、それ自体が危険信号です。詳細は references/project_evaluation.md を参照してください。

ステップ 1.2 — PR の規模がプロジェクトの基準に見合うか確認する

「小さな PR」の基準は相対的です。PR を開く前に、次を実行してください。

gh pr list --repo <owner>/<repo> --state merged --limit 10 \
  --json number,title,author,additions,deletions \
  --jq '.[] | "#\(.number) +\(.additions)/-\(.deletions): \(.title)"'

これにより、マージ済み PR の実際の規模の分布がわかります。自分の PR が最近マージされた最大の PR の 5〜10 倍の規模であれば、危険信号です。提出前に分割してください。基準の評価方法と分割のヒューリスティクスについては、references/phase1_discovery.md を参照してください。

ステップ 1.3 — コーディング前に 1 段落のスコープ契約を書く

スコープ契約とは、エディターを開く前に自分自身に向けて書く 1 段落です。

目標：<1 文で記述>。対象範囲：<箇条書き、3〜5 項目>。明示的に対象外：<箇条書き — 追加したくなったときに、何を追加しないか具体的に記述>。

その後、編集するたびに「これは対象範囲内か？」と自問してください。「ついでにこれも……」と思い始めたら、作業を止めて契約を見直してください。スコープの拡大は、マージされずにクローズされる最大の原因です。スコープを守る方法については、references/phase2_implementation.md を参照してください。

フェーズ 2 — 実装

ステップ 2.1 — upstream を取得したらすぐに main からブランチを作成する

git fetch origin
git switch -c feat/short-descriptive-name origin/main

必ず upstream の main（またはプロジェクトのデフォルトブランチ）からブランチを作成してください。古くなっている可能性のある、自分のフォークの main から作成してはいけません。

ステップ 2.2 — 問題を解決する最小限の差分にする

スコープ契約で直接必要とされていない変更は避けてください。特に、次の点に注意してください。

• 「ついでに」周辺のコードをリファクタリングしないでください。
• 変更していない行を再フォーマットしないでください（どちらも「Prettier」とされていても、フォーマッターがプロジェクトのものと異なる場合があります）。
• リネーム自体が修正に当たる場合を除き、わかりやすさのために変数名を変更しないでください。

後続の改善に本当に価値がある場合は、別のイシューを作成するか、この PR がマージされた後に別の PR を開いてください。

ステップ 2.3 — Conventional Commits を使い、1 コミットにつき1つの論理的な変更を行う

Conventional Commits を使用してください。形式は <type>(<scope>): <description> で、type には feat | fix | docs | refactor | test | chore | ci | perf を指定します。各コミットは、それ単独でレビューできるようにしてください。

レビューで修正を求められた場合は、git commit --fixup=<sha> を使用し、プッシュする前に git -c sequence.editor=: rebase -i --autosquash origin/main でスカッシュしてください。修正コミットのワークフロー全体については、references/phase2_implementation.md を参照してください。

フェーズ 3 — 品質ゲート

メンテナーの信頼は、主張ではなく証拠によって築かれます。このフェーズの目的は、PR に貼り付けられる証拠を用意することです。

ステップ 3.1 — プロジェクトで必須のチェックを確認する

CONTRIBUTING.md と現在の CI ワークフローを読み、必須のコマンドとプラットフォームのマトリックスを確認してください。入力条件が引き続き適用できる場合は、同一の内容に対して成功したチェックを再利用してください。それ以外の場合は、不足しているチェックや影響を受けるチェックを実行してください。一般的な例（プロジェクトで指定されているものを使用してください）：

pnpm typecheck && pnpm format:check && pnpm test:unit
cargo fmt --check && cargo clippy --all-targets && cargo test

失敗した場合は、PR が原因だと判断する前に、隔離したワークツリー内で変更されていない現在のベースに対して同じコマンドを実行し、結果を比較してください。失敗した結果を保持し、リグレッションと既存の不具合または環境上の阻害要因を区別してください。テストを成功させるために、別のセッションのサービスを停止してはいけません。マージ可能と主張する前に、リポジトリで必須のチェックをすべて完了してください。

ステップ 3.2 — GUI／デスクトップアプリの場合：隔離して実際のエンドツーエンドテストを実行する

Tauri／Electron／Cocoa アプリでは、実際のインストール環境を汚染せずに pnpm dev を直接使うことは、ほぼできません。まずデータディレクトリを隔離し、その後で実際のバイナリを実行するのが基本です。

1. プロジェクトのテスト隔離用フックを見つけます（多くの場合、XXX_TEST_HOME、XXX_DATA_DIR、または config.rs／paths.go の設定フラグです）。
2. 起動前に、フックの参照先を /tmp/<app-name>-e2e/ に設定します。
3. URL スキーム、CLI 引数、ディープリンクなど、ユーザーが実際に使う方法で機能を呼び出します。
4. 目視確認だけでなく、実際に永続化された状態（SQLite、JSON ファイル）を読み取って検証します。
5. PR の説明用に GUI のスクリーンショットを撮影します。

Tauri のシングルインスタンス転送を介して macOS LaunchServices に触れずにディープリンクを呼び出す方法を含む、隔離手順の全容については、references/phase3_quality_gates_and_e2e.md を参照してください。

ステップ 3.3 — セルフ監査：これから主張しようとしていることを、本当に実行しましたか？

下流の動作に影響する変更では、ローカルテストの合格を受け入れる前と、レビューに基づく修正の後に、 動作影響レビュー を使って保持テストを選んでください。このマーケットプレイス以外で貢献する場合は、インストール済みの github-review-pr Skill を通じてその参照先を確認してください。利用できない場合は、 元の結果／保持契約に対する実際のコンシューマーチェックを必須とし、 参照先がないことを報告してください。これは独立したレビューを呼び出すものではなく、 メンテナー権限を付与するものでもありません。

PR の説明を書く前に、記載する予定の「テストしました…」「確認しました…」「実行しました…」という文をすべて列挙してください。それぞれについて、「根拠は何か？」と問いかけます。答えが「実行したと思う」または「動くはずだ」であれば、実際には実行していません。裏付けられることだけを書いてください。

このルールは、最も深刻な信頼の失墜を防ぎます。すなわち、メンテナーがあなたの「テスト済み」コマンドを実行したときに、動かないと判明する事態です。

ユーザーが自身の貢献について独立したメンテナー視点の評価を明示的に求めた場合は、読み取り専用のレビュー手法として github-review-pr:github-review-pr を呼び出してください。新しいコンテキストでレビューするレビュアーには、元の課題／レビューのやり取りと、変更されていない head／base オブジェクトを渡します。依頼者は作者の立場を保ってください。これは推奨を提示するものであり、正式な承認やマージの許可を与えるものではありません。既存の権限の範囲内で、このコントリビューター向けワークフローのみを使って修正を続けてください。通常のセルフ監査では、このレビューを呼び出しません。

ステップ 3.4 — プッシュ時の検証

ローカルテストに合格しても、まだ完了ではありません。PR をマージ可能と判断する前に、プッシュ時のチェックリストを実行してください。

1. 公開範囲の確認 — 対象リポジトリが、想定どおり実際に公開または非公開になっていることを確認します。

   gh repo view <owner>/<repo> --json visibility,isPrivate,defaultBranchRef
   

2. セキュリティフック — pre-push が失敗した場合は、ルールまたはコンテンツを修正してください。--no-verify は使用しないでください。
3. プッシュの成功 — 503 または認証エラーで失敗する場合は、git config --global --get-regexp url を確認し、古い URL の書き換えがないか調べてください。
4. マージ可能性の確認 — git push が成功しても、GitHub でマージできるとは限りません。

   gh pr view <pr-number> --repo <owner>/<repo> --json mergeable,mergeStateStatus
   

詳細（URL の書き換え、PII フックの誤検知、--force-with-lease に関する注意点）は、references/push_time_gotchas.md を参照してください。

フェーズ 4 — PR の説明文の作成

優れた PR の説明文には、3 つの役割があります。（1）メンテナーが 30 秒でマージを判断できるようにする、（2）レビュー担当者があなたに DM を送らなくても検証に必要な情報をすべて得られるようにする、（3）チームの人員が入れ替わっても残る記録を作成する、という役割です。

ステップ 4.1 — 構成

以下のひな形を使用してください。詳細なテンプレートとテストカバレッジマトリックスの例は、references/phase4_pr_description.md および references/communication_templates.md にあります。

## Summary / 概述
<two sentences — what changed and why it matters>

## What / 变更内容
<bulleted list of commits with their purpose, or files with their purpose>

## Why / 动机
<the problem this solves; if no prior issue, briefly justify why>

## Test Plan / 测试计划
<exact commands a maintainer can run; coverage matrix for non-trivial changes>

## Backward Compatibility / 向后兼容
<state explicitly; don't make the maintainer infer>

## Security Considerations
<only if the change touches auth, inputs, or shared state>

## Screenshots / 截图
<for UI changes — see Step 4.3>

## Related Issue
<Fixes #N, or explain why no issue exists>

## Checklist
<the project's PR template checklist, with real evidence of each>

## AI-Assisted Disclosure
<see Step 4.4>

ステップ 4.2 — テストカバレッジマトリックス（重要な変更の場合）

テストを 2 件以上追加した場合は、各テストがどの動作を保証するか対応付けた表にまとめてください。テストコードを読むよりも、レビューを大幅に効率化できます。

| Layer | Test | What it proves |
|---|---|---|
| URL parsing | `test_parse_provider_with_extra_env` | extraEnv query param extracted |
| Security | `test_extra_env_stringifies_scalars_and_skips_invalid_values` | bool/number stringified; null/array/object dropped |

ステップ 4.3 — リポジトリを汚さずにスクリーンショットを追加する

gh CLI は、PR への画像添付に対応していません（基盤となる uploads.github.com のアップロード API はブラウザー専用で、PAT トークンを拒否します）。実用的な方法は 3 つあります。

1. 推奨 — GitHub のウェブ UI でユーザーに画像をドラッグしてもらう。 PR 本文の下書きに、明確なプレースホルダー（例：[SCREENSHOT_1_PLACEHOLDER]）を残します。ユーザーが github.com で PR を編集すると、画像を Markdown にドラッグでき、GitHub が user-images.githubusercontent.com にアップロードしてプレースホルダーを置き換えます。リポジトリはまったく汚れません。
2. 代替策 — フォークに孤立ブランチを作成する。 孤立ブランチ（例：assets-pr-N-screenshots という名前）を作成して画像をコミットし、raw.githubusercontent.com 経由で参照します。フォークは汚れますが、PR の差分には影響しません。
3. 最終手段 — サードパーティの画像ホストを使用する。 保存期間とプライバシーが不明確なため、機密情報を含むものには使用しないでください。

ステップ 4.4 — AI 利用の開示（CONTRIBUTING.md またはメンテナーの慣例で求められる場合）

プロジェクトの CONTRIBUTING.md に AI を利用した PR についての記載がある場合、またはメンテナーが過去の PR で AI の出力に懐疑的なコメントをしている場合は、PR 本文の末尾に短い開示を追加してください。曖昧な安心材料ではなく、何をしたのか具体的に説明してください。

## AI-Assisted Disclosure

Per CONTRIBUTING.md §N:

1. I have read every line; happy to walk through any function or design choice.
2. Tested locally: <list actual commands you ran with their results>.
3. Single-topic PR scoped to <one sentence>.
4. <opened/will open> Issue #N for discussion.
5. AI tools used: Claude Code for drafting; <list any others>. Final review and decisions are mine.

開示すれば何でも解決するわけではなく、質の低い PR が許されるわけではありません。しかし、開示を求めるプロジェクトでそれを怠ると、たちまち信頼を損ないます。

フェーズ 5 — 提出後

ステップ 5.1 — 自動ボットレビューには明示的に返信する

最近のプロジェクトでは、初回レビューに Codex、Claude bot、CodeRabbit などが使われています。コメントは PR 全体へのコメントではなく、特定の行に対するレビューコメントとして表示されます。各指摘に直接返信し（メンテナーが指摘のすぐそばで解決内容を確認できるようにします）、解決に対応するコミットハッシュと関数またはテストを記載してください。

gh api repos/<owner>/<repo>/pulls/<pr>/comments \
  -X POST \
  -F in_reply_to=<finding_comment_id> \
  -f body="Addressed in commit \`<sha>\`: <function or test name>. <one-sentence explanation>. Thanks for the catch!"

<finding_comment_id> は、コメントの URL（#discussion_rXXXXXXXX）に含まれる数値 ID です。ボットへの返信ワークフローの詳細は、references/phase5_post_submission.md を参照してください。

ステップ 5.2 — レビュー履歴を失わずに upstream の main にリベースする

upstream の main が進み、PR で競合が発生した場合：

git fetch origin
git rebase origin/main
# resolve conflicts file by file
git add <files>
git -c sequence.editor=: rebase --continue
git push fork <branch> --force-with-lease

--force は使わず、--force-with-lease を使ってください。lease 付きの方法では、別のユーザー（またはボット）がその間にブランチへプッシュしていた場合、処理が中断されます。これにより、レビューのスレッドを気づかないうちに消してしまうことを防げます。

レビュー後に小規模なクリーンアップ（--fixup コミット）を適用した場合は、autosquash を使って関連するコミットにまとめ、マージ後の履歴をクリーンに保ってください。手順の全体については、references/phase2_implementation.md を参照してください。

ステップ 5.3 — サブエージェントや相互レビューで「指摘」が出たら、返信前に取捨選択する

相互レビューエージェントを実行した場合（またはメンテナーのボットが20件以上の指摘を大量に提示した場合）、すべてをPRに貼り付けないでください。各指摘について、次の3つの質問をしてください。

フィルター	却下する条件
発生可能性	「このコードベースで実際に起こり得るか？」→ いいえ
コスト	「修正コストはリスクを上回るか？」→ はい
シナリオ	「このシナリオはすでに upstream で防止されているか？」→ はい

相互レビューの目的は、思いもよらなかった点を見つけることであり、理論上の懸念をすべて修正するよう義務づけることではありません。厳しく取捨選択し、それぞれの提案を採用した理由、または採用しなかった理由をPRで説明してください。

参照ファイル

ファイル	用途
references/phase1_discovery.md	CONTRIBUTING.md の解析、PR サイズの基準、スコープ契約のテンプレート
references/phase2_implementation.md	Fixup コミットと autosquash のワークフロー、スコープ規律に反するアンチパターン
references/phase3_quality_gates_and_e2e.md	分離されたホームディレクトリのパターン、単一インスタンスのフォワード、SQLite の検証、スクリーンキャプチャとウィンドウフォーカス
references/phase4_pr_description.md	本文の骨組み、テストカバレッジマトリクス、AI 開示テンプレート、スクリーンショットのプレースホルダーパターン
references/phase5_post_submission.md	gh api in_reply_to の手順、--force-with-lease の動作、相互レビューの取捨選択
references/push_time_gotchas.md	Git リモート URL の書き換え、PII フックの誤検知、マージ可能性の検証、強制プッシュに関する注意点
references/case_study_cc-switch_pr_2634.md	開発ログ、SQLite ダンプ、スクリーンショットを含む実例の全手順
references/case_study_cc-switch_pr_1624.md	フロントエンド／状態管理のリベース事例 — 非同期初期化ガード、テストの結合、i18n の競合
references/pr_checklist.md	統合された元のチェックリスト（レガシー版。ワークフローの各セクションはフェーズごとのドキュメントに置き換えられています）
references/project_evaluation.md	発見ステップで使用するプロジェクト健全性の評価基準
references/communication_templates.md	Issue の担当表明、レビューへの返信、マージ後のテンプレート
references/high_quality_pr_case_study.md	OpenClaw PR #39763 の手順 — 小規模な修正の事例

避けるべきアンチパターン

これらは、コード自体に問題がなくても PR が却下される原因となる失敗パターンです。いずれも実際の PR で起きたことです。

1. テストしたという虚偽の主張。 実際にはユニットテストしか実行していないのに、「pnpm dev でローカルテスト済み」と書くことです。メンテナーが試して、信頼を永久に失うことになります。
2. プロジェクトの最近のマージ規模の5～10倍に及ぶ PR。 この規模のコードは、内容が優れていても、多くのメンテナーには「AI による大量出力」と受け取られます。
3. リベース時のスコープ拡大。 「コンフリクトを解決しているときに」無関係な上流機能をブランチに持ち込むと、修正 PR が何の断りもなく機能追加 PR に変わります。
4. 修正コミットへのリファクタリングの混在。 どの行がバグ修正につながったのか、レビュアーには判断できません。分割するか、リファクタリングに対する --fixup コミットを使ってください。
5. レビュー中に --lease を付けずに強制プッシュすること。 レビュースレッドが通知なく失われます。
6. ボットのレビューコメントを無視すること。 ボットの指摘が間違っている場合でも、その理由を返信してください。沈黙は「気づかなかった」と受け取られます。
7. 開示を目立たない場所に埋めること。 AI の支援を受けたことは PR の本文に記載し、誰も読まないコミットメッセージの脚注にはしないでください。
8. PR を作成してから CONTRIBUTING.md を読むこと。 CONTRIBUTING.md のルールの半分は、コードの内容ではなく PR の構成に関するものです。
9. プロジェクトで必須とされている Issue を作成せずに機能を提出すること。 同じ時間内に遡って Issue を作成したとしても、メンテナーにとってはタイムスタンプが重要です。
10. カウンターレビューの出力をそのまま貼り付けること。 PR の本文に指摘を20件並べると、ノイズにしか見えません。取捨選択してから対応してください。

クイックリファレンス

必須の gh CLI コマンド

gh repo view <owner>/<repo> --json visibility,isPrivate,defaultBranchRef
gh pr list --repo <owner>/<repo> --state merged --limit 10
gh pr view <pr-number> --repo <owner>/<repo> --json title,body,commits,mergeable,reviewDecision
gh pr edit <pr-number> --repo <owner>/<repo> --body-file pr_body.md
gh api repos/<owner>/<repo>/pulls/<pr>/comments -X POST -F in_reply_to=<id> -f body="..."

Conventional Commits の早見表

feat(<scope>): user-visible new behavior
fix(<scope>):  user-visible bug fix
refactor(<scope>): no behavior change
docs(<scope>): documentation only
test(<scope>): tests only
chore(<scope>): tooling / build / housekeeping
perf(<scope>): measurable performance change
ci(<scope>): CI config only

高品質な PR を示す主要指標

活発なプロジェクトへの貢献が成功した例に基づいています。

• 変更ファイル数：修正の場合は1～5件、テストを含む機能追加の場合は最大約15件
• 本番コードの差分：可能であれば200行未満。残りはテストやドキュメントにします
• PR の説明：根拠を含めて200～600行。マトリックス形式の表も歓迎です
• ボット／メンテナーからの最初の返信までの時間：24時間未満
• 初回プッシュでの CI 通過：目標

これらのうち2つ以上が大幅に基準を外れている場合は、提出前にフェーズ1を読み直してください。