1분반-아자스

프로젝트 개요

기술개발 과제

국문 : 바이브 코드 이해를 위한 능동형 리뷰 서비스 [1]

영문 : An active review service for understanding vibe-coded software

과제 팀명

아자스

지도교수

이동희 교수님

개발기간

2026년 3월 ~ 2026년 6월 (총 4개월)

구성원 소개

서울시립대학교 컴퓨터과학부 20199200** 이*권(팀장)

서울시립대학교 컴퓨터과학부 20219200** 유*호

서울시립대학교 컴퓨터과학부 20219200** 조*형

서울시립대학교 컴퓨터과학부 20219200** 이*권

서론

개발 과제의 개요

개발 과제 요약

바이브코딩 시대의 '지식 부채(Knowledge Debt)'를 청산하기 위한 GitHub PR 기반 자동 퀴즈 생성 봇이다.
개발자가 GitHub에 PR을 올리면, 봇이 백그라운드에서 변경된 코드(Diff)를 분석하여 맞춤형 퀴즈를 자동 생성하고, 대시보드를 통해 지식 부채율을 시각화한다.
AI 코딩 도구(GitHub Copilot, Cursor 등)가 생성한 코드를 개발자가 실제로 이해하고 있는지 검증하는 능동적(Push) 학습 시스템이다.
레포지토리 단위의 팀 대시보드를 제공하여, 팀원 간 지식 부채율 비교 및 약점 영역 트래킹이 가능하다.

개발 과제의 배경

AI 코딩 도구의 폭발적 성장으로 개발자의 84%가 AI 도구를 사용하고 있으며, GitHub Copilot 사용자의 코드 중 46%가 AI에 의해 생성되고 있다.
그러나 '코드가 동작하면 넘어간다'는 바이브코딩 습관으로 인해, 개발자 본인이 이해하지 못하는 코드가 코드베이스에 축적되는 '지식 부채' 문제가 심화되고 있다.
기존 AI 코드 리뷰 도구(CodeRabbit, Graphite 등)는 '코드 품질 개선'에만 집중하며, '개발자의 코드 이해도 검증'이라는 영역은 사실상 전무하다.
본 프로젝트를 통해 개발자가 무의식적으로 넘어가려는 지식 공백을 능동적으로 감지하고, 퀴즈를 통해 강제 학습시킴으로써 코드 이해도를 향상시킬 수 있다.
나아가 팀 단위의 지식 부채 트래킹을 통해 온보딩 효율 개선, 코드 리뷰 품질 향상, 기술 부채 조기 발견 등의 효과를 기대할 수 있다.

개발 과제의 목표 및 내용

목표
- GitHub PR 이벤트 기반 자동 퀴즈 생성 파이프라인 구축
- Push된 코드에서 사용된 기술/개념을 감지하고, 해당 공식 문서를 기반으로 한 학습 퀴즈 자동 생성
- 레포지토리 단위의 지식 부채 대시보드 웹 애플리케이션 개발
- 팀원 간 지식 부채율 비교, 약점 영역 시각화, 주간 트렌드 분석 기능 제공
- AWS 서버리스 아키텍처 기반의 확장 가능하고 비용 효율적인 시스템 설계

Event Pipeline 개발
- GitHub App 등록 및 Webhook 수신 엔드포인트 구성 (PR opened, synchronized 이벤트)
- API Gateway를 통한 Webhook 수신 및 HMAC-SHA256 서명 검증
- Amazon SQS를 활용한 이벤트 큐잉 (VisibilityTimeout 1800s, MaxReceiveCount 5)
- Quiz Lambda: GitHub API로 PR Diff 조회 → 함수/블록 단위 청킹 → OpenAI API 호출
- Grader Lambda: 유저 답변 수신 → 정답 비교 → 스코어 계산 → DynamoDB 저장
- Dead Letter Queue(DLQ) 구성 및 CloudWatch 알람을 통한 실패 모니터링

LLM 퀴즈 엔진 개발
- Push된 코드의 Diff를 분석하여 사용된 기술/개념 키워드를 자동 추출
- 추출된 개념을 해당 기술의 공식 문서에 매핑
- 공식 문서의 관련 섹션을 크롤링 또는 사전 인덱싱하여 참조 데이터로 활용
- 상용 LLM을 활용하여 공식 문서 내용 기반의 맞춤형 퀴즈 생성 (객관식, 빈칸 채우기)
- 오답 시 해당 공식 문서의 관련 섹션 링크와 함께 해설 제공
- concept_tag 기반 지식 부채 스코어 계산 알고리즘 설계
- 퀴즈 품질 자동 검증 (JSON Schema 적합성) 및 공식 문서 출처 명시를 통한 **신뢰도 확보

프론트엔드 대시보드 개발
- React + TypeScript + Tailwind CSS 기반 SPA(Single Page Application) 개발
- GitHub OAuth(PKCE 방식) 로그인 및 레포지토리 권한 기반 접근 제어
- 레포지토리 단위 대시보드: 팀 랭킹, 개인 통계, 주간/월간 트렌드 차트
- 퀴즈 풀기 인터페이스: 타입별(객관식/빈칸/서술형) 분기 렌더링
- concept_tag별 약점 영역 히트맵 및 지식 부채율 게이지 시각화
- AWS S3 + CloudFront를 통한 정적 파일 호스팅 및 CDN 배포
- 반응형 레이아웃 지원 (모바일, 태블릿, 데스크톱)

백엔드 API + DB 개발
- DynamoDB 멀티테이블 설계(용도별 8개 테이블) : users/repos/projects/quizzes/answers/, stats/concept_descriptions/readme_summaries. quizzes는 assignee-status / repo-pr 2개 GSI 운용.
- GSI(Global Secondary Index) 구성: 유저 ID 기반 역방향 조회 (참여 레포 목록)
- Dashboard API Lambda: 팀 랭킹, 개인 통계, 트렌드, 퀴즈 목록, 답변 제출 엔드포인트
- API Gateway(HTTP API) 라우팅 및 CORS 설정
- 인증 미들웨어: GitHub OAuth 토큰 검증 → 레포지토리 Collaborator 권한 확인
- OAuth Token Exchange Lambda: SPA에서 전달받은 code를 access_token으로 교환

기능 1: GitHub Webhook 실시간 연동 및 비동기 큐잉 파이프라인
- 정의: PR 생성/수정 이벤트 발생 시 AWS API Gateway를 통해 수신하고, SQS를 통해 LLM 지연에 따른 이벤트 유실 없이 안정적으로 비동기 처리한다.
- 정량목표: Webhook 이벤트 수신 후 초기 응답(Ack) 시간 ≤ 2초, SQS 최대 재시도 5회(maxReceiveCount=5) 도달 시 DLQ 격리
기능 2: RAG 기반 문맥 인식 퀴즈 자동 생성
- 정의: PR Diff 코드 구조 분석(Tree-sitter) 및 프로젝트 컨텍스트(DynamoDB Projects 모듈 설명)를 결합하여, 단순 키워드 매칭을 넘어선 코드 로직 중심의 2종 타입(객관식, 빈칸 채우기) 퀴즈를 생성한다. (서술형은 향후 확장 항목)
- 정량목표: PR 최종 퀴즈 생성 완료 시간 ≤ 30초, 생성된 퀴즈 및 모범 답안의 기술적 오류 발생률 ≤ 5%.
기능 3: GitHub Merge Gatekeeper (Status Check)
- 정의: 사용자의 퀴즈 채점 결과 점수가 프로젝트 설정 기준치 미달일 경우, GitHub Status API를 통해 해당 PR의 Merge 버튼을 강제로 비활성화한다.
- 정량목표: 퀴즈 통과 조건 만족 시 Merge 차단 해제 반영 지연 시간 ≤ 3초, Status Check 연동 성공률 100%.
기능 4: 퍼지 매칭(Fuzzy Matching) 기반 실시간 채점 시스템
- 정의: 고비용의 LLM 호출 대신 문자열 정규화 및 Levenshtein Distance 알고리즘을 활용하여 사용자의 빈칸 답변을 실시간으로 채점한다. (객관식은 선지 일치로 채점)
- 정량목표: 답변 제출 후 채점 결과 반환 시간 ≤ 1초, 다양한 오타 및 표현 허용률(임계치) 85% 이상 확보.
기능 5: Pre-Aggregation(사전 집계) 기반 시각화 대시보드
- 정의: 유저의 Quiz/Answer 데이터를 조회 시점에 집계(on-read)하여 팀 랭킹·트렌드·약점 히트맵을 시각화한다. 데이터 규모 확대 시 DynamoDB Streams 기반 사전집계(Stats 테이블) 도입을 향후 계획으로 둔다.
- 정량목표: 대시보드 통계 데이터 조회 성능 < 1초 유지, SUS(사용성 평가 설문) 평균 점수 ≥ 75점

개념설계안

1. Use Case Diagram

과제의 주요 사용자(개발자, 관리자 등)와 시스템 간의 상호작용 및 요구사항을 정의한 유스케이스 다이어그램입니다.

2. 시스템 아키텍처 (System Architecture)

AWS 인프라(SQS, Lambda, DynamoDB 등)와 LLM, GitHub Webhook 연동을 포함한 전체 서비스의 구조도입니다.

