PR-Agent Describe 기능 분석

Tasker_Jang·2025년 4월 29일
agent오픈소스인공지능
0

PR-Agent의 /describe 명령어는 Pull Request(PR)에 대한 자동 설명을 생성하는 기능을 제공합니다. 이 글에서는 describe 명령어의 설정, 코드 구조, 작동 원리 및 실제 사용 방법에 대해 상세히 알아보겠습니다.

1. Describe 명령어 개요

/describe 명령어는 PR의 내용을 분석하여 다음과 같은 정보를 자동으로 생성합니다:

  • PR 제목 (Title)
  • PR 유형 (Type) - 버그 수정, 기능 추가, 문서화 등
  • PR 설명 (Description) - 변경 사항에 대한 요약
  • 파일 변경 사항 안내 (Changes Walkthrough) - 변경된 파일 목록과 각 파일의 변경 내용 요약

이렇게 생성된 정보는 PR의 설명으로 자동 게시되거나 댓글로 게시됩니다.

2. Describe 설정 분석

configuration.toml 파일에서 describe 관련 설정은 [pr_description] 섹션에 정의되어 있습니다:

[pr_description] # /describe #
publish_labels=false                         # PR에 라벨을 추가할지 여부
add_original_user_description=true           # 원래 사용자가 작성한 설명을 포함할지 여부
generate_ai_title=false                      # AI가 PR 제목을 생성할지 여부
use_bullet_points=true                       # 설명에 글머리 기호를 사용할지 여부
extra_instructions = ""                      # AI에 제공할 추가 지침
enable_pr_type=true                          # PR 유형을 포함할지 여부
final_update_message = true                  # 최종 업데이트 메시지를 표시할지 여부
enable_help_text=false                       # 도움말 텍스트를 포함할지 여부
enable_help_comment=true                     # 도움말 코멘트를 포함할지 여부

# 댓글로 설명 게시
publish_description_as_comment=false         # 설명을 댓글로 게시할지 여부
publish_description_as_comment_persistent=true # 댓글이 지속적으로 업데이트되는지 여부

## 변경 사항 안내 섹션
enable_semantic_files_types=true             # 파일 유형에 따른 의미론적 분류 사용 여부
collapsible_file_list='adaptive'             # 파일 목록을 접을 수 있게 할지 여부 (true, false, 'adaptive')
collapsible_file_list_threshold=6            # 접을 수 있는 파일 목록의 임계값
inline_file_summary=false                    # 인라인 파일 요약 사용 여부 (false, true, 'table')

# 마커
use_description_markers=false                # 설명 마커 사용 여부
include_generated_by_header=true             # 'Generated by PR Agent' 헤더 포함 여부

# 대규모 PR 모드
enable_large_pr_handling=true                # 대규모 PR 처리 기능 활성화 여부
max_ai_calls=4                               # 최대 AI 호출 횟수
async_ai_calls=true                          # 비동기 AI 호출 사용 여부

이러한 설정을 통해 describe 명령어의 동작을 사용자 정의할 수 있습니다. 각 설정은 PR 설명 생성 방식과 형식을 제어합니다.

3. Describe 코드 구조 및 동작 방식

PR-Agent의 describe 명령어는 PRDescription 클래스에 구현되어 있습니다. 이 클래스의 주요 메서드와 동작 방식은 다음과 같습니다:

3.1 주요 메서드 및 흐름

  1. 초기화 (__init__)

    • Git 제공자(GitHub, GitLab 등) 초기화
    • AI 핸들러 초기화
    • 토큰 핸들러 초기화
    • 변수 및 설정 로드

  2. 실행 (run)

    • PR 정보 수집
    • AI를 통한 PR 설명 예측
    • 예측 결과 처리
    • 설명 게시 (PR 설명 또는 댓글로)

  3. 예측 준비 (_prepare_prediction)

    • PR 차이점(diff) 처리
    • 대규모 PR 처리 (필요한 경우)
    • AI 모델에 요청 보내기

  4. 파일 레이블 준비 (_prepare_file_labels)

    • 변경된 파일에 대한 레이블 및 설명 정리

  5. PR 응답 준비

    • _prepare_pr_answer: 마커를 사용하지 않는 경우
    • _prepare_pr_answer_with_markers: 마커를 사용하는 경우

3.2 특별 기능

  • 대규모 PR 처리: enable_large_pr_handling 설정이 활성화된 경우, 대규모 PR을 여러 청크로 나누어 처리하여 토큰 제한을 초과하지 않도록 합니다.
  • 마커 사용: use_description_markers가 활성화된 경우, 사용자가 정의한 마커(pr_agent:type, pr_agent:summary, pr_agent:walkthrough)를 사용하여 PR 설명 내의 특정 섹션을 대체합니다.
  • 의미론적 파일 분류: enable_semantic_files_types가 활성화된 경우, 변경된 파일을 유형(버그 수정, 문서, 개선 등)에 따라 분류합니다.

