| name | code-review |
| version | 1 |
| description | 코드리뷰 — 코드 변경을 개발자가 바로 고칠 수 있는 리뷰 리포트로 만드는 정밀 리뷰 엔진. diff리뷰와 전체감사를 지원하고 버그, 예외, 보안, 회귀, 테스트 누락을 우선 찾는다. 트리거: 코드리뷰, code-review, 코드검토, 리뷰해줘, PR리뷰, diff리뷰, 버그찾아줘, 보안리뷰, 코드품질. NOT: 기획 핸드오프, ruby-skill 단독 승격, 규제·약관·IP 문서.
|
Code Review — 코드리뷰 (정밀 리뷰 엔진)
핵심 공식: 작성자는 의도한 정상 경로는 잘 짠다. 버그는 바뀐 줄이 아니라 그 변경이 깨뜨린 주변 가정에 산다. 의도를 먼저 복원하고, 그 의도가 통과해야 할 기준을 먼저 세운 뒤, 그 기준으로 코드를 역검증하면, 개발자가 바로 고칠 수 있는 리뷰가 나온다.
TDD 역전: 코딩에서 테스트를 먼저 쓰듯, 리뷰에서 통과 기준(=있어야 할 테스트)을 먼저 강제 생성하고 그 기준으로 코드를 역검증한다. diff는 검증 대상이 아니라 기준 생성의 원료다.
운영 원칙 — 지식 기반 추론 > 패턴 매칭: 이 스킬은 린터가 아니다. 코드를 의미 모델로 이해한 뒤, 사례·카탈로그·라이브러리를 **추론의 근거(prior·exemplar)**로 삼아 실패 공간을 MECE로 덮는다. 화려한 지적이 아니라 완전성 + 거짓양성 0이 목표다. → references/reasoning-method.md (5원칙: 이해 먼저·구조 유추·MECE 커버리지·관련성 판정·적대적 검증)
Skill Boundaries
- 하는 것 — 코드 변경(또는 대상 파일) → 의도 복원 → 통과 기준 역생성 → 결함(RED) 식별 → 수정 처방(패치) + 신뢰도 등급 → 구조·가독성 승격(미학) → 리뷰 리포트(.md) / 옵션 PR 인라인 코멘트.
- 안 하는 것 — 기획 핸드오프(→planning-review), 구조·미학 단독 승격만(→ruby-skill), 보안 인허가·규제대응(→regulatory-skill), 약관·앱 고지문 생성(→app-and-jang), 라이선스·IP 귀속 조항 생성(→ip-skill), 실제 빌드·실행·재현 검증(→verify).
When to Use
- diff·PR·커밋, 또는 특정 파일·모듈을 결함·예외·파급 관점에서 정밀 검토해야 할 때
- "리뷰해줘", "버그 찾아줘", "보안 봐줘", "이 PR 결함 있나", "리팩터링 전에 봐줘" 같은 표현으로 발동
- 머지·배포 전 변경이 주변 가정을 깨는지 확인해야 할 때
- 안 쓸 때 — Skill Boundaries 참조. 특히 "이 코드를 그냥 더 아름답게 상위설계로"만 원하면 →ruby-skill, "실제로 돌려서 동작 확인"은 →verify.
Prerequisites
| # | 체크 | 미충족 시 |
|---|
| 1 | 리뷰 대상 존재 (diff/PR 또는 대상 파일·모듈) | 1줄 확인: "무엇을 리뷰할지(브랜치·PR·파일) 알려달라". diff면 git diff/gh pr diff로 확보 |
| 2 | 파트(백엔드/프론트/Android/iOS/AI)·언어·프레임워크·실행 맥락 식별 가능 | 확장자·경로·import로 자동 판정, 모르면 가정 명시 후 진행 |
| 3 | 변경의 의도(커밋·PR 메시지 또는 사용자 설명) 파악 가능 | 코드에서 의도를 역복원, 불확실하면 가정 명시 |
| 4 | references/ 폴더 접근 가능 | inline fallback |
⛔ 절대 규칙
| # | 규칙 | 이유 |
|---|
| 0 | 지식 기반 추론 — 패턴 매칭 금지 | 카탈로그·디텍터는 발동 트리거가 아니라 참조 사례. 단어·패턴 없어도 의미상 결함이면 다루고, 패턴 보여도 무관/안전하면 사유와 함께 제외. 코드 의미 모델 위에서 추론(reasoning-method.md) |
| 1 | 추측 금지 — 코드를 실제로 읽고 판단 | 변경 라인만 보지 말고 호출처·호출자·정의를 직접 읽는다. "아마 이럴 것"으로 결함 단정 ✗. 확인 못 한 건 [신뢰도: 하]로 명시 |
| 2 | 의도 먼저 복원, 그 다음 공격 | diff는 원료. "잘 짰다/못 짰다" 평가가 아니라, 의도를 복원해 그 의도가 깨지는 지점을 역추출 |
| 3 | 발견 먼저 (기준 → 검증 → 처방 순서 고정) | 통과 기준을 다 세우기 전에 처방하면 결함을 못 찾는다. 처방 선행 금지 |
| 4 | 거짓양성 금지 — 신뢰도 등급 + 적대적 자기검증 | 결함 단정 전 "이게 진짜 버그인가·재현되나·이미 다른 곳에서 막나"를 반증 시도. 거짓양성 1건이 리뷰 신뢰 전체를 깎는다. 코드리뷰 최대 실패모드 |
| 5 | 시스템 파급 필수 — 변경 라인 고립 금지 | 변경 함수만 보지 말고 상류(호출자)·하류(호출처)·계약·마이그레이션·횡단 일관성을 함께 본다. "A 고쳤더니 B 깨짐" 방치 ✗ |
| 6 | 보안·비밀값·라이선스·PII는 감지·라우팅 | 인젝션·권한·비밀노출은 처방하되, 법무·라이선스 귀속·규제 판단은 생성 ✗ 감지·라우팅만 — "전문 검토 필요" 1줄 |
| 7 | 저자 권한 존중 — 결함과 취향 구분 | 처방은 "제안 + 근거". 결함(틀림)은 고치게, 취향(스타일)은 강요 ✗. 승격(미학)은 진단과 섞지 않고 별도 섹션 |
| 8 | 웨이트 게이트 선행 | 처방·리포트 작성 전 라이트/표준/헤비 선택. 임의로 무겁게/가볍게 ✗ |
| 9 | 레드플래그 선행 스캔 | 8축 정밀검사 전에 치명(P0) 패턴 카탈로그(R1~R20)를 먼저 통과. 🔴 중대 적발 시 라이트 선택 경고 |
| 10 | 출력은 쉽게·스캔되게 — 내부 용어 금지 | 리포트 본문에 RED·P0·멱등성·디텍터·신뢰도 같은 엔진 용어를 쓰지 않는다. 쉬운 말 + file:line(클릭 가능) + 표·이모지 앵커. 심각도는 숫자 아닌 순서(먼저 고칠 것↑) → report-template.md |
파트 디스패처 — 하나의 엔진으로 모든 파트 (절대자적 리뷰)
백엔드·프론트·Android·iOS·AI/ML은 언어도 역할도 다르지만 실패의 본질은 같다 — 잘못된 상태, 안 닫힌 자원, 깨진 계약, 막지 못한 공격. 그래서 이 스킬은 파트마다 다른 스킬을 두지 않는다. 8축은 모든 파트 공통의 척추(보편), 파트별로 다른 건 "어느 축이 치명적이고, 그 축이 이 환경에서 어떤 모습으로 터지나"다 — 이걸 **렌즈(overlay)**로 얹는다. → references/part-lens.md
보편 8축 (척추) ──┬── + [백엔드 렌즈] 동시성·트랜잭션·API계약·N+1·인증인가·관측성
├── + [프론트 렌즈] 렌더·상태관리·리렌더·리스너누수·접근성·번들·XSS
├── + [Android 렌즈] 생명주기·Context누수·메인스레드(ANR)·코루틴스코프
├── + [iOS 렌즈] retain cycle·메인스레드UI·강제언래핑·async
└── + [AI/ML 렌즈] 데이터누수·재현성·평가지표오용·프롬프트인젝션·비용
- Phase 0에서 파트 자동 식별: 파일 확장자·경로·import·프레임워크로 파트 판정(예:
.kt+Activity→Android, .swift+UIViewController→iOS, .tsx+useState→프론트, *.py+torch→AI, controller/service/repository→백엔드). 모르면 1줄 확인.
- 멀티파트 PR: 한 PR이 여러 파트를 건드리면(예: 백엔드 API + 프론트 호출 + 앱 연동) 각 파트 렌즈를 모두 얹고, 파트 경계의 계약 정합성(Phase 1.5 파급)을 특히 본다 — "API 응답 형태 바뀜 → 프론트·앱이 깨지나"는 멀티파트 리뷰의 핵심.
- 렌즈는 8축을 대체하지 않고 강조·번역한다: 보편 축으로 다 보되, 그 파트에서 치명적인 항목을 우선순위로 끌어올리고(예: 프론트는 동시성보다 리렌더·접근성), 그 환경 고유의 발현형을 추가 점검(예: Android의 화면회전 시 상태소실).
- 언어 모르면 추론 + 확인: 처음 보는 언어·프레임워크여도 구조 유추(
reasoning-method.md 원칙 2)로 본질을 보고, 언어 고유 함정은 [신뢰도: 하]로 "확인 필요" 표기. 절대자적이되 겸손하게.
3축 분리 (타깃 × 행동 × 웨이트)
세 축은 직교한다. 타깃=무엇을 리뷰, 행동=무엇을 하는가, 웨이트=산출물 깊이.
타깃 (리뷰 대상)
| 타깃 | 트리거 | 범위 |
|---|
| diff리뷰 | "이 PR", "이 커밋", "변경분", "diff" (기본) | 변경분이 1차 대상. 필요시 변경이 건드린 주변·호출처로 확장 |
| 전체감사 | "이 파일 전체", "이 모듈 감사", "레거시 봐줘" | 변경분이 아니라 지정 파일·모듈·디렉터리 전체를 정밀 리뷰 |
행동 (무엇을 하는가)
| 행동 | 트리거 | 실행 |
|---|
| 진단 | "결함 찾아줘", "버그 있나", "리뷰만" | P1+P2 — 통과 기준표 + 결함 목록(심각도·신뢰도) |
| 처방 | "고쳐줘", "패치 제안", "리뷰해줘" | 진단 + 결함마다 수정안(패치) + 근거 (기본 행동) |
| 승격(미학) | "더 아름답게", "구조 개선", "리팩터링 검토" | 처방 + 구조·가독성 상위설계 제언(elevation-method.md) — 결함과 별도 섹션 |
행동 미지정 시 → 처방. "구조까지" 신호 있으면 승격 추가.
웨이트 게이트 (산출물 무게) — 처방 진입 직전 선택
| 웨이트 | 대상 | 범위 |
|---|
| 라이트 | 빠른 검토·소규모 diff | 치명(P0) 결함 + 명백한 버그만. 8축 중 가장 위험한 것 위주. 1~2개 핵심 |
| 표준 | 일반 PR 리뷰 (기본값) | 8축 전수 + 주요 결함·예외·파급 + 핵심 처방. 머지 전 표준 리뷰 |
| 헤비 | 보안·결제·동시성·마이그레이션 등 고위험 | 표준 + 동시성·멱등성·롤백 전수 + 엣지 매트릭스 + 보안 정밀 + 성능 + 테스트 갭 + 승격 |
⚠️ 웨이트 미선택 시: 표준 디폴트로 가되 리포트 첫머리에 "표준 웨이트로 진행 — 라이트/헤비 원하면 말씀" 1줄 고지. 보안·인증·권한·결제·동시성·데이터 마이그레이션이 걸린 변경은 헤비 권장 1줄을 먼저 띄운다.
실행 파이프라인
Phase 0: 입력 정규화 + 레드플래그 선행 스캔
- 리뷰 대상 확보 — diff(
git diff/gh pr diff) 또는 대상 파일. 변경 라인뿐 아니라 그 함수·호출처·정의를 실제로 읽는다(절대규칙 1).
- 파트 식별 + 렌즈 로드: 확장자·경로·import·프레임워크로 파트(백엔드/프론트/Android/iOS/AI/ML) 판정 →
references/part-lens.md에서 해당 렌즈를, references/bug-pattern-casebook.md에서 해당 파트 사례를 로드. 멀티파트면 렌즈를 모두 얹는다. 언어·런타임·동시성 모델도 함께 식별.
- 🚨 레드플래그 선행 스캔:
references/redflag-catalog.md로 1차 통과. 치명(P0) 패턴(인젝션·권한우회·이중처리·자원누수·데이터손실·하드코딩 비밀 등) + 파트 렌즈의 파트별 레드플래그를 8축 검사 전에 선등록. 🔴 중대면 플래그.
- 타깃·행동 판별 (미지정 → diff리뷰·처방)
Phase 0.5: 의도·코드 의미 모델링 (추론의 기준점 — 매칭 방지의 핵심)
references/reasoning-method.md 원칙 1. 변경을 내 말로 의미 모델로 재구성: 무엇을 하려는가(의도)·행위자·입출력 계약·건드리는 불변식·상태·자원. 이 모델로 변경의 본질을 한 줄로 규정한다("이건 경합 자원 갱신 / 외부 IO 경계 / 권한 게이트 / 순수 변환이다"). 이후 모든 축·디텍터·사례는 변경 텍스트가 아니라 이 모델 위에서 작동한다.
Phase 1: 통과 기준 역생성 (발견 준비 — "테스트 먼저")
references/axes-checklist.md + Phase 0에서 로드한 파트 렌즈(part-lens.md)를 함께 적용. 의도 모델의 각 입력·자원·상태를 8축 역추출 엔진 + 파트 렌즈 강조축 + 보안·라이선스·PII 디텍터에 통과시켜 "이 의도가 옳으려면 통과해야 할 기준"표를 만든다. 파트 렌즈는 8축을 대체하지 않고, 그 파트에서 치명적인 항목을 우선순위로 끌어올리고 환경 고유 발현형(예: 화면회전 시 상태소실, retain cycle, 리렌더 폭발, 데이터 누수)을 추가한다.
- 관련성 판정 방식(매칭 ✗): 축·디텍터·카탈로그 항목은 모델에 비춰 ● 해당 / ○ 부분(맥락 번역 후 등록) / – 무관(사유 1줄과 함께 제외)로 판정.
- 사례는 구조 유추로:
bug-pattern-casebook.md는 언어 이름 매칭이 아니라 구조를 가장 가까운 사례에 사상해 패턴을 번역(reasoning-method.md 원칙 2).
- 디텍터(
security-detector.md)는 인젝션·비밀값·권한·라이선스·PII를 감지해 RED로 띄우고, 법무·라이선스 판단은 전문 스킬로 라우팅(생성 ✗).
- 고유 케이스 의무: 카탈로그에 없던 이 코드만의 결함 후보를 최소 1개 도출(추론의 증거). 못 뽑으면 Phase 0.5로 회귀.
| 축 | 역추출 질문 (요약 — 상세는 axes-checklist.md) |
|---|
| 정확성 | 로직 옳은가 / 엣지·off-by-one / null·undefined·빈값 / 타입·형변환 / 반환·분기 누락 |
| 상태·동시성 | 레이스·경합 자원 / 멱등성 / 트랜잭션 원자성 / 캐시·복제 일관성 / 부분실패·롤백 |
| 에러·실패 | 삼킨 예외 / 미처리 에러·전파 / 자원 누수(파일·커넥션·락) / 타임아웃·재시도·백오프 |
| 인터페이스·계약 | 시그니처·호환성 깨짐 / 호출자 영향 / 마이그레이션 / API·스키마 버전 |
| 보안(디텍터) | injection / authz·authn / 비밀값·로그노출 / SSRF·역직렬화 / 입력검증·이스케이프 |
| 성능·자원 | N+1·반복 쿼리 / 불필요 할당·복사 / 알고리즘 복잡도 / 메모리·누수 / 동기 블로킹 |
| 유지보수·구조 | 중복 / 응집·결합 / 네이밍 / 죽은 코드 / 복잡도·깊은 중첩 (→승격 모드 원료) |
| 테스트 | 통과 기준이 테스트로 커버되나 / 회귀 위험 / 검증 누락 경로 |
| 라이선스·PII(디텍터) | OSS 라이선스 충돌 / 비밀·키 커밋 / PII 수집·로깅 → 감지 시 RED + 전문 스킬 라우팅 |
산출물: 통과 기준표 (기준 ID, 축, 대상 file:line, 기대 동작 — 아직 판정 전).
Phase 1.5: 시스템 파급 분석 (변경은 혼자 살지 않는다)
references/ripple-map.md 로드. 변경 라인 고립 분석 금지. 변경이 건드리는 심볼·계약·자원을 식별하고 3방향 파급을 추론한다:
- ⬆ 상류(호출자): 이 함수·API를 부르는 곳들 — 시그니처·반환·예외 변경이 그들을 깨나
- ⬇ 하류(호출처·의존): 이 코드가 부르는 것들 — 그 계약·실패 모드를 올바로 다루나 →
[파급] RED
- ➡ 미래(유발): 이 변경이 곧 요구할 후속(마이그레이션·기능 토글 정리·문서) → 제언
- 🔗 횡단 일관성: 동일 패턴이 코드베이스 다른 곳에도 있나(같은 버그/같은 수정 필요), 설정·피처플래그·로깅·메트릭·에러처리 관행과 정합하나
- ⚠️ 꼬임: 기존 불변식·상태머신·데이터 계약·하위호환을 깨거나 마이그레이션을 강제하나
Phase 2: 역검증 (발견) — 코드가 각 기준을 통과하나?
references/bug-pattern-casebook.md·fix-library.md의 사례·표준을 대조선으로, 기준마다 판정:
| 판정 | 의미 |
|---|
| ✅ 통과 | 코드가 이미 올바로 처리 |
| 🟥 결함(RED) | 기준 미충족 — 버그·구멍 (핵심 산출) |
| ⚠️ 모순/리스크 | 잠재 위험·맥락 의존·재확인 필요 |
🔬 적대적 검증 의무(절대규칙 4): 각 🟥 후보에 대해 반증을 먼저 시도 — "이게 진짜 재현되나? 호출 전에 이미 검증되나? 타입·런타임이 막나? 테스트가 잡나?" 반증 실패해야 결함으로 확정. 확정 결함마다 심각도(P0 치명 / P1 중요 / P2 개선)와 신뢰도[상/중/하] 태깅. 신뢰도 하 = 결정적 단정 금지, "확인 필요"로 제시.
⏸ 웨이트 게이트 (발견 → 처방 전이) — 쉬운 말로 제시
결함 목록을 쉬운 말 + 표로 요약(내부 용어 금지, 절대규칙 10). 형식: ① 한 줄 요약(치명 N·중요 M) ② "먼저 고칠 것"(가장 위험한 것 맨 위) ③ "곧/나중에 고칠 것" ④ "취향(선택)" ⑤ "우리가 판단 안 하는 것(법무·라이선스)". 그 뒤 라이트/표준/헤비 선택받는다.
- 심각도는 P0/P1 라벨 대신 "먼저/곧/나중/취향" 으로.
- 레드플래그 🔴 중대 or 보안·동시성·마이그레이션 연루면 "꼼꼼히(헤비) 권장" 1줄 먼저.
- 사용자가 답(우선순위 + 웨이트)하면 → Phase 3·4.
Phase 3: 처방 (수정안) — 결함마다 패치 + 근거
references/fix-library.md의 "수정 디폴트 카탈로그" 활용. 결함마다:
- 수정 방향 제안 (권장안 / 대안) — 근거 사례·원리 첨부, 가능하면 최소 패치(diff) 제시
- 신뢰도 등급 [상/중/하] — 재현·테스트로 증명=상, 코드상 명백하나 미실행=중, 맥락 의존 추론=하
- 저자 결정 존중(절대규칙 7) — 결함은 고치게, 취향은 "선택" 표시. 임의 확정 ✗
- 보안·라이선스·PII RED는 처방 대신 라우팅 + 전문 검토 1줄(법무·라이선스 생성 ✗)
- 모순(⚠️)은 재확인 질문 + 안전한 디폴트
Phase 3.5: 승격 (미학 모드 한정) — 구조 상위설계
references/elevation-method.md 로드(러비 흡수). 진단·처방과 별도 섹션. 결함이 아니라 "더 나은 구조"를 제언: 분해→평가→상위설계(응집↑ 결합↓ 의도 드러나게). 취향임을 명시하고 강요 ✗. 행동=승격일 때만.
Phase 4: 리뷰 리포트 (게이트에 답한 뒤 출력)
전제: 게이트에서 우선순위 + 웨이트를 받은 뒤 생성. references/report-template.md 로드(쉽고·스캔되고·MECE). 웨이트에 맞는 템플릿으로 MD 리포트 출력. 개발자가 스캔만 해도 무엇을·왜·어떻게 고칠지 알게:
- 맨 위 🔧 먼저 고칠 것(치명·근거·패치) → 🟡 곧/나중 → 🎨 취향·구조(승격) → 🔗 파급(다른 곳도 확인) → ⚖️ 법무·라이선스 확인 → ✅ 잘된 점(짧게).
- 각 항목:
file:line(클릭 가능) + 한 줄 문제 + 한 줄 이유 + 패치/방향. 내부 용어 금지(절대규칙 10).
- 옵션 — PR 인라인 코멘트: 사용자가 "코멘트로"라고 하면
gh pr review/gh api로 변경 라인에 인라인 코멘트 게시(외부 발행 — 사전 확인). 기본은 .md 리포트.
Phase 5: 자기검증
| 체크 | 내용 |
|---|
| 거짓양성 0 | 모든 🟥에 적대적 검증을 거쳤나. 신뢰도 하는 단정 아닌 "확인 필요"로 냈나 |
| MECE 커버리지 | 의도 모델의 모든 입력·자원·상태·경로가 최소 1축에서 검사됐나. 같은 결함 중복 등록 안 했나 |
| 시스템 파급 | 호출자·호출처·마이그레이션·횡단(같은 패턴 타 위치)을 봤나 |
| 고유 케이스 | 카탈로그에 없던 이 코드 고유 결함을 1개+ 도출했나(매칭 아닌 추론의 증거) |
| 8축 전수 | 8축 모두 다뤘나 (N/A는 "해당 없음" 명시) |
| 파트 렌즈 | 대상 파트의 렌즈(강조축·고유 발현형·레드플래그)를 적용했나. 멀티파트면 파트 경계 계약을 봤나 |
| 코드 실독 | 변경 라인뿐 아니라 호출처·정의를 실제로 읽었나(추측 아님) |
| 권한 경계 | 결함과 취향을 구분했나. 보안·라이선스를 직접 판단하지 않고 라우팅했나 |
| 스캔 가능성 | file:line 클릭 가능·내부 용어 없음·심각도 순서로. 개발자가 바로 착수 가능한가 |
| 웨이트 정합 | 산출물 무게가 선택된 웨이트와 맞나 |
Output Path
| 산출물 | 경로 |
|---|
| 주 산출물 (리뷰 리포트) | mnt/outputs/code-review_{대상}_{YYYY-MM-DD}.md |
| 옵션 | PR 인라인 코멘트(gh — 외부 발행, 사전 확인) |
| 형식 | 통과기준표 / 결함목록(심각도·신뢰도) / 리뷰 리포트. .md |
Reference Index
| 파일 | 내용 | 언제 |
|---|
references/reasoning-method.md | 지식 기반 추론 5원칙 (의미 모델링·구조 유추·MECE·관련성 판정·적대적 검증) — 패턴매칭·거짓양성 방지 | Phase 0.5·2·전 단계 |
references/part-lens.md | 파트별 렌즈 (백엔드·프론트·Android·iOS·AI/ML) — 파트별 강조축·레드플래그·고유 발현형·역할 우선순위 | Phase 0·1 |
references/axes-checklist.md | 8축 역추출 엔진 상세 (정확성·상태/동시성·에러·계약·보안·성능·구조·테스트 질문 전수) | Phase 1 |
references/ripple-map.md | 시스템 파급 (호출 그래프·횡단 일관성·마이그레이션·꼬임) | Phase 1.5 |
references/redflag-catalog.md | 레드플래그 자동 스크리너 — P0 코드 재앙 20종 | Phase 0 (선행) |
references/security-detector.md | 보안·비밀값·라이선스·PII 디텍터 (감지 + 전문 스킬 라우팅) | Phase 1 |
references/bug-pattern-casebook.md | 언어·도메인별 흔한 버그 패턴 사례집 (구조·근거) | Phase 0~2 |
references/fix-library.md | 수정 디폴트 추천 카탈로그 (패턴별 권장 처방·패치) | Phase 2~3 |
references/elevation-method.md | 승격(미학) 모드 — 구조분해 상위설계 (러비 흡수) | Phase 3.5 |
references/report-template.md | 라이트/표준/헤비 리뷰 리포트 + PR 코멘트 템플릿 | Phase 4 |
references/examples.md | 입력→통과기준→발견→처방→리포트 전 과정 워크드 예제 | 학습·포맷 참조 |
Next Phase
본 스킬 작업 후 자연스럽게 이어지는 흐름:
- 수정 적용 후 실제 동작 확인 →
verify
- 구조 대수술·상위설계 본격화 →
ruby-skill
- 리뷰 결과를 외부 보고 문서로 →
shaper-skill → submission-cleanup
- 변경 전 설계 빈틈(기획) →
planning-review
보안·라이선스·PII 디텍터가 띄운 RED의 전문 처리 (판단은 이쪽에서):
- 규제·인허가·제재(개인정보위·금융 등) →
regulatory-skill
- 약관·개인정보처리방침·앱스토어 고지 →
app-and-jang
- OSS 라이선스·저작권 귀속·크롤링/AI학습 →
ip-skill
Failure Modes (Gotchas)
- 거짓양성 함정: "아마 null일 것"으로 결함 단정 → 호출 전 이미 검증되는 코드였음. 거짓양성 1건이 리뷰 전체 신뢰를 깎는다. 단정 전 반드시 반증 시도(적대적 검증). 못 확인하면 [신뢰도: 하] + "확인 필요".
- 변경 라인 근시 함정: diff 줄만 보고 호출처·정의를 안 읽음 → 진짜 버그는 변경이 깬 주변 가정에 있음. 항상 함수·호출처·정의를 실제로 읽는다.
- 처방 선행 함정: 결함을 다 세우기 전에 "이렇게 고치면 됩니다"로 빠지면 다른 구멍을 놓침. 발견→검증→처방 순서 고정.
- 린터 퇴화 함정: 패턴 스캔으로 표의 행을 꺼내면 린터로 퇴화. 먼저 코드 의미 모델을 세우고(Phase 0.5), 카탈로그는 관련성 판정(●○-)으로. 고유 케이스 1개+ 도출로 추론을 증명.
- 취향 강요 함정: 스타일·네이밍 선호를 결함처럼 단정하면 월권. 결함(틀림)과 취향(선택)을 구분, 취향은 "선택"으로 표시.
- 8축 침묵 누락: 어떤 축을 안 보고 조용히 넘기면 그 자체가 구멍. N/A도 "해당 없음" 명시.
- 변경 고립 함정: 변경 함수만 보고 끝내면 호출자가 깨진다. 항상 상류·하류·미래·횡단(같은 패턴 타 위치)을 본다. 특히 시그니처·반환·예외 변경의 호출자 영향과 같은 버그가 코드베이스 다른 곳에도 있나는 자주 누락.
- 보안 월권 함정: 라이선스 충돌·규제 적합성을 직접 판단하면 무자격. 감지·라우팅·"전문 검토" 1줄까지만. (인젝션·권한 같은 코드 결함은 처방 OK)
- 웨이트 폭주: 작은 diff에 헤비를 들이대면 안 읽힘. 반대로 결제·동시성에 라이트를 쓰면 사고. 게이트로 선택받을 것.
- 데이터 시트 함정: 결함을 나열만 하고 "그래서 어떻게 고칠지"를 안 주면 개발자가 못 움직임. 패치/방향을 항상 붙인다.
- 사례 맹신 함정: casebook의 패턴은 사례지 정답 아님. 해당 코드 맥락에 맞게 번역해 적용.
❌ WRONG vs ✅ CORRECT
❌ WRONG: diff 받자마자 "이 줄에서 null 터질 수 있음, 버그!" → 호출 전 검증되는 코드. 거짓양성.
❌ WRONG: 코드에서 'eval·exec·password' 단어 스캔 → 카탈로그 행 그대로 출력 → 린터로 퇴화.
✅ CORRECT: 코드 의미 모델 수립 → 본질 규정 → 사례 구조 유추 → 8축+디텍터 관련성 판정(●○-) → 통과기준 역생성 → 역검증 + 적대적 검증(거짓양성 제거) → 신뢰도 등급 처방 + 패치 → 스캔 가능한 리포트.
