Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

FND-005: 貢献文化: 人間同士の協働、AI とのパートナーシップ、そしてチームの成長

v0.7.0 以降 · 種類: Culture · 改訂: 2

正式なリファレンス · チーム承認済み · 改訂 2 元の RFC に関する議論: #5615

これを読む前にチームへの注意。

これは ZeroClaw の成熟度フレームワークにおける 5 番目のドキュメントです。他の 4 つは、アーキテクチャ、ドキュメント、ガバナンス、エンジニアリングインフラストラクチャという、プロジェクトを機能させる構造的なレイヤーを扱っています。本ドキュメントが扱うのは、それら 4 つが当然のものと前提しながらも明示的には教えてこなかったこと、つまり「どのように協働するか」です。

他の RFC に記載されているツールやプロセスは、それを利用するチームの質に依存します。完璧な CI パイプラインも、率直なフィードバックを提供できないチームには役立ちません。クリーンなアーキテクチャも、建設的な議論ができないチームでは維持できません。ガバナンスモデルも、所有権の意味を教わったことのない人々には所有権を育むことができません。

この文書は、そうしたチームを築くためのものです。単に技術的に有能な個人を集めるのではなく、フィードバックの与え方や受け取り方を知り、助けの求め方を心得え、強力なツールを責任を持って使いこなし、時間をかけて共に成長していける人々を育てることが目的です。これらは習得できるスキルです。最初から完璧に身につけている人はいません。この文書では、それらを十分に明確に名づけることで、ここで、本当に意味のある実際の仕事の文脈の中で、意図的に練習を始められるようにします。

この文書の内容は、あなたが誰であるか、あるいはどこから始めたかについての批判ではありません。それは、私たちが一緒に目指している場所への地図です。

成熟度フレームワークスイート

このRFCは、ZeroClawの成熟度フレームワークを構成する5つの文書のうち5番目です。これらは全体として読むことを意図していますが、それぞれが独立して成立します。

RFCスコープ問題
意図的なアーキテクチャ: マイクロカーネルへの移行私たちが構築しているものとその構造#5574
ドキュメントの標準化とナレッジアーキテクチャ私たちが構築するものの文書化方法#5576
チーム編成とプロジェクトガバナンス私たちの調整と意思決定の方法#5577
エンジニアリングインフラ：CI/CDパイプライン信頼性の高いビルド、テスト、およびリリースの方法#5579
コントリビューション文化: 人間同士のコラボレーションとAIパートナーシップ私たちの協力と成長FND-005

最初の4つのRFCは構造的な問いに答えます。このRFCは人間に関する問いに答えます：構造が与えられたとき、その中の人々は互い、および彼らのツールに対してどのように振る舞うべきか？この問いには、コンパイラ、リンター、CIゲートはありません。あるのは、私たちが築く習慣、私たちが示す例、そしてそれに込める意図性だけです。

目次

  1. このドキュメントが存在する理由
  2. 作業前の作業
  3. 人々との連携
  4. AIとの連携
  5. フィードバック分類
  6. レビュアーおよびメンターへの注意

改訂履歴

Rev日付目次
12026-04-11初期ドラフト
22026-05-09解決済みの指摘を含め、レビューウェイトの契約を保守されているPRレビュー・プロトコルに合わせました（#6473）

1. この文書が存在する理由

多くのコントリビューションガイドは、PR をどのように開くかを説明しています。どのようなラベルを使用するか、テストスイートをどのように実行するか、コミットメッセージに何を記載するかについても言及しています。これらは重要であり、それらをカバーする文書がすでに存在します。

このドキュメントは異なる内容を扱っています。それは、才能ある人々のグループが機能するチームになるのか、単に同じリポジトリを共有している個々の人々の集まりになるのかを決定するスキルについてです。

これらは習得可能なスキルです。あなたが持っているか持っていないかという性格的特性ではありません。技術力に自動的に付随してくるものでもありません。これらは、他のどんなスキルとも同じように、時間をかけてゆっくりと、フィードバックを受けながら練習して身につけるものです。ソフトウェアエンジニアリング教育のほとんどは技術的な層にほぼ完全に焦点を当てており、人間的な層は運任せにしています。その結果、技術的に有能な多くの人々が、何が欠けているのか、どう修正すればいいのかを明確に理解しないまま、うまく協働できないチームに行き着いてしまうのです。

