はじめに：「導入したけど、当たり障りのない指摘ばかり…」その不満、設定の問題です

CodeRabbitを導入したものの、実際の現場でこんなジレンマを感じていませんか？

「PRに『セミコロンが抜けてます』ばかりで、本質的な指摘が来ない」
「プロジェクト固有の規約（例：『カスタムフックの戻り値にはas constを付ける』）を守ってくれない」
「チームの技術的負債や暗黙知を理解したレビューがほしいのに、一般的なベストプラクティスしか言ってこない」

これはCodeRabbitのせいではありません。設定の問題です。

多くのチームが「CodeRabbitを有効化した」だけで満足し、本来の価値の10～30%しか引き出せていないのが現状です。デフォルト設定は「一般的なベストプラクティス」に最適化されていますが、あなたのチーム特有の文脈、暗黙知、アーキテクチャの制約を理解しているわけではないのです。

本記事では、.coderabbit.yamlを徹底的にカスタマイズし、CodeRabbitを「自社の技術文化を体現した専属シニアエンジニア」に育て上げる、現場で泥臭くチューニングした結果たどり着いた「魔改造」テクニックを全公開します。

この記事のゴール
読了後、あなたのチームのCodeRabbitは、アーキテクチャ違反を指摘し、セキュリティホールを塞ぎ、チーム固有の規約を強制する「最強のレビュアー」に生まれ変わります。

1. `.coderabbit.yaml`の構造を正しく理解する

CodeRabbitの設定ファイルは、AIエンジニアに対する 「役割定義書」「評価基準」「行動規範」 そのものです。
まずは全体像を把握しましょう。公式スキーマに基づいた正しい階層構造は以下のようになります。

# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
# ↑ 最初の1行は重要。VS CodeなどのIDEで補完とバリデーションを有効化します

version: "0.1"
language: "ja-JP"

# 層1: reviews（PRレビュー時の振る舞い・指示・ツール設定）
reviews:
  profile: "assertive"
  
  # ツール設定（ast-grep等）は reviews の配下に置くのが正解
  tools:
    ast-grep:
      essential_rules: true
      # ...

# 層2: chat（対話機能の振る舞い）
chat:
  auto_reply: true
  # ...

以前はトップレベルに tools を書く例もありましたが、現在は reviews 配下で管理するのが基本です。

2. AIの人格形成：`system_prompt` のハック

これが本記事の核です。instructions（または system_prompt）は単なる「口調の指定」ではなく、AIの「認知フレーム」と「優先度付け」を再プログラムする最強の道具です。

デフォルトの「親切なアシスタント」を捨て、 「妥協なきシニアエンジニア」 を召喚します。

reviews:
  profile: "assertive" # 積極的に指摘させる設定
  
  # request_changes_workflow: true # 自信がある場合はtrueにして、AIに「修正要求」を出させる

  instructions: |
    あなたは、当社プロジェクトの技術文化を深く理解したシニアエンジニアです。
    このプロジェクトのコード品質、保守性、セキュリティに対して全責任を持っています。
    
    【役割】
    - 単なるバグ検出ではなく、アーキテクチャへの影響を考慮したレビューを行う
    - チームメンバーを教育し、成長させることを意識する
    - パフォーマンス、セキュリティ、保守性を同じ重さで評価する
    
    【トーン】
    - 日本語で、敬意を持ちながらも率直に指摘する
    - 「なぜそれが問題なのか」を必ず説明する
    - 改善提案は「例」を交えて具体的に示す
    - "Looks good" などの社交辞令は不要
    
    【判断基準】
    - 当プロジェクトのコーディング標準（CODING_STANDARDS.md参照）を最優先
    - ESLint/Prettierで検出できるスタイル違反は言及しない（ノイズになるため）
    - アーキテクチャ違反、セキュリティホール、パフォーマンス劣化を最優先で指摘

このプロンプトの重要なポイントは3つです：

役割の明確化：「シニアエンジニア」という役割を与えることで、視座を高める。
判断基準の明示：Linterでわかることは指摘させず、本質的な問題に集中させる。
コンテキストの注入：ドキュメントを参照させ、チームの暗黙知を理解させる。

3. チーム固有ルールの注入：`instructions` の極意

