MseeP.ai Security Assessment Badge
Reviewflow
CI
License: MIT
Node.js
TypeScript
Documentation
Claude Code를 활용한 자동화된 AI 코드 리뷰 기능을 제공합니다. 머지 요청(merge request) 시 검토자를 지정하면, Claude가 코드를 검토하고 진행 상황을 실시간으로 추적하며, 수정 사항이 푸시될 때까지 후속 조치를 취합니다.
GitLab 및 GitHub와 별도의 설정 없이 바로 작동합니다.
작동 방식 (How It Works)
Developer pushes code
│
▼
...
주요 기능 (Key Features)
다중 에이전트 리뷰 (Multi-Agent Reviews)
각 검토는 설정 가능한 전문 감사 에이전트 세트를 실행합니다. 여기에는 Clean Architecture, SOLID, Testing, DDD, Code Quality 등이 포함됩니다. 팀의 표준에 맞게 프로젝트별로 자체 에이전트를 정의할 수 있습니다.
{
"agents": [
{ "name": "clean-architecture", "displayName": "Clean Archi" },
...
MCP 통합 (MCP Integration)
내장된 Model Context Protocol 서버는 Claude에게 진행 상황 보고, 리뷰 단계 관리, 토론 스레드에서 작업 예약 등 구조화된 도구를 제공합니다. 이는 취약한 텍스트 마커 파싱을 타입이 지정된 도구 호출로 대체합니다.
| MCP 도구 | 목적 |
|---|
get_workflow | 현재 리뷰 상태 및 에이전트 목록 읽기 |
| ... | |
스마트 큐 (Smart Queue)
p-queue를 기반으로 하며 다음 기능을 제공합니다:
- 동시성 제어 (Concurrency control) — 병렬 리뷰 제한 (기본값: 2)
- 중복 제거 (Deduplication) — 설정 가능한 시간 창 내에서 중복 검토 방지
- 우아한 취소 (Graceful cancellation) — 대시보드 또는 API를 통해 실행 중인 리뷰 중단
- 메모리 가드 (Memory guard) — RSS가 4 GB를 초과하면 자동 종료
- 실패 시 재시도 (Retry on failure) — 실패한 작업은 중복 제거 상태를 초기화하여 즉시 재트리거 가능
실시간 대시보드 (Real-Time Dashboard)
WebSocket 기반의 대시보드를 통해 라이브 리뷰 진행 상황을 보여줍니다:
- 단계 및 에이전트 레벨 진행률 표시줄
- 실행 중/대기 중/완료된 리뷰 횟수
- 소요 시간, 점수, 오류 세부 정보가 포함된 리뷰 기록
- 개발자 카드, 인사이트 및 AI 분석이 있는 팀 탭
- 캔버스 차트, 점수 추세, 애니메이션 카운터가 포함된 통계 섹션
- 디버깅을 위한 로그 스트림
- 지수 백오프(exponential backoff)를 사용한 자동 재연결 기능
개발자 및 팀 인사이트 (Developer & Team Insights)
대시보드는 리뷰 기록을 기반으로 성능 인사이트를 계산하며, 별도의 설정이 필요하지 않습니다.
개발자별 분석(Per-developer analysis): 4가지 카테고리에서 분석합니다:
| 카테고리 | 측정 항목 |
|---|
| 품질 (Quality) | 평균 점수, 블로킹 이슈 비율 |
| ... | |
각 개발자는 레벨(초급자(beginner) → 전문가(expert)), 추세(개선 중/안정적/감소), 식별된 강점 및 약점, 그리고 가장 강한 카테고리(아키텍트(Architect), 파이어파이터(Firefighter), 워크호스(Workhorse), 센티넬(Sentinel) 또는 균형 잡힌(Balanced))를 기반으로 한 직함을 받습니다.
팀 레벨 분석(Team-level analysis): 최고 성과자, 가장 많이 개선된 개발자, 그리고 실행 가능한 팁을 보여줍니다.
AI 기반 서술 (AI-powered narrative) (선택 사항): "AI 인사이트 생성(Generate AI Insights)"을 클릭하여 Claude가 개발자별 및 팀 추천이 포함된 서면 분석을 생성하도록 할 수 있습니다.
인사이트는 첫 5개 리뷰부터 계산되며 세션 전반에 걸쳐 유지됩니다.
후속 리뷰 (Follow-Up Reviews)
개발자가 리뷰 이후 수정 사항을 푸시하면, Claude가 자동으로 다음 작업을 수행합니다:
- 토론 스레드를 다시 읽습니다.
- 블로킹 이슈가 해결되었는지 확인합니다.
- GitLab/GitHub에서 스레드를 해결합니다.
- 업데이트된 점수와 함께 후속 요약을 게시합니다.
이는 일회성 점검이 아닌, 반복적인 리뷰 루프를 생성합니다.
| 기능 | GitLab | GitHub |
|---|
| 웹훅 트리거 | 리뷰어 할당 시 | 리뷰 요청 또는 needs-review 레이블 적용 시 |
| ... | | |
API 토큰이 필요하지 않습니다. 두 플랫폼 모두 안전한 CLI 기반의 OAuth를 사용합니다.
사용자 정의 가능한 리뷰 스킬 (Customizable Review Skills)
리뷰 동작은 Claude Code skills에 의해 정의됩니다. 이는 프로젝트 내의 마크다운 파일로, Claude에게 무엇을 감사(audit)하고 어떻게 할지 알려줍니다. 영어와 프랑스어로 프론트엔드, 백엔드, API 리뷰를 위한 템플릿이 포함되어 있습니다.
내부 작동 방식 (Under the Hood)
기여자 및 호기심 많은 운영자를 위해 — 웹훅과 게시된 리뷰 사이에 실제로 무슨 일이 일어나는가?
포그라운드 스폰 대신 백그라운드 세션 사용(Background sessions, not foreground spawn)
이전 버전의 Reviewflow는 claude -p를 호출하고 포그라운드에서 JSON을 스트리밍했습니다. 이제 서버는 각 리뷰를 claude --bg를 사용하여 분리된(detached) 백그라운드 세션으로 전송합니다. Fastify 프로세스는 즉시 세션 ID를 반환하고 비동기적으로 완료를 관찰합니다.
완료는 최초 승리(first-wins) 의미론을 가진 세 가지 독립적인 신호를 통해 감지됩니다:
- MCP
set_phase('completed') — 리뷰가 완료되면 Claude의 스킬이 MCP 서버를 호출합니다.
claude agents --json 폴링(polling) — 30초마다 completed / failed / stopped 상태를 확인합니다.- 15분 하드 타임아웃(hard timeout) — 다른 두 신호가 놓칠 경우의 안전장치입니다.
가장 먼저 발생하는 신호가 승리하며, 나머지 두 신호는 취소됩니다. 이후 리뷰 보고서는 <worktree>/.claude/reviews/report-<mrNumber>.md에서 읽히고 세션은 claude stop + claude rm으로 정리됩니다.
격리된 git 워크트리(Isolated git worktrees)
각 MR은 ~/.reviewflow/worktrees/<platform>-<slug>-<mrNumber>에 자체적으로 구축된 git 워크트리에서 실행됩니다. 이는 다음을 수행합니다:
- 동시 리뷰 격리: 서로의 인덱스에 영향을 주지 않도록 합니다.
- 메인 체크아웃 보존: Claude 내부의
git checkout이 작업 브랜치를 오염시키는 것을 방지합니다.
- 후속 조치 속도 향상: 워크트리가 처음부터 다시 생성되지 않고, 가져오기(fetched) 및 새 HEAD로 리셋됩니다.
- 자동 정리: 병합/닫힐 때
removeWorktree가 실행되며, 또한 24시간 이상 닫혔거나 mtime이 7일을 초과한 MR의 워크트리를 일일 스윕(daily sweep)을 통해 회수합니다.
전체 상태 기계: Worktree Lifecycle.
슈퍼바이저 상태 (Supervisor health)
Claude agents supervisor(백그라운드 세션을 호스팅하는 장기 실행 데몬)는 60초마다 프로빙됩니다. 만약 이 프로세스가 죽으면, 분리된 스폰(detached spawn)이 ~/.reviewflow/supervisor.lock에 PID 검증 파일 잠금(file lock)을 걸어 다시 시작합니다. /health 엔드포인트는 실시간 상태를 표시하며, 슈퍼바이저가 다운되면 status: degraded를 보고합니다. 이 경우 Reviewflow는 계속 부팅되지만, 리뷰는 빠르게 실패하게 됩니다 (fail fast).
토큰 예산 제한(Token budget cap)
모든 세션의 토큰 사용량은 Claude 트랜스크립트에서 파싱되어 영구 저장됩니다(persisted). 구성 가능한 월별 예산이 추가적인 디스패치(dispatch)를 제한하며, 세션이 완료될 때마다 WebSocket을 통해 예산 패널 업데이트를 브로드캐스트합니다. 시간별 청구 감사(billing audit)는 claude /usage를 호출하고 예상치 못한 API 풀 사용량을 감지하면 디스패치를 일시 중단합니다 (활성화되어야 할 유일한 청구 경로는 OAuth 구독입니다).
빠른 시작(Quick Start)
1. 설치(Install)
npm install -g reviewflow
2. 초기화(Initialize)
대화형 마법사(interactive wizard)는 다음을 수행합니다:
- 서버 포트 및 사용자 이름 구성
- 웹훅 시크릿 생성
- Git 리포지토리를 위해 파일 시스템 스캔
- Claude Code와 MCP 서버 통합 설정
비대화형 설정의 경우: reviewflow init --yes
3. 시작(Start)
그런 다음 GitLab/GitHub 프로젝트에서 서버를 가리키는 웹훅을 구성하세요.
설정 검증(Validate your setup)
자세한 설정은 **빠른 시작 가이드**를 참조하세요.
CLI 레퍼런스(CLI Reference)
| 명령어 | 설명 |
|---|
reviewflow init | 대화형 설정 마법사 |
| ... | |
| Init 플래그 | 설명 |
| ----------- | ------------- |
-y, --yes | 모든 기본값 수락 (비대화형) |
| ... | |
문서(Documentation)
API
| 엔드포인트 | 메서드 | 설명 |
|---|
/dashboard/ | GET | 웹 대시보드 |
| ... | | |
개발 (Development)
npm run dev
npm test
npm run test:ci
...
가이드라인은 CONTRIBUTING.md를 참조하세요.
라이선스 (License)
MIT — Damien Gouron
