CodeRabbitCodeRabbitKorea User Group
코드래빗(CodeRabbit) 설정 완벽 가이드: .coderabbit.yaml 모든 옵션 정리
코드래빗 설정coderabbit yamlAI 코드 리뷰 설정PR 리뷰 봇 설정코드레빗CodeRabbitAI 코드 리뷰코드 리뷰 자동화

코드래빗(CodeRabbit) 설정 완벽 가이드: .coderabbit.yaml 모든 옵션 정리

CodeRabbit Korea User Group·

CodeRabbit을 처음 도입하면 PR마다 자동으로 리뷰 코멘트가 달리기 시작합니다. 며칠 지나면 자연스럽게 떠오르는 질문이 있습니다. "이 옵션을 어떻게 저희 팀 컨벤션에 맞춰 조정할 수 있을까?" 답은 .coderabbit.yaml입니다.

이 글은 한국 개발자 시각에서 .coderabbit.yaml의 핵심 옵션, 팀 규모별 추천 프리셋, 실전 yaml 예제 3개, 자주 발생하는 실수까지 한 번에 정리한 완벽 가이드입니다. CodeRabbit의 AI 코드 리뷰를 팀 환경에 정확하게 맞추고 싶으신 분께 추천드립니다.

왜 .coderabbit.yaml을 설정해야 하나요?

CodeRabbit은 기본 설정만으로도 잘 동작합니다. 그렇다면 왜 yaml을 따로 두어야 할까요?

  • 코멘트 양 조절: 기본 프로필은 다소 적극적입니다. 사이드 프로젝트에는 적당하지만, 큰 팀에서는 잡음이 되기도 합니다.
  • 자동 생성 파일 제외: node_modules, dist, *.lock, 자동 생성된 schema 파일까지 리뷰하면 노이즈가 큽니다.
  • 언어/프레임워크별 가이드 주입: TypeScript 팀은 React 컨벤션을, 백엔드 팀은 도메인 모델 규칙을 AI에게 알려줄 수 있습니다.
  • 한국어 리뷰: language: ko 한 줄로 모든 리뷰가 한국어로 바뀝니다.

이 모든 게 yaml 한 파일로 가능하다는 게 핵심입니다.

기본 위치와 우선순위

.coderabbit.yaml은 다음 위치에서 인식됩니다.

  1. 레포지토리 루트: 가장 일반적인 위치. 이 글에서 다루는 모든 예제가 이 형태입니다.
  2. 조직 단위 설정: 엔터프라이즈 플랜에서 조직 전체 기본값을 둘 수 있습니다.

레포지토리 yaml이 조직 yaml을 덮어씁니다. 즉, 조직에서 보안 관련 옵션을 강제하려면 별도 정책이 필요합니다.

파일이 없으면 CodeRabbit의 기본값이 그대로 적용됩니다. 처음 도입하시는 팀은 1~2주 정도 기본값으로 돌려 보시고, 본인 팀에 안 맞는 부분만 yaml에 적어 가는 방법을 권장드립니다.

핵심 옵션 그룹별 설명

.coderabbit.yaml의 옵션은 크게 다섯 그룹으로 나뉩니다. 여기서는 한국 팀이 가장 자주 만지는 옵션 위주로 정리합니다. 전체 옵션은 공식 설정 문서에서 확인하실 수 있습니다.

1) reviews: 리뷰 동작 전반

리뷰의 강도, 자동 리뷰 여부, base 브랜치 등을 정합니다.

reviews:
  profile: "chill"               # "chill" | "assertive" 코멘트 강도
  request_changes_workflow: false # true면 리뷰 결과를 PR Approval/Request Changes로 표시
  high_level_summary: true        # PR 요약 생성
  poem: false                     # 마무리 시(詩) 생성. 즐거우시면 true :)
  review_status: true             # 리뷰 상태 코멘트 표시
  auto_review:
    enabled: true                 # PR이 열릴 때 자동 리뷰
    drafts: false                 # 드래프트 PR도 리뷰할지
    base_branches:
      - main
      - develop
  ignore_usernames:
    - "dependabot[bot]"           # 봇 PR은 무시
  ignore_titles:
    - "^chore: release"           # 릴리스 PR 무시
  sequence_diagrams: true         # 변경 흐름을 다이어그램으로 시각화

처음 도입하실 때 가장 먼저 만지는 옵션은 profileauto_review.base_branches입니다. profile: chill로 두면 사소한 코멘트가 줄어듭니다.

2) chat: Q&A 동작

PR 안에서 멘션으로 질문할 때의 동작입니다.

chat:
  auto_reply: true   # 멘션 없이도 답변. false면 @coderabbitai 멘션 필요

큰 팀에서는 false로 두어 의도된 멘션에만 답하도록 만들기를 권장드립니다.

