junior-engineer-review

ジュニアエンジニアによるレビュー

生成されたコードが、十分な能力を持つ新しいチームメンバーに理解、変更、デバッグ、説明できるものかどうかをレビューする際に、このスキルを使用します。

主な判断基準は、認知負荷の総量です。優れたコードは、そのファイル内で一目で理解でき、パッケージ全体の構成の中でも筋が通っており、作者の意図が隠れていることに頼りません。

レビューの姿勢

• 洗練された書き方よりも、読みやすさ、追跡可能性、安全な変更を優先します。
• 次の保守担当者はリポジトリの背景を知っていても、エージェントの非公開の推論は知らないものとしてコードをレビューします。
• 広範なスタイル上の意見より、コード内の具体的な箇所に結び付いた指摘を優先します。
• 理解、デバッグ、変更の安全性に実質的な影響がない限り、主観的な好みを理由に変更を求めないでください。
• 有用な簡潔さは尊重しますが、コードを説明しにくくする、あまり知られていない言語機能、圧縮された式、巧妙な処理フローは避けます。

レビュープロセス

ユーザーが個別のレビューを依頼していない場合でも、コード変更のたびに必ずこのレビューを実施します。コードを変更した場合は、以下のチェックリストを使い、問題が解決するまでレビューを繰り返します。

1. 以下のチェックリストを使い、変更したコードをレビューします。
2. 指摘事項があれば、対応可能でスコープ内のものをすべて修正します。
3. 修正後にレビューを再実施します。
4. 未解決の指摘事項がなくなるか、レビューを合計10回実施するまで続けます。
5. レビューが10回に達しても指摘事項が残っている場合は、コードの変更を止め、未解決の指摘事項と、残っている理由、次に必要な対応を報告します。

各レビューでは、次の手順を実施します。

1. 生成または変更されたコードと、それが支える動作を特定します。
2. エントリーポイントから副作用まで、主な実行経路をたどります。
3. 新しいチームメンバーが、関係のないディレクトリを先に調べなくても各手順を説明できるか確認します。
4. オーケストレーション、検証、永続化、フォーマット、エラー処理が混在していないか確認します。
5. 選択された抽象化や依存関係が、実際の問題の規模に見合っているか確認します。
6. テストが動作の説明と変更への確信につながるか確認します。
7. 読みやすさ、保守性、デバッグ、安全な変更に実質的な影響を与える問題だけを報告します。

ガードレール

• 命名：コメントがなくても意図が伝わる名前を優先します。曖昧な名前、ドメイン上の前提を埋め込んだ名前、仕組みだけを表す名前は指摘します。
• 関数：明確な責務を1つ持つ関数を優先します。ファイルの規模から見て単純になる場合を除き、オーケストレーション、検証、永続化、フォーマット、表示を混在させている関数は指摘します。
• 抽象化：実際の実装が2つ以上ある場合、明確なテスト境界がある場合、または既存のプロジェクト規約で定められている場合を除き、インターフェース、ファクトリー、ストラテジー、レジストリ、汎用ラッパーは避けます。
• ファイル：恣意的な技術上の儀礼ではなく、ドメインや概念ごとに分割します。複雑さを減らさず、移動の手間だけを増やす小さすぎるファイルは指摘します。
• ディレクトリ：直感的にたどれる、パッケージを中心としたグループ分けを優先します。関連コードを見つけるために、ツリー全体を把握する必要がない構成にします。
• 制御フロー：読みやすく、直線的なフローを優先します。経路を見えにくくしたり、テストを複雑にしたりする巧妙な連鎖、多用された三項演算子、ネストしたコールバック、深くネストした分岐は指摘します。
• エラー処理：エラーは、原因となった処理の近くで扱います。離れた場所で処理されるエラー、汎用的なエラー、握りつぶされるエラー、コンテキストに乏しいエラーは指摘します。
• 実行経路の追跡可能性：暗黙の仕組みより、明示的な処理フローを優先します。実行内容を不明瞭にする、隠れたコールバック、動的ディスパッチ、リフレクション、グローバル登録、ライフサイクルフックは指摘します。
• テスト：テストは、実装の仕組みだけでなく、動作と有用なエッジケースを説明するものであるべきです。非公開の内部構造をそのままなぞる脆いテストや、重要な経路を網羅していないテストは指摘します。
• コメント：コメントは、コードが必要とされる理由を説明するものです。コードの内容を言い換えたコメントは指摘します。
• 依存関係：小さな問題にライブラリを導入するのは避けます。ローカルなコードのほうが単純で明確、かつリスクも低い場合に、新たに追加された依存関係は指摘します。

出力

重大度の高い順に指摘事項を示してください。各指摘事項には、次の内容を含めてください。

• 場所：該当する場合はファイルと行番号。
• 問題点：認知負荷または保守性に関する問題。
• 重要な理由：新しいチームメンバーがコードを理解、変更、デバッグ、説明する際にどのような影響があるか。
• 変更案：大幅な書き直しが必要でない限り、よりシンプルな方向性を示してください。

コードが問題ない場合は、その旨を明確に伝え、残っているリスクやテストの不足を記してください。

コード変更後にこのスキルを実行する場合は、最終的なループ回数と、すべての指摘事項が解決して終了したのか、10ループの上限に達して終了したのかを含めてください。

実用的で親切な口調を保ってください。目的は、害のないスタイルの違いを責めることではなく、生成されたコードを人が保守しやすくすることです。