PR Agent는 GitHub, GitLab, Bitbucket과 같은 플랫폼에서 Pull Request(이하 PR)의 생성부터 병합까지 과정을 자동화하고, 코드 리뷰 품질과 일관성을 높여주는 오픈소스 AI 도구입니다.
이 글에서는 PR Agent의 전체 아키텍처 구조, 명령어별 세부 동작 흐름(예: /pr_add_docs, /pr_analyze 등), 그리고 로컬 또는 서버 환경에서의 세팅 방법까지 단계별로 정리합니다.
PR Agent를 활용해 자동화된 코드 리뷰 파이프라인을 구축하거나, 팀 내 리뷰 효율을 높이고 싶은 개발자라면 이 글을 통해 핵심 개념부터 실전 적용까지 한눈에 확인할 수 있습니다.
PR Agent 아키텍처 및 주요 기능
PR Agent의 아키텍처는 다음과 같은 구성으로 이뤄져 있습니다.
> 1. Digest Request → 2. Planning → 3. Execution (function)

1. 전체 구성요소 설명
1.1 Digest Request
- PR 상태 탐지: 오픈 PR인지, 업데이트된 PR인지 등 유형 파악
- Hunk 탐지& 우선순위화: 변경된 파일의 패치 단위(hunk) 인식, 코드 추가(addition)위주로 우선순위 설정
- PR Compression: 긴 diff를 토큰 예산에 맞춰 최적화 — 삭제-only hunk 제거, 추가 위주 병합, tiktoken 기반 토큰 카운팅 및 적응적 분할 기법 적용 (공식 문서 참조)
1.2 Planning
- 토큰 인식 압축 & 우선순위화: 모델 최대 입력 길이를 고려해 핵심 정보만 선별, 덜 중요한 내용은 생략 혹은 후순위로 조정
- 사용자 요청 분석: PR 코멘트로 받은 명령어(/review, /ask 등)를 LLM에 전달하기 전 사전처리(reflect)수행
- Questioning 단계: 필요 시 추가 정보(예: 어떤 파일에 대해 질문할지)를 사용자에게 재질문하여 맥락 보완

1.3 Tool Execution
- 모듈별 기능 (참고 링크)
- /review : 자동 코드 리뷰 (버그, 보안 취약점, 스타일 위반)
- /describe : PR 제목·요약·코드 워크스루·라벨 자동 생성
- /ask : PR 전반에 대한 Q&A
- /improve : 코드 개선 제안
- /add_docs : 변경된 메서드·클래스 문서 자동 생성
- /update_changelog : CHANGELOG.md 업데이트
- /generate_labels : 커스텀 라벨링
- /analyze : PR 구성 요소별 테스트·문서·코드 제안 보조
- /find_similar_component : 내부 코드베이스 유사 컴포넌트 검색
- 그외 상세한 명령어는 아래의 공식 문서 링크에서 자세히 확인할 수 있습니다.
pr-agent/docs/docs/tools/ask.md at main · qodo-ai/pr-agent
🚀 PR-Agent (Qodo Merge open-source): An AI-Powered 🤖 Tool for Automated Pull Request Analysis, Feedback, Suggestions and More! 💻🔍 - qodo-ai/pr-agent
github.com
- 단일 LLM 호출: 각 기능은 JSON 프롬프트 1회 호출로 설계되어 응답 시간을 단축하고 API 호출 횟수 최소화
- 멀티 프로바이더 지원: GitHub, GitLab, Bitbucket, Azure DevOps 등 다양한 플랫폼에서 동일 동작 보장
- RAG Context Implement: 구성된 저장소에서 상황에 맞는 코드 세그먼트를 검색하여 풀 리퀘스트(PR) 통찰력을 풍부하게 하고 검토 정확도를 높임, Enterprise Plan에서 사용가능 (공식 문서)
모듈별 자세한 기능
1. Review

review : PR을 철저하고 포괄적으로 검토할 수 있는 기능
- 개요 : 코드의 전반적인 품질에 대한 귀중한 피드백을 제공하고 개선 방안을 제시하여 전체 코드베이스를 개선하고 더 높은 품질의 코드에 기여
- 기능 : PR Analysis와 PR Feedback으로 이뤄져있다.
| PR Analysis | PR Feedback | |
| 기능 | - PR의 유형, 요약, 종류 분석 - 관련테스트의 존재여부 - PR 검토에 필요한 예상 노력 (1~5점) - 보안 문제 파악 |
- PR에 대한 제안 및 상세 피드백 → General suggestions : 전체 PR의 평가 → Code Feedback : 유관 파일 및 문제점 → 제안 → 예시 |
- 목적 : PR을 빠르게 초기 검토하여 가장 중요한 측면에 집중하고 주요 PR 문제를 신속하게 해결


2. Describe

describe : 풀 리퀘스트(PR) 설명 방식을 크게 개선할 수 있는 강력한 도구
- 개요: 원본 설명이 명확하지 않거나 세부 사항이 부족한 경우, 이 명령을 사용하면 PR에 대한 포괄적이고 표준화된 설명 제공
- 기능: PR 제목이 자동으로 생성되고, PR 유형(예: 버그 수정, 기능 추가, 문서 업데이트)을 정확하게 식별하며, 변경 사항에 대한 간결하면서도 유익한 설명 작성
- 목적: 관련 파일 목록을 레이블별로 정리하여 제공하여 검토자가 변경 사항을 쉽게 탐색하고 범위를 파악
3. Ask

