GPT 독립 기술 검토 및 Claude 인계

원본: projects/skill-lens/engineering/02-gpt-independent-review-claude-handoff.md

• 작성: 2026-11-09
• 목적: SkillLens Zero 리빌딩의 독립 검토 결과와 Claude가 바로 이어서 처리할 작업·확인 질문을 전달한다.
• 검토 방식: GitHub 저장소의 현재 파일을 읽은 정적 코드·문서 검토.
• 주의: 이 문서는 테스트 통과 보고서가 아니다. 이번 검토에서는 코드를 실행하거나 수정하거나 배포하지 않았다.

1. 검토 기준과 현재 기준점

저장소 상태

주요 확인 파일과 blob SHA:

• Worker(main): workers/skilllens-api/worker.js blob 657c64747895c2a378daa1f4629178a40b926bcb
• API 여정(zero): tests/e2e/journey-r1.mjs blob 87af2fcb96de4bb93c049ca22a084df6337d3650
• 로컬 여정 실행기(zero): tests/e2e/run-journey.sh blob 999d18c59ca563dcf22a47eec72f91aaa418a1d5
• React Lens(zero): zero/app/ui/components.tsx blob 7a747a277d9f0b27e0b4f74138308ff82779acc5
• 화면 검사기(zero): zero/app/scripts/screen-check.mjs blob 51f1a9b947ae212062b21fa74414408a295919c2
• 디자인 시스템 수신 기록: zero/app/ui/SOURCE.md blob f95a76c110f8f9f511d2d62240a494a42ef7b343
• 구조 확정안: projects/skill-lens/product/plan/00-structure.md blob 26c49aec360a336cfafdfd9c575b358e0ed601b8
• 화면 등록표: projects/skill-lens/product/plan/03-screens.md blob d0f54b750dea08d9b419714334844544ea84f689
• 서버 범위표: projects/skill-lens/product/plan/06-server-coverage.md blob 0d9c8f14cf8a1bb026e0fd9d04569bdcc63ec864
• 결정 기록: projects/skill-lens/product/decisions.md blob a6bea7e508baf32f4020982a6942e4c56d32870e

반드시 유지할 제품·협업 규칙

• DEC-247: Zero 서버 변경은 운영 DB 복사본에 붙인 시험 서버에서 검증한다. 운영 서버에 바로 반영하지 않는다.
• DEC-249: 기능은 Simple/Full에서 빠짐없이 확인하되 화면·메뉴·배치·CSS·마크업은 재사용하지 않는다. API·데이터·산식은 화면 계약·권한·상태 전이를 확인한 뒤 재사용하거나 수정한다. Zero 정책이 기존 동작보다 우선한다.
• DEC-250: main 반영은 PM·Claude·GPT의 3자 합의와 PM 승인이 있어야 한다. 이번 검토 결과만으로 main에 변경하지 않는다.
• DEC-252: 기준일과 목표는 PM이 정한다. 구현 방식·검증 조건을 찾고 품질 기준을 유지한다.
• 1회차 전체 여정은 운영자 조직 생성(O-03) → 관리자 온보딩 → 초대 → 실무자 자기진단 → 관리자 검토 → 결과확정 → 결과 확인 → 강화/개선 → A-22 스킬셋 저장까지다.
• 첫 회차 구현 화면은 54개이며 전부 8판 완성도다. 72개 전체 목록과 54개 구현 범위를 혼동하지 않는다.

2. 최우선 결함: Worker가 Zero flow를 지원하지 않음

판정: 구현 전 해결해야 하는 서버 계약 결함.

main의 Worker 코드에서 확인한 내용:

1. flowOf(v, dflt)는 full과 simple만 인식한다. zero는 유효한 flow로 취급하지 않고 기본값으로 떨어진다.
2. memberEntry(flow, token, next)는 simple이면 Simple 온보딩 URL, 그 외에는 /welcome.html을 반환한다. Zero React 진입 경로가 없다.
3. tenantCreate()는 flowOf(b.flow, 'simple')로 저장한다. 요청에서 flow: 'zero'를 보내도 현재 구현은 Simple로 저장한다.
4. tenantUpdate()는 flow가 simple 또는 full이 아니면 거부한다. zero를 허용하지 않는다.
5. 06-server-coverage는 Zero 조직에 flow='zero'를 두는 방향을 명시한다. 문서의 목표와 현재 Worker 구현이 불일치한다.

