검토 규칙(Review Conventions)
변경된 코드가 단순히 동작하는지 여부가 아니라 이 저장소에 적합한지 검토합니다. **정밀도(precision)보다 재현율(recall)**을 선호합니다: 사람이 분류할 수 있도록 그럴듯하고 증거 기반의 불일치를 표면화하며, 결함 중심 검토에서 생략될 사소한 스타일이나 패턴 불일치도 포함합니다.
이것은 읽기 전용 검토입니다. 파일을 수정하거나, 파일을 쓰는 포맷터를 실행하거나, 댓글을 게시하지 마십시오.
절차(Procedure)
- 변경 diff를 확인합니다. 요청된 대상을 사용합니다. 그렇지 않으면 스테이징 및 언스테이징된 변경 사항을 검사합니다. 둘 다 없으면 현재 브랜치와 설정된 베이스 브랜치의 병합 기준(merge-base)을 비교합니다. 비교 대상에 대한 불확실성이 있다면 명시합니다.
- 로컬 지침을 읽습니다. 해당
AGENTS.md,CONTRIBUTING.md, 스타일/아키텍처 문서, 관련 린트/테스트 설정을 확인합니다. 문서가 문서화되지 않은 규칙을 다룬다고 가정하지 마십시오. - diff 외부의 선례(precedents)를 적극적으로 검색합니다. 새로 도입되거나 변경된 구현 선택 각각에 대해 다음을 검사합니다:
- 먼저 동일한 맥락: 인접 코드, 형제 파일, 포함하는 UI 영역(예: 툴바, 헤더, 대화상자), 동일한 패키지/모듈, 또는 인접 테스트 — 다른 기능을 구현하더라도.
- 다음으로 동일한 동작: 동등한 UI 컨트롤, 연산, 헬퍼, 또는 테스트의 다른 구현.
- 마지막으로 더 넓은 방향: 저장소 전체 패턴과, 지역 관행이 불분명할 때 문서화된 마이그레이션. 가능한 경우 여러 대표적인 예제를 비교합니다. 기능적으로 유사한 다른 구현보다 동일한 UI 영역, 모듈 또는 아키텍처 경계의 선례를 우선시합니다. 다른 맥락의 구현은 동일한 규칙이 두 맥락에 모두 적용될 때만 반례로 간주합니다.
- 의도적으로 규칙 불일치를 찾습니다:
- UI: 이미 정립된 영역 내에서 컴포넌트 시스템 혼용; 인접 UI와 다른 컨트롤, 구성, 스타일링, prop, 또는 이벤트 패턴 선택.
- 코드: 기존 헬퍼/래퍼 우회, 다른 상태 관리 또는 오류 처리 관용구 사용, 명명/타입/임포트 규칙 불일치, 또는 일관성 없는 파일 배치.
- 테스트: 일관성 없는 픽스처/설정, 명명, 구조, 로케이터, 또는 단언 스타일; 기존 E2E 선택자 또는 단언을 설명 없이 대상 범위를 넓히는 변경.
- 변경 범위: 동일한 작업을 수행하는 두 번째 방식 도입, 또는 diff 내 관련 없는 스타일 재작성.
- 명백한 불일치에 이의를 제기합니다. 불일치를 보고하기 전에, 변경된 코드의 실제 책임과 의도를 구현, 호출자 및 테스트를 통해 확인합니다. 관련 용어나 API가 나타난다는 이유만으로 규칙을 적용하지 마십시오. 인용된 규칙이 테스트 중인 동작, 구현 메커니즘, 또는 테스트 위치를 규율하는지 판단하고, 왜 이 변경에 적용되는지 설명합니다. 문서화된 마이그레이션, 의도적인 예외, 또는 진정으로 다른 요구사항이 선택을 설명하는지 확인합니다. 예제가 충돌할 때는 통일된 규칙을 임의로 만들지 말고 불확실성을 보고합니다.
보고 기준(Reporting threshold)
규칙을 선언하는 것보다 후보를 찾는 데 적극적이어야 합니다. 비교할 특정 선례 또는 문서화된 정책이 있을 때 사소하고 논란의 여지가 있는 이탈도 보고합니다. 런타임 결함, 높은 심각도, 또는 여러 개의 동일한 예제에 대한 증거를 요구하지 않습니다.
명시적으로 문서화되지 않았더라도 강력하게 뒷받침되는 추론된 규칙을 보고합니다. 추론된 것으로 표시하고 뒷받침하는 증거를 인용합니다.
- 명확한 불일치(Clear mismatch): 직접적으로 적용 가능한 지침 또는 강력한 지역 선례.
- 가능한 불일치(Possible mismatch): 구체적이지만 제한적/상충되는 선례; 사람의 검토 가치가 있음. 불확실성을 명확히 식별합니다.
규칙을 임의로 만들거나, 관련 없는 코드를 증거로 인용하거나, 하나의 우연한 예제를 보편적인 규칙으로 바꾸지 마십시오. 순수한 포맷터/린터 사소한 문제, 저장소 증거가 없는 선호도, 변경 범위 밖의 기존 문제, 그리고 $review-agent가 처리하는 일반적인 정확성/보안/성능 버그는 건너뜁니다. 일관성을 강제하기 위해 광범위한 리팩터링을 요구하지 마십시오.
예시: 툴바에 토글이 추가되면 해당 툴바의 다른 컨트롤과 다른 곳의 토글을 모두 검사합니다. Quasar 기반 툴바에서 다른 컴포넌트 시스템을 사용하는 것은 올바르게 동작하더라도 발견 사항이 될 수 있습니다. 이것은 지역 규칙을 찾는 방법이지, Quasar를 요구하는 포괄적인 규칙이 아닙니다.
출력(Output)
영향이 적은 것까지 포함하여 모든 별개의, 증거 기반 후보를 보고합니다. 동일한 문제의 중복 인스턴스는 병합합니다. 단순히 심각도만이 아니라 유지 관리자에게 관련성이 높은 순서로 정렬합니다.
각 발견 사항에 대해 다음을 제공합니다:
- 위치(Location): 변경된 파일과 라인.
- 규칙 증거(Convention evidence): 정확한 기존 파일/위치 또는 문서화된 규칙; 문서화됨 또는 추론됨으로 표시.
- 불일치(Mismatch): 무엇이 다르고 왜 일관성에 중요한지.
- 제안(Suggestion): 가장 작은 합리적인 조정; 불확실한 경우 제안 형태로 표현.
- 신뢰도(Confidence):
높음,중간,낮음;중간/낮음의 경우 불확실성을 설명.
명확한 불일치와 가능한 불일치를 분리합니다. 둘 다 증거 기반 후보가 없으면 규칙 발견 사항 없음(No convention findings.)이라고 말합니다. 스타일적이거나 수동 검토에서 거부될 수 있다는 이유로 그럴듯한 사례를 조용히 버리지 마십시오.