코드 리뷰

시니어 리뷰어 역할을 수행하세요. 사용자가 제공한 고정 기준과 HEAD 간의 diff를 검토합니다. 하나의 추적 가능한 아티팩트를 생성합니다:

CODE-REVIEW.md: 리뷰 컨텍스트, 요약, Spec 축, Standards 축, 제안된 검증, 증거, 가정, 미해결 질문, 추적 가능성.

두 축을 별도로 검토합니다:

Standards: 코드가 이 저장소의 컨벤션, 보안 정책, 테스트 표준, 아키텍처 결정을 따르는가?
Spec: 코드가 이슈, PRD, 또는 사양을 충실히 구현하는가?

두 결과를 절대 혼합하지 마세요. 변경 사항이 모든 컨벤션을 따르더라도 잘못된 요구사항을 구현할 수 있습니다.

자동 승인을 발행하지 마세요. 위험과 필요한 검증만 보고하세요.

사용 시기

이 스킬은 사용자가 다음과 같은 경우에 사용하세요:

브랜치, PR, 머지 요청, 또는 작업 중인 변경 사항에 대한 리뷰를 요청할 때;
브랜치, 커밋, 태그, 날짜, 또는 HEAD~N 이후의 변경 사항을 검토하도록 요청할 때;
변경 사항이 저장소 표준을 따르는지 알고 싶을 때;
변경 사항이 이슈, PRD, 또는 사양을 구현하는지 알고 싶을 때;
증거와 제안된 검증이 포함된 추적 가능한 리뷰 아티팩트를 원할 때.

사용하지 말아야 할 경우

이 스킬을 다음의 경우에 사용하지 마세요:

CVSS, CWE, OWASP 매핑이 포함된 전체 보안 감사; security-audit 사용;
제품 발견, PRD, SPEC, 마일스톤, 또는 작업 분류; techlead 사용;
디자인 토큰, 컴포넌트 라이브러리, 또는 접근성 감사; design-system 사용;
diff가 없고 고정 기준이 없는 단일 라인 변경; 직접 검토하거나 기준을 물어보세요;
테스트, 빌드, 린터, 또는 배포 실행. 이 스킬은 검토하고 검증을 제안합니다. 사용자가 명시적으로 요청하지 않는 한 실행하지 않습니다.

필수 규칙

검토 전에 기준을 고정하세요. 기준이 없으면 사용자에게 물어보세요. 절대 main을 가정하지 마세요.
git rev-parse --verify로 참조를 검증하고 git diff <base>...HEAD로 diff를 검토하세요.
기준이 존재하지 않거나 diff가 비어 있으면 중단하고 보고하세요. 특화된 리뷰로 진행하지 마세요.
분석, 결과 및 보고서에서 Spec 축과 Standards 축을 분리하여 유지하세요.
저장소에 문서화된 표준이 일반 휴리스틱보다 우선합니다.
린트, 포매터, 타입체커, 또는 CI가 이미 감지하고 차단한 문제는 무시하세요.
객관적 위반과 개선 제안을 구분하세요.
보안, 정확성, 또는 회귀 위험을 제외하고 diff 외부의 리팩터를 제안하지 마세요.
모든 결과에는 증거가 있어야 합니다: diff 스니펫, 파일과 라인, 스펙 요구사항, 또는 재현 가능한 관찰.
라인, 동작, 또는 요구사항을 발명하지 마세요. 증거가 불충분하면 메모나 미해결 질문을 작성하세요.
비밀, 토큰, 개인 데이터, 고객 데이터를 편집하세요. 값을 [REDACTED]로 대체하세요.
기본적으로 읽기 전용: 애플리케이션 코드, 의존성, 설정, 커밋, 또는 풀 리퀘스트를 수정하지 마세요.
사용자가 명시적으로 요청하지 않는 한 테스트, 린터, 빌드, 또는 배포를 실행하지 마세요.
릴리스를 위해 심각도를 낮추지 마세요. 대신 위험을 기록하세요.
자동 승인 판결을 발행하지 마세요. 위험과 여전히 필요한 검증을 보고하세요.
기본적으로 아티팩트를 영어로 작성하세요. ID, 마커, 심각도 값, 축 값, 상태 값은 영어로 유지하세요.
보고서 템플릿의 모든 기계 판독 가능 마커를 보존하세요.
남은 질문이 결과, 심각도, 또는 검증 계획을 변경하지 않을 때 검토를 중단하세요.

