engineering-review-feedback について
エンジニアリングレビューのフィードバックを協働として扱うスキルです。依頼の確認、コードやテストの適切な修正、建設的な応答を支援し、レビュー上の説明だけでなく成果物自体の改善を促します。
主な機能
- 01フィードバックの分類手順
- 02同意や確認の応答指針
- 03トレードオフに基づく異論の伝え方
- 04コード、テスト、文書の修正
- 05検証と返信のテンプレート
活用シーン
- 01レビューコメントをコード変更に反映
- 02曖昧なレビュー依頼の確認
- 03技術的な意見の相違の説明
- 04変更内容と検証結果の報告
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/engineering-review-feedbackを入力して読み込まれたか確認します。
詳細
エンジニアリングレビューのフィードバック
レビュー担当者からのフィードバックは、より良いコードを目指すための協力として受け止めましょう。多くの場合、レビューのスレッド内で説明するだけでなく、コード、テスト、コメントを変更して、後から読む人にも役立つようにするのが最善です。
Google Engineering Practices Documentation、特に「レビュー担当者のコメントへの対応方法」をもとにしています。出典：https://google.github.io/eng-practices/review/developer/handling-comments.html。ライセンス：CC-BY 3.0。
対応の流れ
- コメントにいら立ちを感じたら、返信する前に一度立ち止まります。
- レビュー担当者が何を求めているのかを特定します。
- 各コメントを分類します。
- コードの変更が必要。
- テストの変更が必要。
- ドキュメントまたはコメントの変更が必要。
- 明確化が必要。
- 話し合うべき意見の相違。
- 対応必須ではない提案。
- レビューツール上で説明するより、成果物を改善することを優先します。
- 関連する検証を実行します。
- 何を、なぜ変更し、どのようにテストしたかを返信します。
レビュー担当者がコードを理解できないと言った場合は、まずコードをより明確にする方法を試してください。なぜそうするのかをコードで明確に表現できない場合に限り、コードコメントを追加します。
同意する場合
短く返信し、変更を加えます。
Done. I renamed the helper to describe normalization rather than validation and updated the two call sites.
Tested with: npm test -- user-profile.test.ts
明確化が必要な場合
不足している判断や制約について尋ねます。防御的な言い回しは避けます。
I want to make sure I understand the concern. Are you asking for this to reject duplicate requests at the API boundary, or for the worker to make duplicate processing idempotent?
同意できない場合
相手を否定するのではなく、トレードオフを比較して意見の相違を伝えます。
I chose X because it keeps the retry policy in one place and avoids a second queue state. My concern with Y is that it makes cancellation observable in two different layers.
If you think Y better serves the rollback requirement, I can switch to it. Is that the tradeoff you want prioritized?
レビュー担当者がより優れた技術的根拠を示した場合は、それを受け入れて調整します。どちらも合意に至らない場合は、より情報量の多い方法で話し合い、決定事項をレビューに要約して記録します。
建設的でないフィードバックへの対応
同じような言い方で返してはいけません。コード、テスト、ドキュメントで対処できる技術的な懸念があれば、それを取り出して対応します。コメントが敵意を含む、曖昧、または何度も建設的な成果につながらない場合は、非公開の場や、より情報量の多い方法で話し合います。必要に応じてリードを交え、技術的な決定事項だけをレビューに要約して記録します。
適切な箇所を修正する
- わかりにくい式：簡潔にするか、名前を変更します。
- 隠れた不変条件：型、検証、アサーション、または目的を絞ったコメントで表現します。
- 動作の信頼性を確かめる手段が不足している：テストを追加または改善します。
- コンテキストが不足している：PR の説明、コードコメント、README、または設計ドキュメントを更新します。
- 古い差分が原因でレビュー担当者が誤解している：リベースする、不要なコードを削除する、または説明を更新します。
- 単なる好み：必須かどうかを尋ね、そうでなければ任意の提案として扱います。
返信の要約テンプレート
Addressed this round:
- Changed ...
- Added/updated tests for ...
- Clarified ...
Verification:
- `...`
Open:
- ...
よくある間違い
- 怒りや皮肉を込めて返信する。
- わかりにくいコードの説明をレビューのスレッド内だけで行う。
- 深刻度を確認せず、レビュー担当者からの提案をすべて必須として扱う。
- 現在の変更で複雑さを持ち込んだにもかかわらず、「後で整理する」と言う。
- 範囲の狭いレビューコメントへの対応中に、無関係な大規模リファクタリングを行う。