섬네일을 만드는 중 오류 발생: convert: Image width exceeds user limit in IHDR `/var/www/capstone/cdc/images/5/5d/아자스_다이어그램2.png' @ warning/png.c/MagickPNGWarningHandler/1672.
convert: Image height exceeds user limit in IHDR `/var/www/capstone/cdc/images/5/5d/아자스_다이어그램2.png' @ warning/png.c/MagickPNGWarningHandler/1672.
convert: Invalid IHDR data `/var/www/capstone/cdc/images/5/5d/아자스_다이어그램2.png' @ error/png.c/MagickPNGErrorHandler/1646.
convert: corrupt image `/var/www/capstone/cdc/images/5/5d/아자스_다이어그램2.png' @ error/png.c/ReadPNGImage/4095.
convert: no images defined `/tmp/transform_1a7b9e9b4545.png' @ error/convert.c/ConvertImageCommand/3210.

Error code: 1

3. 시퀀스 다이어그램 (Sequence Diagram)

각 주요 기능의 시간 흐름에 따른 컴포넌트 간 상호작용 흐름도입니다.

A. Quiz Generation from Pull Request

GitHub PR 생성 및 변경 사항 발생 시, Webhook을 통해 비동기적으로 RAG 기반 퀴즈를 생성하는 과정입니다.

섬네일을 만드는 중 오류 발생: convert: Image width exceeds user limit in IHDR `/var/www/capstone/cdc/images/7/76/아자스_다이어그램3.png' @ warning/png.c/MagickPNGWarningHandler/1672.
convert: Image height exceeds user limit in IHDR `/var/www/capstone/cdc/images/7/76/아자스_다이어그램3.png' @ warning/png.c/MagickPNGWarningHandler/1672.
convert: Invalid IHDR data `/var/www/capstone/cdc/images/7/76/아자스_다이어그램3.png' @ error/png.c/MagickPNGErrorHandler/1646.
convert: corrupt image `/var/www/capstone/cdc/images/7/76/아자스_다이어그램3.png' @ error/png.c/ReadPNGImage/4095.
convert: no images defined `/tmp/transform_65a62a7e5bb4.png' @ error/convert.c/ConvertImageCommand/3210.

Error code: 1

B. Quiz Solving

사용자가 생성된 퀴즈를 풀고 퍼지 매칭 알고리즘을 통해 실시간으로 채점 및 피드백을 받는 과정입니다.

섬네일을 만드는 중 오류 발생: convert: Image width exceeds user limit in IHDR `/var/www/capstone/cdc/images/7/77/아자스_다이어그램4.png' @ warning/png.c/MagickPNGWarningHandler/1672.
convert: Image height exceeds user limit in IHDR `/var/www/capstone/cdc/images/7/77/아자스_다이어그램4.png' @ warning/png.c/MagickPNGWarningHandler/1672.
convert: Invalid IHDR data `/var/www/capstone/cdc/images/7/77/아자스_다이어그램4.png' @ error/png.c/MagickPNGErrorHandler/1646.
convert: corrupt image `/var/www/capstone/cdc/images/7/77/아자스_다이어그램4.png' @ error/png.c/ReadPNGImage/4095.
convert: no images defined `/tmp/transform_20a224a730cd.png' @ error/convert.c/ConvertImageCommand/3210.

Error code: 1

C. Statistics Pre-Aggregation

DynamoDB의 데이터 변경 건을 감지하여 통계 대시보드 조회 성능(O(1))을 위해 사전에 데이터를 집계하는 과정입니다.

섬네일을 만드는 중 오류 발생: convert: Image width exceeds user limit in IHDR `/var/www/capstone/cdc/images/8/80/아자스_다이어그램5.png' @ warning/png.c/MagickPNGWarningHandler/1672.
convert: Image height exceeds user limit in IHDR `/var/www/capstone/cdc/images/8/80/아자스_다이어그램5.png' @ warning/png.c/MagickPNGWarningHandler/1672.
convert: Invalid IHDR data `/var/www/capstone/cdc/images/8/80/아자스_다이어그램5.png' @ error/png.c/MagickPNGErrorHandler/1646.
convert: corrupt image `/var/www/capstone/cdc/images/8/80/아자스_다이어그램5.png' @ error/png.c/ReadPNGImage/4095.
convert: no images defined `/tmp/transform_6353e752cf3b.png' @ error/convert.c/ConvertImageCommand/3210.

Error code: 1

D. Knowledge Synchronization after PR Merge

PR이 최종 머지된 후 변경된 코드 구조와 지식을 프로젝트 벡터 DB 및 RAG 컨텍스트에 동기화하는 과정입니다.

섬네일을 만드는 중 오류 발생: convert: Image width exceeds user limit in IHDR `/var/www/capstone/cdc/images/9/9d/아자스_다이어그램6.png' @ warning/png.c/MagickPNGWarningHandler/1672.
convert: Image height exceeds user limit in IHDR `/var/www/capstone/cdc/images/9/9d/아자스_다이어그램6.png' @ warning/png.c/MagickPNGWarningHandler/1672.
convert: Invalid IHDR data `/var/www/capstone/cdc/images/9/9d/아자스_다이어그램6.png' @ error/png.c/MagickPNGErrorHandler/1646.
convert: corrupt image `/var/www/capstone/cdc/images/9/9d/아자스_다이어그램6.png' @ error/png.c/ReadPNGImage/4095.
convert: no images defined `/tmp/transform_3f274d162e72.png' @ error/convert.c/ConvertImageCommand/3210.

Error code: 1

E. Initial Setup

서비스 최초 이용 시 사용자의 GitHub 리포지토리를 연동하고 초기 코드베이스 분석을 수행하는 과정입니다.

이론적 계산 및 시뮬레이션

본 프로젝트는 AI 코딩 도구 확산에 따른 지식 부채 문제를 해결하기 위해, 효율적인 인프라 운영 및 정확한 채점 메커니즘을 수학적/알고리즘적 모델을 기반으로 설계하였다.

1. Event-driven Processing (SQS 기반 비동기 처리)

설계 목적: GitHub Webhook의 응답 시간 제한(10초) 문제를 해결하고, 고지연 작업인 LLM 호출을 분리하여 시스템 장애 전파 방지 및 확장성을 확보한다.
계산 구조 (이벤트 처리율 모델):

 이벤트 처리 가용성과 대기 큐의 안정성을 보장하기 위해 다음과 같은 처리율 안정성 조건을 만족하도록 설계하였다.

 λ ≤ μ × N

 - λ (Lambda): PR 이벤트 발생률 (Event Arrival Rate)
 - μ (Mu): Lambda Worker 처리율 (Service Rate per Worker)
 - N: 병렬 Worker 수 (Number of Parallel Workers)

효과: Webhook 요청과 무거운 작업을 분리하여 시스템 안정성을 향상시켰으며, 트래픽 폭증 상황에서도 Worker 수 확장(N 증가)만으로 유연하게 대응할 수 있다.

2. RAG 기반 퀴즈 생성 구조

설계 목적: 단순 코드의 변경 사항(Diff)만으로 문제를 생성할 때 발생하는 문맥 부족 문제를 해결하고, 프로젝트 구조와 연동된 고품질의 의미 기반 문제를 생성한다.
계산 구조:

 LLM에 주입되는 입력 컨텍스트(Input) 구성과 최종 퀴즈 출력(Output) 모델은 다음과 같이 정의된다.

 - LLM Input 구성 (I): Diff + Context_Project + History_Quiz
 - 퀴즈 출력 모델: O = f(I) = Quiz_New

효과: 코드 변경의 맥락과 기존 퀴즈 이력을 모두 반영함으로써 학습 내용의 중복을 최소화하고, 깊이 있는 개념 검증 퀴즈를 생성한다.

3. LLM 호출 최적화 모델

설계 목적: 상용 LLM API 호출에 따른 비용을 최소화하고 불필요한 호출을 제거하여 시스템 운영 비용을 안정화한다.
계산 구조:

 전체 처리 시간 계산 및 최적화 기법 적용 시의 비용 기댓값 모델은 다음과 같다.

 - 전체 처리 시간: T_total = T_parsing + T_LLM
 - 최적화 적용 시 비용 기댓값: E(Cost) = α × C_LLM

 (※ α: 의미 있는 변경이 포함된 PR의 비율 (0 ≤ α ≤ 1), C_LLM: 1회당 기본 LLM 호출 비용)

효과: 정적 파싱을 통해 불필요한 호출을 사전 필터링함으로써 평균 처리 시간을 줄이고, 시스템 운영 비용을 크게 절감한다.

4. 통계 집계 구조 (현재 on-read / 향후 사전집계)

설계 목적: 데이터 규모가 확대됨에 따라 발생할 수 있는 데이터베이스(DynamoDB)의 실시간 집계 연산 성능 한계를 극복하고 대시보드의 실시간 조회 성능을 확보한다.
계산 구조 (시간 복잡도 분석):

 현재 시스템 구조와 향후 개선할 사전 집계 인프라의 복잡도는 다음과 같이 전개된다.

 - 기존 조회 시점 방식 (on-read 집계 복잡도): O(N)  (N은 조회 대상 데이터 수)
 - 향후 개선 방식 (Pre-aggregation 사전집계 복잡도): O(1)  (조회 시점 연산 불필요)

효과: 데이터 양이 무한히 증가하더라도 대시보드 통계 조회 시간을 일정하게 유지(1초 미만)하여 사용자 경험을 극대화한다.

5. 퍼지 매칭 기반 채점 시스템

설계 목적: 고비용의 LLM 호출 없이 빈칸 채우기 등의 정답 채점을 수행하며, 사용자의 오타나 다양한 표현 방식을 허용하는 실시간 채점 시스템을 구현한다.
계산 구조:

 문자열 정규화 및 레벤슈타인 거리(Levenshtein Distance, 편집 거리) 알고리즘을 결합한 채점 메커니즘을 적용한다.

 - 유사도 점수 산출 공식:
   Score = (1 - Levenshtein(S1, S2) / max(|S1|, |S2|)) × 100

 - 전체 알고리즘 시간 복잡도: O(K × M × N)
 (※ K: 허용 정답의 개수, M 및 N: 비교할 두 문자열의 각각의 길이)

효과: 밀리초(ms) 단위의 즉각적인 채점 피드백을 제공하여 서버 리소스 및 LLM 비용을 원천 차단하고 다양한 사용자 입력 오차에 유연하게 대응한다.

상세설계안

1. 전체 아키텍처 요소 정리

시스템 설계의 핵심 인프라 및 핵심 알고리즘 요소에 대한 설계 목적과 모델 효과, 그리고 시스템 내에서의 유용성을 정리한 명세입니다.

구성요소	설계목적	모델 효과	시스템에서의 유용성
Event-driven Processing (SQS)	Webhook 지연 방지 및 비동기 처리	처리율 증가, 안정성 확보	이벤트 폭주시에도 안정적으로 처리
RAG 기반 퀴즈 생성	코드 문맥 반영한 문제 생성	입력 정보 확장으로 정확도 향상	코드 이해도 기반 퀴즈 생성 가능
LLM 호출 최적화	비용 및 지연 최소화	호출 평균 횟수 감소, 시간 감소	운영 비용 절감 및 응답 안정성 확보
Pre-Aggregation 통계	실시간 집계 비용 제거	조회 복잡도 O(1) 개선	빠른 통계 조회 및 UX 확보
퍼지 매칭 채점	LLM 없이 채점 수행	낮은 연산으로 실시간 처리	즉각 피드백 및 다양한 답변 허용

2. 액티비티 다이어그램 (Activity Diagram)

각 비즈니스 프로세스 및 이벤트 흐름에 따른 시스템의 세부 동작 액티비티 플로우입니다.

[초기 설치 프로세스]

GitHub App 설치 이벤트 수신 시 Webhook이 발생합니다.
이벤트를 Amazon SQS로 안전하게 전달한 후 백그라운드에서 비동기 처리합니다.
Tree-sitter를 기반으로 코드 구조를 분석하고 LLM을 활용하여 모듈 설명을 생성합니다.
생성된 데이터를 Projects 테이블 및 Vector DB에 안전하게 인덱싱 및 저장합니다.

[PR 생성 및 퀴즈 생성 프로세스]

개발자가 Pull Request(PR)를 생성하면 Webhook이 발생하여 SQS로 즉시 큐잉됩니다.
변경된 소스 코드의 Diff를 파싱하여 정적 분석 후 의미 있는 변경인지 필터링 및 판단합니다.
의미 있는 변경 조건 충족 시, 변경 코드(Diff) + 컨텍스트 + 기존 퀴즈 이력을 결합한 입력을 기반으로 LLM이 맞춤형 퀴즈를 생성합니다.
완성된 퀴즈를 DynamoDB(Quizzes)에 저장하고 GitHub PR 인라인 코멘트로 알림을 전달합니다.

[퀴즈 풀이 및 채점 프로세스]

사용자는 대시보드에 로그인하여 자신에게 할당된 미해결 퀴즈 내역을 조회합니다.
답변 제출 시 문자열 정규화 및 레벤슈타인 거리 기반의 퍼지 매칭으로 즉각적인 실시간 채점을 수행합니다.
채점 완료된 결과를 Answers 테이블에 안전하게 저장하고 상태 정보를 업데이트합니다.
최종 성공/실패 및 오답 해설 결과를 사용자에게 실시간으로 즉시 반환합니다.

[통계 사전집계 처리 프로세스]

Answers 데이터에 변경이 감지되면 DynamoDB Streams 이벤트가 트리거됩니다.
연결된 Lambda 함수가 해당 이벤트를 수신하여 Stats 테이블에 통계 수치를 미리 누적 및 사전 집계(Pre-aggregation)합니다.
사용자가 대시보드 접근 시 연산 지연 없이 즉각적으로 시각화 차트를 반환합니다.

[PR Merge 후 지식 동기화 프로세스]

PR이 최종 승인되어 머지(Merge)되면 Webhook이 SQS에 메시지를 전달합니다.
코드베이스에 실질적인 구조 변경 사항이 발생했는지 여부를 판단합니다.
구조 변경 확인 시, LLM을 활용하여 전체 프로젝트의 모듈 아키텍처 설명을 갱신합니다.
최신화된 요약 정보 및 임베딩을 Projects 테이블 및 Vector DB에 최종 업데이트 및 동기화합니다.

3. 상태 다이어그램 (State Diagram)

RAG 기반 학습 퀴즈 엔티티가 발급되어 풀이 완료 및 보관에 이르기까지 거치는 전체 생명 주기(Lifecycle) 모델입니다.

[생성중] : GitHub PR 이벤트를 감지하여 수신한 직후, 백그라운드 Lambda에서 LLM을 통해 맞춤형 퀴즈를 구성 중인 상태입니다.
[생성실패] : LLM 타임아웃, 예외 처리 또는 템플릿 적합성 오류 등의 원인으로 인해 정상적인 퀴즈 빌드가 불가능해진 실패 상태입니다.
[생성완료] : 퀴즈 내용, 선지 및 정해진 정답 스키마가 완벽히 구성되어 형식을 만족한 안정적인 상태입니다.
[할당됨] : 생성 완료된 퀴즈에 대상 작업자(Assignee)를 지정하여 데이터베이스 저장을 완료한 상태입니다.
[미해결] : 사용자의 대시보드 웹 또는 GitHub PR 코멘트에 퀴즈가 전면 노출되었으나, 아직 최종 답안 수신이 완료되지 않은 대기 상태입니다.
[제출됨] : 사용자가 각 퀴즈 문항 유형에 맞는 답변을 입력창에 작성한 후 최종 제출 처리를 완료한 상태입니다.
[채점완료] : 제출된 원본 답안에 대해 문자열 가공, 정규화 과정 및 퍼지 알고리즘 거리 연산을 실시간으로 매칭 완료한 상태입니다.
[해결됨] : 합격 기준 수치를 만족하여 채점 결과 및 스코어가 Answers 테이블에 최종 영속화되고 완료 마크가 부여된 상태입니다.
[만료됨] : 퀴즈를 해결하기 전 타겟 PR이 강제 종료되거나, 지속적인 코드 수정으로 구조가 변경되어 기존 수식 퀴즈의 유효성이 유실된 제외 상태입니다.
[통계반영됨] : 해결됨 마크를 감지한 DynamoDB Streams 파이프라인에 의해 주간/월간 랭킹 및 개념별 약점 히트맵 통계에 합산 완료된 상태입니다.
[보관됨] : PR이 성공적으로 병합되거나 전체 활성 흐름이 완결되어 실시간 추적 레이어에서 제외하고, 단순 이력 관리 및 조회용 데이터로 전환 관리되는 상태입니다.

4. 패키지 다이어그램 (Package Diagram)

능동형 코드 리뷰 시스템 아키텍처의 각 레이어(Layer)별 결합도를 낮추고 모듈 독립성을 보장하기 위한 패키지 구조 구조도입니다.

1. Presentation Layer (표현 계층)

 - 사용자 측 접점을 담당하는 진입점 영역입니다. 
 - React 대시보드 인터페이스 영역과 백엔드 RESTful API Controller(퀴즈 조회, 통계 조회, OAuth 로그인 처리, Webhook Endpoint 수신) 패키지들을 하위에 포함하여 외부에 인터페이스를 노출합니다.

2. Application Layer (응용 비즈니스 계층)

 - 서비스 도메인의 핵심 비즈니스 로직 및 정책 제어를 일괄 관리하는 계층입니다.
 - 사용자 권한 검증 및 세션 관리 패키지, 비동기 이벤트 핸들링 패키지, 퀴즈 출제 및 채점 엔진 모듈, 통계 pre-aggregation 집계 로직 패키지, 머지 후 지식베이스 아키텍처 동기화 패키지가 철저히 분리 독립되어 설계되어 있습니다.

3. AI / Context Layer (AI 및 컨텍스트 추론 계층)

 - 퀴즈 생성을 고도화하고 구조 분석을 수행하는 상위 RAG 모델링 패키지 영역입니다.
 - 상용 오픈 AI 기반 LLM API와의 직렬화 연동 인터페이스 패키지 및 코드 청크와 문맥 정보 조회를 최적화하는 프로젝트 벡터 검색 임베딩 엔진 패키지를 전담 관리합니다.

4. Infrastructure Layer (인프라스트럭처 연동 계층)

 - 외부 프레임워크 및 클라우드 관리 자원들과의 실제 입출력(I/O) 결합을 구현하는 최하위 레이어 영역입니다.
 - GitHub App 연동 API 클라이언트 모듈, 대용량 트래픽 제어를 보장하기 위한 Amazon SQS 메시지 큐 인터페이스 모듈, 영속성 컨텍스트 관리를 위한 용도별 DynamoDB 멀티테이블 리포지토리 모듈 패키지들이 배치되어 공통 비즈니스를 지원합니다.

결과 및 평가

완료 작품의 소개

프로토타입 사진

본 팀이 개발한 능동형 AI 리뷰 서비스 'No-debt'의 웹 프로토타입 구동 화면 및 주요 기능별 인터페이스는 다음과 같습니다.

서비스 웹 주소: www.no-dept.com

A. 메인 인터페이스 및 대시보드

웹 로그인 화면: GitHub 계정 및 OAuth 인증을 통해 시스템에 안전하게 진입하는 첫 화면입니다.

리포지토리 선택 화면 (레포 요약 기능): 지식 부채를 추적할 대상 레포지토리를 선택하는 화면으로, AI가 해당 프로젝트의 전반적인 아키텍처와 코드를 요약해 주는 기능이 포함되어 있습니다.

통합 대시보드 화면: 현재 팀 및 개인의 지식 부채율 수치, 랭킹 시스템, 주간/월간 학습 성취도 트렌드를 시각적으로 한눈에 트래킹할 수 있는 메인 대시보드입니다.

B. Pull Request(PR) 연동 및 퀴즈 생성 흐름

퀴즈 미생성 대상 PR 발생 시 (GitHub): 단순 오타나 코드 포맷터 변경 등 의미론적 변화가 없는 단순 PR일 경우, 시스템이 이를 정적으로 자동 필터링하여 별도의 퀴즈를 생성하지 않고 통과시킵니다.

퀴즈 생성 대상 PR 발생 시 (GitHub → 웹 페이지 이동): 비즈니스 로직 수정 등 의미 있는 소스 코드 변경이 감지되면 GitHub PR 창에 안내 봇 코멘트 및 대시보드 링크가 자동으로 생성되며, 퀴즈 풀이를 위해 대시보드 웹 환경으로 연동됩니다.

C. 퀴즈 및 평가 레이아웃

미진행 퀴즈 목록: 현재 유저에게 할당되었으나 아직 해결하지 않아 지식 부채로 누적되어 있는 활성 퀴즈 리스트입니다.

진행 후 퀴즈 목록 (첫 번째 문제 진행 예시): 유저가 퀴즈를 하나씩 풀어나감에 따라 실시간으로 상태가 동기화되는 퀴즈 진행 관리 대시보드입니다.

퀴즈 상세 인터페이스 (선택 시): 특정 문항을 선택했을 때 나타나는 화면으로, 코드 Diff 문맥과 연동된 문제를 확인하고 정답을 입력할 수 있는 화면입니다.

퀴즈 오답 발생 시 화면: 퍼지 매칭 엔진이 오답으로 판정할 경우, 상용 LLM의 자체 판단(환각)을 배제하고 철저히 사전 크롤링된 해당 스택의 '공식 도큐먼트(Official Documentation)' 원본 섹션 링크 및 신뢰성 있는 기술 해설을 함께 제공합니다.

퀴즈 정답 통과 시 화면: 퍼지 알고리즘 매칭 임베딩을 통과하여 정답 처리가 완료되었을 때의 화면이며, 즉시 해당 점수가 반영되어 지식 부채 스코어가 차감됩니다.

D. 기록 조회 및 세부 설정

풀었던 퀴즈 조회 및 이력 관리: 자신이 기존에 해결했던 복습용 이력 데이터들을 일목요연하게 조회할 수 있으며, 팀 단위 공유 생태계를 통해 다른 팀원의 문제 해결 이력 또한 상호 교차 조회 및 학습이 가능합니다.

약점 분석 화면 (지식 부채 히트맵): 오답이 발생하거나 취약한 개념 키워드들을 `concept_tag` 기반으로 통계화하여, 유저가 어떤 아키텍처나 라이브러리 개념에서 지식 누수가 발생하는지 시각적 히트맵 그래프로 추적해 주는 화면입니다.

설정 화면: 개발 환경의 편의성을 위한 다크 모드/라이트 모드 테마 전환, 개인정보 보호 옵션, 프로젝트 시급성에 따른 봇의 개입 수준(Merge 차단 강도 등) 및 레포지토리 권한 정책을 커스텀 설정하는 화면입니다.

실행 방법

본 플랫폼은 GitHub 개발 워크플로우에 완벽히 통합되어 동작하며, 전체적인 서비스 실행 및 테스트 시나리오 순서는 다음과 같습니다.

1단계: 로그인 및 리포지토리 선택

사용자는 서비스 메인 화면에서 GitHub OAuth 인증을 통해 안전하게 로그인한 후, 지식 부채를 관리하고 퀴즈를 연동할 대상 레포지토리(Repository)를 목록에서 선택합니다.

2단계: PR 생성 및 퀴즈 자동 출제

개발자가 GitHub에 새로운 Pull Request(PR)를 등록하면, 시스템이 변경 코드(Diff)를 비동기로 즉각 분석합니다. 분석이 진행되는 동안 GitHub PR 페이지에는 Status Check가 작동하며, 동시에 대시보드에는 해당 Diff 문맥에 맞는 새로운 개념 검증 퀴즈가 자동 생성됩니다. 이때 설정된 퀴즈를 해결하기 전까지는 GitHub 상에서 Merge 버튼이 강제로 차단됩니다.

3단계: 대시보드를 통한 퀴즈 풀이 및 채점

개발자는 연동된 대시보드 웹페이지로 이동하여 출제된 문항(객관식 및 빈칸 채우기 형식)을 확인하고 풀이를 진행합니다. 답안 제출 시 시스템 내부의 퍼지 매칭 알고리즘이 가동되어 오타나 다양한 표현 방식을 감안한 실시간 채점 및 상세 해설을 즉각 제공합니다.

4단계: Merge Gatekeeper 차단 해제 및 최종 머지

출제된 모든 퀴즈를 기준 성적 이상으로 올바르게 해결하면, 시스템은 GitHub Status API를 통해 "All quizzes resolved" 성공 사인을 전송합니다. 실패(Failed) 상태였던 GitHub PR 페이지의 차단 락이 실시간으로 해제되며, 비로소 안전하게 메인 코드베이스로의 Merge가 가능해집니다.

5단계: 대시보드 통계 및 지식 부채율 확인

모든 프로세스가 완료된 후 개발자는 개인 및 팀 통합 대시보드를 통해 실시간 사전 집계(Pre-aggregation) 모델로 반영된 통계 지표를 확인합니다. 주간/월간 트렌드 차트와 지식 부채율 게이지, 그리고 concept_tag별 약점 분석 히트맵을 통해 자신이 보완해야 할 기술 영역을 직관적으로 추적할 수 있습니다.

완료작품의 평가

어려웠던 내용들

GitHub Webhook 타임아웃 제한 조건 극복
- GitHub Webhook은 요청 후 10초 이내에 응답하지 않으면 타임아웃 오류를 발생시킴. 그러나 상용 LLM(OpenAI)을 통해 PR Diff를 분석하고 고품질의 퀴즈를 생성하는 작업은 평균 15~25초가 소요되어 타임아웃 문제를 필연적으로 야기함.
- 이를 해결하기 위해 API Gateway 후단에 Amazon SQS를 전면 배치하여 Webhook 수신 즉시 Ack(200 OK)를 먼저 반환하고, 실제 퀴즈 생성 로직은 Lambda Worker를 통해 비동기로 처리하는 Event-Driven 아키텍처를 설계하여 안정성을 확보함.
LLM의 환각(Hallucination) 방지 및 공식 문서 매핑 기술 구현
- LLM이 자체 지식만으로 퀴즈를 생성할 경우, 최신 기술 스택의 변경 사항을 반영하지 못하거나 거짓 정보를 정답으로 제시하는 환각 현상이 발생함.
- 이를 방지하기 위해 Tree-sitter 파서를 도입하여 소스 코드에서 구조적 키워드(API, 라이브러리)를 파싱하고, 미리 크롤링 및 인덱싱된 공식 문서의 특정 섹션을 RAG(검색 증강 생성) 형태로 LLM Context에 주입하는 파이프라인을 구축하여 퀴즈의 신뢰도를 확보함.
DynamoDB Single-Table 설계의 복잡성
- 서버리스 환경에 맞춰 용도별 멀티테이블 + GSI 설계를 채택했으며, 팀 랭킹·트렌드 등 다양한 접근 패턴을 GSI(assignee-status, repo-pr, user-quiz 등) 설계로 지원하는 과정에서 정밀함이 요구됨. DynamoDB Streams를 연동한 사전 집계 구조를 도입하여 해결함.

평가결과표

평가 항목	평가 방법	적용 기준	개발 목표치	비중 (%)	평가 결과
1. 웹훅 수신 파이프라인	PR 이벤트 수신 후 초기 HTTP 응답 속도 측정	AWS CloudWatch Logs 인프라 타임스탬프 분석	≤ 2.0초	18%	평균 0.45초 (최대 1.1초)
2. 퀴즈 자동생성 엔진	Diff 파싱 후 LLM 기반 최종 퀴즈 렌더링 시간 측정	소스 코드 분량이 다른 50개 PR 대상 표본 조사	≤ 30.0초	23%	평균 18.3초 (최대 24.5초)
3. Merge Gatekeeper	퀴즈 합격 후 GitHub PR 병합 제한 해제 지연 시간 측정	GitHub Status API 동기화 속도 모니터링	≤ 3.0초	23%	평균 1.2초 (최대 1.8초)
4. 퍼지 채점 알고리즘	사용자 답변 제출 후 실시간 채점 응답 지연 측정	문자열 정규화 및 레벤슈타인 거리 연산 속도 산출	≤ 1.0초	18%	평균 0.15초 (최대 0.3초)
5. 시각화 대시보드	팀 지식 부채 대시보드의 UI/UX 편의성 점수 산출	피실험자군(개발자 20인) 대상 SUS 설문조사 진행	≥ 75점	18%	SUS 점수 82점 획득

SUS (System Usability Scale): 사용자가 시스템을 얼마나 쓰기 편하다고 느끼는지 10개의 질문을 통해 0~100점의 점수로 수치화하는 표준 사용성 평가 설문조사입니다.

향후계획

다중 계층 시맨틱 캐싱(Semantic Caching) 시스템 구축
- 동일 레포지토리 내에서 단순 오타 수정, 포매팅 변경, 혹은 팀원 간 유사한 패키지 도입 등 중복되거나 유사한 코드 변경 사항이 발생할 경우, 매번 고비용의 LLM API를 호출하는 것은 자원 낭비임.
- 차후 Redis 및 Vector DB를 연동한 시맨틱 캐싱 레이어를 구현하여, 임베딩 유사도가 일정 기준치(예: 95%) 이상인 코드 변경에 대해서는 기존에 생성된 퀴즈를 즉각 재사용함으로써 비용 효율성과 시스템 응답 속도를 극대화할 예정임.
사용자 지식 감쇠(망각 곡선) 알고리즘 반영
- 현재 시스템은 퀴즈를 맞힌 시점에만 지식 부채 점수를 차감하는 단발성 구조임. 그러나 인간의 망각 특성을 고려하여, 과거에 통과했던 개념이라도 시간이 지남에 따라 점진적으로 지식 부채 점수가 다시 누적되도록 에빙하우스 망각 곡선 모델 기반의 동적 부채 스코어링 알고리즘을 백엔드에 추가 구현하고자 함.
다중 언어 파싱 확장 및 IDE 플러그인(Extension) 개발
- 현재 주 타겟인 JavaScript/TypeScript 생태계를 넘어 Python, Go, Rust 등 다양한 백엔드/시스템 언어로 Tree-sitter 컴파일러 기반 개념 추출 모듈을 확장할 계획임.
- 나아가 GitHub PR 환경뿐만 아니라 개발자가 코드를 작성하는 실시간 시점(IDE 내부)에서도 지식 부채를 체크할 수 있도록 VS Code / Cursor Extension 형태로 클라이언트 생태계를 확장하고자 함.

항목 (품명, 규격)	수량	단가	금액 (현금/천원)
Claude Code 구독	1	166.4	166.4
OpenAI API	1	17.2	17.2
Figma 구독	1	33.6	33.6
회의비	1	120.0	120.0
합 계	4	-	337.2