테스트는 초록색인데, 합치기엔 찜찜하다
AI 코딩 에이전트에게 작은 변경을 맡겼는데 예상보다 많은 파일이 바뀌었습니다. 테스트와 린트는 모두 통과했지만, 자세히 보니 기존 데이터 흐름을 우회하거나 요청하지 않은 업무 규칙까지 바꿔놓았어요.
이럴 때 일반적인 자동 검사는 문법 오류나 타입 문제는 알려줘도, “우리 팀이 합의한 제품을 여전히 만들고 있는가?”에는 답하지 못할 수 있습니다. 코드가 실행된다는 사실과 제품 의도에 맞는다는 판단은 서로 다른 검토이기 때문이에요.
Prelint는 이 두 번째 질문에 집중합니다. 저장소의 제품 사양, ADR, 업무 규칙을 PR 변경 내용과 대조해 범위 이탈과 결정 위반을 찾는 제품 정합성 검토 계층이에요. 린터·타입 검사기·보안 스캐너를 대체하는 도구는 아닙니다.
차이는 버그 탐지가 아니라 검토 기준에 있다
Prelint가 보는 기준은 코드의 모양보다 코드가 따라야 했던 결정입니다. 공식 문서에 따르면 제품 사양 위반, ADR 준수 여부, 업무 로직과 작업 범위 이탈을 검토하며 코드 스타일이나 일반 보안 취약점 검사는 전용 도구에 맡깁니다.
| 검토 계층 | 묻는 질문 | 대표 근거 |
|---|---|---|
| CI·정적 분석 | 빌드되고 테스트를 통과하는가? | 테스트, 타입, 린트 규칙 |
| 보안 검사 | 알려진 취약점이나 위험한 패턴이 있는가? | 보안 규칙, 의존성 데이터 |
| 제품 정합성 검토 | 합의한 요구사항과 설계를 따르는가? | 제품 사양, ADR, 업무 규칙 |
예를 들어 문서에 “모든 청구서의 기본 결제 기한은 발행일로부터 30일”이라고 적혀 있는데 PR이 기본값을 60일로 바꿨다고 해볼게요. 코드는 정상적으로 실행될 수 있지만 문서화된 업무 규칙과는 충돌합니다. Prelint가 잡으려는 것이 바로 이런 변경입니다.
설치부터 하지 말고, 규칙 하나와 PR 하나로 시험하세요
첫 검토의 목표는 저장소 전체를 문서화하는 것이 아닙니다. 현재 유효한 규칙 하나를 넣고, 그 규칙을 어기는 작은 PR에서 근거가 연결된 finding이 나오는지 확인하면 돼요. 현재 공개된 일반 시작 경로는 GitHub App이며, 설치를 승인할 조직 또는 저장소 권한이 필요합니다.
- Prelint 앱에서 GitHub로 인증합니다. GitHub App을 설치할 때는 전체 조직보다 시험할 저장소만 선택하세요. Prelint는 검토에 필요한 코드와 PR 데이터를 읽지만 저장소 코드를 직접 실행하지 않습니다.
- 저장소에 현재 유효한 규칙 하나를 마크다운으로 추가합니다. 예를 들어
specs/billing.md에 “모든 청구서의 기본 결제 기한은 발행일로부터 30일이다”라고 기록하세요. 첫 검토를 위한 별도 설정 파일은 필수가 아닙니다. - 기본 결제 기한을 60일로 바꾸는 작은 PR을 엽니다. 별도 브랜치에서 변경하고 초안이 아닌 PR로 전환하세요. 초안 PR이나 기본 제외 대상 봇이 만든 PR, 관련 파일 변경이 없는 PR은 검토가 건너뛰어질 수 있습니다.
- PR의 check run 요약과 diff 인라인 댓글을 확인합니다. 성공 기준은 변경이 문서와 충돌할 때 해당 줄에 근거가 연결된 finding이 게시되는 것입니다. 충돌하지 않는 변경이라면 현재 PR 버전에 활성 finding이 없다는 결과가 표시됩니다.
- 지적된 값을 수정해 새 커밋을 푸시합니다. 갱신된 결과에서 기존 finding이 사라졌는지 확인하세요. PR 생성·재개·초안 해제와 새 커밋 푸시가 검토 계기가 될 수 있습니다.
- 시험을 넓히기 전에 Billing을 확인합니다. 완료된 검토는 1건당 1달러이며 실패·취소·시간 초과 검토는 청구되지 않습니다. 가입 시 10달러 크레딧이 제공되고 공개 저장소 검토는 무료지만, 새 커밋 뒤 완료된 재검토도 별도 건으로 계산됩니다. 자동 충전 상태와 월 지출 한도를 먼저 확인하세요.
첫 시험은 일부러 명확한 충돌로 만드세요.
애매한 설계 원칙보다 “30일을 60일로 변경”처럼 문서와 diff의 충돌을 사람이 바로 판별할 수 있는 사례가 좋습니다. 결과가 이상할 때 도구의 판단 문제인지, 원래 문서가 모호했던 것인지 구분하기 쉬워집니다.
문서를 많이 넣는다고 더 잘 보는 것은 아니다
Prelint는 저장소의 마크다운 사양과 ADR을 자동으로 색인하지만, 한 번의 검토에 구성되는 문맥은 최대 80K자입니다. 조직·프로젝트·저장소 문서 등의 우선순위에 따라 문맥을 구성하고 한도를 넘으면 우선순위가 낮은 자료가 잘릴 수 있어요.
따라서 과거 회의록을 전부 넣기보다 결정의 상태를 분명히 하는 편이 낫습니다. 무엇을 결정했는지, 어느 범위에 적용되는지, 지금도 유효한지, 무엇이 예외인지를 짧고 명확하게 적으세요. 서로 충돌하거나 폐기 여부가 표시되지 않은 문서는 AI뿐 아니라 사람 리뷰어도 혼란스럽게 만듭니다.
검토에 포함될 문서와 코드를 먼저 살펴보세요.
Prelint는 저장소 코드를 실행하지 않지만 검토를 위해 코드와 PR 데이터를 읽고 AWS 환경에서 처리합니다. 민감한 파일이 있다면 저장소를 연결하기 전에 접근 범위와 제외 설정, 조직의 데이터 처리 기준을 확인해야 합니다.
36.6%는 효과가 아니라 검토 범위가 달라졌다는 신호다
Prelint의 자체 연구는 331개 공개 저장소에서 PR 56,706건을 문서가 있는 조건과 없는 조건으로 각각 검토했습니다. 문서가 없을 때 플래그율은 13.3%, 문서를 포함했을 때는 36.6%였습니다. 문맥이 있어야 발견된 항목은 979건, 반대로 문맥이 불필요한 경고를 억제한 경우는 232건으로 보고됐습니다.
이 결과는 문서가 검토 대상을 바꿀 수 있다는 가설을 보여줍니다. 다만 플래그율이 높아졌다고 실제 결함이나 장애가 그만큼 줄었다는 뜻은 아닙니다. 연구를 제품 공급사가 수행했고 모델 채점에 Opus 4.6을 사용했으며, 저장소 표집과 사람 검수 절차, 원시 결과가 독립 재현에 충분할 만큼 공개되지는 않았어요.
팀에서 판단할 때는 발견 개수보다 세 가지를 보세요. finding이 실제로 유효했는지, 사람이 놓칠 만한 제품 결정을 짚었는지, 수정 후 같은 위반이 사라졌는지입니다. 이 세 가지가 확인돼야 제품 정합성 리뷰가 댓글을 늘리는 도구가 아니라 병합 판단을 돕는 계층이 됩니다.
도입 여부는 첫 다섯 건으로 판단하면 된다
Prelint의 가치는 기존 코드 리뷰를 없애는 데 있지 않습니다. 테스트와 보안 검사를 유지한 채, 문서화된 의도를 대조하는 질문을 하나 더 추가하는 데 있어요.
처음부터 저장소 전체에 적용하지 말고, 결론이 분명한 규칙과 작은 PR 다섯 건으로 시작해 보세요. 각 finding을 유효한 위반, 문서가 모호함, 잘못된 경고로 분류하면 다음 행동이 선명해집니다. 유효한 위반이 반복되면 적용 범위를 넓히고, 문서 문제가 많으면 ADR부터 정리하며, 잘못된 경고가 많으면 자동 병합 게이트로 쓰지 않는 편이 안전합니다.