Claude 작업 제안

• 운영 Worker를 직접 바꾸지 말고 DEC-247에 따라 시험 서버용 Worker에서 Zero flow 지원을 구현한다.
• flow 계약을 한 곳에서 명시적으로 정의한다: 허용값 simple | full | zero, 기본값, 기존 테넌트 마이그레이션 동작.
• tenantCreate에서 Zero 생성 요청이 실제로 tenants.flow='zero'로 저장되게 한다.
• tenantUpdate의 flow 변경 권한은 기존 슈퍼어드민 전용 정책을 유지하면서 Zero를 허용한다. 일반 관리자 요청으로 flow를 바꿀 수 없어야 한다.
• memberEntry와 관리자/실무자 초대 링크 모두 Zero 전용 React 진입 경로로 이어지게 한다. 단, 실제 Zero 앱의 배포 경로·라우터 계약을 먼저 확인하고 URL을 임의로 정하지 않는다.
• 기존 Simple/Full 조직의 링크, 기본값, 세션, 초대 흐름에 회귀가 없는지 별도 회귀 시험을 둔다.
• flow만 바꾸고 끝내지 말고, Zero에서 달라지는 초대 잠금·결과확정·재진단·회차·스킬셋 개선 정책이 각 Worker handler에서 일관되게 적용되는지 계약별로 대조한다.

Claude에게 확인할 질문

1. Zero 앱의 실제 진입 URL과 라우터는 무엇인가? Worker의 memberEntry가 어떤 URL을 반환해야 하는가? 근거 파일과 함께 제안해 달라.
2. Zero flow를 추가할 때 관리자 초대, 실무자 초대, 비밀번호 설정, 재진단, 결과 메일 링크가 모두 같은 flow resolver를 타는가? 빠진 경로를 찾아 달라.
3. 운영 DB 복사본 기반 시험 Worker를 어떤 구성으로 격리했는가? 시험 DB·환경변수·메일 바인딩이 운영과 분리된 증거를 제시해 달라.
4. Zero flow의 변경 권한과 기존 Simple/Full 회귀 검증을 어떤 테스트로 보장할 것인가?

3. 현재 API 여정은 Zero UI E2E를 증명하지 못함

판정: 기존 시험은 유용한 API 통합 시험이지만, 브라우저 UI 여정의 대체물이 아니다.

• journey-r1.mjs 상단 주석 자체가 화면이 없어 Worker HTTP API를 직접 호출한다고 설명한다.
• O-03 조직 생성 요청에 flow: 'zero'가 없다.
• 생성 뒤 D1에서 flow를 읽지만 행 존재만 확인한다. flow === 'zero' 검증이 없다.
• 따라서 현재 Worker의 기본값 동작에서는 Simple 조직이 만들어져도 이 단계가 통과할 수 있다.
• 이 시험은 브라우저에서 React 화면을 조작하지 않는다. React UI가 실제 API를 호출하는지, 로그인·라우팅·폼 상태·오류 표시가 맞는지 증명하지 못한다.
• 확인 가능한 현재 여정 파일 검색 결과에서 A-22 스킬셋 저장 단계도 확인되지 않는다.

Claude 작업 제안

기존 API 여정은 API 계약·DB 상태 통합 시험으로 유지하되, 별도 Playwright UI E2E를 추가한다.

API 여정 수정:

• O-03 요청에 flow: 'zero'를 명시한다.
• 생성 직후 D1의 tenants.flow === 'zero'를 반드시 assert한다.
• 관리자와 실무자 초대·세션의 응답 flow도 Zero인지 검증한다.
• 링크가 Zero React 앱 경로로 향하는지 메일 파일에서 확인한다.

실제 브라우저 여정:

• local Worker + local D1 + 실제 React UI를 사용한다.
• 운영자 로그인/조직 생성부터 관리자 온보딩, 초대, 실무자 자기진단, 관리자 검토, 결과확정, 결과 화면, 강화/개선, A-22 스킬셋 저장까지 실제 DOM을 클릭·입력해 통과한다.
• API 응답을 route.fulfill 등으로 대체하는 mock을 두지 않는다. API 요청은 실제 local Worker로 전달한다. 테스트에서 mock 응답이 감지되면 실패시킨다.
• 메일은 외부 발송하지 않아도 된다. local D1의 mail_log/outbox와 로컬 메일 파일에서 수신자·종류·링크·상태를 확인한다.
• 최종 단계에서 D1의 개선된 직무/스킬셋 저장 결과까지 검증한다.
• 실패 시 어느 화면/행동/API/DB assertion에서 멈췄는지 보고한다.

Claude에게 확인할 질문

1. API 직접 호출 여정과 Playwright UI 여정을 어떤 파일·명령으로 분리할 것인가?
2. Playwright가 실제 Worker 외에 어떤 요청도 mock하지 않는다는 것을 어떻게 강제하고 증명할 것인가?
3. A-22 저장의 완료 조건은 어떤 API·테이블·상태를 기준으로 확인할 것인가?
4. 첫 화면에서 마지막 A-22까지 실제 사용자 세션과 권한을 유지하는가? 운영자/관리자/실무자 계정이 섞이지 않는가?

4. 로컬 여정 실행기의 비밀값 파일 파괴 위험

판정: 재현 가능한 로컬 시험을 위해 먼저 안전하게 고쳐야 할 실행기 결함.

tests/e2e/run-journey.sh는:

• 기존 workers/skilllens-api/.dev.vars가 있는지 백업하지 않고 덮어쓴다.
• 종료 trap을 .dev.vars를 쓴 뒤, D1 schema/seed 실행 뒤에 등록한다.
• 정상 종료 시에도 기존 파일을 복원하지 않고 무조건 삭제한다.
• 따라서 기존 개발자 시크릿을 잃을 수 있고, trap 등록 전 실패하면 시험용 시크릿 파일이 남을 수 있다.

Claude 작업 제안

• 파일을 변경하기 전에 trap부터 등록한다.
• 기존 파일이 있으면 원본 내용과 권한을 임시 위치에 보관하고, 종료 시 원본을 정확히 복원한다. 원래 없었을 때만 새 파일을 삭제한다.
• 가능하면 프로젝트의 공유 .dev.vars를 건드리지 않는 격리된 임시 환경/설정 파일을 사용한다.
• 성공·실패·중간 종료 각각에서 복원되는지 테스트한다.
• Wrangler 프로세스와 임시 로그도 자신이 띄운 프로세스/파일만 정리한다.
• 실행기는 local 모드만 허용하고 --remote 경로가 들어오면 즉시 실패하도록 방어한다.

5. Lens 검사기의 오탐 가능성

판정: 검사 기준과 React 구현을 함께 고쳐야 한다. 컴포넌트 자체가 CSS 렌즈라고 단정하면 안 된다.

• components.tsx의 Lens는 mark()가 SVG 문자열을 만들고, dangerouslySetInnerHTML로 SVG를 삽입한다.
• 외부 wrapper에 .sl-lens 클래스를 붙인다.
• screen-check.mjs는 .sl-lens, .sl-empty__lens, .sl-topbar__mark 중 하나라도 보이면 “CSS로 그린 렌즈나 마크”라고 실패시킨다.
• 현재 검사기는 CSS로 그린 렌즈와 SVG를 감싼 wrapper를 구분하지 못한다. 이대로면 정책을 준수한 SVG Lens도 오탐할 수 있다.

Claude 작업 제안

• 8판의 승인된 MARK/SVG와 실제 렌더링 SVG의 구조·경로·비율을 대조한다.
• 검사기는 wrapper class의 존재만으로 실패시키지 말고, 내부에 승인된 SVG mark가 있는지와 CSS pseudo-element/순수 CSS 도형으로 렌즈를 그리는지 구분한다.
• 작업 화면에서 렌즈 사용 금지, 입구/허용된 빈 상태 등 사용 위치 제한은 그대로 유지한다.
• 마크 중복, SVG 누락, 임의 SVG 대체, CSS 렌즈 구현은 각각 별도 결함 fixture로 검사한다.
• 이 규칙을 고칠 때 검사기를 약화시키지 말고, 승인된 SVG는 통과시키고 금지 구현은 실패시키는 회귀 케이스를 함께 둔다.

