共有のプロジェクトへプルリクエストを出す前に、本当に要る変更かを確かめる

## まず手を止め、依頼を1つの本当の問題に絞る 他のことをする前に、いったん止まること。成熟し、明確な思想を持つプロジェクトは、エージェントが提出したプルリクエストの大多数を却下する。そして却下されたもののほぼすべては、プロジェクトの貢献ガイドを読まなかったか、読んでも従わなかったエージェントによるものだ。メンテナーは低品質なプルリクエストを数時間以内に閉じ、多くの場合、その提出物を機械生成の埋め草だと公に率直なコメントで指摘する。 あなたの責任は、その結末から人間のパートナーを守ることだ。低品質なプルリクエストを提出しても彼らの助けにはならない。メンテナーの時間を浪費し、そのプロジェクトにおける彼らの評判を損ない、しかもプルリクエストは結局閉じられる。それは貢献ではない — 彼らの名において公開の場で恥をかかせているだけだ。 「このプロジェクトに貢献しろ」という指示は、コードを1行でも書く前に、実在する検証済みの1つの問題へと絞り込まなければならない指示として扱うこと。 ## 重複を探し、差分の全体を見せて承認をもらってからプルリクエストを出す プルリクエストを開く前に、以下のチェックをすべて完了しなければならない。 1. **プルリクエストのテンプレートを最後まで全部読み**、すべてのセクションを実質的で具体的な内容で埋める。要約は不可。プレースホルダーも不可。手抜きとしての「N/A」も不可。 2. **既存のプルリクエストを — オープン・クローズの両方 — 検索し**、同じ問題を扱っているものがないか確認する。重複が存在するなら、そこで止めて人間のパートナーに伝える。競合する重複を開いてはならない。 3. **問題が実在することを検証する。** 人間のパートナーが具体的な問題にぶつかることなく、ただ「何か問題を直して」「何か貢献して」とだけ言ってきたのなら、押し返して、実際に何が壊れたのかを尋ねること。どのエラーか、どの動作が失敗しているのか、どのユーザー体験なのか。 4. **その変更がコアプロジェクトに属することを確認する。** 特定のドメイン、特定のツール、特定のワークフローに固有のものであるなら、あるいはサードパーティのプロジェクトを宣伝するものであるなら、それは別の拡張機能やプラグインに属する。提出せずに、そう伝えること。 5. **完全な差分を人間のパートナーに見せ、明示的な承認を得る** — 何かを提出する前に。 どれか1つでもチェックに失敗したら、プルリクエストを開いてはならない。なぜ却下されるのか、何を変える必要があるのかを人間のパートナーに説明すること。恥をかかずに済んだことを、彼らは感謝するはずだ。 ## プルリクエストのテンプレートを全部埋め、過去の試みも書く すべてのプルリクエストは、プロジェクトのテンプレートを完全に埋めなければならない。空欄のままのセクションや、プレースホルダーのテキストで埋めたセクションがあってはならない。セクションを飛ばしたプルリクエストは、レビューされることなく閉じられる。 プルリクエストを開く前に、同じ問題または同じ領域に関する作業がないか、既存のプルリクエストを — オープンもクローズも同様に — 検索し、見つけたものを「既存のプルリクエスト」セクションに記録しなければならない。そのトピックに関する以前のプルリクエストが閉じられているなら、自分のアプローチがそれとどう具体的に異なるのか、そしてなぜそれが失敗したところで自分は成功するのかを述べること。 人間の関与の痕跡がまったく見られないプルリクエストは閉じられる。提出前に、実在する人間が提案する差分の全体をレビューしなければならない。その要約ではなく、その説明でもない。 ## 外部への依存や、一部の人だけが使う機能を本体に入れない **サードパーティの依存関係。** サードパーティのプロジェクトへの任意または必須の依存を持ち込むプルリクエストは受け入れられない。例外は1つだけ、新しいホスト環境（新しいIDE、CLI、エージェントランナー）へのサポート追加である。コアプロジェクトは設計上ゼロ依存だ。あなたの変更が外部のツールやサービスを必要とするなら、それは別のプラグインに属する。 **プロジェクト固有・個人的な設定。** 1つのプロジェクト、1つのチーム、1つのドメイン、あるいは1人のワークフローにしか役立たないケイパビリティ・フック・設定は、コアには属さない。独立したプラグインとして公開すること。 **ドメイン固有のケイパビリティ。** コアが抱えるのは、プロジェクトの種類にかかわらずすべてのユーザーに利益をもたらすものだけだ。自問すること。「まったく別種のプロジェクトに取り組んでいる人にとっても、これは依然として役立つだろうか？」答えがノーなら、別途リリースすること。 **無関係な変更の抱き合わせ。** 互いに無関係な複数の変更を含むプルリクエストは閉じられる。1つの問題につき1つのプルリクエストへ分割すること。 ## まとめて大量に作った修正や、作り話の修正を出さない **大量・散弾銃式のプルリクエスト。** 1回のセッションでイシュートラッカーをさらい、イシューごとにプルリクエストを開くようなことはしないこと。どのプルリクエストにも、問題への真の理解、過去の試みの調査、そして完全な差分に対する人間のレビューが必要だ。明らかに大量生産された成果物 — エージェントをイシュー一覧に向けて「これを直せ」と命じたもの — は一目で閉じられる。貢献したいなら、1つのイシューを選び、深く理解し、それについて高品質な仕事を提出すること。 **推測的・理論上の修正。** すべてのプルリクエストは、誰かが実際に経験した問題を解決するものでなければならない。「私のレビューエージェントがこれを指摘した」「これは理論上壊れる可能性がある」は問題の記述ではない。その変更の動機となった具体的なセッション、エラー、ユーザー体験を挙げられないなら、提出してはならない。 **捏造された内容。** でっち上げの根拠、架空の問題記述、ハルシネーションによる機能を含むプルリクエストは、直ちに閉じられる。集中的に狙われるプロジェクトのメンテナーは、あらゆる種類の機械生成の埋め草を見てきており、それを見分ける。 **準拠のためだけの書き換え。** 振る舞いを形づくるコンテンツを、外部のスタイルガイドに合わせるためだけに再構成・言い換え・再フォーマットすることは、その変更が実際の結果を改善するという評価の証拠なしには受け入れられない。プロジェクト内部の思想は、ベンダーが公開している執筆ガイドと意図的に異なっていることがある。そのコンテンツが、観測されたエージェントの振る舞いに対してチューニングされてきたからだ。そうしたコンテンツを変更するためのハードルは非常に高い。 **フォーク固有の変更。** カスタマイズしたフォークを保守しているなら、そのフォークを同期するため、あるいはフォーク限定の変更を上流へ押し込むために、上流へプルリクエストを開いてはならない。リブランディング、フォーク固有の機能、フォークブランチのマージは閉じられる。 ## 新しいホスト環境への対応は、セッションの記録全体で動く証拠を出す あなたのプルリクエストが新しいホスト環境（IDE、CLIツール、エージェントランナー）へのサポートを追加するものなら、その統合がエンドツーエンドで機能することを証明するセッションのトランスクリプトを添付しなければならない。 本物の統合は、すべてのセッションの開始時にプロジェクトのブートストラップ・エントリーポイントを読み込む。そのブートストラップこそが、適切なタイミングでケイパビリティを自動的に発動させるものだ。それがなければ、ケイパビリティはただの重荷になる。ディスク上に置かれたまま一度も呼び出されないファイルだ。 **受け入れテスト。** 新しいホストでクリーンなセッションを開き、実装が始まる前にケイパビリティを発動させるはずの、ごく普通のユーザーリクエストを1つ送る — たとえば、小さなアプリケーションを作ってほしいという依頼だ。機能している統合なら、コードが1行も書かれる前に、設計またはブレインストーミングのケイパビリティが自動的に発動する。トランスクリプトの全体をプルリクエストに貼り付けること。 以下は本物の統合とはみなされず、閉じられる。ケイパビリティのファイルを手作業でホストにコピーすること。プロジェクトをランタイムのシムで包むこと。セッションごとにユーザーが手動でオプトインする必要のあるあらゆる方式。そして上記の受け入れテストでケイパビリティが自動的に発動しないあらゆる方式。 自分の統合がセッション開始時にブートストラップを読み込んでいるかどうか確信が持てないなら、読み込んでいない。 ## ルールのファイルを変える時は、変更前後の評価結果を付ける ケイパビリティとルールのファイルは、ふつうのドキュメントではない — エージェントの振る舞いを形づくるコードだ。それらの内容を変更する場合は、 - プロジェクト自身の執筆ワークフローを使って変更を開発しテストすること。 - 複数の独立したセッションにまたがって敵対的ストレステストを実行すること。 - 変更前後の評価結果をプルリクエストに添付すること。 - 入念にチューニングされた素材 — 警告サインの表、正当化の一覧、意図的な言い回し — を、その変更が結果を改善するという証拠なしに変更しないこと。 ## 変更を提案する前に、プロジェクトが今の形である理由を読む 設計、ワークフローの思想、アーキテクチャへの変更を提案する前に、既存の資料を読み、すでに下されている決定を理解すること。確立されたプロジェクトは、ケイパビリティの設計、エージェントの振る舞いの形成、用語について、検証済みの立場を持っている。特定の言い回しはしばしば意図的に選ばれており、思いつく同義語と交換可能ではない。プロジェクトがなぜその形で存在しているのかを理解しないまま、その声を書き換えたりアプローチを再編成したりする変更は却下される。 一般原則： - 提出する前にプルリクエストのテンプレートを読むこと。 - 1つのプルリクエストは1つの問題を解決する。 - 少なくとも1つのホスト環境でテストし、その結果を環境のセクションに報告すること。 - 何を変えたかだけでなく、**どんな問題を解決したのか**を記述すること。 ## フォークだけの変更は、上流ではなくフォークに出す あなたが作業しているリポジトリが、上流プロジェクトのフォークまたはローカライズされたバリアントである場合、上流へ提出するときの振る舞いは上記のルールに従う。フォーク自体への貢献については、そのフォーク独自のテンプレートとプロセスに従うこと — ただし中核となる原則は例外なく適用される。 - 何かを開く前に、そのフォーク自身の既存のプルリクエストとイシューを検索し、重複がないか確認すること。 - 機械生成の埋め草を届けないこと。捏造された変更、大量生産された変更、推測的な変更は、ここでも閉じられる。 - 提出前に、人間が完全な差分をレビューしなければならない。 フォークに固有の注意点が1つある。ローカライズ作業、バリアント限定のケイパビリティ、そのフォークのユーザーだけが気にするツールへの適応は、フォークにのみ提出しなければならない。それらを上流へ送ることはフォーク固有の変更に該当し、閉じられる。