4. describe 실행 흐름 및 데이터 처리

describe 명령어의 실행 흐름을 순서대로 설명하면 다음과 같습니다:

  1. 초기화: PR URL을 입력받아 Git 제공자와 AI 핸들러 초기화
  2. PR 정보 수집: PR의 기존 제목, 설명, 브랜치, 커밋 메시지 수집
  3. 차이점 처리: PR의 코드 차이점(diff) 분석 및 토큰 제한 내에서 처리
  4. AI 예측: 처리된 정보를 AI 모델에 전송하여 PR 설명 생성
  5. 결과 가공: AI 생성 결과를 YAML에서 파싱하여 처리
  6. 출력 생성: 결과를 바탕으로 마크다운 형식의 설명 생성
  7. 게시: 생성된 설명을 PR 설명 또는 댓글로 게시

대규모 PR의 경우 추가 단계가 있습니다:
1. PR을 여러 청크로 분할
2. 각 청크에 대해 별도의 AI 호출 수행
3. 파일 설명을 먼저 생성
4. 다음으로 PR 헤더 정보(제목, 유형, 설명) 생성
5. 모든 정보를 병합하여 최종 PR 설명 생성

5. 실제 사용 방법

5.1 기본 사용법

describe 명령어는 다음과 같은 방법으로 사용할 수 있습니다:

1. CLI 사용 (로컬)

python -m pr_agent.cli --pr_url=<PR URL> describe

2. PR 댓글로 사용 (온라인)

PR 댓글에 다음과 같이 작성합니다:

/describe

3. GitHub Action으로 자동 실행

GitHub Action을 설정하여 PR이 열릴 때 자동으로 실행할 수 있습니다.

5.2 추가 옵션 사용

describe 명령어에 추가 옵션을 사용할 수 있습니다:

/describe --pr_description.generate_ai_title=true --pr_description.publish_labels=true

이렇게 하면 AI가 제목을 생성하고 라벨을 발행하도록 설정할 수 있습니다.

5.3 마커 사용

마커를 사용하여 기존 PR 설명의 특정 부분만 업데이트할 수 있습니다:

# 제목

pr_agent:type

## 설명

pr_agent:summary

## 변경된 파일

pr_agent:walkthrough

이 경우 use_description_markers=true로 설정해야 합니다.

6. 활용 예시 및 팁

6.1 대규모 PR 처리

대규모 PR을 효과적으로 처리하기 위한 설정:

[pr_description]
enable_large_pr_handling=true
max_ai_calls=4
async_ai_calls=true

6.2 파일 분류 최적화

파일 분류를 최적화하기 위한 설정:

[pr_description]
enable_semantic_files_types=true
collapsible_file_list='adaptive'
collapsible_file_list_threshold=10

6.3 추가 지침 제공

특정 요구 사항이나 포맷에 맞는 설명을 생성하기 위해 추가 지침을 제공할 수 있습니다:

[pr_description]
extra_instructions = "설명은 변경 사항의 목적, 영향, 그리고 테스트 전략을 포함해야 합니다."

6.4 원본 사용자 설명 유지

자동 생성된 설명에 원본 사용자 설명을 유지하기 위한 설정:

[pr_description]
add_original_user_description=true

7. describe 명령어 사용 시 고려 사항

7.1 장점

  • 시간 절약: PR 설명을 수동으로 작성하는 시간을 줄여줍니다.
  • 일관성: 모든 PR에 대해 일관된 형식의 설명을 제공합니다.
  • 상세함: 변경된 모든 파일에 대한 설명을 자동으로 생성합니다.
  • 유연성: 다양한 설정을 통해 출력을 사용자 지정할 수 있습니다.

7.2 제한 사항

  • 토큰 한계: 매우 큰 PR의 경우 일부 정보가 누락될 수 있습니다.
  • 컨텍스트 이해: AI는 코드베이스의 전체 컨텍스트나 비즈니스 로직을 완전히 이해하지 못할 수 있습니다.
  • 자연어 제한: 특정 언어나 방언에 대한 설명이 부정확할 수 있습니다.

7.3 보안 고려 사항

PR 설명에 민감한 정보가 포함되지 않도록 주의해야 합니다. patch_extension_skip_types 설정을 사용하여 민감한 파일 유형(예: .env, .key)을 제외할 수 있습니다.

profile
Tasker_Jang
ML Engineer 🧠 | AI 모델 개발과 최적화 경험을 기록하며 성장하는 개발자 🚀 The light that burns twice as bright burns half as long ✨
이전 포스트

PR-Agent 기본 설정 및 사용법 분석

다음 포스트

PR-Agent Describe 프롬프트 분석

0개의 댓글