heydeer ログイン
ベストプラクティス

レビューガイダンスの書き方

レビューへの指示と AGENTS.md は、新しいチームメイトが従えるような短く具体的なルールとして書くと最も効果的です。どちらに書くかは、ルールの置き場所を参照してください。

実際のレビューから始める

何かを書く前に、HeyDeer にいくつかのプルリクエストをレビューさせてください。繰り返し発生する見逃しや不要なコメントに対してルールを追加し、一度に追加するのは数個にとどめ、次のレビューを読んで効果を確認します。

短く具体的なルールを書く

  • ルールを「優先事項」「対象外」「規約」など、いくつかの見出しの下にまとめます。
  • 箇条書き 1 つにつきルールを 1 つ書き、対象となるパス、関数、ライブラリを明記します。
  • 理由が明らかでない場合は、理由を添えます。
  • 除外は範囲を絞ります。「スクリプトにはコメントしない」ではなく「scripts/one-off/ のファイルにはコメントしない」と書きます。前者は本当の問題まで隠してしまいます。
  • コードベースから、誤ったコードと正しいコードを数行ずつ示します。
  • 12,000 文字の上限よりかなり短くすることを目指してください。指示が長くなってきたら、規約は AGENTS.md に、必須の要件はリポジトリのチェックに移します。

含めるべきでないもの

含めないもの理由代わりの方法
インデントやインポート順などのフォーマットのルールフォーマッターやリンターなら、これらを正確に強制できます。それらのツールを CI で実行します。
「もっと徹底的に」「何も見逃さないで」HeyDeer が具体的に行動できる内容がありません。重要なリスクを明記するか、詳細の深さや、より広いフィードバックの範囲を使います。
「あなたはシニアセキュリティエンジニアです」のようなペルソナの設定役割を与えても、何を探すべきかは伝わりません。その人が適用するであろうルールを書きます。
「…の場合はマージをブロック」「小さな PR は承認」指示はレビューの内容を方向付けるものであり、HeyDeer が GitHub で行う操作を決めるものではありません。ブランチルールと組み合わせた「問題が見つかった場合はチェックを失敗にする」と、自動承認を使います。
「テストを実行して」「先にプロジェクトをビルドして」HeyDeer はコードを読みます。コード、テスト、ビルドを実行することはありません。HeyDeer が読んで検証できることを依頼します。
「社内 Wiki の基準に従う」のようなリンクHeyDeer は Web リンクを開けません。重要なルールをコピーするか、ドキュメントをリポジトリに置くか、MCP サーバーを接続します。
「指摘事項は日本語で書いて」言語は設定項目で、要約や見出しにも適用されます。レビューの言語を設定します。

書き換え前と書き換え後

書き換え前：

You are a world-class senior engineer. Be extremely thorough and
never miss a bug. Follow our standards at
https://wiki.example.com/engineering/standards. Use 2-space
indentation. Write all comments in Japanese. Run the tests before
you review, and block the PR if anything is wrong.

書き換え後：

## Priorities

- Code under src/payments/ is high risk. Every call to chargeCard()
  passes an idempotency key derived from the order ID, so a retried
  request cannot charge twice.
- Retries use retry() from src/lib/retry.ts, which adds backoff.
  Replace hand-written retry loops with it.

## Leave alone

- Files under scripts/one-off/. They run once by hand and are deleted.
- Formatting. The formatter enforces it in CI.

## Conventions

- Return client errors through AppError with a stable code.

  Incorrect:

  ```ts
  return Response.json({ error: err.message }, { status: 500 });
  ```

  Correct:

  ```ts
  throw new AppError('INVOICE_NOT_FOUND', 404);
  ```

書き換え後は、ペルソナと Wiki のリンクを具体的なルールに置き換えています。それ以外の内容は、上の表の置き場所に移します。