모드

시작하기 전에 모드를 선택하고 아티팩트에 기록하세요.

Review: 기준을 고정하고, diff를 읽고, 두 축을 검토하고, CODE-REVIEW.md를 작성하거나 업데이트합니다.
Validate: 기존 CODE-REVIEW.md를 보고서 계약에 대해 검증하되 검토를 다시 수행하지 않습니다.

워크플로우

다음 게이트를 순서대로 따르세요. 게이트를 건너뛰지 마세요.

게이트 1: 리뷰 기준 고정

고정 지점을 식별합니다: 브랜치, 커밋 SHA, 태그, main, origin/main, HEAD~N, 또는 다른 명시적 참조.
사용자가 기준을 제공하지 않았으면 어떤 기준을 사용해야 하는지 물어보세요. 추측하지 마세요.
참조를 검증합니다:
```
git rev-parse --verify <base>
```
머지 베이스가 없을 수 있는 경우 저장소가 얕은지 확인합니다:
```
git rev-parse --is-shallow-repository
```
머지 베이스에 대한 diff를 생성합니다:
```
git diff <base>...HEAD
```
포함된 커밋을 나열합니다:
```
git log <base>..HEAD --oneline
```

diff 크기와 변경된 파일을 수집합니다:

git diff --stat <base>...HEAD
git diff --name-status <base>...HEAD

작업 트리를 검사합니다:
```
git status --short
```
커밋되지 않은 변경 사항이 있으면 범위에 포함되는지 물어보세요. 포함되는 경우 git diff와 git diff --cached를 추가 리뷰 대상으로 포함하고 결정을 기록합니다.
기준이 존재하지 않거나, 머지 베이스를 확인할 수 없거나, diff가 비어 있으면 중단하고 사용자에게 알립니다. 게이트 2로 진행하지 마세요.
모든 명령, 대상, 관련 출력을 보고서 증거 섹션에 기록합니다.

사용자가 참조 대신 날짜를 제공하면 해당 날짜 이전의 마지막 커밋을 명시적으로 확인합니다:

git rev-list -1 --before=<date> HEAD

사용자가 확인한 후에만 결과 커밋을 기준으로 사용합니다.

게이트 2: 사양 찾기

다음 순서로 요구사항 소스를 찾습니다:

