[OSSCA] 2025 체험형-1차 : PR Agent 프로젝트 후기

Judy·2025년 6월 22일

LLM OSSCA agent opensource 오픈소스

[OSSCA] 오픈소스 컨트리뷰션 아카데미

목록 보기

2/3

기여 내용 : #TODO 주석을 자동으로 수집하여 사용자에게 알려주는 기능 추가
최종 기여 PR : https://github.com/qodo-ai/pr-agent/pull/1869

6주간 진행된 오픈소스 컨트리뷰션 프로젝트를 수료했다.

우리 조는 당초 프로젝트 목표대로 6주 안에 PR을 보내지는 못했지만
수료 이후에도 계속해서 개발과 보완, 피드백 반영을 거쳐 최종적으로 PR 및 Merge 완료했다!

지원서 작성 & 합격 후기 : [OSSCA] 2025 체험형-1차 : 합격 후기

프로젝트 소개

1. 프로그램 개요

프로그램 명칭: Git 활용 및 PR Agent
멘토링 주제: 협업 도구(Git) 심화 학습 및 실제 오픈소스 프로젝트(PR Agent) 기여 경험
기간: 2025년 4월 14일 ~ 5월 27일 (총 6주)
멘토링 GitHub 레포 : https://github.com/ossca-2025/pr-agent-mentoring

2. 멘토링 목표

사전 학습 조건

Python 언어에 대한 이해
LLM에 대한 기본지식 이해
Google Gemini API 사용법 이해
Git 활용 능력 심화
- 다양한 Git 명령어 및 고급 기능(브랜치 전략-GitHub Flow, rebase, cherry-pick 등)을 이해하고 능숙하게 활용합니다.
- 팀 프로젝트 환경에서의 PR 기반 코드리뷰 플로우를 이해하고 실천합니다.

오픈소스 생태계 이해 및 기여 경험

