간단히 말해: AI 코드 리뷰는 사용자가 수정한 코드를 관련 컨텍스트의 제한된 양과 함께 읽고, 증거와 권장 사항이 포함된 우선순위가 지정된 발견 사항을 반환하는 도구입니다. 이는 로컬 git diff와 정의(definitions), 호출자(callers), 임포트(imports)를 해결하는 파서(parsers)를 기반으로 작동합니다. 이 도구는 애플리케이션을 실행하지 않으며, 코드가 정확하다는 것을 증명하지도 않습니다. 사용자가 각 발견 사항을 평가하고 어떤 조치를 취할지 결정해야 합니다.
실제 검토하는 내용
입력은 전체 레포지토리(repository)에 대한 모호한 스캔이 아닙니다. 이는 사용자가 곧 배포하려는 추가, 삭제 및 수정된 라인들로 구성된 로컬 git diff에서 시작합니다. 그 위에 리뷰는 제한된 관련 컨텍스트를 끌어옵니다: 변경 사항이 참조하는 정의, 함수의 호출자, 그리고 파일을 연결하는 임포트입니다.
각 발견 사항은 세 부분으로 제공됩니다:
- 우선순위(Priority): 이를 통해 사용자는 막는 결함(blocking defect)과 사소한 참고 사항을 구분할 수 있습니다.
- 증거(Evidence): 단순히 레이블이 아니라, 해당 발견 사항이 제기된 구체적인 이유입니다.
- 권장 사항(Recommendation): 자동 편집보다는 제안되는 다음 단계입니다.
리뷰는 사용자가 요청했을 때만 시작됩니다. 이 도구는 파일을 스스로 다시 작성하거나, 무언가를 승인/병합하지 않습니다.
데스크톱 워크플로우에 통합하는 방법
코드 폴더를 선택하면 프로젝트 구조가 먼저 열립니다. 그런 다음 파일을 열어 소스 코드 전체를 볼 수 있으며, 소스 전용 보기, 전체 비교 보기, 변경 사항 전용 보기 등의 뷰가 제공됩니다. 추가 및 삭제된 라인은 표시되며, 인라인 문자 하이라이트는 정확히 무엇이 이동했는지 보여주고, 탐색(navigation)과 검색 기능은 사용자가 큰 diff를 통과하는 데 도움을 줍니다.
구조 필터는 눈으로 폴더를 보는 것만으로는 얻기 어려운 신호를 추가합니다:
| 필터 | 알려주는 내용 |
|---|
| Heavily referenced files | 변경 사항이 많은 호출자들에게 파급될 수 있는 위치 |
| ... | |
| 이것들은 판결(verdicts)이 아니라 리뷰를 위한 단서입니다. 들어오는 참조가 없는 파일이라고 해서 자동으로 삭제해도 안전한 것은 아니며, 동일한 텍스트라고 해서 두 코드 조각이 같은 방식으로 작동한다는 것을 의미하지는 않습니다. | |
발견 사항의 기반이 되는 증거 모델
발견 사항(Findings)은 모두 같은 종류가 아니며, 그렇게 취급하면 잘못된 결정을 내리게 됩니다. 이 검토는 증거 클래스를 구분합니다:
- 정적(Static) 신호: 타입 체크(typecheck), 린트(lint), 빌드(build), 그리고 존재하지 않는 API에 대한 참조와 같은 것들.
- 동적(Dynamic) 신호: 테스트, 커버리지(coverage), 스모크 런(smoke runs) 등에서 나오는 신호.
- 계약(Contract) 신호: 스키마 및 타입 드리프트(schema and type drift)와 관련된 신호.
- AI 가설(AI hypothesis): 결정론적 확인 과정 없이 모델에서 나오는 모든 것.
모델만으로 주장하는 것은 항상 가설이며, 결코 확정된 결함이 아닙니다. 프로젝트 검사를 실행하면 누락된 스크립트는 통과(passed)가 아닌 미확인(unverified)으로 보고됩니다. 증거가 돌아오지 않으면 빈 결과는 통과가 아니기 때문에 결론을 내릴 수 없습니다(inconclusive).
정직한 한계 (Honest limits)
Powerduck은 결함을 놓치거나 잘못된 의심을 제기할 수 있으며, 앱 자체를 실행하지 않습니다. 동적 로딩(Dynamic loading), 프레임워크 진입점(framework entry points), 외부 소비자(external consumers)는 정적 분석(static analysis)에서 누락될 수 있습니다. 검토는 주의를 기울여야 할 영역을 좁히고 변경 사항을 구조적으로 읽는 방법을 제공하지만, 각 발견 사항에 대한 판단은 여전히 엔지니어에게 달려 있습니다.
또한 에이전트 작업 패키지를 마크다운(Markdown) 핸드오프 형태로 내보낼 수 있으며, 여기에는 컨텍스트와 리비전 앵커가 포함됩니다. 수정은 선택 사항이며, 수신하는 에이전트는 내보낸 내용을 신뢰하기보다는 모든 의심을 독립적으로 평가합니다.
자주 묻는 질문 (Frequently asked questions)
AI 코드 리뷰가 인간 검토자를 대체할 수 있나요? 아닙니다. 이는 diff를 정리하고 증거 기반의 발견 사항을 노출하지만, 제품 의도(product intent)나 외부 시스템과 같이 정적 분석이 볼 수 없는 컨텍스트는 여전히 사람이 판단해야 합니다.
제 테스트 또는 애플리케이션을 실행하나요? 명시적인 검사(explicit checks)로 감지된 프로젝트 명령은 실행할 수 있지만, 앱 자체는 실행하지 않습니다. 누락된 스크립트는 통과가 아닌 미확인으로 표시됩니다.
발견 사항이 틀릴 수 있나요? 예. 검토는 잘못된 의심을 제기할 수 있으며, 모델만으로 주장하는 것은 가설입니다. 코드를 변경하기 전에 증거를 확인하십시오.
깨끗한 리뷰가 코드가 정확하다는 의미인가요? 아닙니다. 리뷰는 정확성을 증명하지 못하며, 동적 로딩(dynamic loading) 및 외부 소비자(external consumers)를 포함한 알려진 사각지대(blind spots)가 존재합니다.
핵심 사항
AI 코드 리뷰는 제한된 컨텍스트(bounded context)를 가진 사용자의 diff에 대한 집중적인 읽기이며, 발견된 각 항목마다 우선순위(priority), 증거(evidence), 그리고 권장 사항을 반환합니다. 이것의 가치는 정적(static), 동적(dynamic), 계약(contract), 그리고 가설(hypothesis) 신호를 분리하여 사용자가 각 주석을 얼마나 신뢰해야 하는지 알게 하면서도, 최종 결정권을 사용자에게 남겨둔다는 점입니다. 이를 정확성 증명서(correctness certificate)로 취급하지 말고, 무언가를 놓치거나 틀릴 수 있는 빠르고 구조화된 첫 번째 검토자(first reviewer)로 간주하십시오. 더 자세한 내용은 AI 코드 리뷰 가이드를 참고하십시오.