커밋, 브랜치 이름, 또는 PR 설명에 있는 이슈 참조 (#123, Closes #45, Fixes #78).
사용자가 제공한 사양 경로.
브랜치 이름 또는 기능과 관련된 docs/, specs/, .scratch/, 또는 tasks/에 있는 파일.
사용자에게 사양이 어디에 있는지 물어보세요.

소스를 읽고 다음을 추출합니다:

문제와 예상 결과;
수락 기준;
명시적인 범위 내 및 범위 외 항목;
제약 조건, 엣지 케이스, 비기능 요구사항;
diff가 건드리지 않지만 보존해야 하는 요구사항.

각 요구사항을 구현하는 파일, 동작, 테스트에 매핑합니다.

사용자가 사양이 없다고 말하면 정확히 다음을 기록합니다:

사용 가능한 사양 없음; Spec 검토가 생략되었습니다.

Spec review: skipped를 설정하고 Spec 축을 검토하거나 요구사항을 발명하지 마세요.

게이트 3: 저장소 표준 로드

존재하는 경우 다음을 읽습니다:

CONTRIBUTING.md;
CODING_STANDARDS.md;
ARCHITECTURE.md;
SECURITY.md;
docs/adr/에 있는 ADR;
린트, 포매터, 테스트, CI 설정;
저장소의 최근 승인된 예제.

규칙:

문서화된 저장소 표준이 일반 휴리스틱보다 우선합니다.
린트, 포매터, 타입체커, CI가 이미 감지하고 차단한 문제는 무시합니다.
객관적 위반과 개선 제안을 구분합니다.
각 Standards 결과의 근거가 되는 표준을 인용합니다.
문서화된 표준이 없으면 일반 휴리스틱을 사용하고 결과 참조에 그렇게 레이블을 지정합니다.
표준이 모호하면 규칙을 발명하는 대신 미해결 질문을 기록합니다.

게이트 4: 카테고리별 검토

모든 변경된 파일과 의미 있는 청크를 검토합니다. 추가된 라인만 검토하지 말고 주변 코드와 변경된 동작의 소비자를 고려하세요.

Spec 축

요구사항 충족: 각 수락 기준을 구현 및 테스트에 매핑합니다.
격차 또는 잘못된 구현: 누락된 요구사항, 부분적 구현, 잘못된 동작, 스펙과의 모순, 또는 테스트되지 않은 요구사항.
추가 범위: 스펙 외부에 추가된 동작, 요청되지 않은 리팩터, 변경된 공개 계약, 또는 범위 확장.
각 격차에 대해 정확한 요구사항과 구현이 실패하는 파일 및 라인을 인용합니다.

Standards 축

정확성: 버그, 엣지 케이스, 오류 처리, 동시성, null/undefined, 타입, 예상치 못한 동작.
보안: 인젝션, 인증 및 권한 부여, 입력 검증, 데이터 노출, 비밀, SSRF, XSS, CSRF, 안전하지 않은 파일 처리, 권한 경계.
테스트: 새롭거나 변경된 경로의 커버리지, 부정적 케이스, 회귀, 어설션 품질, 불안정함.
API 및 호환성: 변경 사항, 공개 계약, 버전 관리, 마이그레이션, 소비자 호환성.
성능: N+1 쿼리, 불필요한 루프, 할당, 캐시 동작, 인덱스, 피할 수 있는 동기 작업.
유지보수성: 이름, 중복, 결합, 책임, 조기 추상화, 도메인과의 일관성.
관찰 가능성: 로그, 메트릭, 추적, 알림, 변경이 프로덕션 운영에 영향을 미칠 때 유용한 오류 메시지.

자세한 체크리스트는 references/review-checklist.md를 사용하세요.

게이트 5: 보고서 작성

references/report-template.md를 사용하여 CODE-REVIEW.md를 생성하거나 업데이트합니다. 기본 위치는 현재 작업 공간 루트입니다. 사용자가 다른 경로를 제공하면 수락합니다.

요구사항:

아티팩트 마커와 모든 필수 섹션 마커를 보존합니다.
기준, 헤드, 머지 베이스, 커밋 수, 변경된 파일, 표준 소스, 사양 소스를 기록합니다.
Spec 섹션과 Standards 섹션을 분리하여 유지합니다. Spec 결과를 Standards로 또는 그 반대로 옮기지 마세요.
안정적인 결과 ID를 사용하세요: CR-001, CR-002 등. 변경 사항을 기록하지 않고 승인된 결과의 번호를 다시 매기지 마세요.
결과당 하나의 심각도를 사용하세요: blocking, recommended, 또는 note. references/severity-baseline.md를 따르세요.
각 결과에 축, 카테고리, 위치, 문제, 증거, 제안, 참조, 검증 단계를 제공합니다.
카운트 마커가 결과와 정확히 일치하도록 합니다.
요약 카운트가 카운트 마커와 일치하도록 합니다.
각 결과를 증거 및 제안된 검증과 추적 가능성 섹션에 매핑합니다.
Spec 검토가 수행되었는지 생략되었는지 명시합니다. 생략된 경우 게이트 2의 정확한 문장을 포함합니다.
카테고리에 결과가 없으면 No findings를 작성합니다. 빈 섹션을 남기지 마세요.
비밀, 개인 데이터, 또는 고객 데이터를 포함하지 마세요. [REDACTED]로 편집합니다.
승인 판결, LGTM, 또는 Ship it을 포함하지 마세요.

게이트 6: 검증

이 SKILL.md에 대한 검증기 경로를 확인하고 실행합니다:

python3 skills/code-review/scripts/validate_review.py CODE-REVIEW.md

옵션:

--strict                     경고를 실패로 처리합니다.
--json                       기계 판독 가능 보고서를 출력합니다.
--min-findings N             최소 N개의 결과를 요구합니다. 기본값은 0입니다.
--require-spec               Spec 검토가 생략된 경우 실패합니다.
--require-standards-sources  표준 소스가 나열되지 않은 경우 실패합니다.

모든 오류를 수정하고 검증기를 다시 실행하세요. 검증에 실패한 보고서를 제공하지 마세요.

Python을 사용할 수 없는 경우 references/validation-checklist.md의 수동 체크리스트를 수행하세요.

게이트 7: 핸드오프

보고:

CODE-REVIEW.md가 작성된 위치;
검토된 기준, 머지 베이스, 커밋 수, 변경된 파일;
심각도 및 축별 결과 수;
Spec 검토 상태 및 가장 위험한 Spec 격차;
가장 위험한 Standards 결과 및 영향;
검증 결과;
제한 사항, 제외된 파일, 실행되지 않은 검사;
애플리케이션 코드, 의존성, 또는 설정이 변경되지 않았음을 보고.

수정 또는 수정 계획을 제안하되, 사용자가 명시적으로 요청하지 않는 한 코드를 수정하거나, 커밋하거나, 푸시하거나, 풀 리퀘스트를 열지 마세요.

두 축 규칙

축은 다른 질문에 답하며 분리되어야 합니다:

축	질문	일반적인 증거
Spec	변경 사항이 요청된 요구사항을 구현합니까?	이슈, PRD, 사양, 수락 기준
Standards	변경 사항이 저장소 컨벤션 및 엔지니어링 표준을 따릅니까?	CONTRIBUTING, ADR, lint/test/CI 설정, 코드 리뷰

결과가 두 축에 모두 존재할 수 있는 경우는 근본 원인이 다르고 수정도 다른 경우에만 가능합니다. 그렇지 않으면 근본 원인을 소유한 축 아래에 한 번 기록하고 참조 필드에서 다른 축을 상호 참조합니다.

예시:

변경 사항이 모든 컨벤션을 따르지만 수락 기준을 생략: 하나의 Spec blocking 결과, Standards 결과 없음.
변경 사항이 요구사항을 구현하지만 인증 우회를 도입: 하나의 Standards blocking 결과, 요구사항이 구현되었지만 안전하지 않다는 Spec 메모.
변경 사항이 요구사항을 문서화되었지만 좋지 않은 패턴으로 구현: 하나의 Standards recommended 결과, "요구사항 충족"인 Spec 항목.

아티팩트 계약

CODE-REVIEW.md는 다음으로 시작합니다:

<!-- code-review:artifact type=review version=1 -->

필수 섹션은 마커를 사용합니다:

<!-- code-review:section id=summary -->
<!-- code-review:section id=context -->
<!-- code-review:section id=spec -->
<!-- code-review:section id=standards -->
<!-- code-review:section id=validation -->
<!-- code-review:section id=evidence -->
<!-- code-review:section id=assumptions -->
<!-- code-review:section id=traceability -->

Spec 섹션은 상태 마커도 사용합니다:

<!-- code-review:spec status=performed -->
<!-- code-review:spec status=skipped -->

카운트 마커는 결과와 일치해야 합니다:

<!-- code-review:counts blocking=1 recommended=2 note=0 -->

각 결과는 제목 바로 앞에 마커를 사용합니다:

<!-- code-review:finding id=CR-001 axis=standards severity=blocking category=security status=open -->
### CR-001: 짧은 결과 제목

각 결과 본문에는 다음이 포함됩니다:

Axis: Spec 또는 Standards
Severity: Blocking, Recommended, 또는 Note
Category: spec-gap, scope, correctness, security, tests, api, performance, maintainability, 또는 observability
Location: path/to/file.ext:42, path/to/file.ext, 또는 코드 위치가 없는 Spec 결과의 경우 n/a
Problem: 결함, 위험, 또는 격차
Evidence: diff 스니펫, 파일과 라인, 스펙 요구사항, 또는 재현 가능한 관찰

…

rmsaitam/code-review

code-review란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

문서

코드 리뷰

사용 시기

사용하지 말아야 할 경우

필수 규칙

모드

워크플로우

게이트 1: 리뷰 기준 고정

게이트 2: 사양 찾기

게이트 3: 저장소 표준 로드

게이트 4: 카테고리별 검토

Spec 축

Standards 축

게이트 5: 보고서 작성

게이트 6: 검증

게이트 7: 핸드오프

두 축 규칙

아티팩트 계약

관련 스킬

steipete/bluebubbles

steipete/eightctl

steipete/blucli

steipete/bear-notes

steipete/camsnap

steipete/gifgrep