ここでは、プロジェクト全体に適用する具体的なルールを記述します。
「〜しないように」という否定形よりも、「〜の場合は〜せよ」という条件分岐型プロンプトの方が精度が高くなります。

    # ... (instructionsの続き)

    【命名規則チェック】
    - Reactコンポーネント名は PascalCase のみ（例：UserCard.tsx）
    - カスタムフックは「use」プレフィックス必須（例：useUserAuth）
    
    【セキュリティチェック】
    - 環境変数へのアクセスは process.env から直接ではなく、config.ts を通じて一元管理していることを確認せよ
    - SQL/NoSQLクエリでは、プレースホルダーまたはORMのprepare機能を必ず使用せよ
    
    【ライブラリ選定】
    - moment.js は公式に “legacy project in maintenance mode” とされているため、新規採用は避け、dayjs / date-fns 等を検討するよう提案せよ
    - lodash の単機能は、ESモジュールの標準機能で代用するよう提案せよ

ディレクトリごとに人格を変える `path_instructions`

これが本稿の真骨頂です。同じコードを見ても、文脈によってレビュー基準を変えることで、AIを「専門性の高いレビュアー」に変身させます。

reviews:
  path_instructions:
    # フロントエンド：React/UIコンポーネント
    - path: "src/components/**"
      instructions: |
        【Reactコンポーネント固有のルール】
        - Propsの型定義は interface を使用（typeではなく）
        - 副作用（API呼び出し等）は useEffect 内に限定する
        - Suspense対応コンポーネントか否か、責務を明確にする
    
    # バックエンド：Node.js/Express
    - path: "src/api/routes/**"
      instructions: |
        【APIルート固有のルール】
        - エラーハンドリングは必ず try-catch で統一
        - 外部API呼び出しはタイムアウト設定を必須に
        - トランザクションの粒度を確認（ACID特性の担保）
    
    # インフラ：Terraform/Docker
    - path: "infra/**"
      instructions: |
        【インフラ固有のルール】
        - ハードコーディングされたIP/ポートがないことを確認
        - Security scan（Hadolintなど）に通過していることを前提とする

4. 構造的欠陥を見抜く：AST解析（ast-grep）の活用

ここが「ただのLLMラッパー」とCodeRabbitの一線を画す部分です。
CodeRabbitは内部で AST（抽象構文木）解析ツール ast-grep を利用可能です。これを利用することで、テキストマッチングでは不可能な「構造的なバグ」を検出できます。

なぜAST解析なのか？

例えば eval() の使用を禁止したい場合：

テキスト検索: コメントアウトされた // eval(...) や文字列 const s = "eval" まで誤検知してしまう。
AST解析: 「関数呼び出しとしての eval」だけをピンポイントで検出できる。

実装手順（正しい設定位置）

CodeRabbitで ast-grep を動かすには、reviews.tools 配下に記述し、かつ ルールディレクトリ等の指定 が必須です（単に enabled: true だけでは動作しないケースがあります）。

reviews:
  tools:
    ast-grep:
      # CodeRabbit標準のベストプラクティスルールセットを有効化
      essential_rules: true
      # 自作ルールのディレクトリを指定
      rule_dirs:
        - ".coderabbit/rules"

リポジトリ内に .coderabbit/rules/n-plus-one.yml を作成します。

# .coderabbit/rules/n-plus-one.yml
id: n-plus-one-query
language: typescript
severity: warning
message: "ループ内でDBクエリを実行しています。N+1問題の原因となります。"
rule:
  kind: for_statement # forループの中で
  has:
    kind: call_expression # 関数呼び出しがあり
    pattern: db.query($$$) # それがdb.queryである場合

このように設定することで、AIは「なんとなく怪しい」ではなく**「構造的に間違いなくN+1である」**箇所を確信を持って指摘できるようになります。

5. Shift Left：ローカル開発フローの変革

設定ファイルを魔改造しても、PRを出してから指摘されていては手戻りが発生します。
CodeRabbitの真価は、 CIを回す前、コミットする前の「ローカル環境」 で発揮されます。

VS Code拡張機能による「セルフレビュー」

CodeRabbitのVS Code拡張を活用し、 「コミット前セルフレビュー」 のフローを構築します。チャットでコマンドを打つよりも、サイドバーのGUIを使うのが確実です。

最強の開発フロー

コードを書く（まだコミットしていなくてOK）
VS Codeの左サイドバーから CodeRabbit アイコンを開く
Review Scope を確認:
- 必要に応じて比較対象のブランチ（Base Branch）を選択します。
「Review」ボタンをクリック:
- 変更差分（Staged/Unstaged含む）に対して、魔改造した .coderabbit.yaml の人格で即座にレビューが走ります。
修正:
- 指摘事項をその場で修正し、クリーンな状態でコミット＆プッシュ。

