レビューが成立する Issue 設計
今年は仕事で海外のエンジニアと GitHub 上でコードレビューをすることがありました。
その時に学んだことを紹介します。
まず、問題となる点は以下の通りです。
- 英語で書くこと
- PR は出てきたが、期待していた修正とズレることがあった
- 時差やワークライフバランスの違いがあり、そもそもやり取りは少なめ
実際に立てた Issue を題材にしながら、
コードレビューに適した Issue を整理します。
コードレビューの前提
ここで扱うコードレビューの目的は以下の通りです。
Issue で定義された目的（Why / Expected Result）に対して、
提出された変更（コード・設定・依存関係の判断）が
妥当か、スコープ内か、安全かを検証する
実装者のスキルを評価することはせず、Issue に対して、PR が十分回答されているかなどを確認します。
やり取りに使った Issue の構造
実際に以下のような、作り方をしました。例として、中身はpackage.jsonに必要なライブラリが入っていないシンプルなバグに対する Issue です。
特に、言語や開発スタイルの違いで意図が伝わっていない、断定や推論 / 過程など日本語と英語との違いを区別するために以下のヘッダーをテンプレ的に使うのが良いと感じます。
## Scope
This issue only affects `apps/user-web`.
## Summary
Running the dev server fails during Vite dependency optimization because the module `react-is` cannot be resolved. The error originates from Recharts importing `react-is`.
## Environment
- App: `apps/user-web`
- Command: `npm run dev` (runs `vite`)
- OS: Windows (see paths in stack trace)
## Steps to Reproduce
1. Clone the repository
2. Go to `apps/user-web`
3. Install dependencies
- `npm install`
4. Start the dev server
- `npm run dev`
## Actual Result
The dev server starts, but dependency optimization fails with:
"実際のエラーログ"
## Expected Result
`npm run dev` should start successfully without module resolution errors.
## Suspected Cause
`react-is` is required by Recharts but is not available in the installed dependency tree.
## Proposed Fix
- Add `react-is` to dependencies, then reinstall and verify.
- Commit the updated `package.json`.
## Review Focus
Please focus on the following points during review:
- [ ] The dev server (`npm run dev`) starts successfully without errors
- [ ] The fix is limited to `apps/user-web`
- [ ] The dependency addition (`react-is`) is appropriate and minimal
- [ ] No unnecessary dependency upgrades are included
- [ ] The root cause is clearly explained in the PR
この Issue は、「エラーを直してください」という依頼ではなく、
コードレビューを成立させるための情報を揃えることを意識して書いています。
以下で、そのポイントを分解します。
1. Scope を最初に書く
## Scope
This issue only affects `apps/user-web`.
最初に影響範囲を限定しています。
- モノレポ構成でも、他アプリは対象外
- 「ついで修正」を防ぐ
- レビュアーが影響範囲を迷わない
Scope は実装範囲であると同時に、レビュー範囲そのものです。
2. Summary で Why と What を同時に伝える
## Summary
Running the dev server fails during Vite dependency optimization because the module `react-is` cannot be resolved.
ここでは次の点を一文で伝えています。
- 何が起きているか → dev server が起動しない
- どこで起きているか → Vite の dependency optimization
- 直接的な原因 →
react-isが解決できない
レビュー時、この Summary がそのまま「前提条件」になります。
3. Environment / Steps はレビューを成立させるために書く
## Environment
- App: `apps/user-web`
- Command: `npm run dev`
- OS: Windows
## Steps to Reproduce
1. npm install
2. npm run dev
レビュアーが必ず再現する必要はありません。
重要なのは、
- 再現手順が論理的か
- 環境差分が明示されているか
を判断できることです。
これはレビューで妥当性を確認するための情報です。
4. Expected Result が基準になる
## Expected Result
`npm run dev` should start successfully without module resolution errors.
この一文があることで、レビュー時の判断軸が一つに絞られます。
- この PR によって dev server は起動するか
- 余計な変更は入っていないか
レビューは良い・悪いの評価ではなく、期待する結果を満たしているかで判断できます。
5. Suspected Cause / Proposed Fix の書き方
## Suspected Cause
`react-is` is required by Recharts but is not available in the dependency tree.
## Proposed Fix
- Add `react-is` to dependencies
ここでは、断定しないことが重要です。
- 原因は仮説として書く
- 実装方法の裁量は残す
これにより、PR では自然と
- なぜこの修正で直るのか
- 他の選択肢はあったのか
といった説明が行われ、レビューがしやすくなります。
6. Review Focus を書かない場合、レビューでは次が起こりがちです。
動いたから OK という状態を回避します。
レビュアー側
- どこを見れば良いか即座に分かる
- 好みの指摘に流れにくい
- Scope 外チェックを忘れにくい
実装者側
- PR の説明を書く指針になる
- 「なぜこの修正か」を書きやすい
- 余計な修正を入れなくなる
まとめ
気づいたのは以下の点です。
- 海外のエンジニアとのレビューに苦戦した原因は英語力ではなかった
- 英語と日本語の表現の違いは確かにある
- デバッグの依頼にしても前提の共有は重要
- Issue が作業依頼になっていると、レビューが属人化する
良いコードレビューのために、良い Issue をつくっていきましょう。