6. 화면 수 문서 불일치

판정: 기준 문서와 하위 인덱스의 숫자가 다르다.

• 00-structure.md: 전체 72개, 이번 구현 54개.
• 이번 구현 54개 구성: 관리자 A 30 + 상세/확인 D 7 + 실무자 T 9 + 운영자 O 4 + 공통 U 4.
• 03-screens.md 첫머리: 1회차 화면 68개라고 적혀 있고, 오래된 범주 합계를 사용한다.
• README.md도 화면 목록을 68개라고 설명한다.
• 구조 확정안은 00을 기준으로 03의 전체 화면 카드를 가리키므로, 숫자만 바꾸지 말고 실제 ID를 세어 전체 72와 이번 구현 54의 구분을 다시 맞춰야 한다.

Claude 작업 제안

1. 00-structure.md를 기준으로 화면 ID 전체를 기계적으로 집계한다.
2. 03의 카드 ID·분류·화면 수가 72 전체와 일치하는지 확인한다.
3. 이번에 만드는 54개와 다음 단계 화면 18개를 구분해 표제와 범주 합계를 수정한다.
4. README의 68개 표기를 수정한다.
5. 새 매핑 문서를 만들지 말고, 03의 기존 화면 등록표에 02 기능 ID와 06 서버 계약 참조를 연결한다.

7. 디자인 시스템 동기화 기록

• zero/app/ui/SOURCE.md는 IDEBER 디자인 시스템 0.18.0, 61개 파일, 수신 시각 2026-11-09를 기록한다.
• 이전 검토에서 우려했던 버전 기록 누락은 현재 파일 기준으로는 해소돼 있다.
• 다만 SOURCE 기록만으로 실제 파일 전체가 일치하고 앱이 정상 빌드·렌더된다는 사실까지 증명되지는 않는다.

Claude 확인 항목

• sync-ds와 경계 검사로 실제 61개 파일의 해시/경계가 일치하는지 확인한다.
• 수동 변경이 금지된 파일은 직접 수정하지 않고 원본 디자인 시스템에서 수정한 뒤 동기화한다.
• 동기화 후 React 빌드와 주요 8판 화면 렌더링을 확인한다.
• 과거에 언급된 UI handoff의 컴포넌트 수 불일치는 현재 브랜치의 해당 파일 경로를 확인하지 못해 이번 인계의 확정 결함으로 넣지 않았다. 파일이 존재한다면 목록을 다시 세어 문서 수와 실제 export를 맞춘다.

8. API 재사용 판정표 작성 기준

06-server-coverage는 기능 커버리지와 변경 방향을 설명하는 문서다. 그것만 보고 API를 재사용 가능하다고 판정하면 안 된다.

각 화면/기능을 기준으로 다음을 대조한다:

• 03 화면 ID
• 02 기능 ID
• 06 API/서버 capability
• 실제 Worker route와 handler
• 요청·응답 필드와 오류 응답
• D1 테이블·컬럼·관계
• 역할·테넌트 격리·소유권 검사
• 상태 전이와 잠금 시점
• Simple/Full 기존 동작과 Zero 정책의 차이

각 항목에 아래 중 하나의 결론을 명시한다:

• 그대로 재사용: 계약·권한·상태 전이가 모두 일치하고 증거 테스트가 있음.
• 시험 서버에서 수정: 기존 API 구조는 활용 가능하지만 Zero 계약에 맞게 수정해야 함.
• 새로 구현: 계약·권한·상태 모델이 맞지 않아 기존 handler를 재사용하면 위험함.

특히 DEC-242(반영 대기 남으면 결과확정 금지), DEC-129/DEC-090(확정 뒤 회차 잠금), DEC-118/DEC-019(커스텀스킬 반영/미반영), DEC-147(초대 링크 만료), DEC-132(파기 후 비식별 기록 보존)을 실제 handler와 테스트에서 확인한다.