ask "질문": PR 관련 구체적인 질문을 할 수 있고, 댓글로 정확한 답변을 제공
- 기능 : PR 테스트 중 버그나 오류가 발생할 때무엇이 잘못되었는지 알아내려고 몇 시간을 허비할 필요 없이, 직접 문제에 대해 문의하면 문제 해결 방법에 대한 적절한 제안을 제공
- 목적 : 프로젝트의 특정 측면에 대한 명확한 설명이나 통찰력을 얻고 싶을 때 질문
- 질문 : 새로운 MultiLayerPerceptron에서 학습 데이터에 필요한 입력 크기를 확인
- 답변 : X → (n_samples, n_features), y → (n_samples) 형태뿐 아니라
- train 메서드 내부에서 (n_features, n_samples)로 전치(transpose) 후 처리된다는 점까지 짚음
- 데이터의 transpose는 사실은 코드 흐름을 깊이 분석하지 않으면 놓치기 쉬운 디테일
- 평가
- 1. 정밀 답변 제공: 간단한 shape 확인을 넘어 내부 로직(전치 처리)까지 분석
- 2. 코드 리뷰 강화: 사람이 미처 체크하지 못하는 숨은 가정(hidden assumption)까지 짚어줌

4. Improve

improve : PR 내의 코드를 분석하고 코드의 품질과 가독성을 향상시키기 위한 유용한 제안을 제공
- 개요 : 코드 성능 향상을 위한 권장 사항을 제공할 뿐만 아니라, 이 명령을 사용하면 제안된 변경 사항을 PR 환경 내에서 직접 쉽게 커밋 가능
- 기능 : Commit Suggestion의 간소화된 프로세스를 통해 코드 베이스를 수동으로 풀하고 로컬에서 수정한 후 변경 사항을 다시 푸시할 필요가 없음
- 목적 : 상당한 시간과 노력을 절약하는 동시에 코드가 최고 수준의 품질과 효율성을 충족하도록 보장
5. Add docs

add_docs : PR 코드를 검토하여 함수와 클래스 설명에 대한 유용한 docstring을 생성
- 기능 : 실행하기만 하면 자동으로 PR 코드를 검토하여 함수와 클래스 설명에 대한 유용한 문서를 생성
- 목적 : 코드에 너무 많은 시간을 들이지 않고도 고품질 문서를 작성
명령어별 세부 동작 흐름
| 명령어 | 입력 예시 | 내부 처리 | 결과 출력 |
| /review | @CodiumAI-Agent /review | PR Compression → /review JSON 프롬프트 생성→ LLM 호출 | PR 코멘트(리뷰) |
| /describe | @CodiumAI-Agent /describe | Diff 요약 → PR 설명용 텍스트 패키징 → LLM 호출 | PR 설명(코멘트) |
| /ask | @CodiumAI-Agent /ask “질문” | 사용자 질문 파싱 → 관련 hunk 컨텍스트 매핑 → LLM 호출 | PR 코멘트(Q&A) |
| /improve | @CodiumAI-Agent /improve | 코드 스니펫 분석 → 개선 제안 프롬프트 → LLM 호출 | 인라인 제안 |
| /update_changelog | @CodiumAI-Agent /update_changelog | 변경 내역 분석 → changelog 템플릿 적용 → LLM 호출 | CHANGELOG 업데이트 |
| /add_docs | @CodiumAI-Agent /add_docs | 변경된 코드 식별 → docstring 프롬프트 생성→ LLM 호출 | 인라인 문서 제안 |
| /generate_labels | @CodiumAI-Agent /generate_labels | PR 메타분석 → 라벨링 가이드라인 적용→ LLM 호출 | PR 라벨 |
참고
: 각 명령어는 단일 기능 단위로 모듈화되어 있으며, pr_agent.toml을 통해 세부 동작을 커스터마이징할 수 있습니다.
환경 세팅
# git clone 및 이동
git clone https://github.com/Codium-ai/pr-agent.git
cd pr-agent
# 가상환경 설치 및 실행
python3 -m venv venv # venv 가상 환경 폴더 생성
source venv/bin/activate # Linux 가상 환경 활성화
# 모듈 설치
pip install -e .
# .secrets.toml 파일 생성 (템플릿 파일 pr_agent/settings/.secrets_template.toml 활용)
cp pr_agent/settings/.secrets_template.toml pr_agent/settings/.secrets.toml
chmod 600 pr_agent/settings/.secrets.toml # 읽기, 쓰기 권한 부여
# pr_agent/settings/.secrets.toml에서 API Key 편집
gemini_api_key = <api-key> # 사용할 AI 모델의 API Key ex.Gemini
user_token = <github-user-token> # GitHub 사용자 토큰
# pr_agent/settings/configuration.toml에서 AI 모델 편집
# 가능한 모델명은 pr_agent/algo/__init__.py에서 확인 가능 (default는 gpt-4)
[config]
# models
model=<ai-model>
fallback_models=[<ai-model>]
# <pr_url> : pull request를 요청한 링크
# <command> : review, improve 등의 PR Agent 명령어 - 예시 describe
python3 -m pr_agent.cli --pr_url <pr_url> <command>
아래의 공식문서를 참고하여 세팅하는 것도 좋다!
Configuration File - Qodo Merge (and open-source PR-Agent)
None
qodo-merge-docs.qodo.ai
PR Agent를 세팅하여 PR Suggestion을 받을 수 있었다!
Gemini-1.5-flash를 사용한 이유는 무료였기에,,

'오픈소스 컨트리뷰션 아카데미 2025' 카테고리의 다른 글
| 대형 언어 모델(LLM)과 ChatGPT의 작동 원리 (0) | 2025.04.27 |
|---|