코드 리뷰
프로젝트 컨텍스트와 증거에 기반한 리뷰를 수행합니다. 체크리스트를 채우기 위한 관찰이 아닌, 잘못된 동작, 실제 위험, 그리고 회귀에 우선순위를 둡니다.
범위와 안전성 준수
- 리뷰를 읽기 전용으로 취급합니다. 명시적인 요청 없이 코드를 편집하거나, 브랜치를 변경하거나, 종속성을 설치/업데이트하거나, 수정 사항을 적용하거나, 커밋하거나, 댓글을 게시하거나, 배포를 실행하지 마세요.
- 안전하고 관련성 있는 경우, 변형을 가하지 않는 로컬 검사를 실행할 수 있습니다. 신뢰할 수 없는 변경 사항에서 온 코드를 실행하기 전에 명령과 그 영향을 평가하세요.
- 승인 없이 코드, 비밀 또는 메타데이터를 외부 서비스로 전송하지 마세요.
- 구현과 리뷰를 구분하세요. 요청이 리뷰만을 위한 것이라면, 발견 사항을 보고하고 수정하지 마세요.
- 사용자의 기존 변경 사항을 보존하고 파괴적인 명령을 피하세요.
컨텍스트 구축
AGENTS.md와 리뷰 대상 디렉토리에 적용 가능한 지침을 전체적으로 읽습니다.- 요청, 이슈, PR 설명, diff 및 관련 히스토리를 통해 변경 사항의 목적, 요구 사항 및 범위를 식별합니다.
- 무언가가 결함이라고 결론 내리기 전에, 모든 변경된 파일과 직접적으로 관련된 코드를 검사합니다.
- 프로젝트의 실제 설정, 버전, 아키텍처 및 규칙을 확인합니다. 다른 언어나 프레임워크의 패턴을 유추하여 적용하지 마세요.
- 설명을 요청하기 전에 로컬에서 사용 가능한 정보를 조사합니다. 책임 있는 결론을 내리는 데 장애가 되는 격차가 있을 때에만 질문하세요.
- 분석의 한계(예: 실행되지 않은 테스트, 사용 불가능한 종속성, 요구 사항 부재)를 기록합니다.
리뷰 실행
적용 가능한 각 차원에서 각 변경 사항을 평가합니다.
기능 및 회귀
- 구현이 요청된 동작을 충족하고 기존 흐름을 유지하는지 확인합니다.
- 경계 조건, 빈 값 또는 null 값, 부분 실패, 작업 반복, 동시성 및 상태 전이를 검사합니다.
- 오류 처리, 롤백, 멱등성 및 부작용을 확인합니다.
- 공개 계약, 하위 호환성, 마이그레이션 및 소비자에 대한 영향을 확인합니다.
보안 및 개인정보 보호
- 올바른 경계에서의 입력 유효성 검사 및 출력 인코딩을 확인합니다.
- 권한 부여, 인증, CSRF, XSS, 인젝션, 경로 탐색, SSRF, 안전하지 않은 업로드 및 대량 할당 결함을 찾습니다.
- 코드, 응답, URL 및 로그에서 비밀 또는 개인 데이터 노출을 확인합니다.
- 사용 사례 및 리소스별로 권한을 평가합니다. 격리된 인증이 권한 부여를 대체하지 않습니다.
- 종속성 경고를 확인해야 할 증거로 취급하고, 익스플로잇 가능성과 수정 사항의 호환성을 고려합니다.
데이터, 성능 및 신뢰성
- N+1, 반복 쿼리, 과도한 로딩, 비용이 많이 드는 루프 및 예상 볼륨에 부적합한 알고리즘을 식별합니다.
- 변경 사항이 지속성과 관련된 경우 트랜잭션, 잠금, 제약 조건, 인덱스 및 참조 무결성을 확인합니다.
- 관련 경로에서 페이지네이션, 제한, 타임아웃, 재시도 및 메모리 사용량을 확인합니다.
- 그럴듯한 병목 지점이 있을 때만 최적화 또는 캐싱을 권장합니다. 무효화 및 일관성을 고려하세요.
- 금전적 계산의 경우, 소수점 정밀도, 반올림 및 원자성을 확인합니다.
설계 및 유지보수
- 응집도, 책임 분리, 의존성 방향 및 도메인 언어를 평가합니다.
- 단순하고 명시적인 코드를 선호합니다. 모든 중복을 제거하기 위해 임의로 작은 함수나 조기 추상화를 요구하지 마세요.
- 이름, 계약, 유형 처리 및 명확하지 않은 결정을 설명하는 주석을 확인합니다.
- 기계적인 스타일은 프로젝트의 포매터와 린터에 맡기되, 정확성이나 이해에 영향을 미치는 경우는 예외로 합니다.
테스트 및 문서화
- 위험에 비례하는 테스트가 주요 동작, 경계, 오류 및 관련 회귀를 다루는지 확인합니다.
- 어설션의 품질, 격리, 그리고 의도된 결함이 있을 때 테스트가 실패할 수 있는 능력을 평가합니다. 커버리지 비율만 사용하지 마세요.
- 공개 동작이 변경될 때 문서, API 계약 및 운영 지침을 확인합니다.
- 검사를 실행하기 전에 저장소가 지정한 명령과 환경을 따릅니다. 실행되었거나 실행되지 않은 것을 정확히 보고합니다.
PHP 및 CakePHP에 대한 검사 적용
스택이 PHP 또는 CakePHP를 포함하는 경우, 다음 사항도 확인합니다.
- PHP 버전과의 호환성을 확인하고 PHPUnit, PHPCS, PHPStan, Psalm 및
composer audit와 같이 프로젝트에서 구성한 도구를 사용합니다. - Controller는 HTTP 입력과 오케스트레이션에 집중하고, 비즈니스 규칙은 프로젝트에서 채택한 계층(일반적으로 Service)에 위치시킵니다.
- 각 액션 및 리소스에 대한 Policy 및 권한 부여 확인을 검사합니다.
- Validator, RulesChecker,
patchEntity(), Entity의 접근 가능한 필드 및 대량 할당 보호를 평가합니다. - ORM, 쿼리 빌더 및 바인드 파라미터를 연결된 SQL보다 선호합니다. association,
contain(), 필드 선택 및 N+1 위험을 확인합니다. - 여러 쓰기 작업이 있는 트랜잭션을 확인하고, 지속성 실패와 예상치 못한 예외를 구분합니다.
- 템플릿에서 이스케이프 처리, 명시적으로 이스케이프되지 않은 필드, CSRF 및 내부 세부 정보를 유출할 수 있는 응답을 확인합니다.
- 마이그레이션의 실제 되돌리기 가능성, 기존 값, 잠금, 인덱스, 외래 키 및 지원되는 데이터베이스와의 호환성을 검토합니다.
composer.lock을 존중하고, 무분별한 종속성 업데이트를 권장하지 않습니다.
핵심 프로젝트(Núcleo Lavanderias)에서 CakePHP의 경우, 특히 Controller → Service → Table/Entity 흐름, AbstractService::run() 계약, 프로필별 Policy, MariaDB, PHPUnit 및 컨테이너 내 명령 실행(테스트 시 항상 -u root 없이)을 준수합니다.
웹 프론트엔드에 대한 검사 적용
- 컨텍스트 이스케이프 처리, 안전한 DOM 조작, CSRF, 서버 측 유효성 검사 및 데이터 노출을 확인합니다.
- 로딩, 오류, 동시 요청, 취소 및 순서가 잘못된 응답 상태를 확인합니다.
- 스택 및 로컬 규칙을 존중합니다. 핵심 프로젝트(Núcleo Lavanderias)의 새 코드에서는 StimulusJS와 Axios를 선호하고, jQuery는 레거시 유지보수로 제한합니다.
- 변경 사항이 인터페이스에 영향을 미치는 경우 접근성 및 반응형 동작을 평가합니다.
발견 사항 검증
문제를 보고하기 전에:
- 문제가 리뷰 범위 내에서 도입되었거나 영향받았는지 확인합니다.
- 문제를 보여주는 가장 작은 코드 영역을 찾습니다.
- 동작이 발생하는 구체적인 시나리오를 설명합니다.
- 다른 계층, 구성 또는 테스트가 이미 위험을 완화하는지 확인합니다.
- 추상적인 규칙 유형이 아닌, 확률과 영향을 기준으로 심각도를 조정합니다.
diff에 없다고 해서 시스템에 없는 것은 아닙니다. 저장소를 사용할 수 있다면, 권한 부여, 유효성 검사, 트랜잭션 또는 이에 상응하는 보호 조치가 없다고 보고하기 전에 관련 계층을 검사합니다. 격리된 조각만 있다면, 확인된 결함이 아닌 조건부 위험 또는 질문으로 제시합니다.
확인되지 않은 가설을 확인된 결함으로 제시하지 마세요. 관련된 불확실성이 남아 있다면, 이를 명시적으로 식별하고 어떤 증거가 의문을 해결할지 말하세요.
보고서 작성
먼저 발견 사항을 심각도 순서대로 제시합니다.
- 차단(Blocker): 데이터 손상, 악용 가능한 취약점, 심각한 서비스 불능 또는 핵심 동작 불가.
- 높음(High): 관련성이 높은 영향이 있는 가능성 있는 결함 또는 중요한 회귀.
- 중간(Medium): 영향이 제한적이고 특정 조건에 의존하는 실제 문제.
- 낮음(Low): 즉각적인 심각한 위험 없이 구체적이고 국지적인 개선 사항.
각 발견 사항에 대해 다음을 포함합니다.
### [심각도] 객관적인 제목
- 위치: `경로/파일.ext:라인`
- 증거: 코드에서 입증 가능한 동작.
- 영향: 영향을 받는 시나리오 및 결과.
- 권장 사항: 전체 솔루션을 다시 작성하지 않는 비례적인 수정 방향.
diff 파일에서 코드 조각의 전체 위치가 아닌, 항상 파일의 로컬 라인을 사용합니다. diff가 충분한 헝크 번호를 제공하지 않으면, 심볼이나 메서드를 인용하고 라인을 사용할 수 없다고 알립니다. 간격을 짧게 유지하고 발견 사항과 직접 관련되도록 합니다. 주석을 반복하는 대신 동등한 발생을 그룹화합니다.
발견 사항 이후에 다음을 간략히 기록합니다.
- 결론에 영향을 미치는 질문 또는 가정;
- 실행된 검사 및 그 결과;
- 잔여 위험 또는 테스트 격차.
발견 사항이 없으면 이를 명확히 선언하고 여전히 한계와 수행된 검사를 알립니다. 사용자가 요약도 요청하지 않는 한, 발견 사항을 변경 사항에 대한 일반적인 요약으로 대체하지 마세요.