3) early_access: 베타 기능

early_access: false   # 신규 기능을 먼저 받아볼지 여부

신기능을 빠르게 시도하고 싶으신 팀만 true로 두세요. 안정성이 가장 중요하면 그대로 false가 안전합니다.

4) path_filters / path_instructions: 경로별 제어

가장 강력한 옵션입니다. 특정 경로만 리뷰하거나, 경로별로 다른 가이드를 주입할 수 있습니다.

reviews:
  path_filters:
    - "!**/*.lock"
    - "!**/dist/**"
    - "!**/build/**"
    - "!**/__generated__/**"
  path_instructions:
    - path: "src/components/**/*.tsx"
      instructions: |
        React 함수형 컴포넌트만 사용합니다.
        클래스 컴포넌트가 보이면 함수형으로 리팩토링을 제안하세요.
        useEffect의 의존성 배열을 항상 점검하세요.
    - path: "src/api/**/*.ts"
      instructions: |
        모든 API 응답은 zod 스키마로 검증되어야 합니다.
        에러는 Result 패턴으로 반환합니다.

path_instructions는 사실상 팀 컨벤션 문서를 AI에게 직접 주입하는 통로입니다. 회사 위키에 있는 코드 컨벤션 문서를 그대로 옮기기만 해도 리뷰 품질이 크게 올라갑니다.

5) tools / language: 보조 도구와 언어

tools:
  ast-grep:
    enabled: true
  semgrep:
    enabled: true
 
language: ko    # 모든 리뷰 코멘트를 한국어로

tools는 정적 분석 도구 토글입니다. 정확한 사용 가능 도구 목록은 공식 문서에서 확인해 주세요. language: ko는 한국 팀에서 거의 필수에 가깝습니다.

팀 규모별·언어별 추천 프리셋

오픈소스 메인테이너용

reviews:
  profile: "assertive"
  high_level_summary: true
  auto_review:
    enabled: true
    drafts: false
    base_branches:
      - main
  ignore_usernames:
    - "dependabot[bot]"
chat:
  auto_reply: true
language: ko

오픈소스는 다양한 컨트리뷰터가 들어오므로 assertive로 강도를 높여 컨벤션을 적극 안내하는 게 효과적입니다.

스타트업 / 소규모 팀용

reviews:
  profile: "chill"
  high_level_summary: true
  poem: false
  auto_review:
    enabled: true
    base_branches:
      - main
      - develop
  path_filters:
    - "!**/*.lock"
    - "!**/dist/**"
language: ko

빠르게 머지해야 하는 팀은 chill로 두어 잡음을 최소화합니다.

엔터프라이즈용

reviews:
  profile: "assertive"
  request_changes_workflow: true
  high_level_summary: true
  auto_review:
    enabled: true
    drafts: false
    base_branches:
      - main
      - release/*
  path_instructions:
    - path: "**/*.{ts,tsx,js,jsx}"
      instructions: |
        OWASP Top 10에 해당하는 보안 패턴을 항상 점검하세요.
        외부 입력값은 반드시 sanitize 검사를 거쳐야 합니다.
chat:
  auto_reply: false
language: ko

request_changes_workflow: true로 두면 CodeRabbit 리뷰가 GitHub Approval/Request Changes에 그대로 반영되므로 머지 게이트로 활용할 수 있습니다.

자주 발생하는 실수와 해결법

실수 1: yaml 들여쓰기 오류

.coderabbit.yaml은 yaml 파일이라 들여쓰기가 잘못되면 통째로 무시됩니다. PR을 올렸는데 평소와 다르게 동작한다면 가장 먼저 yaml 린트를 돌려 보세요.

실수 2: path_filters에 부정 표현을 잊음

!(부정)을 빼고 **/*.lock만 적으면 lock 파일만 리뷰하라는 뜻이 됩니다. 제외하려면 반드시 "!**/*.lock" 형태로 작성합니다.

실수 3: auto_review.base_branches에 main이 없음

develop만 적어 두고 main으로 가는 PR이 리뷰되지 않아 당황하는 케이스가 흔합니다. 두 브랜치 모두 필요하면 둘 다 명시해야 합니다.

실수 4: language: ko를 적었는데 영어 리뷰가 옴

캐시 영향일 수 있습니다. yaml 변경 후 새 PR을 열어 확인해 보시고, 그래도 영어가 오면 일정 시간이 지난 뒤 다시 시도해 주세요.

실전 yaml 예제 3개

예제 1: TypeScript + Next.js

