변경 검토
이 스킬은 화면이 아닌 변경 사항을 검토합니다. 변경 범위를 해석하고, 변경된 파일이 영향을 미치는 표면으로 확장하며, diff의 양쪽을 모두 읽고 각 발견 사항을 분류합니다.
범위는 이 스킬이 자체적으로 처리합니다. 도메인 규칙은 better-* 스킬에 속합니다. 심각도, 통합, 적용 범위, 상한 및 판정은 better-interface에 속하며, 이 스킬은 해당 스킬에 검토를 넘깁니다.
정확성, 테스트, 보안 및 성능은 프로젝트의 일반 코드 검토에 속합니다. 해당 우려 사항을 한 번 언급하고 넘어가십시오.
변경 사항, 코드베이스가 아닌
작성자는 "내가 이걸 더 나빠지게 만들었나?"라고 묻고 있습니다. 변경 사항이 초래한 것을 보고하고, 단지 건드렸을 뿐인 것에 대해서는 대부분 침묵을 지키십시오. 기존 발견 사항 세 개는 예의지만, 서른 개는 다른 검토이며 아무도 요청하지 않은 것입니다.
변경 사항에 대한 의견을 형성하기 전에 먼저 읽으십시오. 명시된 의도가 무엇이 불완전한지 결정하며, 대충 훑어본 diff는 다음 헝크(hunk)에서 이미 수정한 코드에 대한 발견 사항을 만들어냅니다.
핵심 원칙
1. 변경 범위를 먼저 해석하십시오
전체 호출이 대상이므로, /interface-review pr 482는 풀 리퀘스트 482를 검토합니다. 범위 해석에는 허용되는 대상과 각 대상이 어떻게 해석되는지가 나와 있습니다.
대상이 제공되지 않으면 다음 순서대로 해석하고 첫 번째 일치 항목에서 중단하십시오:
HEAD가git merge-base origin/<default-branch> HEAD보다 앞서 있는 경우: 해당 범위 더하기 커밋되지 않은 변경 사항. 커밋 수와 커밋되지 않은 파일 수는 별도로 명시합니다.- 워킹 트리가 더티(dirty)인 경우: 커밋되지 않은 변경 사항.
- 둘 다 아닌 경우: 검토할 변경 사항이 없습니다. 중단하고 변경 사항이 없으면 발명하기보다 질문하십시오에 따라 질문하십시오.
순서가 중요합니다. 워킹 트리를 먼저 확인하면 하나의 잘못된 포맷팅 편집이 12개의 커밋이 있는 브랜치를 가릴 수 있으며, 보고서는 여전히 전체 적용 범위를 주장합니다.
락파일, 스냅샷, 생성된 출력물, 벤더 코드 및 바이너리는 제외하고, 제외한 대상을 명시하십시오. 제외 후 범위가 비어 있으면 다른 경로를 통해 동일한 지점에 도달합니다.
2. 변경 사항이 없으면 발명하기보다 질문하십시오
클린 트리이고 머지 베이스보다 앞선 것이 없다면, 사용자가 존재하지 않는 변경 사항을 검토하도록 요청한 것입니다. 절대 스스로 HEAD~1..HEAD로 대체하지 마십시오. 마지막 커밋은 우연히 도착한 무엇이든, 종종 머지 커밋이거나 다른 사람의 작업이며, 이에 대한 보고서는 사용자가 의도한 것에 대한 보고서와 구별할 수 없습니다.
발견한 저장소 사실을 명시한 다음, 옵션을 제시하고 기다리십시오. 검토할 내용 없음에는 수집할 사실이 나와 있습니다:
- 마지막 커밋,
HEAD~1..HEAD, 짧은 SHA와 제목으로 표시되어 사용자가 선택하기 전에 무엇을 얻게 될지 볼 수 있습니다. - 사용자가 지정한 대상:
pr <n>, 브랜치, ref 또는 범위. 변경 범위를 먼저 해석하십시오에 따라 해석됩니다. - 전체 저장소 인터페이스 감사: 변경 검토가 아닙니다. 이 스킬의 범위 블록, 상태 또는 기존 섹션 없이 저장소 범위 검토로
better-interface에 넘기십시오. 변경 사항이 없으면 모든 발견 사항은 기존 항목이며 분류는 아무것도 말해주지 않습니다.
질문하기 전에 현재 브랜치에 열린 풀 리퀘스트가 있는지 확인하고, 있으면 먼저 제안하십시오. 커밋이 이미 도착한 브랜치는 변경 사항 없음으로 해석되지만, 해당 풀 리퀘스트는 사용자가 정확히 의도한 것입니다.
제외 후 범위가 비어 버린 경우, 어떤 파일이 제외되었는지 말하고 같은 방식으로 질문하십시오. 아무것도 없는 검토를 Approve로 보고하지 마십시오.
3. diff는 표면이 아닙니다
변경된 파일은 증거이지 검토 대상이 아닙니다. 파일의 blast radius는 파일이 렌더링되는 표면의 집합입니다. 해당 표면을 검토하십시오.
기본적으로 blast radius를 한 단계 확장하십시오: 직접 임포트하는 파일과 호출자. 디자인 토큰, 테마 값 및 공유 프리미티브의 경우에만 두 번째 단계까지 확장하십시오. 한 줄이 전체 제품에 영향을 미칠 수 있기 때문입니다.
최대 5개의 소비자를 범위 해석의 규칙에 따라 순서대로 검토하고, 확장하지 않은 수를 명시하십시오. 경계 없는 스윕은 주장하는 적용 범위를 뒷받침할 수 없으며, 명시되지 않은 한계는 완전성으로 읽힙니다.
4. 제거된 줄을 읽으십시오
회귀(regression)는 변경 후 상태에서는 보이지 않습니다. 모든 헝크의 - 쪽을 제거된 신호와 대조하여 읽으십시오.
신호는 단서일 뿐 발견 사항이 아닙니다. 변경 사항에서 이를 대체하는 것이 없을 때에만 제거가 회귀이며, 해당 판단은 도메인 스킬이 소유합니다. 일치하지 않는 각 제거를 해당 소유자에게 전달하고, 해당 스킬이 확인한 것만 보고하고 상태를 Regression으로 지정하십시오. 이는 작성자에게 새로운 실수를 저지른 것이 아니라 이전에 작동하던 것을 망가뜨렸음을 알려줍니다.
5. 모든 발견 사항을 분류하십시오
모든 발견 사항에 하나의 상태를 부여하십시오:
Introduced: 변경 사항이 생성함.Regression: 변경 사항이 이전에 올바르던 것을 약화시킴.Pre-existing: 건드린 코드에 존재하지만 이 변경 사항으로 인한 것은 아님.
어떤 파일에 있는지가 아니라 diff가 건드린 대상에 따라 상태를 결정하십시오. 변경 사항이 전혀 건드리지 않은 줄은 헝크에서 세 줄 떨어져 있어도 Pre-existing입니다. 필요한 경우 베이스 ref를 기준으로 확인하십시오:
git blame -L <line>,<line> "$BASE" -- path/to/file
모든 발견 사항을 상태와 함께 전달하고, better-interface가 상한 및 판정 규칙을 적용하도록 하십시오.
6. 변경 사항을 명시된 의도에 맞추십시오
풀 리퀘스트 제목과 본문, 연결된 이슈 및 커밋 메시지를 읽은 다음, 인터페이스가 주장하는 바를 제공하는지 검토하십시오.
이것이 불완전한 변경 사항을 드러내는 방법입니다. 표면 검토로는 이를 볼 수 없습니다. 왜냐하면 표면 검토는 존재하는 상태를 검사하는 반면, 여기서 핵심은 없는 상태이기 때문입니다:
- 일부 상태에는 적용되었지만 모든 상태에는 적용되지 않은 새로운 변형, 크기 또는 테마: 호버, 포커스, 활성, 비활성, 로딩, 선택됨.
- 프로젝트가 유지 관리하는 번역 카탈로그에 항목이 없는 새로운 사용자 대상 문자열.
- 빈 상태, 로딩 상태, 오류 상태, 비활성 상태 또는 좁은 너비 상태가 없는 새로운 컴포넌트.
- 하나의 표면에는 추가되었지만 이미 동반 컨트롤을 가지고 있는 형제 표면에는 추가되지 않은 컨트롤.
범위 확장(scope creep)을 보고하지 마십시오. 변경 사항이 너무 많은 일을 하는지 여부는 프로세스 질문이지 인터페이스 질문이 아닙니다.
7. 검토를 better-interface에 넘기십시오
better-interface에 범위 블록, 영향을 받는 표면 및 모든 발견 사항의 상태를 전달하십시오. 그러면 도메인 스킬로 라우팅하고, 심각도를 적용하며, 통합하고, 상한을 적용하며 판정을 내립니다.
better-interface를 사용할 수 없는 경우, 해석된 범위와 파일 인벤토리를 보고하고, 누락된 스킬임을 명시한 후 중단하십시오. 심각도 척도, 상한 또는 판정을 발명하지 마십시오.
8. 워킹 트리를 절대 변경하지 마십시오
변경 검토는 읽기 전용입니다. 체크아웃도 포함됩니다. 풀 리퀘스트 ref를 가져오고(fetch), 절대 체크아웃하지 마십시오. git fetch는 .git에만 쓰므로 허용됩니다. gh pr checkout, git checkout, git switch 및 git stash는 작성자가 열어둔 파일을 덮어씁니다. 로컬 편집과 충돌하거나 이를 폐기하므로 절대 허용되지 않습니다.
렌더링된 확인은 옵트인(opt-in)입니다. 프로젝트가 저렴한 미리보기를 제공하거나 사용자가 렌더링된 검토를 요청하지 않는 한, 시각적 및 런타임 주장을 **미확인(Not verified)**으로 표시하십시오. 요청하는 경우, 격리된 작업 트리(git worktree add /tmp/review-<n> refs/remotes/pr/<n>)를 사용하고 완료되면 제거하십시오.
완료하기 전에
| 실수 | 해결책 |
|---|---|
| 하나의 잘못된 편집이 브랜치 대신 검토됨 | 워킹 트리보다 먼저 merge-base를 확인하고, 두 개수를 모두 보고 |
| 변경 사항이 없어 마지막 커밋이 검토됨 | 사실을 명시하고 마지막 커밋, 명명된 대상 또는 저장소 감사를 제안 |
| 헝크가 소비자 없이 검토됨 | 한 단계 확장, 토큰과 프리미티브의 경우 두 단계 확장하고 건너뛴 것을 명시 |
diff의 + 쪽만 읽음 | - 쪽에서 제거된 접근성, 포커스, 모션 및 텍스트 신호 검색 |
| 동등한 대체가 회귀로 보고됨 | 제거를 소유자에게 전달하고, 확인된 것만 보고 |
| 제거가 새로운 실수로 보고됨 | Regression 상태로 지정하여 작성자가 이전에 작동했음을 알게 함 |
헝크 근처의 줄이 Introduced로 상태 지정됨 | diff가 건드린 대상에 따라 상태를 지정하고, 베이스 ref에 대한 git blame으로 확인 |
| 검토하기 위해 풀 리퀘스트가 체크아웃됨 | ref를 가져오고(fetch) 그 자리에서 검토 |
| 검토된 ref에는 없는 줄 번호 인용 | 범위 블록에 명명된 head ref에 대해 인용 |
| 여기서 심각도 척도 또는 발견 사항 상한 재진술 | better-interface에 위임 |
| 보고서에 정확성, 테스트 또는 보안 발견 사항 포함 | 우려 사항을 한 번 언급하고, 프로젝트의 코드 검토를 가리킨 후 삭제 |
검토 출력 형식
범위 블록으로 시작하십시오:
| 필드 | 값 |
|---|---|
| 대상 | branch, working, staged, pr 482 또는 입력된 범위 |
| 베이스 ref | origin/main at a1b2c3d |
| 헤드 ref | refs/remotes/pr/482 at e4f5g6h |
| 커밋 | 7개 커밋됨, 2개 파일 커밋되지 않음 |
| 범위 내 파일 | 제외 후 12개 |
| 제외됨 | pnpm-lock.yaml, src/__snapshots__/: 락파일 및 스냅샷 |
| 확장된 표면 | CheckoutPage, SettingsPanel; Button 소비자 3개는 확장되지 않음 |
그 뒤에 적용 범위 표가 변경 없이 따라옵니다. 변경 범위에 증거가 없는 도메인은 Not reviewed: no evidence in the change scope이며, 이는 공백이 아니라 적용 범위 진술입니다.
그런 다음 발견 사항. 모든 발견 사항을 분류하십시오에 따라 Status 열을 포함합니다:
| 심각도 | 도메인 | 상태 | 위치 | 이전 | 이후 | 이유 |
|---|---|---|---|---|---|---|
| HIGH | 접근성 | Regression | src/Dialog.tsx:42 | aria-label="Close"가 이 변경에서 제거됨 | 아이콘 전용 컨트롤에 aria-label="Close" 복원 | 닫기 컨트롤은 이 변경 전에 접근 가능한 이름이 있었지만 이제 없음 |
Introduced 또는 Regression 발견 사항이 없으면 표를 생략하고 "이 변경 사항에 실행 가능한 인터페이스 발견 사항이 없습니다."라고 명시하십시오.
그런 다음 Pre-existing 발견 사항(최대 3개, 가장 높은 심각도 순), 이 변경 사항의 책임이 아님을 간결하게 명시합니다. 없으면 섹션을 생략합니다.
| 심각도 | 도메인 | 위치 | 문제 |
|---|---|---|---|
| MEDIUM | 타이포그래피 | src/Toolbar.tsx:7 | 숫자 배지가 비례 폰트를 사용함; 이 변경 이전부터 있던 문제 |
상한과 판정은 Introduced 및 Regression만 다룹니다. Pre-existing 발견 사항은 상한 밖에 있으므로, 레거시 파일을 건드리는 것이 전체 파일 감사로 이어질 수 없습니다. 또한 판정 밖에 있으므로, 유일한 발견 사항이 기존 항목인 변경은 Approve입니다.
HIGH가 남아 있으면 Block으로, 그렇지 않으면 Approve로 끝내고, 나머지 발견 사항은 표에 남겨 작업할 항목으로 둡니다. better-interface를 사용할 수 있는 경우, 심각도 척도와 상한은 해당 스킬에서 가져옵니다.