PR Agent 프로젝트 (https://github.com/qodo-ai/pr-agent)를 중심으로 오픈소스 프로젝트를 분석하는 능력을 기릅니다.
LLM 기반 AI 코드리뷰를 위한 MVK(Minimum Viable Knowledge)를 습득합니다.
PR Agent 프로젝트의 기여 가이드라인(Contribution Guideline)을 이해하고 준수합니다.
PR Agent 프로젝트에 코드, 문서 등 의미 있는 기여(Contribution)를 최소 1회 이상 경험합니다.

주차별 진행 내역

1주 1회 조별 모임, 1회 정기 모임을 진행했다.
우리 조는 매주 수요일에 조별 모임을 갖고 중간점검과 회의, 보강 및 개인별로 조사 및 작업한 내역을 취합하여
돌아오는 일요일 정기 모임에서 취합한 내용을 발표하고 멘토님께 피드백을 받았다.

1주차 : Kick-Off

팀명/팀 목표/팀 정기 모임 일정 정하기
조별 소개서 작성

2주차 : 자료조사

PR Agent의 구조 및 주요 기능 분석 (공식문서 참고)
AI 코드리뷰 툴 조사 (도구 간 기능, 성능, 사용성 관점 비교)
- gemini / 코드래빗 / git copilot 중 1인당 1개씩 조사
RAG, MCP, A2A 개념 조사

PR‑Agent?
Pull Request(PR)를 효과적으로 리뷰하고 보다 쉽게 관리하는 데 도움을 주는 AI 기반 코드 리뷰 어시스턴트

주요 특징 :

GitHub, GitLab, Bitbucket 등과 연동 가능
다양한 LLM 모델 지원 (GPT, Claude, DeepSeek 등)
오픈소스로 self-hosting 가능
CLI, GitHub App, GitHub Action, Docker 연동 지원

아키텍쳐 :

사용 예시(review) :

python3 -m pr_agent.cli --pr_url <리뷰할 PR URL> review

테스트 URL : https://github.com/Judy-Choi/pr-agent-study/pull/3

3주차 : 개발 환경 설정 & 코드 분석

pr agent 로컬 개발 환경 설정 (gemini API 연동 포함)
- 환경 설정 참고 : 세팅(문서)
IDE 디버그 모드로 pr agent cli(로컬 소스 기반 설치) 실행하고 코드 추적해보기
각 조별로 기본 설정, tool 3가지, 프롬프트 = 총 5개의 주제에 대해 심층적으로 조사

우리 조의 경우 tool 중 improve 툴을 조사, 분석, 사용방법을 조사하여 정리했다.
improve 툴은 아래 캡쳐와 같이 PR에서 변경된 코드를 스캔한 후, AI(LLM) 을 이용해 코드를 개선할 수 있는 제안 (Code Suggestion) 을 생성해 준다.

나의 경우 improve 의 옵션 중 AI가 생성한 코드 개선 제안을 PR에 자동으로 코멘트로 남기는 기능인 Code validation 에 대해 조사하였으며
조사 과정에서 공식문서를 참고하며 디버깅을 통해 코드의 흐름을 파악했다.

테스트 PR : https://github.com/Judy-Choi/pr-agent-study/pull/2

4주차 : 기여 아이디어 제안 & 구현 계획

조별로 Top 3 PR Agent 개선 아이디어 정리 및 발표 (10분 분량)
- 각 아이디어는 What / Why / How / 구현 계획 포함

우선 조별 모임까지 1인당 3개의 아이디어를 냈고, 이 중 Top3 아이디어를 선정했다.

Rule-Based 코드 분석기(Pylint)와 LLM의 하이브리드 리뷰
존재하지 않는 PR URL 호출 시 사용자 친화적인 에러 로그 개선
✅ describe 명령어에 TODO/FIXME 자동 수집 기능 추가 (최종 구현)

선정되지 않은 아이디어도 각자 이슈로 등록하여 Maintainer 에게 피드백을 받았고,
결과적으로 조별 과제 이외에 Maintainer 의 피드백을 받아들여 PR 및 Merge 성공한 멘티들이 많았다!
(너무 부러웠다 🥲)

5주차 : 기여 계획서 작성

기여 계획서 작성
- 2주 내 PR 기여 가능한 아이디어 선정
- 과제 목표, 범위, 참여자 포함

우리 팀의 기여 계획서는 다음과 같고,
https://github.com/ossca-2025/pr-agent-mentoring/blob/main/weekly/week-5/group-5/assignment.md

요약하자면 다음과 같다.

📌 과제 개요
문제 인식
PR 과정에서 코드 내 TODO/FIXME 주석이 PR 설명에 누락되어 리뷰 시 인지 못하고 머지되는 문제가 발생.

목표
PR-Agent 기능 확장 → PR에 포함된 코드의 TODO/FIXME 주석을 자동 감지하여 PR Description에 요약 표시.

📌 구현 기능
1. PR diff 내 TODO/FIXME 주석 자동 탐색.
2. 파일 경로, 라인 번호, 주석 내용을 추출하여 PR Description 하단에 표준 포맷으로 추가.
예시:

## 📌 TODO Summary (Auto-generated)
- [ ] main.py:42 — 리팩토링 필요

사용자 설정 지원 (configuration.toml 내 scan_patterns 설정 가능).
기능 문서화 및 사용 가이드 제공.

📌 기대 효과

리뷰 품질 향상
작업 누락 방지
팀 커뮤니케이션 효율 증대

PR Agent 의 Maintainer 는 다음과 같이 기능을 구현해 주길 요청했다.
https://github.com/qodo-ai/pr-agent/issues/1763

review tool 섹션에 #TODO 주석을 수집하여 보여 주기

6주차 : 구현 & 초기 PR 작성

초기 PR : https://github.com/PullPullers/pr-agent-qodo/pull/1

우리는 먼저 review 툴의 다른 옵션이 어떻게 동작하는지 디버깅을 포함한 코드리뷰를 거쳤고,
다음과 같은 과정을 통해 #TODO 주석이 수집되고 review섹션이 생성되도록 했다.

설정 파일에서 require_todo_scan flag 값 로드 (default = false)
프롬프트를 이용해 다음 작업 수행
2.1. require_todo_scan == true 이면
2.2. PR Diff (변경된 코드) 에서 TODO 주석 정보 추출 (Pydantic 스타일 적용)
```
class TodoSection(BaseModel):
    - relevant_file : TODO 주석이 포함된 파일명
    - line_range : TODO 주석이 포함된 코드 줄 번호
    - content : TODO 주석 내용
```
2.3. 추출한 TodoSection 을 리스트로 만들고, 모든 TODO 주석들의 내용을 요약
review 에 TODO 정보 섹션 추가

2.3 에서 생성된 TODO 정보를 사용자에게 제공하는 섹션 추가
파일 링크 추가 (클릭 시 #TODO 주석의 위치로 바로 이동하도록)
GitHub Flavored Markdown 지원 유/무에 따라 적합한 템플릿 적용

7~8주차 : 멘토님 피드백 반영

구현한 내용에 대해 멘토님의 피드백을 받고 반영했다.

print로 출력되는 메시지 ➡️ 로그 메시지로 변경
타입 힌트 추가
싱글라인 TODO 주석만 지원 ➡️ 멀티라인 TODO 주석도 지원
TODO 주석이 많은 경우 섹션을 접어 가독성 개선

테스트 URL : https://github.com/Judy-Choi/pr-agent-study/pull/10

9주차 : 최종 PR 제출

피드백 반영 및 테스트 후, 최종 PR을 보내기 위해 영문으로 코멘트를 작성하고 취합했다.

이후 제출한 최종 PR 에 대해 Maintainer 가 아주 상세하게 피드백을 해 주었고, 모두 PR 코드에 반영했다.

메뉴얼 문서의 TODO default 값 true → false 로 수정
TODO 섹션 이모지 ✅ → 📝 로 교체
TODO 섹션이 기본적으로 접혀(닫혀) 있도록 수정
- ex : Code suggestion 섹션도 기본적으로 접혀(닫혀) 있듯이, 다른 피드백 섹션과 공존(co-exist) 해야 함
TODO 섹션의 (N entries) 같은 표시 없이 깔끔한 header로 수정
TODO 섹션 UI 수정
TODO 섹션의 field description 추출 프롬프트 수정
TODO 요약 프롬프트를 더 짧게 수정
- "코드에 있는 TODO 주석의 기능 영역을 요약한 최대 6단어" 정도면 됩니다.
- 프롬프트는 담요와 같습니다. 누군가 한쪽에서 당기면 다른 쪽에 남는 양이 줄어듭니다.

성과 ✨

긴 협업과 피드백을 거쳐 최종 Merge 완료되었다!!
https://github.com/qodo-ai/pr-agent/pull/1869

(이 메시지 한 줄을 보기 위해 9주를 달려왔다... 완전 뿌듯 🥹)

Before

TODO scan 기능 추가 전
https://github.com/Judy-Choi/pr-agent-study/pull/3

After

공식문서에 옵션 박제📌

PR 코드에 TODO 주석이 있는 경우
https://github.com/Judy-Choi/pr-agent-study/pull/8

✅ TODO sections 생성
✅ TODO 주석 요약 정보(최대 6단어)를 제공하여 사용자가 빠른 확인 가능

TODO sections 를 펼치면?
✅ 싱글라인 TODO 주석은 텍스트 그대로 보여주지만
✅ 멀티라인 TODO 주석은 텍스트를 <block> 처리하여 깔끔하게 보인다.

이외에 사용자 편의성을 고려하여
✅ 파일 링크를 클릭하면 즉시 TODO 주석의 위치로 이동한다.

TODO 주석이 없는 경우
https://github.com/Judy-Choi/pr-agent-study/pull/7

✅ No TODO sections 표시
TODO sections 가 아예 생성되지 않는 경우, TODO scan 기능이 비활성화되어 있는 경우와 구분할 수 없는 단점을 고려했다.

회고

잘한 점

첫 오픈소스 기여 도전, 대성공!
처음으로 오픈소스에 기여해 보았는데 결과가 매우 만족스럽다.
아이디어 단계부터 Maintainer 가 매우 마음에 들어하며 적극적으로 PR을 열길 원했고,
아이디어를 구현하는 동안 새로운 아이디어와 피드백이 더해져 완성도 높은 기능을 만들 수 있었다.
개인적으로 나는 새로운 시도와 발상을 선호하는 편이라 (tmi : MBTI = ENFP 🤩)
TODO 주석을 수집해서 사용자에게 보여준다는, 우리 조의 간단하지만 개발자들에게 매우 유용한 기능을 추가하는 기여가 정말 마음에 들었고, 기능이 완성된 후 공식문서에 등재된 것을 보니 매우 뿌듯했다.

오픈소스 사용자에서 기여자로
오픈소스를 가져다 쓰기만 했는데, 처음으로 기여하겠다는 목적으로 오픈소스를 리뷰하니 의외로(?) 기여할 수 있는 점이 많았다.
우리 조는 기능을 추가했지만, 다른 조는 문서화, 리팩토링, 테스트 코드 추가 등등을 통해 기여하는 모습을 보고 무궁무진한 기여 방향을 간접적으로 체험할 수 있었다.
앞으로는 오픈소스를 사용할 때 좀 더 능동적인 사용자가 될 것 같다.
아쉬운 기능에 대해 개선 방안을 제안한다던가, 더 나은 코드를 제안한다던가.

코드의 통일성, 사용자의 편의성, 가독성 모두 고려한 개발 경험
신규 기능 추가 및 유지보수 업무를 할 때, 기존 코드와의 통일성을 고려해 개발한 경험은 있지만
지금까지 실제 사용자의 편의성과 가독성까지 고려해 개발한 경험은 드물었다.
(특히 나는 AI와 백엔드 개발을 주로 하다 보니 이 점까지 고려할 일이 없었다.)

이번에는 우리가 만든 기능이 바로 사용자에게 제공되므로, 사용자 입장에서 생각해 보고 편의성, 가독성까지 모두 고려하여 개발했다.
나의 아이디어 중 하나를 예로 들면, 멀티라인 TODO 주석을 보여 줄 때 단순히 주석을 보여주는 것을 넘어 어떻게 보여주면 가독성이 좋을지 한번 더 고민하고, 팀원들의 의견을 모아 반영했다.

이외에도 멘토님과 Maintainer 의 피드백대로 TODO 섹션을 접어서 깔끔한 UI를 구현했고,
제공하는 정보의 양이 줄어드는 대신 한번에 많은 양의 TODO 주석 정보를 파악할 수 있게 주석 내용을 요약해 제공했다.

Maintainer 또한 그래픽과 프롬프트 등을 꼼꼼하게 검토 후 피드백을 건넸고,
그 결과 초안과 비교하여 코드의 완성도도 높아졌고, UI 측면에서는 깔끔해 보이는데다 정보가 한 눈에 들어와서 사용하기에 편리하다! 🤩

팀 프로젝트를 통해 협업하는 자세와 소통 스킬 향상
집단 지성이 모여 더 완성도 높은 코드와 편리하게 사용할 수 있는 개발물이 탄생했다!
아이디어를 모아 반영하는 과정 속에서 협업과 소통 스킬을 다듬을 수 있었고
특히 프로젝트 후반에 멘토님과 Maintainer 에게 많은 양의 피드백을 받았을 때, 작업 내용을 빠르게 리스트업하고, 작업 현황을 실시간으로 공유하여 팀원들 간 작업이 겹치지 않도록 했다.
덕분에 우리 팀은 끝까지 효율적인 협업과 원활한 소통이 가능했다.

Git 커밋 메시지 컨벤션 복습
커밋을 자주 날리는 동안 직관적이고 압축적인 커밋 메시지를 작성할 수 있게 되었고, 이 과정에서 커밋 메시지 컨벤션을 복습했다.
나는 add, remove, update 등등을 사용해 왔는데, 이번 기회에 알고 보니 이것들은 커밋 태그로 적합하지 않았다.
(fix, feat 등이 적절한 태그였다. 😂)
그리고 이번에 처음으로 프롬프트 수정, UI개선 커밋도 작성 같은 커밋도 작성하면서 refactor, style 과 같은 태그도 처음 써 보았다.

문제를 정의하고 해결하는 프로세스 습득
멘토님의 가이드를 따라 처음부터 step by step 으로 오픈소스에 기여하기 위한 과정을 거쳤다.
나는 AI로 커리어를 전환한 이래, 부트캠프 제외하고 이렇게 한 단계씩 멘토님이 이끌어 주는 경험이 처음이었다. 🥲
앞으로는 문제 정의부터 해결 및 개발까지 혼자서도 차근차근 해낼 수 있을 것 같다.

끝까지 해냈다. 완성도 있게!
공식 프로젝트 기간인 6주가 지난 후에도 우리는 끝까지 하던 작업을 지속했고,
결과적으로 우리가 제안한 기능을 완성도 높게 개발하여 성공적으로 오픈소스에 기여할 수 있었다.

특히 나는 어떤 일을 빠르게 시작하는 추진력이 좋지만, 지속적으로 끌고 나가고 마무리하는 힘이 부족하다고 생각해 왔는데
이번에는 반대로 초반에 적극적으로 나서지 못한 만큼 프로젝트 중-후반에 팀에 기여하려고 노력했다.
주어진 피드백들을 반영하고, 최종 PR 내용을 취합하고 내용을 덧붙이고, 일정을 계산해 제안하는 등등.
나는 이번 기회에 나의 한계를 극복했다. 이제 나는 추진력도 강하고 마무리도 잘 하는 사람이다!!!! 😎

물론 다른 팀원분들도 대단했다 🌟
조장님은 매주 조원들을 리딩하는 동시에 밋업 때마다 바쁘게 회의록을 작성하여 문서화로 활동을 뒷받침했고
MVP 팀원분은 어려운 코드도 척척 구현해내며 대부분의 주요 기능들을 개발하셨다!

아쉬운 점

늦은 합류로 인한 도미노 효과
OT및 1주차에는 여행중이라 충분히 안내를 숙지하지 못한 상태에서 뒤늦게 합류했고,
2주차까지 재취업 면접 준비와 극심한 번아웃 때문에 스터디 진도를 따라가지 못했다.
3주차부터 따라잡기 시작했지만 초반에 PR Agent 자료조사를 놓쳤더니 이후에 좋은 기여 아이디어가 생각나지 않았다.
또한 초반에 공식 문서를 읽고 컨트리뷰션 가이드를 숙지해야 했는데, 진도 따라가기에 벅차서 일단 넘어갔더니(...)
이후에 내가 제안한 기능이 사실은 유료버전에 이미 있는 기능이라 퇴짜를 맞기도 했다 😇

시야는 좁은데 의욕이 앞섰다
의욕이 앞서서 개선점은 많이 제시했는데, 그 중 정말 기여할 가치가 있는 개선점은 드물었고 개선 시 기대 효과도 크지 않았다.
또, 내가 아이디어를 낸 개선점들은 나중에 다른 팀원들의 아이디어들과 비교해 보니 너무 지엽적이었던 것 같다.

나는 전 직업이 악성코드 분석가이다 보니 숲보다는 나무를 보는 경향이 있다.
일단 코드를 돌려보고, 파고들어서 버그나 에러를 포착하곤 하지만
돌이켜 생각해 보니 이게 실제로 서비스를 만들거나 품질을 개선하는 데에 중요하지는 않았던 것 같다.
한 가지 경우의 에러 메시지를 가독성 좋게 수정하는 것과, 우리 조의 기여와 같이 사용자에게 유용한 기능을 새로 추가하는 것, 둘 중 어느 쪽이 더 기여할 가치가 있겠는가.

청춘을 돌려다오 😂
이번 오픈소스 컨트리뷰션 프로그램은 '체험형' 인 만큼 대학생 참가자들이 많았다.
아직 학생일 때에 멘토링을 받으며 차근차근 성장해 나가는 모습이 부러웠고
실제로 일부 기능은 유료로 제공중인, 완성형 서비스를 분석하고 코드리뷰하며 실무를 미리 경험하는 모습도 부러웠다.
내가 대학생이었을 때 이런 프로그램이 있었다면 정말 좋았을텐데!
아니면 몇 년 전에라도 이런 프로그램에 참여했다면 내 커리어가 조금은 더 나아졌을텐데. 🥲