reviews:
  profile: "chill"
  high_level_summary: true
  auto_review:
    enabled: true
    base_branches:
      - main
      - develop
  path_filters:
    - "!**/*.lock"
    - "!**/.next/**"
    - "!**/dist/**"
    - "!**/node_modules/**"
  path_instructions:
    - path: "app/**/*.tsx"
      instructions: |
        Next.js 14 App Router를 사용합니다.
        서버 컴포넌트가 기본이며, 클라이언트 컴포넌트는 'use client'를 명시합니다.
        데이터 페칭은 fetch + cache 옵션으로 일관되게 작성합니다.
    - path: "components/**/*.tsx"
      instructions: |
        Tailwind CSS 클래스를 우선 사용합니다.
        접근성(aria-*) 속성을 누락하지 않도록 점검하세요.
language: ko

예제 2: Python + Django

reviews:
  profile: "assertive"
  auto_review:
    enabled: true
    base_branches:
      - main
  path_filters:
    - "!**/migrations/**"
    - "!**/__pycache__/**"
    - "!**/*.pyc"
  path_instructions:
    - path: "**/views.py"
      instructions: |
        Django의 select_related, prefetch_related로 N+1 쿼리를 방지하세요.
        외부 입력은 폼이나 시리얼라이저로 검증된 값만 신뢰합니다.
    - path: "**/models.py"
      instructions: |
        모델 변경 시 마이그레이션 누락이 없는지 확인하세요.
        on_delete 정책이 도메인 의도와 맞는지 점검하세요.
tools:
  ast-grep:
    enabled: true
language: ko

예제 3: Go + gRPC

reviews:
  profile: "assertive"
  request_changes_workflow: true
  auto_review:
    enabled: true
    base_branches:
      - main
      - release/*
  path_filters:
    - "!**/*.pb.go"
    - "!**/mocks/**"
    - "!**/vendor/**"
  path_instructions:
    - path: "**/*.go"
      instructions: |
        에러는 무시하지 말고 반드시 처리하거나 명시적으로 _ 처리하세요.
        context.Context는 첫 번째 파라미터로 전달합니다.
        고루틴 누수 방지를 위해 종료 조건을 명확히 하세요.
language: ko

세 예제 모두 그대로 복사해서 사용하실 수 있습니다. 본인 팀 상황에 맞춰 path_instructions만 다듬어 주세요.

추가로, Kotlin 환경이라면 CodeRabbit Kotlin Best Practices 가이드, 그리고 yaml 옵션의 더 깊은 활용은 CodeRabbit YAML Best Practices도 참고하실 수 있습니다.

자주 묻는 질문

Q. .coderabbit.yaml을 적용했는데 적용이 안 되는 것 같습니다.

가장 흔한 원인 두 가지: (1) yaml 들여쓰기 오류로 파일 전체가 무시됨, (2) PR이 yaml 변경 이전에 열려 캐시된 설정으로 리뷰됨. yaml 변경 후 새 커밋을 푸시해 새로운 리뷰를 트리거해 주세요.

Q. 한국어 리뷰 품질이 영어보다 떨어진다는 말이 있던데 사실인가요?

기술 용어가 많은 코드베이스에서는 영어가 더 정확할 때가 있습니다. 다만 한국어 응답 품질도 빠르게 좋아지고 있습니다. 팀 커뮤니케이션 비용을 고려하면 한국어 권장이고, 미세한 정확도가 중요한 핵심 모듈만 영어로 받는 하이브리드도 가능합니다(path_instructions로 특정 경로만 영어 가이드를 주입).

Q. CodeRabbit이 너무 사소한 코멘트까지 답니다.

profile: chill로 변경하시고, path_filters로 자동 생성 파일을 제외해 보세요. 그래도 많다면 path_instructions에 "사소한 스타일 코멘트는 생략하고 버그·보안 위주로 리뷰하세요" 같은 지시를 명시할 수 있습니다.

Q. 로컬에서 리뷰를 미리 받아볼 수도 있나요?

네, CodeRabbit CLI로 PR을 올리기 전에 로컬에서 리뷰를 받을 수 있습니다. 같은 .coderabbit.yaml 설정이 그대로 적용됩니다.

Q. 멀티 레포지토리 환경에서도 yaml 설정이 통할까요?

네. 각 레포지토리에 .coderabbit.yaml을 두면 됩니다. 멀티 레포 분석 자체는 에이전틱 코드 리뷰 기능이 처리합니다.

결론

.coderabbit.yaml은 단순한 설정 파일이 아니라 팀의 코드 리뷰 컨벤션을 AI에 주입하는 통로입니다. 처음에는 기본값으로 돌리시다가, 팀에 안 맞는 부분이 보일 때 yaml에 한 줄씩 추가해 가시는 게 가장 안전한 도입 방식입니다. 위의 세 가지 실전 예제 중 하나로 시작해 보시고, 1~2주 안에 본인 팀 컨벤션을 반영해 다듬으시면 충분합니다.

CodeRabbit이 처음이시라면 도입 가이드부터 가볍게 살펴보시는 것을 권장드립니다.

CodeRabbit 시작하기