この文書の目的は、これらのスキルを明確に命名し、あなたが実際に重要な仕事を行う文脈で、意図的に練習を始めることができるようにすることです。

2. 作業前の作業

コードを1行書く前に、PRを作成する前に、またはAIに何かを生成させる前に、あなたは以下の質問に答えられるはずです。このプロジェクトでは、それらを説明するために意思決定の階層構造を使用しています：

Vision
  └── Architecture
        └── Design
              └── Implementation
                    └── Testing
                          └── Documentation
                                └── Release

階層構造はアーキテクチャ RFC (#5574) で完全に説明されています。ここで重要なのは、その背後にある原則です：あなたが下すすべての決定は、トップまで遡って追跡可能でなければなりません。

実際には、これは構築を始める前に自分自身に問いかけることを意味します：

  • 私はどんな問題を解決しているのか？ 「どのチケットをクローズしているか」ではなく、これが誰かにとってどんな実際の問題を解決するのか、ということです。
  • これはアーキテクチャに適合しますか？ システム構造の中でこれがどこに属するかを説明できない場合、そのシステムを十分に理解しておらず、変更する準備ができていません。
  • 完了の基準はどのようなものですか？ コードを書く前に、受入基準を明確にしてください。「動作する」は受入基準ではありません。「ユーザーが Rust ツールチェーンなしでプラグインをインストールし、正しく動作させることができる」ことが受入基準です。
  • これを知っておくべきなのは誰か？ 他の人の作業に影響を与える変更や、チーム全体で決定すべき判断を伴う変更は、実装後ではなく実装前に可視化する必要があります。

これは官僚主義ではありません。何かを構築することと、正しいものを構築することの違いです。これは、AI ツールとの連携方法にも直接適用され、これについては第4章で詳しく説明します。

このステップを省略したときに実際に起こることを正直に言えば、こうです。動くものを作り、PRを開き、そしてレビューの中で、間違った問題を解決していること、あるいは正しい問題を別の場所で既に下された決定と矛盾する方法で解決していることを知らされるのです。これはあなたの時間とレビュアーの時間を無駄にし、その作業に依存している人たちを遅らせることになります。事前作業は余分なものではありません。それは自分自身の努力を守るための手段なのです。

3. 人との連携

フィードバックを提供する

フィードバックは、他のエンジニアに対して最も効果的な支援の一つです。適切に書かれたレビューコメントは、一人で学ぶのに数年かかるようなことを教えることができます。一方、不適切なフィードバックは、その人が再び貢献することをためらわせる可能性があります。

具体的に。 曖昧なフィードバックは、方向性のない不安を生み出します。

❌ 「これは読みづらいです。」

✅ 「この関数は3つの別々の関心事を扱っています。入力のバリデーション、ビジネスロジック、そしてレスポンスのフォーマットです。それぞれの関数が1つのことだけを行うように分割することを検討してください。そうすることで、各部分のテストがしやすくなり、それぞれが何をしているのか一目で理解しやすくなります。」

2 番目のバージョンは長くなっていますが、何かを教えます。読者は今、問題が何であるか、それがなぜ重要なのか、そしてそれに対してどうすべきかを知っています。

判決だけでなく、その原理も説明してください。 誰かに何かを変更するよう求める場合、その理由も伝えてください。「X を Y に変更する」という指示は修正を生みますが、「Z の理由で X を Y に変更する」という指示は、同じ原理が適用される次の10の状況にも応用できる理解を生み出します。

作業と個人を分離する。 「このアプローチには問題がある」と「あなたがミスをした」は同じ意味ではありません。前者はコードに関するもので、後者は個人に関するものです。フィードバックは作業に焦点を当ててください。

良い点を明示する。 これは優しくするためではなく、有用であるためのものです。何が正しかったかを伝え、なぜそれが正しいのかを説明すると、繰り返すべきパターンを相手に教えることになります。ありきたりな称賛（「素晴らしい仕事！」）は何も教えません。具体的な称賛（「これを独自のクレートに切り出したのは正しい判断でした。なぜなら、エージェントループ全体を立ち上げることなく、このロジックを単独でテストできるようになるからです」）は、原則を教え、その判断を補強します。

フィードバック分類を活用する。 セクション5の分類は、すべてのコメントに明確な重み付けを与えます。ブロッキングの問題と些細な提案を区別せずに混在させるレビュアーは、どれを実際に変更する必要があるのかを作者に推測させることになります。人に推測させてはいけません。

フィードバックの受信

これは、多くの人がフィードバックを与えるよりも難しく、その理由を正直に説明する価値があります。

何かに何時間も費やし、問題に取り組み、決断を下し、コードを書いてきたとき、誰かにそれには問題があると言われると、自然な人間の反応として、その批判が自分自身に向けられているように感じてしまいます。しかし、そうではありません。批判は仕事に向けられているのです。この2つを切り離して捉えられるようになることは1つのスキルであり、練習を必要とします。

いくつか役立つことがあります：

返信する前にフィードバックをよく読みましょう。 要約行だけでなく、説明を含むコメント全体を読みます。多くのフィードバックへの返信は、その人が理由を理解する前に、判定への反応として書かれています。「何を」についてどう感じるかを決める前に、「なぜ」を読みましょう。

「同意しない」と「理解していない」を区別する。 これらは異なる対応が必要です。フィードバックを理解できない場合は、明確化のための質問をしてください。理解した上で同意できない場合は、根拠を示してその旨を伝えてください。どちらも良い結果です。質問があるのに黙り続けることや、実際に同意できないのに「わかりました」と言うことは有用ではありません。

すべてのフィードバックに同意しなくても、そこから学ぶことはできます。 フィードバックが間違っていることもあります。あなたが最適化しようとしていたものとは異なるトレードオフを反映していることもあります。反論することは許されています。後述の「建設的に反対する」を参照してください。しかし、最終的に却下するフィードバックであっても、却下を決める前に十分に理解しておく価値があります。

ループを閉じる。 誰かが時間を割いてあなたの作業をレビューしてくれたら、フィードバックに対応したことを伝えましょう。大げさに感謝する必要はありません。「最新のコミットで対応しました」というシンプルな一言で十分です。それによって相手の時間が無駄でなかったことが伝わり、PR がスムーズに進みます。

コードに対するフィードバックは、あなたの価値に対するフィードバックではありません。 これは当然のことのように思えます。しかし、実際にその状況に直面すると、そう簡単には思えません。経験豊富なエンジニアでも、より経験のある人からコードレビューを受けることはあり、そのプロセスは毎回不快なものです。その不快感は、学習の感覚です。この感覚が消えることはありません。ただ、それに耐える力が身につくだけです。

ヘルプを求めています

学校では、助けを求めることは自分が遅れていることや、居場所がないことを認めることのように感じられることがあります。しかし、チームでは、助けを求めることはあなたが最もプロフェッショナルに行えることの1つです。

立ち止まって質問しないことのコストは、質問することのコストよりも常に高いです。5分間の会話で解決できる問題に3時間向き合うことは、あなたとチームの貴重な3時間を無駄にするということです。いつ質問すべきかを知ることは、弱さではなくスキルです。

良いヘルプリクエストには3つの部分があります：

  1. 何をしようとしているのか。 単に「壊れている」ではなく、目標は何か。
  2. これまでに試したこと。 これにより、あなたが問題に取り組んでいることが示され、あなたを助ける人がゼロからではなく、そこから始めることができます。
  3. あなたが具体的にどこでつまずいているか。 「何が悪いのかわからない」というのは、「何が悪いのかはわかっているが、どう修正すればいいのかわからない」という問題とは異なりますし、「修正はしたが、なぜその修正が機能するのか理解していない」という問題とも異なります。

この3つの要素を含むヘルプリクエストは、回答が早く、より多くのことを学べます。なぜなら、助けてくれる人があなたの状況を正確に把握できるからです。

可能な限り公開の場で質問しましょう。 共有チャンネルやPRで尋ねた質問は、後で同じ疑問を持つすべての人に役立ちます。プライベートで尋ねた質問は、あなた一人にしか役立ちません。プライベートが適切な場合、たとえば機密性の高いフィードバックや個人的な事情などもありますが、コードベースに関する技術的な質問は、ほとんどの場合、公開の場で尋ねた方が良いでしょう。

わからないことを恥じる必要はありません。 誰しもすべてを知っているわけではありません。すべてを知っているように見えるエンジニアも、長い時間をかけて多くの質問をし、その答えが蓄積されてきたのです。そこにたどり着く唯一の方法は、質問を始めることです。

建設的な意見の相違

アーキテクチャに関する意見の相違は健全なものです。これは、システムの構築方法に関心を持ち、下される決定に注意を払っている人々がいることを意味します。誰も異議を唱えないチームは、全員が同意しているチームではありません。それは、人々が関与することをやめてしまったチームなのです。

生産的な議論と生産的でない議論の違いは、通常、枠組み（フレーム）にあります。

結論ではなく、懸念事項を先に示す。

❌ 「このアプローチは誤りです。」

✅「このアプローチについて懸念があります。具体的には、ここでゲートウェイをランタイムに直接接続すると、RFC §4.2 の依存関係ルールに違反します。その結合なしで同じ結果を達成する方法があるか、検討できますか?」

2番目のバージョンは会話を開きます。1番目のバージョンは会話を閉じます。

根拠を示してください。 測定された事実、特定のRFCの節、または具体的な障害シナリオによって裏付けられたアーキテクチャに関する意見の相違は、貢献となります。「なんとなくそう思う」という意見に基づくアーキテクチャに関する意見の相違は、単なる意見です。どちらも表明する価値がありますが、会話を迅速に進めることができるのは前者のみです。

自分が間違っているかもしれないと、心から受け入れる姿勢を持ちましょう。 すでに自分が正しいと決めつけて意見の相違に臨むなら、それは会話ではありません。それは陳情です。人はその違いに気づきますし、そうなるとあなたの懸念に真剣に向き合おうという気持ちが薄れてしまいます。目指すべきはプロジェクトにとって最善の結果であって、自分が正しいことではありません。

チームが決定したら、チームとともに進む。 自分の反対意見は記録に残してよい。Issue、RFCのコメント、PRのスレッドに残しておき、その上で決定された内容を構築する。これは屈服ではない。これがチームの機能の仕方である。決着した決定を蒸し返し続けるチームは、出荷できない。

一部の決定は取り消し可能ですが、そうでないものもあります。 どちらの種類の決定について議論しているのかを理解しましょう。命名に関する決定は取り消し可能です。しかし、2年間生産環境のバイナリに含まれるワイヤープロトコルの決定は取り消し不可能です。エネルギーを適切に配分してください。

所有権

「所有権」は、明確な定義なしに頻繁に使用される言葉の一つです。このプロジェクトにおける実際の意味は以下の通りです：

所有権とは、指示される前に問題を把握することを意味します。 これは、自分の担当領域に関連するPRを読み、著者が気づいていない副作用に気づくことを意味します。また、担当者がいないフォローアップの課題を見つけ、それを引き受けることを意味します。指示を待つ必要はありません。

オーナーシップとは、自分の言葉に責任を持つということです。 自分の名前を付けてフォローアップの課題を起票したなら、その課題はあなたのコミットメントです。「誰かがこれをやるべきだ」ではなく、「あなたがこれをやる」のです。状況が変わって対応できなくなった場合は、早めにその旨を伝え、引き継ぎ先を見つけます。名前が付いたまま起票されて放置された課題で溢れたトラッカーは、信頼の記録が破綻している状態です。

オーナーシップとは「自分の担当分はやった」ということではありません。 それは「全体がきちんと機能するかどうかを気にかける」ということです。クレートをオーナーとして担当しながら、そのクレートが存在するシステムが健全かどうかに無関心でいることはできません。機能をオーナーとして担当しながら、ユーザーが実際にそれを使えるかどうかに無関心でいることはできません。「自分の分はやった、あとは誰か他の人の問題」という狭量なオーナーシップは、技術的にはあらゆる部分にオーナーがいながら、機能的には誰も何にも責任を負っていないシステムを生み出します。

所有権には後続の対応が含まれます。 コードをリリースすることは所有権の終わりではなく、それが正しく動作することを確認し、壊れたものを修正し、その領域で作業する次の人にあなたが学んだことを教えるという責任の始まりです。

struggling している人をサポートする

このプロジェクトの途中で、あるスレッドにおいて他の人よりもあなたがより経験豊富になることがあります。おそらく、あなたがここに長く在籍しているからかもしれません。あるいは、あなたが彼らが作業しているコードベースの部分をたまたま知っているのかもしれません。あるいは、あなたがこの特定の失敗モードを以前に見たことがあるのかもしれません。

そのポジションで何をするかが重要です。

単に修正するだけでなく、その理由も説明しましょう。 何が問題だったのか、なぜあなたの修正案が機能するのかを説明せずに、動作する解決策だけを提示すると、マージされたPRは残りますが、学習効果はゼロです。次に彼らが似たような問題に直面したとき、同じ状況に陥ることになります。何が問題で、なぜその修正案が機能するのかを説明するために、さらに5分ほど時間を割きましょう。

指導する意図を持ってレビューする。 出来の悪いPRは、単に閉じるべき問題ではありません。それは指導の機会です。突き放すようなレビュー（「これはアーキテクチャに沿っていません」）は、何が見落とされたかを指摘し、それが違反している原則を説明し、コントリビューターがさらに学べる場所を示すレビューよりも役に立ちません。その追加の労力は、それ以降より良いPRを書くようになるコントリビューターへの投資なのです。

誰かが行き詰まっているのに助けを求めていないなら、声をかけましょう。 苦労していると思われたくなくて尋ねない人もいます。誰に聞けばいいか分からない人もいます。あまりにも長く悩み続けて、自分がどれほど行き詰まっているかに気づかなくなっている人もいます。「これ、しばらく止まってるみたいだね。何か手伝えることある？」というさりげない一言は、ほとんどコストがかからない一方で、空回りしている人にとっては大きな意味を持つことがあります。

「わからないことを安全に認める環境を作る」 チームメンバーが「わからない」ことを理由に評価されると感じると、彼らは知っているふりをするようになります。それはより悪い意思決定につながります。「わかりません、調べてみます」と言える環境を作っているチームの方が、全員が自信を持っているふりをするチームよりも、より良い意思決定を行います。

4. AIとの連携

このセクションでは、多くのコントリビューションガイドで取り上げられていない、AI コーディングツールをより効果的に活用する方法について説明します。

委任のメンタルモデル

AIと効果的に作業するための最も有用な再定義は次の通りです：

AIとの協働は、人への委譲と同じスキルです。

同僚やジュニアエンジニアに業務を委譲する際には、文脈を提供します。目標、制約条件、成功の基準、そして境界を説明します。「機能を実装して」とだけ言うのではなく、「ユーザーが何を達成しようとしているのか」「これがシステム全体でどのように位置づくのか」「完了したとどうやって判断するのか」「何をすべきでないのか」を具体的に伝えます。

そして決定的に重要なのは、返ってきたものをレビューすることです。ジュニアエンジニアのPRを読まずにマージすることはないでしょう。それが要求どおりの動作をするか、アーキテクチャに適合するか、テストカバレッジがあるか、エラーハンドリングが正しいかを確認します。フィードバックを与えます。何度か繰り返すこともあるでしょう。

AI ツールも全く同じように動作します。返ってくる結果の品質は、入力する内容の品質によってほぼ完全に決まります。曖昧なプロンプトは曖昧な出力を生み出します。一方、明確なコンテキスト、具体的な制約条件、具体的な受入基準を含むプロンプトは、実際に有用な出発点となる出力を生み出します。

AIツールに苦戦するエンジニアは、たいてい人間であれAIであれ、あらゆる対象に明確な指示を与えることをまだ学んでいる段階にあります。AIツールを使いこなして成果を上げるエンジニアは、依頼する前に自分が何を求めているのかをすでに把握している人たちです。

このメンタルモデルは、出力はあなたの責任であることを意味します。PR を提出して「AI が書いた」と言うことはできません。あなたはそれをレビューし、PR を開いたのです。それはあなたの仕事です。

AIは実装層で動作します

これは理解すべき最も重要な技術的制限です。

AIによるコード生成は、意思決定階層の実装層で動作します：

Vision          ← AI cannot set this. You must.
Architecture    ← AI cannot make these decisions. You must.
Design          ← AI will sometimes guess. You must verify.
Implementation  ← AI can help here.
Testing         ← AI can help, but you define what to test.
Documentation   ← AI can draft. You must review for accuracy.
Release         ← Human judgment required.

AIツールは、あなたが説明した機能を実装する関数を生成します。しかし、その関数がこのクレートに属するのか、それとも別のクレートに属するのかについては教えてくれません。3か月前に決定されたアーキテクチャの決定と矛盾しているという点も指摘しません。セキュリティ上の影響を考慮したかどうかを問うこともありません。あなたが間違った問題を解決していることに気づくこともありません。

ZeroClaw自体が有用な一例です。初期のコードベースはAIの支援を受けて立ち上げられました。その結果は、アーキテクチャRFCが述べているように、「驚くほど機能的だが、アーキテクチャ的には偶発的」なものでした。コードは現在必要とされることをこなしていますが、それは設計されたものではなく、積み重なってできたものです。これはAIツールの失敗ではありません。実装に方向性を与えるビジョン、アーキテクチャ、設計の作業を先に行わずに実装層のツールを使った場合に予測される結果なのです。

解決策は、AIの使用を減らすことではありません。AIに何かを構築させる前に、常に階層の上位の作業を自分で行うことです。

増幅は魔法ではありません

AIツールは既存の能力を増幅します。それが彼らが行うことの正直な説明です。

明確なビジョン、定義されたアーキテクチャ、明文化できる品質基準、そして出力を批判的に評価する能力を備えているなら、AI は真の戦力増強要因となります。作業のスピードが上がります。より多くの選択肢を探求できます。より多くのテストを書けます。より多くのドキュメントを作成できます。

それらが揃っていない場合、AIはもっともらしく見えるが整合性のないコードを大量に生成します。何ら意味のあるテストをせずにパスするだけのテストを生成します。コードを説明するものの意図は説明しないドキュメントを生成します。局所的には一貫しているが全体的には支離滅裂なアーキテクチャを生成します。

増幅は中立です。良い入力と悪い入力を同様に増幅します。

これは、AI支援ワークフローにおいて最も重要なスキルがプロンプトエンジニアリングではないことを意味します。重要なのは、出力を評価する能力です。これには、何かを依頼する前に「良い状態」がどのようなものかを知っていることが必要です。それは、あなたが常に意思決定の階層の最上位に戻ってくることを意味します。

AIツールを使用して何かを実装する前に、役立つ自己チェックポイント：

  • 実装の詳細に触れずに、問題を一文で説明できるか？
  • この実装が対応するRFCのセクションや設計決定に名前を付けることはできますか？
  • 正しい実装がどのようなものか、それを見る前に説明できますか？
  • 生成された実装が正しいかどうかを確認した後、その理由を説明できますか？

これらのいずれかの答えが「いいえ」の場合、まだ実装する準備ができていません。まだ設計フェーズにあります。

レビューの規律

AIによって生成されたコードは、人間が書いたコードと同じレビューの厳格さが求められます。ある意味では、より多くの注意が必要です。なぜなら、確認すべき問題の範囲が広くなるからです。

AI生成の出力（自分のものでも他人のものでも）をレビューする際は、以下を確認してください。

アーキテクチャの適合性。 これは依存関係のルールを尊重していますか？適切なクレートに属していますか？設計で明示的に回避されている結合を導入していませんか？

境界での正確性。 AI モデルは一般的なケースでは非常に優れていますが、エッジケースでは頻繁に誤った結果を返します。入力が空、null、不正な形式、または最大予想サイズの場合に何が起こるかを確認してください。依存関係が利用できない場合の挙動も確認してください。

セキュリティ上の影響。 AIツールはデフォルトでセキュリティを考慮した設計にはなっていません。検証なしでユーザー入力を許可するコード、機密値をログに記録するコード、非推奨の暗号化プリミティブを使用するコード、パスのチェックなしでファイルを開くコードなどを生成する可能性があります。セキュリティの視点を明示的に持ち込む必要があります。

テスト品質。 AIが生成するテストは、振る舞いではなく実装をテストしていることが多々あります。関数が特定の内部構造体の値を返すことをアサートするテストは、振る舞いテストではありません。それは実装のスナップショットであり、実装が変わるたびに壊れてしまいます。次のことを問いかけてください。このテストは、システムがユーザーや呼び出し元が必要とすることを行っていることを検証しているのか、それともコードが現在行っていることを検証しているだけなのか、と。

完全性。 AIツールは、一見して完全に見えるように最適化されます。これらは、正常系を徹底的に処理し、エラーパスを表面的に処理するコードを生成します。エラーが呼び出し元に実際に有用な方法で伝播、処理、または表示されていることを確認してください。

これがあなたのキャリアに与える影響

ここで説明されているスキル、つまり明確に方向性を示すこと、出力を批判的に評価すること、コンポーネントが大きなシステムの中でどこに位置づけられるかを理解すること、構築する前に何が良いものなのかを把握しておくことは、AI特有のスキルではありません。これらは、優れたエンジニア、優れたテックリード、そして最終的には優れたエンジニアリングマネージャーを形作るスキルなのです。

AI生成のコードがあふれる世界で最も価値を持つエンジニアは、最も速く、最も多くのコードを書ける人々ではありません。彼らは、そのコードが正しいかどうかを判断できる人々です。それには、システム思考、アーキテクチャの判断力、そしてあなたが内面化した基準に対して作業を評価する能力が必要です。

ここで実践することすべて——実装前にRFCを理解すること、構築する前に「なぜ」を問うこと、ジュニアエンジニアのPRに向けるのと同じ目でAIの出力をレビューすること——は、そうした判断力を養う練習です。それは積み重なっていきます。アーキテクチャに真剣に向き合うPRの一つひとつが、次のアーキテクチャ上の意思決定をより容易にするデータポイントとなるのです。

このプロジェクトの貢献者には、特筆すべき利点があります。あなたは実際のシステム上で、現実的なアーキテクチャの制約のもと、あなたの作業をレビューし、その理由を説明してくれる人々と共に、これらの習慣を築いているのです。この組み合わせは稀です。真剣に取り組む価値があります。

5. フィードバックの分類

このプロジェクトのすべてのレビューコメントには、明示的な重み付けが付与されています。これらの重み付けを一貫して使用することで、レビュアーは明確に意思を伝え、作者は何に対応が必要かを正確に把握できます。

以下のカテゴリは、プロジェクトのレビュー意図を示しています。PR レビューでは、レビュープロトコルの絵文字見出しを通じてその意図を表現します: 🔴 ブロッキング、🟡 警告、🔵 提案、🟢 称賛、✅ 解決済み。正確な PR レビュー形式については docs/book/src/contributing/pr-review-protocol.md を参照してください。

✅ 表彰

著者が正しく捉えたこと。具体的に名前が付けられ、説明されており、そのパターンが繰り返される。

これは礼儀ではありません。一般的な称賛（「よくできました！」）は何も教えません。具体的な称賛と説明を行うことで、何が良かったのかの原則を教えることができ、それは同じカテゴリの将来のすべての意思決定に適用されます。

称賛にはアクションは不要です。その目的は強化することです。

例: 「ツール呼び出しパーサーを独立したクレートに切り出したのは正しい判断でした。このコードはエージェントの状態に一切依存しておらず、単独でテスト可能になっています。追加された91個のテストは、このロジックが loop_.rs 内にあった頃には到底実現できなかった類のカバレッジです。」

🔴 ブロッキング

PRがマージされる前に解決しなければならないもの。ブロックされる項目は2つのカテゴリに分かれます：

  • アーキテクチャの違反: デザインで明示的に禁止されている依存関係の境界をまたぐコード、または RFC や ADR に記録された決定に反するコード。
  • 品質の低下: 新しい動作に対するテストカバレッジの欠如、セキュリティ上の問題、契約互換性の破綻、または欠陥を引き起こすコード。

ブロッキングコメントでは、問題が何であるか、なぜそれが重要なのか、そして可能であれば解決への道筋がどのようなものかを説明します。ブロッキングコメントは作成者に対する評価ではありません。それは、コードベースとそれに依存するユーザーに対するレビュアーの責任です。

著者はブロックコメントを拒絶と解釈すべきではありません。 これは具体的で解決可能な問題です。これを解決して先に進みましょう。

🟡 条件

延期しても問題ないが、コミットされた追跡用Issueと担当者が必要だ。条件付きの項目とは、レビュアーが「これは対応されると信じているが、マージする前にそのコミットメントを記録として残す必要がある」と言うことを意味する。

ブロッキングと条件付きの区別は、多くの場合タイミングとリスクに関係しています。次のPRで提供される予定の欠けている機能は条件付きです。セキュリティ上のギャップを生み出す欠けている機能はブロッキングです。

**担当者のいない条件付き先送りは、先送りではありません。願望です。**所有者のいない追跡対象の問題は、無期限に未解決のまま残る傾向があります。レビュー担当者が何かを条件付きとしてマークするとき、求めているのは理論上の将来的な意図ではなく、名前付きのコミットメントです。

🔵 チームの決定

PR が浮かび上がらせる、単一のレビュアーや作者が一方的に答えるべきではない問いです。チーム決定にはトレードオフが伴い、それはプロジェクトの方向性、アーキテクチャ、あるいはユーザーに影響を与えるため、グループに属するものです。

このラベルを使うことで、レビュアーは個々のコントリビューターを、実際には共有の方向性に関する質問で足止めすることを避けられます。これにより決定事項を表面化させ、トレードオフを整理し、チームに意見を求めます。その際、作者に対して、自分のPRが制御外の何かでブロックされているかのように感じさせることはありません。

チームの決定は、結果の責任を持つ人々によって、PRスレッド上で記録として回答されるべきです。 PRスレッドに現れないサイドチャットで回答された決定は、後で履歴を読む人々にとって存在しないことになります。

6. レビュアーとメンターへの注意

あなたがコードオーナー、より経験豊富なコントリビューター、あるいは単にここに長くいる人として、他の誰かの作業をレビューする立場にある場合、このセクションはあなたのためのものです。

あなたは協力のあり方の手本を示しています。 あなたが書くすべてのレビューは、作者にレビューの仕方を教えています。PRスレッドで投げかけるすべての質問は、新しい貢献者にどんな質問をする価値があるかを教えています。これを避けることはできません。唯一の選択肢は、それを意図的に行うか、無意識に行うかだけです。

丁寧さは敬意です。 理由を説明する丁寧なレビューは、素早い承認よりも著者の努力を尊重します。著者はその仕事に時間を費やしました。それがマージできるかどうか、そしてそのやり取りから何を学べるかを理解する価値があります。

すべてのレビューのやり取りの目的は、作成者がそれ以前よりも能力を高められた状態にすることです。 単にPRをマージすることではありません。自分の知識を誇示することでもありません。ルールを強制することでもありません。目の前のPRを超えて応用できるもの、つまり原則、パターン、トレードオフの理解を、作成者が活用できる形で残すことです。

インスタンスではなく、パターンに名前を付ける。 変更を求めるときは、その背後にある原則を説明しましょう。「この変数を、何が格納されているかを表す名前に変更してください」というのは、「変数名は実装の観点ではなく、呼び出し側の観点からその目的を表すべきです。この関数の呼び出し側は、この値が何を表しているかを実際に何を気にするのでしょうか?」というよりも有用性が低いのです。後者のバージョンは、その作者が今後書くすべての関数のすべての変数に適用できます。

何が好みで何が要件なのかを正直に伝えましょう。 「私ならこう書く」というのは「これは変更しなければならない」と同じではありません。好みを述べているなら、その旨を伝えてください。アーキテクチャ、セキュリティ、互換性といった厳格な要件を挙げているなら、具体的な理由を示してください。レビュアーの好みとアーキテクチャ上の必要性の違いを見分けられない著者は、すべてを変更するか何も変更しないかのどちらかになります。どちらも著者のためにはなりません。

あなたが支援しているチームは、あなたが所属するチームです。 今日行う丁寧で教育的なレビューへの投資は、より良いコードを書き、より良いPRを提出し、他者のレビューをより慎重に行うコントリビューターへと蓄積されます。それはプロジェクトをより良いものにします。また、周囲の人々が成長することで、あなた自身の作業も容易になります。

これはソフトスキルではありません。エンジニアリング作業です。