feat(skill): route fixes, delivery report, composition diversity, platform refresh
- route table: extension route for products with an existing visual language, feedback row, derived state tokens stay local - completion: blocking 0 plus reported unverified; hard-gate surface is the touched scope; delivery report starts with what and how to open - design.md created at step 0 with a skeleton, fingerprint line and change log; product-surface rubric reading; direction delegation states the chosen card and reason - layout: hero families, nav forms, footer forms; art-direction page convergence 6 axes; genre sections; image treatments; placeholder conventions; multi-screen order; Tailwind theme mapping - platform: scroll-driven examples, anchor positioning, canvas OT, three/R3F pins, shadcn style prefixes, Safari 26 notes, subgrid - design-gate: four result states, exit codes, cwd module resolution, --url/--out-dir/--strict, oklch contrast, dead selector word match - Korean font budget split from the Latin baseline
This commit is contained in:
Yun Chan
parent
9bcb45cbd3
commit
88c11682b1
51 changed files with 5834 additions and 2259 deletions
|
|
@ -1,6 +1,6 @@
|
|||
# change-review — diff·PR·커밋 범위 리뷰
|
||||
|
||||
**리뷰 경로**에서 연다. 화면 전체가 아니라 **git diff·PR·커밋 범위로 정의된 변경**을 스코프로 잡는 요청("이 PR 봐줘", "이 브랜치 확인해줘", "방금 커밋 리뷰해줘", "이거 고친 거 회귀 있는지 봐줘")이 트리거다. 화면 전체를 감사할 때는 이 문서가 아니라 [preflight.md](preflight.md)·[audit-gate.md](audit-gate.md)를 쓴다. 이 문서가 소유하는 것은 **스코프를 어떻게 잡는가**와 **finding에 어떤 상태를 매기는가** 두 가지뿐이다. 무엇이 얼마나 나쁜가(심각도·에스컬레이션·저비용 수정 사다리)는 [critique.md](critique.md) 소관이며, 이 문서는 그것을 다시 정의하지 않는다. 정확성·테스트·보안·성능은 프로젝트의 일반 코드 리뷰 소관이다 — 한 번만 짚고 넘어간다[SKILL-INTERFACE-REVIEW].
|
||||
**리뷰 경로**에서 연다. 화면 전체가 아니라 **git diff·PR·커밋 범위로 정의된 변경**을 스코프로 잡는 요청("이 PR 봐줘", "이 브랜치 확인해줘", "방금 커밋 리뷰해줘", "이거 고친 거 회귀 있는지 봐줘")이 트리거다. 화면 전체를 감사할 때는 이 문서가 아니라 [preflight.md](preflight.md)·[audit-gate.md](audit-gate.md)를 쓴다. 이 문서가 소유하는 것은 **스코프를 어떻게 잡는가**와 **finding에 어떤 상태를 매기는가** 두 가지, 그리고 화면 감사까지 포함한 **리뷰 경로 전체의 비변경 계약**(§1-1)이다. 무엇이 얼마나 나쁜가(심각도·에스컬레이션·저비용 수정 사다리)는 [critique.md](critique.md) 소관이며, 이 문서는 그것을 다시 정의하지 않는다. 정확성·테스트·보안·성능은 프로젝트의 일반 코드 리뷰 소관이다 — 한 번만 짚고 넘어간다[SKILL-INTERFACE-REVIEW].
|
||||
|
||||
이 문서의 **필수 절차**는 리뷰를 진행하는 과정의 규칙이다. 하드 게이트·프로젝트 계약·관찰 후보라는 판정 위계는 finding 자체에만 붙인다 — 절차 규칙을 하드 게이트라 부르면 심각도 매핑(하드 게이트 = Blocking)과 섞인다.
|
||||
|
||||
|
|
@ -8,6 +8,8 @@
|
|||
|
||||
| 상황 | 읽을 곳 |
|
||||
|---|---|
|
||||
| 리뷰하다가 게이트 설치·빌드·의존성 추가가 필요해 보인다 | §1-1 |
|
||||
| 렌더를 볼 수 없는데 디자인 리뷰를 요청받았다 | §11 "렌더가 없을 때" |
|
||||
| 리뷰 대상 자체가 뭔지부터 정해야 한다 | §2 |
|
||||
| 락파일·스냅샷 같은 게 스코프에 잡혀 노이즈가 커진다 | §3 |
|
||||
| 토큰 파일 하나 고쳤는데 몇 화면에 퍼지는지 모른다 | §4 |
|
||||
|
|
@ -37,7 +39,34 @@
|
|||
- **허용**: `git fetch`(원격 ref를 `.git` 안에만 쓴다), `git show <ref>:<path>`로 파일 읽기, `git blame`, `git diff`, `git log -L`, `git grep <ref>`.
|
||||
- **금지**: `git checkout <ref>`, `git switch <ref>`, `git stash`, `git reset --hard`, 포지 CLI의 `pr checkout`류 명령.
|
||||
- **파일은 워킹트리 사본이 아니라 `git show <ref>:<path>`로 읽는다.** 특히 포크에서 온 PR은 워킹트리와 다른 파일일 수 있다.
|
||||
- **렌더 검증이 필요하면**: 옵트인이다. 프로젝트가 저렴한 프리뷰(스테이징 배포 등)를 이미 제공하거나 사용자가 명시적으로 요청하지 않는 한, 시각·런타임 주장은 **"미검증"**으로 남긴다(§11). 격리가 필요하면 저장소 안 디렉터리에 `git worktree add`로 임시 워크트리를 만들고 끝나면 `git worktree remove`로 정리한다 — `rm -rf`로 지우지 않는다. 리뷰 대상 저장소가 무엇이든 같은 위생을 지킨다[SKILL-INTERFACE-REVIEW].
|
||||
- **렌더 검증이 필요하면**: 옵트인이다. 프로젝트가 저렴한 프리뷰(스테이징 배포 등)를 이미 제공하거나 사용자가 명시적으로 요청하지 않는 한, 시각·런타임 주장은 **"미검증"**으로 남긴다(§11). 격리가 필요하면 저장소 안 디렉터리에 `git worktree add`로 임시 워크트리를 만들고 끝나면 `git worktree remove`로 정리한다 — `rm -rf`로 지우지 않는다. 리뷰 대상 저장소가 무엇이든 같은 위생을 지킨다[SKILL-INTERFACE-REVIEW]. 워크트리 생성도 저장소에 흔적을 남기므로 §1-1의 동의 대상이다.
|
||||
|
||||
### 1-1. 리뷰 경로 전체의 비변경 계약
|
||||
|
||||
**필수 절차.** 위 git 규칙은 diff 리뷰만의 것이 아니다. SKILL.md의 **리뷰(평가만) 경로 전체** — diff·PR 리뷰든, 화면 감사(5′)든 — 는 사용자의 프로젝트를 바꾸지 않는다. 평가만 요청한 사용자의 워킹트리가 리뷰 뒤에 더러워져 있으면, 그것은 리뷰가 아니라 요청하지 않은 변경이다(레드팀 01 F10: 게이트 설정 생성·devDependency 설치·빌드 산출물이 실제로 남는 경로가 있었다).
|
||||
|
||||
| 하지 않는 것 | 이유 |
|
||||
|---|---|
|
||||
| `tools/design-gate.mjs --init`으로 프로젝트에 `gate.config.json`을 만드는 것 | 프로젝트 파일 생성이다 |
|
||||
| `npm i -D`·`pnpm add -D` 등 의존성 설치, `package.json`·락파일 수정, `"verify"` 같은 스크립트 추가 | 의존성·설정 변경이다. 스크립트에 스킬 설치 경로(사용자 홈)가 박혀 팀원·CI에서 깨지기도 한다 |
|
||||
| 프로젝트 디렉터리 안에 빌드 산출물(`dist/` 등)·스크린샷·보고서 파일을 남기는 것 | 리뷰 결과는 응답으로 전달한다 |
|
||||
| `design.md` 작성·추기 | 6단계는 리뷰 경로에 없다 |
|
||||
| 전역 도구 설치(`npm i -g`, 브라우저 내려받기) | 사용자 환경 변경이다. 크기가 수백 MB일 수 있다 |
|
||||
|
||||
**측정이 필요할 때 할 수 있는 것**
|
||||
|
||||
1. **프로젝트 밖 임시 디렉터리에서 돌린다.** 게이트 설정·캡처·측정 스크립트는 하네스의 스크래치 디렉터리나 OS 임시 디렉터리에 만들고, 스킬 경로의 `tools/design-gate.mjs`를 그 설정으로 실행한다. 결과 파일도 그곳에 둔다. 떠 있는 주소가 있으면 설정 파일도 필요 없다 — 아래 명령은 프로젝트 디렉터리에 아무것도 쓰지 않는다(`--out-dir`을 빼면 리포트 파일 없이 표준 출력으로만 낸다). `--init`은 리뷰 경로에서 쓰지 않는다.
|
||||
|
||||
```
|
||||
node <스킬>/tools/design-gate.mjs --url <주소> --out-dir <프로젝트 밖 임시 경로>
|
||||
```
|
||||
|
||||
`url`만 준 실행은 파일을 읽는 검사(죽은 선택자·토큰 위생)가 미검증으로 남는다. 게이트가 `미검증`으로 낸 줄과 브라우저·`puppeteer-core`가 없어 못 돌린 계층은 §11의 미검증으로 옮긴다. 옵션과 종료 코드는 [audit-gate.md](audit-gate.md) "게이트 실행"에 있다.
|
||||
2. **이미 떠 있는 것을 쓴다.** 사용자가 띄워 둔 개발 서버, 배포된 URL, 스테이징 프리뷰처럼 프로젝트를 바꾸지 않고 접근할 수 있는 렌더를 우선한다.
|
||||
3. **바꿔야만 측정할 수 있으면 먼저 묻는다.** 빌드·서버 기동이 프로젝트 안에 파일을 쓰거나, 도구 설치가 필요하면, 무엇이 생기고 어떻게 지울지 한 줄로 말하고 동의를 받는다. 이 질문은 0단계 인터뷰 라운드가 아니라 리뷰 범위 확인(§2와 같은 축)이다. 물었으면 턴을 끝낸다.
|
||||
4. **못 돌린 검사는 미검증이다.** 동의가 없거나 도구가 없으면 그 항목을 §11의 "미검증"으로 남긴다. 소스만 보고 시각 주장을 통과로 추정하지 않는다.
|
||||
|
||||
리뷰 중에 사용자가 "고쳐 줘"라고 하면 그때부터는 리뷰 경로가 아니다. SKILL.md 0단계 경로 판정으로 국소·연장 중 어디로 가는지 정하고 **경로를 바꿨다고 말한 뒤** 그 경로의 규칙(5단계 하드 게이트, 6단계 기록)을 따른다. "리뷰하면서 고칠 수 있는 건 고쳐 줘"도 같다 — 손댄 섹션 수로 경로를 판정하고, 리뷰 경로의 자동 적용이라는 이유로 5·6단계를 건너뛰지 않는다.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -280,12 +309,23 @@ finding 형식·표 컬럼(심각도·위치·무엇·왜·고침)은 새로 만
|
|||
|---|---|---|---|---|---|
|
||||
| Regression | Blocking | `src/Dialog.tsx:42` | `aria-label="닫기"`가 이 변경에서 제거됨 | 하드 게이트 — 닫기 컨트롤이 이 변경 전에는 접근 가능한 이름을 갖고 있었고 지금은 없다 [WCAG-NRV] | `aria-label="닫기"` 복원 |
|
||||
|
||||
`Introduced`·`Regression`이 하나도 없으면 표를 생략하고 critique.md §13 템플릿을 그대로 쓴다: **"이 흐름에서 Blocking·Important 발견 없음. Polish 관찰 후보는 \<있으면 나열, 없으면 없음\>."**
|
||||
`Introduced`·`Regression`이 하나도 없으면 표를 생략하고 critique.md §13 템플릿을 그대로 쓴다: **"이 흐름에서 Blocking·Direction·Important 발견 없음. Polish 관찰 후보는 \<있으면 나열, 없으면 없음\>."**
|
||||
|
||||
### Pre-existing 섹션
|
||||
|
||||
§6에서 분리한 목록을 심각도 높은 순으로 따로 둔다. "이 변경의 책임이 아니다"라고 평이하게 적는다. 없으면 섹션 자체를 생략한다. 이 섹션은 critique.md §4의 심각도 집계에 들어가지 않는다(§12).
|
||||
|
||||
### 렌더가 없을 때 — 멈추지 않고 나눠서 보고한다
|
||||
|
||||
**우선 규칙.** diff·PR 리뷰는 렌더가 없어도 멈추지 않는다. 코드로 확정 가능한 것과 렌더가 있어야 하는 것을 나눠, 뒤쪽은 미검증으로 보고한다. 스크린샷을 요청하고 턴을 끝내는 것은 화면 전체의 시각 평가만 요청받았고 볼 것이 하나도 없을 때다. 변경분 리뷰에서는 코드로 확정되는 finding을 먼저 내고, 보고 끝에서 스크린샷이나 프리뷰 주소를 한 번 청한다.
|
||||
|
||||
| 구분 | 예 | 보고 |
|
||||
|---|---|---|
|
||||
| 코드로 확정 가능 | 토큰 대신 들어온 색·radius·간격 리터럴, 없는 토큰 참조 / `aria-label` 삭제, `button` → `div`, `alt` 누락, 제목 단계 건너뜀 / 대체 스타일 없는 `outline: none`, `prefers-reduced-motion` 분기 삭제 / 삭제된 상태 분기(빈·오류·로딩), 지워진 문구 | finding으로 낸다. 미검증이 아니다 |
|
||||
| 렌더가 있어야 함 | 실제 대비(합성 뒤 색), 줄바꿈·잘림·겹침, 뷰포트별 배치와 가로 스크롤, 터치 타깃의 실측 크기, 포커스 표시가 보이는지, 모션의 체감, 시각 위계와 루브릭 점수 | 미검증으로 낸다. 무엇이 있으면 검증되는지 적는다 |
|
||||
|
||||
코드로 확정한 finding에는 `path:line`을 붙이고, 렌더가 필요한 항목을 코드만 보고 통과·실패로 단정하지 않는다(증거 방향성, critique §9). 이 규칙은 "코드로 확정 가능" 범위를 미검증으로 뭉개지 말라는 뜻이기도 하다.
|
||||
|
||||
### 미검증 · 미점검
|
||||
|
||||
렌더 검증을 하지 않았거나(§1, 옵트인) 확인할 수단이 없는 주장은 [critique.md](critique.md) §8의 두 상태를 그대로 구분해 쓴다 — **미검증**(시도했지만 도구·권한·환경 제약으로 확인 못 함, 통과로 추정하지 않는다)과 **미점검**(§4의 파급 범위 확장에서 의도적으로 뺀 컨슈머 등, "확인 안 함"이라고 명시). 둘 다 finding 개수·심각도 집계에 넣지 않는다.
|
||||
|
|
@ -298,6 +338,6 @@ finding 형식·표 컬럼(심각도·위치·무엇·왜·고침)은 새로 만
|
|||
|
||||
**심각도 스케일·에스컬레이션 트리거·finding 상한·저비용 수정 우선순위는 이 문서가 소유하지 않는다.** 심각도·에스컬레이션·저비용 수정은 [critique.md](critique.md) §4~§5, finding에 상한을 두지 않는 원칙은 §7을 따른다. 이 문서가 하는 일은 findings에 상태(§6)를 매겨 그 심각도 체계에 넘기는 것뿐이다.
|
||||
|
||||
- `Pre-existing`은 critique.md §4의 심각도 집계에서 제외한다 — 레거시 결함만 있는 변경은 Blocking·Important 집계가 비게 된다.
|
||||
- `Pre-existing`은 critique.md §4의 심각도 집계에서 제외한다 — 레거시 결함만 있는 변경은 Blocking·Direction·Important 집계가 비게 된다.
|
||||
- `Introduced`·`Regression`만 심각도 집계에 들어간다.
|
||||
- critique.md가 아직 없거나 심각도 매핑을 못 찾으면, 스코프와 파일 인벤토리만 보고하고 무엇이 누락됐는지 밝힌 뒤 멈춘다 — 심각도 스케일을 이 문서에서 임의로 지어내지 않는다[SKILL-INTERFACE-REVIEW].
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue