PR Agent 아키텍처, 명령어별 세부 동작 흐름, 환경 세팅

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 단계: 필요 시 추가 정보(예: 어떤 파일에 대해 질문할지)를 사용자에게 재질문하여 맥락 보완

PR Agent의 토큰 인식 압축 및 우선순위화 과정 도식화

 

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

• 단일 LLM 호출: 각 기능은 JSON 프롬프트 1회 호출로 설계되어 응답 시간을 단축하고 API 호출 횟수 최소화
• 멀티 프로바이더 지원: GitHub, GitLab, Bitbucket, Azure DevOps 등 다양한 플랫폼에서 동일 동작 보장
• RAG Context Implement: 구성된 저장소에서 상황에 맞는 코드 세그먼트를 검색하여 풀 리퀘스트(PR) 통찰력을 풍부하게 하고 검토 정확도를 높임, Enterprise Plan에서 사용가능 (공식 문서)

모듈별 자세한 기능

1. Review 

PR Agent : /review 명령어

 

review : PR을 철저하고 포괄적으로 검토할 수 있는 기능

• 개요 : 코드의 전반적인 품질에 대한 귀중한 피드백을 제공하고 개선 방안을 제시하여 전체 코드베이스를 개선하고 더 높은 품질의 코드에 기여
• 기능 : PR Analysis와 PR Feedback으로 이뤄져있다.

	PR Analysis	PR Feedback
기능	- PR의 유형, 요약, 종류 분석 - 관련테스트의 존재여부 - PR 검토에 필요한 예상 노력 (1~5점) - 보안 문제 파악	- PR에 대한 제안 및 상세 피드백 → General suggestions : 전체 PR의 평가 → Code Feedback : 유관 파일 및 문제점 → 제안 → 예시

 

• 목적 : PR을 빠르게 초기 검토하여 가장 중요한 측면에 집중하고 주요 PR 문제를 신속하게 해결
  
  
  

review의 PR Analysis

 

review의 PR Feedback

 

2. Describe

PR Agent의 describe 명령어

 

describe : 풀 리퀘스트(PR) 설명 방식을 크게 개선할 수 있는 강력한 도구

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

 

3. Ask

PR Agent의 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)까지 짚어줌

PR Agent의 ask기능을 통해 생성한 질문에 대한 답변 예시

 

4. Improve

PR Agent의 Improve 명령어

 

improve : PR 내의 코드를 분석하고 코드의 품질과 가독성을 향상시키기 위한 유용한 제안을 제공

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

5. Add docs

PR Agent의 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)

 

PR Agent를 세팅하여 PR Suggestion을 받을 수 있었다!

Gemini-1.5-flash를 사용한 이유는 무료였기에,,