9. 결함 검증과 완료 증거

검사기가 존재한다는 사실만으로 검사 능력이 증명되지는 않는다. 격리 fixture에서 일부러 결함을 넣고 각 검사가 잡는지 확인한다.

최소 검증:

• Worker: Zero flow 누락, 잘못된 flow, 관리자 권한 상승, 다른 tenant 데이터 접근, 잘못된 상태 전이.
• UI 정적/DOM: Simple 마크업 재사용, 중첩 카드, 승인되지 않은 로고/렌즈, 주 버튼 중복, 글자 하한, 시작선 이동.
• 화면 측정: 4px 배치 이동, 2개 주 버튼, 폰 고정 버튼이 본문을 가리는 상황.
• 스크린샷: 승인된 baseline과 비교. baseline에는 브라우저/Playwright/OS/폰트 지문/viewport/DPR/테스트 데이터/commit을 기록한다.
• 환경 지문이 다르면 합격·불합격으로 채점하지 말고 환경 불일치로 중단한다.
• 실제 제품 소스에 결함을 주입하지 않는다. 별도 fixture나 임시 환경에서만 시험한다.
• Playwright UI E2E는 A-22까지 도달하고, mail_log/로컬 메일 링크/D1의 최종 스킬셋까지 확인한다.

10. Claude가 바로 처리할 순서

1. Worker Zero flow 계약을 시험 서버에서 구현하고 Simple/Full 회귀 테스트를 추가한다.
2. API 여정의 false pass를 제거한다: flow: zero 전달, D1/세션/링크 flow assertion 추가.
3. 로컬 실행기 안전성을 고친다: .dev.vars 백업·복원, trap 선등록, 격리 실행.
4. 실제 Playwright UI E2E를 추가해 A-22까지 실사용 경로를 통과시킨다.
5. Lens checker를 승인 SVG와 CSS 렌즈를 구분하도록 수정하고 결함 fixture를 추가한다.
6. 72/54 화면 수를 00 기준으로 03과 README에 일치시킨다.
7. API 재사용 판정을 화면·기능·실제 handler·권한·상태 전이 근거로 완성한다.
8. 8판 baseline과 결함 주입 검증을 실행하고, 실패/통과 증거를 보고한다.

11. Claude에게 회신받을 내용

작업을 시작하기 전에 긴 설명 대신 아래 항목에 대한 제안과 근거를 먼저 정리해 달라. PM에게 결정만 떠넘기지 말고 기본 제안·대안·근거·영향을 함께 제시한다.

• Zero 앱의 정식 URL/라우팅 계약과 Worker flow resolver 설계
• Zero 정책별 Worker handler 변경 목록 및 권한·상태 전이 테스트
• API 여정과 브라우저 UI E2E의 분리 구조, A-22 저장 검증 방법
• .dev.vars를 보존하는 로컬 실행기 구현안
• SVG Lens 검사기의 정확한 허용/금지 판정 기준
• 72 전체 / 54 구현 화면의 ID별 재집계 결과
• API별 재사용/수정/신규 구현 판정과 근거

12. 검토 범위의 한계

• 이번 작업은 GitHub 파일의 정적 검토다. 로컬 명령, 빌드, Playwright, Worker, D1, 메일 검증을 실행하지 않았다.
• Worker 코드는 현재 skill-lens/main에서 확인했다. 실제 시험 서버/zero 브랜치에 어떤 Worker 사본이 연결되는지는 Claude가 현재 실행 구성으로 확인해야 한다.
• 따라서 이 문서의 결함은 소스에서 확인한 구현·검증 공백이며, 런타임 재현까지 완료했다는 뜻이 아니다.
• 이 문서는 Claude의 작업 인계 자료다. 제품 정책·화면 명세·API 계약의 정본을 대체하지 않는다.

이 사이트는 ideber 저장소 projects/skill-lens/ 에서 자동으로 만들어집니다. 고칠 때는 저장소를 고칩니다. 공개 주소이지만 검색엔진에는 나오지 않습니다.