프로젝트 컨텍스트 없이 AI 코드 리뷰가 실패하는 이유
Source: Dev.to
모든 AI 코드 리뷰는 같은 방식으로 시작됩니다.
봇은 당신의 PR을 열고, diff를 스캔한 뒤, 누락된 try/catch를 표시하고, 더 설명적인 변수명을 제안하며, 성능을 위해 해당 함수를 메모이제이션할 수 있다고 알려줍니다. 기술적으로는 모두 맞지만, 실제로는 도움이 되지 않습니다.
왜냐하면 봇은 fetchUser가 팀에서 강제하는 의도적인 네이밍 규칙이라는 것, 오류 처리가 전역 경계에 위임되어 있다는 것, 혹은 성능보다 정확성이 우선이라는 사실을 알지 못하기 때문입니다. 봇은 당신의 프로젝트를 전혀 몰랐습니다.
이는 모델 자체의 문제가 아니라 컨텍스트 문제입니다.
이것이 pi‑reviewer가 구축된 이유입니다 — 프로젝트 규칙을 모든 리뷰에 반영하는 GitHub Action 및 pi TUI 확장 기능입니다.
에이전트가 diff의 한 줄이라도 보기 전에 다음을 읽습니다:
AGENTS.md또는CLAUDE.md– 프로젝트 전반의 규칙: 네이밍 규칙, 아키텍처 결정, 따라야 할 패턴REVIEW.md– 리뷰 전용 규칙: 항상 표시해야 할 항목, 명시적으로 건너뛰어야 할 항목
이 파일들에 있는 Markdown 링크는 재귀적으로 따라가집니다. AGENTS.md가 docs/api-conventions.md를 링크하고 있다면, 그 파일도 인라인으로 포함됩니다. 에이전트는 요약이 아닌 전체 그림을 보게 됩니다.
검토 지침
항상 표시
fetch호출에서.json()전에res.ok검사가 누락된 경우/api/v1/아래에 버전이 지정되지 않은 API 엔드포인트getData,doStuff또는 기타 일반적인 이름으로 된 함수
건너뛰기
- 형식만 변경하는 경우
pi-review.md내부의 변경 사항
프로젝트 컨텍스트 추가
Before: 에이전트가 내부 헬퍼에 대한 누락된 타입 주석을 표시하고, 변수 이름 변경을 제안했으며, 떠돌아다니는 console.log를 지적했습니다.
After: 동일한 PR에 추가된 버전이 없는 API 엔드포인트를 포착하고, fetch 호출에서 res.ok 검사가 누락된 것을 표시했습니다 — REVIEW.md에 명시된 규칙과 정확히 일치하며, 지시대로 생성된 파일에서 형식만 변경된 부분을 건너뛰었습니다.
동일한 모델. 동일한 diff. 완전히 다른 검토.
Severity Filtering
모든 발견이 동일한 무게를 가질 필요는 없습니다. pi‑reviewer는 심각도별로 필터링할 수 있게 하여 중요한 부분에 집중할 수 있게 해줍니다.
uses: zeflq/pi-reviewer@main
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
pi-api-key: ${{ secrets.PI_API_KEY }}
min-severity: warnmin-severity: warn를 설정하면 에이전트가 INFO 수준의 제안을 완전히 건너뛰게 됩니다 — 생성되는 내용과 PR에 게시되는 내용 모두에서요. 또한 GitHub Actions UI에서 수동 리뷰를 트리거하고 실시간으로 심각도 수준을 선택할 수도 있습니다.
Three tiers
- 🔴 CRITICAL – 버그 및 보안 이슈
- 🟡 WARN – 논리 및 타입 오류
- 🔵 INFO – 스타일 및 제안
Running pi‑reviewer
pi‑reviewer는 pi 위에서 실행됩니다 — pi mono 플랫폼 위에 놓인 터미널 기반 코딩 에이전트입니다. 하나의 PI_API_KEY로 모든 지원 모델 및 제공자를 사용할 수 있습니다. 모델을 선택하면 pi가 요청을 라우팅합니다. 이는 단일 제공자에 얽매이지 않음을 의미합니다 — 워크플로우를 건드리지 않고 모델을 교체할 수 있으며, 리뷰 로직은 동일하게 유지됩니다.
또한 SSH를 통해서도 작동합니다. 프로젝트가 원격 머신에 있다면 --ssh 모드가 에이전트가 diff를 가져오고 원격에서 직접 컨벤션을 읽을 수 있게 해줍니다 — 로컬 복사가 필요 없습니다.
Anthropic Code Review와의 비교
Anthropic은 최근 Code Review를 출시했습니다. 이는 Claude Code에 내장된 관리형 PR 리뷰 서비스로, CLAUDE.md와 REVIEW.md를 읽고, 전체 코드베이스에 대해 여러 특화된 에이전트를 병렬로 실행한 뒤, 심각도 태그와 함께 인라인 결과를 게시합니다. 정말 인상적이지만 다음과 같은 제약이 있습니다:
- Anthropic 인프라에서 제공되는 관리형 서비스
- GitHub App 설치가 필요하며, Teams 및 Enterprise 플랜에서만 사용 가능
- 리뷰당 비용이 대략 $15–25 정도
- Claude 전용이며, 실행 위치를 제어할 수 없음
pi‑reviewer는 자체 CI에서 실행되며, 토큰 사용량에 따른 비용만 발생하고, pi mono를 통해 어떤 모델이든 사용할 수 있으며, 비밀 키와 워크플로 파일만 있으면 됩니다. GitHub App도, 관리자 승인 흐름도 필요 없습니다.
푸시하기 전에 로컬에서 리뷰하고 싶다면—아예 PR을 열지 않고도—pi TUI 확장 기능을 통해 터미널에서 /review 명령을 사용할 수 있습니다.
두 도구 모두 CLAUDE.md와 REVIEW.md를 읽습니다. 차이점은 실행 위치, 비용, 그리고 유지할 수 있는 제어 수준입니다.
시작하기
npx github:zeflq/pi-reviewer init이 명령은 워크플로 파일을 생성합니다. PI_API_KEY 비밀을 추가하세요. 그 시점부터 모든 PR은 프로젝트를 인식하는 리뷰를 받게 됩니다.
컨텍스트 파일인 AGENTS.md, REVIEW.md는 저장소에 존재합니다. 이 파일들은 버전 관리되고, 팀이 편집 가능하며, 프로젝트와 함께 진화합니다. 컨벤션을 잘 문서화할수록 리뷰 품질도 향상됩니다.
결론
통찰은 AI가 코드를 검토할 수 있다는 것이 아니라, 프로젝트 컨텍스트 없이 AI 검토는 단지 더 나은 문장을 가진 또 다른 린터에 불과하다는 점이다. 중요한 검토는 왜 여러분의 코드베이스가 현재와 같은 모습을 갖게 되었는지를 알고, 그 기준에 맞춰 차이를 확인하는 것이며, 일반적인 좋은 소프트웨어에 대한 추상적인 기준과 비교하는 것이 아니다.
컨텍스트가 전부다. 컨텍스트 없이 차이는 단지 잡음일 뿐이다.