このフローにより、PR作成時には既に「LGTM」に近い状態からスタートできます。

6. 検証：教育前 vs 教育後

実際に、意図的に「動くけど汚いコード」を含むPRを作成し、デフォルト設定と魔改造設定で比較しました。

対象コード（TypeScript）:

// ユーザー情報を取得して保存する（悪い例）
export const processUser = async (id: any) => {
  const user = await db.query(`SELECT * FROM users WHERE id = ${id}`); // SQLインジェクション
  if (user) {
    console.log("User found:", user); // console.log残留
    // ...複雑なロジック...
  }
}

Before（デフォルト設定）

🤖 CodeRabbit:

id の型を any ではなく具体的にした方が良いですね。

console.log は本番環境では削除しましょう。

全体的に読みやすいコードです！

（感想：優しいけど、SQLインジェクションを見逃している…！）

After（魔改造設定）

👹 CodeRabbit (Customized):

【重大なセキュリティリスク】 SQLインジェクションの脆弱性があります。テンプレートリテラルで変数を埋め込むのではなく、必ずパラメータ化クエリを使用してください。

【規約違反】 any 型の使用は禁止されています。UserId 型を定義して使用してください。

【修正要求】 console.log が残っています。ロガーライブラリを使用するか、削除してください。

【設計】 関数名 processUser が曖昧です。fetchAndSaveUser など、責務を表す名前に変更してください。

圧倒的な差です。
特にセキュリティリスクや命名規則への指摘は、instructions で明示した効果がてきめんに現れています。

まとめ：設定ファイルは「チームの技術文化」である

CodeRabbitの .coderabbit.yaml を作り込む作業は、単なるツール設定ではありません。
「自分たちのチームは何を大切にするのか」「どういうコードを美しいとするのか」を言語化し、合意形成するプロセスそのものです。

今回紹介した設定をベースに、ぜひあなたのチームだけの色を加えていってください。
AIを「育てる」過程で、チーム自体の技術力も間違いなく向上します。

🎁 プレゼント：コピペ用テンプレート

本記事で解説した設定をまとめた「最強の .coderabbit.yaml テンプレート」を以下に用意しました。
これを .coderabbit.yaml として保存し、あなたのチームに合わせて調整してください。

クリックしてテンプレートを展開

# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
version: "0.1"
language: "ja-JP"

reviews:
  profile: "assertive"
  request_changes_workflow: false
  high_level_summary: true

  auto_review:
    enabled: true

  # tools は reviews 配下に置く（公式推奨）
  tools:
    ast-grep:
      # essential_rules か rule_dirs のどちらか（あるいは両方）がないと動作しないため注意
      essential_rules: true
      rule_dirs:
        - ".coderabbit/rules"
    # 必要に応じて他のツールもここへ
    # linter:
    #   enabled: true

  instructions: |
    あなたは、GoogleとNetflixでテックリードを歴任した、世界トップクラスのソフトウェアアーキテクトです。
    このプロジェクトのコード品質、保守性、セキュリティに対して全責任を持っています。
    
    ## 行動指針
    1. **褒めるな、指摘せよ**: "Looks good" などの社交辞令は不要です。改善点のみを簡潔に指摘してください。
    2. **Whyを語れ**: 指摘をする際は、必ず「なぜそれが問題なのか」を論理的に説明してください。
    3. **具体案を出せ**: 抽象的な指摘ではなく、修正後のコードスニペットを必ず提示してください。

    ## 共通ルール
    - console.log の残留は禁止
    - 複雑度が10を超える関数は分割を提案
    - マジックナンバーの使用禁止

  path_instructions:
    - path: "src/domain/**/*"
      instructions: |
        ここはドメイン層です。
        - 外部ライブラリへの依存を極力排除してください。
        - プリミティブ型ではなく値オブジェクトの使用を推奨してください。

    - path: "src/infrastructure/**/*"
      instructions: |
        ここはインフラ層です。
        - SQLインジェクションのリスクを最優先でチェックしてください。
        - エラーハンドリングが握りつぶされていないか確認してください。

chat:
  auto_reply: true

最後に
もしこの記事のおかげでMac miniが当たったら、この設定ファイルをさらに高速に回すためのビルドサーバーとして活用させていただきます（笑）。

Happy Coding & Happy Reviewing!