Community코딩 & 개발github.com

리뷰

태스크, 기능, 브랜치 작업이 완료되고 병합되기 전에 사용합니다. PR, diff, 진행 중인 작업, 다른 에이전트나 모델이 작성한 코드를 리뷰할 때, '이게 무엇을 깨뜨릴까?', '병합해도 안전한가?'와 같은 질문을 받을 때, 그리고 리뷰 피드백을 받고 조치를 취하기 전에 사용합니다. 또한 '리뷰', '코드 리뷰', '<ref> 이후 리뷰', '병합 전 확인', '이 변경 사항 스트레스 테스트' 등의 요청에도 사용합니다.

리뷰란 무엇인가요?

이 리뷰 스킬은 AI 에이전트(Claude Code, Cursor, Codex 등)가 변경 사항을 체계적이고 증거 기반으로 평가하기 위한 포괄적인 프레임워크입니다. **사양 축**과 **품질 축**이라는 두 가지 축으로 변경 사항을 판단하며, 각 축은 독립적인 리뷰어(서브에이전트)가 신선한 컨텍스트로 평가합니다. 변경 범위를 확정하고, 의도를 파악한 후, 테스트, 정확성, 가독성, 설계, 보안, 성능 등을 기준으로 품질을 평가합니다. 발견된 문제는 심각도(Critical, Important, Minor, Nit, FYI)에 따라 등급을 매기고 증거로 입증해야 합니다. 승인 기준은 코드베이스의 건강을 확실히 개선하고 요청된 대로 작동하는 경우이며, 리뷰어는 문제를 지적할 뿐만 아니라 구체적인 해결 방안을 제안해야 합니다. 마지막으로, 작성자는 리뷰 피드백을 기술적 요구사항으로 재진술하고 코드를 통해 검증한 후, 실패하는 테스트를 먼저 작성하고 수정하는 방식으로 대응합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/hesedcasa/frankenskills/tree/main/skills/review

Installed? Explore more 코딩 & 개발 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

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

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

리뷰은(는) 무엇을 하나요?

변경 사항을 **올바른 것을 구축했는가(사양)**와 **잘 구축했는가(품질)**라는 두 가지 축으로 판단합니다. 새로운 시각으로 바라보고, 발견 사항은 증거로 뒷받침하며, 심각도는 실제 사용자가 겪을 수준으로 평가합니다. 그런 다음 기술적 엄격함(존중이 아닌)을 바탕으로 발견 사항에 대해 조치합니다.

핵심 원칙: 변경 사항이 코드베이스의 건강을 분명히 개선하고 요청된 대로 작동한다면, 비록 자신이 작성했다면 다르게 작성했을지라도 승인합니다. 직접 읽고 확인하지 않은 변경 사항은 절대 승인하지 마세요.

파이프라인 위치: 사양 → 계획 → 구축 (+ 테스트) → 리뷰 → 병합

1단계: 범위 확정

  • 사용자가 범위(PR, 브랜치, 커밋 범위, 파일)를 지정합니다. 그렇지 않은 경우: 기본 브랜치와의 병합 기준(base)에 대한 현재 브랜치와 커밋되지 않은 변경 사항을 포함합니다.
  • 다른 작업을 수행하기 전에 고정 지점을 확인하고 범위가 비어 있지 않은지 확인합니다: git rev-parse <ref>, git log <ref>..HEAD --oneline (커밋된 작업), git diff <ref>...HEAD --stat (커밋된 작업), git diff --cached --stat (스테이징됨), git diff --stat (스테이징 안 됨), git status --short (추적 안 됨). 두 항목의 합집합을 리뷰하며, 커밋되지 않은 변경 사항이 범위에 포함된 경우 각 리뷰어에게 알립니다(리뷰어 프롬프트에 해당 줄이 있습니다). 잘못된 ref이거나 두 항목 모두 비어 있으면 여기서 실패합니다.
  • PR의 경우, 설명과 연결된 이슈를 읽습니다.

2단계: 의도 파악

다음을 순서대로 찾습니다: 변경 사항이 구현하는 사양 및 계획(specs/<slug>/, 커밋/PR 링크, 사용자가 제공한 경로), 빌드 원장의 Ruling: 줄, 그리고 해결하는 이슈. 의도를 두세 문장으로 다시 설명합니다. 사양이 없으면 그렇게 말합니다. 그러면 사양 축은 PR 설명과 사용자의 합리적인 기대에 대해 판단합니다.

또한 표준을 찾습니다: CONTRIBUTING.md, CODING_STANDARDS.md, CLAUDE.md/AGENTS.md, 린트 설정, ADR, 용어집.

크기 확인. 약 100줄 변경이 이상적이며, 하나의 논리적 변경에는 약 300줄이 적당하고, 약 1000줄은 제대로 리뷰하기엔 너무 큽니다: 발견 사항으로 분할(스택, 파일 그룹별, 또는 수직 슬라이스)을 권장합니다. 리팩토링과 기능 작업이 섞여 있으면 두 가지 변경입니다.

3단계: 새로운 컨텍스트로 리뷰

작성자는 자신의 가정에 대해 눈이 멀어 있으며, 코드를 작성한 세션도 마찬가지입니다. 서브에이전트 도구를 사용할 수 있는 경우, 리뷰어-프롬프트.md를 사용하여 신선한 컨텍스트로 리뷰어를 파견합니다: diff(파일 또는 정확한 명령어), 사양/계획 경로, 표준 파일, 원장 판결을 제공합니다. 자신의 세션 기록은 절대 제공하지 않습니다. 리뷰어는 읽기 전용이며 자체 리뷰어를 생성하지 않습니다.

하나의 축이 다른 축을 가릴 수 없도록 병렬로 실행합니다:

  • 사양 리뷰어: 누락, 추가, 오해.
  • 품질 리뷰어: 정확성, 테스트, 설계, 보안, 성능.
  • (선택 사항, 위험하거나 광범위한 변경의 경우) 폭발 반경 리뷰어: grep만으로는 드러나지 않는 관련 내용을 확인합니다.

전체 브랜치 리뷰에는 가장 강력한 모델을 사용합니다. 서브에이전트 도구가 없으면 각 축을 별도의 패스로 직접 수행하고, 결과에 자기-리뷰라고 표시합니다: 신선한 리뷰어보다 약하며, 사용자가 충분한지 결정합니다.

방금 완료한 자신의 브랜치를 인라인으로 리뷰하는 것은 이 단계를 대체할 수 없습니다.

사양 축

diff를 요청된 사항과 비교합니다:

  • 누락: 요구사항 또는 성공 기준이 건너뛰어졌거나, 부분적이거나, 구현되었다고 주장되었지만 실제로는 구현되지 않음. 사양 줄을 인용합니다.
  • 추가: 아무도 요청하지 않은 동작, 추측성 옵션, 훅, 또는 추상화(범위 확장, YAGNI).
  • 오해: 올바른 기능을 잘못된 방식으로 구축했거나, 잘못된 문제를 해결함.
  • diff에서 확인 불가: 변경되지 않은 코드에 존재하거나 여러 변경에 걸쳐 있는 요구사항. 추측하지 말고 확인해야 할 사항을 나열합니다.

사양은 비전 문서이지, 철저한 목록이 아닙니다. 사양에 명시되지 않은 경우, 합리적인 사용자의 기대가 요구사항입니다. 입력에 대한 침묵이 충돌을 허용하는 것은 아닙니다.

품질 축

테스트를 먼저 읽습니다: 의도와 테스트 범위를 드러냅니다.

테스트

  • 모든 새로운 동작에 대해, 해당 동작이 깨졌을 때 실패할 테스트가 있습니까? 가능하다면 실험을 통해 확인합니다: 변경 사항이 추가하는 조건을 뒤집고 전체 테스트 스위트를 실행합니다(리뷰 중인 체크아웃이 변경되지 않도록 일회용 작업 트리나 복사본에서 수행). 변경 후에도 여전히 통과하는 변이는 발견 사항입니다: 누락된 테스트의 이름을 지정합니다.
  • 공개 인터페이스를 통한 동작, 내부 구현이 아닌; 목(mock)에 대한 단언(assertion) 금지; 테스트 대상 코드가 계산한 예상값 사용 금지; 목(mock)은 시스템 경계에서만 사용.
  • 버그 수정에는 회귀 테스트가 포함되어야 합니다. 건너뛰거나 비활성화된 테스트는 없어야 합니다. 테스트 출력은 깨끗해야 합니다.

정확성

  • 사양과 일치; 경계 조건(null, 빈 값, 0, 최대값, 유니코드, 동시성); 예외 경로(에러 경로), 행복한 경로만이 아닌; 1차이(off-by-one), 경쟁 조건(race condition), 동기화되지 않을 수 있는 상태.

가독성 및 단순성

  • 이름은 사물의 정체와 역할을 설명합니다. 제어 흐름은 직관적입니다. 더 적은 줄로 표현할 수 있습니까? 각 추상화가 그 존재 가치가 있습니까?(세 번째 사용 전에 일반화하지 않음)
  • 죽은 코드, 무효 변수, // removed 주석, 아무도 필요로 하지 않는 호환성 shim.
  • 주석은 *왜(why)*를 설명해야 하며, *무엇(what)*이 아닙니다. 해결 방법을 설명하는 주석은 종종 수정되지 않은 근본 원인을 표시합니다.

설계

  • 기존 패턴에 적합; 새로운 패턴에는 이유가 필요합니다.
  • 리팩토링이 독자가 유지해야 하는 개념을 줄이는가, 아니면 단지 이동시키는가? 분기, 모드, 또는 계층이 사라지는 버전을 선호합니다.
  • 기능 로직이 공유 모듈로 누출됨; 기존 헬퍼와 거의 중복됨; 관련 없는 흐름에 조건문이 덧붙여짐; 동일한 형태에 대한 반복적인 switch(누락된 모델 또는 디스패처); 첫 번째와 동기화를 유지해야 하는 두 번째 불리언(누락된 상태 기계).
  • 단일 호출자 래퍼와 통과 계층(인라인 처리). 필요 이상으로 넓은 변경 가능한 상태.
  • 경계에서 검증, 내부는 신뢰. 불분명한 불변성을 감추는 조용한 폴백(fallback) 금지; 불필요한 any/캐스트 금지.
  • 파일 성장: 파일을 건강한 크기보다 훨씬 넘어서게 만드는 변경은 먼저 분해해야 합니다.

보안

  • 신뢰할 수 없는 입력(HTTP, CLI, 파일, env, LLM 출력, 타사 응답)은 경계에서 검증. 쿼리는 매개변수화. 출력은 인코딩. 인증/인가가 필요한 곳에서 확인. 비밀은 코드, 로그, VCS 밖에 보관. 새로운 종속성은 정당화되고, 유지 관리되며, 라이선스가 호환되어야 함; 잠금 파일 diff 리뷰.

성능

  • N+1 쿼리, 무제한 루프 또는 가져오기, 페이지네이션 누락, 차단하는 동기 작업, 핫 경로의 큰 할당, 불필요한 재렌더링. 가능하면 수치화합니다("1k 행에서 행당 ~50ms").

악취 기준선(판단 호출; 저장소의 문서화된 표준이 우선): 수수께끼 이름, 중복 코드, 기능 선망, 데이터 덩어리, 원시 타입 집착, 반복 스위치, 샷건 수술, 발산적 변경, 추측성 일반화, 메시지 체인, 중개자.

폭발 반경 축(위험하거나 광범위한 변경)

호출자를 나열하는 것이 작업이 아닙니다. grep은 1초 안에 수행합니다. 작업은 grep이 보여주지 못할 손상입니다:

  • 변경 사항이 안전한 이유가 되는 한 가지 사실을 찾습니다(“이 호출은 이미 죽은 항목만 삭제합니다.”). 코드를 실행하여 증명합니다: 고정된 버전의 실제 라이브러리를 임포트하고 해당 함수를 호출하는 스크립트.
  • 심볼 검색이 중단되는 곳을 살펴봅니다: 라이브러리 소스 및 로컬 패치, 실행 타이밍(비동기 순서, 종료), 직렬화 형식(JSON 형태, DB 열, 와이어 프로토콜, 동일한 바이트를 읽는 다른 언어), 기능 플래그, 세 단계 떨어진 소비자.
  • 각 위험에 대해: 어떻게 깨지는지, 파일:줄, 가능성, 비용, 가장 저렴한 확인 방법. 확인 및 해제된 위험은 별도로 나열합니다.

4단계: 모든 발견 사항 검증

맞는 것처럼 들리는 발견 사항은 확인되기 전까지는 발견 사항이 아닙니다.

  • 코드에 도달하는 호출자, 가드, 테스트에 대해 확인하세요. 이들이 배제하면 제거합니다.
  • 중요한 발견 사항은 증명합니다: 실패하는 테스트, 재현 스크립트, 또는 잘못된 동작을 보여주는 명령어 출력. 그럴듯한 발견 사항보다 실행을 통해 증명된 발견 사항을 선호합니다.
  • 기존 결함과 이 변경 사항이 도입한 회귀를 별도로 표시합니다.
  • 근본 원인을 공유하는 발견 사항은 병합합니다.
  • 발견 사항이 0개인 것도 유효한 결과입니다. 철저해 보이려고 발견 사항을 지어내지 마십시오.

병합 차단 기준

발견 사항이 Critical 또는 Important이며, 증거에 의해 입증된 경우에만 병합을 차단할 수 있습니다:

  • 잘못된 동작을 보여주는 실행(테스트, 스크립트, 명령어), 또는
  • 각 단계의 파일:줄과 함께 코드를 통해 잘못된 출력까지 단계별로 추적된 구체적인 입력.

이러한 방식으로 입증할 수 없는 그럴듯한 우려 사항(“이게 X를 깨뜨릴 수도 있음”, “경계 조건이 처리되지 않을 수 있음”)은 Minor 등급으로 평가되고 *미확인(미검증)*으로 표시됩니다. 차단하지 않습니다. 작성자가 확인할 수 있도록 나열합니다.

5단계: 등급 부여 및 보고

소프트웨어가 출시될 때 합리적인 사람이 경험할 효과에 따라 등급을 부여하며, 사양이 트리거를 언급했는지 여부에 따르지 않습니다.

심각도의미필요한 조치
Critical보안 허점, 데이터 손실, 핵심 기능 손상병합 차단
Important잘못되거나 취약한 동작, 누락된 요구사항, 테스트되지 않은 동작, 삼켜진 에러, 해로운 중복 또는 설계병합 전 수정
Minor마무리, 작은 단순화, 더 넓은 범위작성자 결정; 연기된 경우 기록
Nit스타일 선호선택 사항
FYI맥락, 조치 불필요없음

영향력이 큰 순서로 시작: 정확성과 보안이 먼저, 그 다음 구조적 문제와 놓친 단순화, 그 다음 나머지. 하나의 구조적 문제와 열 개의 nit이 있다면, 구조적 문제가 리뷰의 전부입니다. 문제뿐만 아니라 해결 방안을 제안하십시오: "이 if-체인을 kind를 키로 하는 조회로 대체", "이 단일 호출자 래퍼를 인라인 처리", "utils/date.ts의 formatDate 재사용".

솔직하게 작성하세요: 도장 찍기 식의 "LGTM" 금지, 실제 버그를 "사소한 우려일 수 있음"으로 완화하지 않음, nit을 Critical로 부풀리지 않음. 잘된 점을 구체적으로 인정하십시오.

리뷰어-프롬프트.md의 형식을 사용하세요: 사양 판결, 강점, 심각도별 이슈(각각 파일:줄, 무엇이 잘못되었는지, 왜 중요한지, 수정 방법, 증거), 폭발 반경 노트, 판단 거부(고려했다가 제외한 동작과 그 이유), 그리고 판결: 승인, 수정 후 승인, 또는 변경 요청. 사양 섹션과 품질 섹션을 분리하고, 두 축을 혼합하여 재순위를 매기지 마세요.

판결 규칙: 증거 기준을 충족하는 Critical 또는 Important 발견 사항이 하나 이상 있을 때만 변경을 요청합니다. 요청된 대로 작동하고 Minor 또는 미확인 우려 사항만 있는 변경은 승인되며, 해당 우려 사항은 나열됩니다. 올바른 변경을 거부하는 것은 잘못된 변경을 승인하는 것만큼 작성자에게 비용을 발생시킵니다.

6단계: 발견 사항에 대한 조치(작성자로서)

리뷰 피드백은 수행해야 할 명령이 아니라 평가해야 할 입력입니다.

  1. 반응하기 전에 모든 피드백을 읽습니다. 항목이 불분명하면 무엇이든 구현하기 전에 먼저 질문합니다: 항목들은 종종 관련되어 있습니다.
  2. 각 항목을 기술적 요구사항으로 재진술하고, 코드에 대해 검증합니다. 이 코드베이스에 대해 올바른가? 무언가를 깨뜨리나요? 현재 코드에 이유가 있었나요? 리뷰어가 전체 맥락을 가지고 있나요?
  3. 잘못된 경우 증거(테스트, 파일:줄, 측정값)를 가지고 반박합니다. 제안이 사용되지 않는 "적절한" 기능을 추가하는 경우, 사용 여부를 확인합니다. YAGNI는 리뷰어에게도 적용됩니다. 사용자의 이전 결정과 충돌하는 사항은 사용자에게 에스컬레이션합니다.
  4. 순서대로 수정: Critical/차단 → 간단 → 복잡. 각 수정은 먼저 발견 사항을 재현하는 실패하는 테스트( test 를 통해)를 작성하고, 그 다음 수정, 마지막으로 전체 스위트가 통과하는지 확인합니다. 하나의 집중된 수정 패스, 무한 루프 금지.
  5. 수정하지 않은 Minor 사항은 최종 메시지의 "연기" 목록에 넣습니다. 수정하지 않기로 결정한 발견 사항은 이유와 함께 기록된 결정입니다.
  6. 가식적인 동의 금지. "완전히 맞습니다!", "좋은 발견 감사합니다!" 또는 감사 표현 금지. 변경한 사항을 명시("수정됨: 빈 행은 이제 헤더만 있는 CSV를 출력합니다. 테스트 빈 뷰에 대한 헤더 내보내기 추가") 또는 코드가 그대로 유지되는 이유를 설명합니다. 반박했다가 틀렸다면, 한 줄로 말하고 수정합니다.

GitHub에서는 최상위 댓글이 아닌 인라인 댓글 스레드에 답변합니다.

병합 전(완료 정의)

  • 모든 사양 성공 기준이 충족되고 실행 중인 시스템에서 확인됨
  • 새로운 동작에는 변경 없이는 실패하는 테스트가 있음; 전체 스위트 통과, 깨끗한 출력
  • 열려 있는 Critical 또는 Important 발견 사항 없음; 연기 사항은 이유와 함께 기록됨
  • 죽은 코드, 디버그 출력, 주석 처리된 블록 없음; 변경 사항은 작업 범위로 제한됨
  • 린트, 타입체크, 빌드 통과
  • 마이그레이션, 설정, 플래그 처리됨; 위험한 변경에 대한 롤백 경로 존재
  • 공개 인터페이스와 사용자에게 보이는 동작이 문서화됨; 되돌리기 어려운 결정에 대한 ADR
  • 커밋 메시지와 PR 설명이 독립적인 용어로 변경 사항과 이유를 설명
  • 프로젝트 요구 시 사람이 승인함

일반적인 합리화

생각현실
"테스트가 통과하니까 괜찮다"테스트는 잘못된 설계, 보안 허점, 사양 오독을 잡지 못합니다.
"내가 작성했으니 맞다는 걸 안다"같은 작성자, 같은 사각지대. 새로운 시각을 얻으십시오.
"AI가 만든 코드는 아마 괜찮을 거야"잘못되었을 때 자신감 있고 그럴듯합니다. 더 많은 검토가 필요합니다.
"리팩토링이 더 깔끔하다"독자가 동일한 수의 개념을 유지한다면, 단지 이동시킨 것뿐입니다.
"나중에 정리하자"나중은 거의 오지 않습니다. 지금 수정하거나 명시적으로 기록하십시오.
"사양이 그 입력을 언급하지 않았다"침묵은 허락이 아닙니다. 사용자가 받는 영향으로 등급을 매기십시오.
"리뷰어가 Minor라고 했으니 Minor다"효과에 따라 재평가하십시오.
"수정은 명백하니 테스트가 필요 없다"실패하는 테스트만이 발견 사항이 실제였고 이제 사라졌다는 유일한 증거입니다.
"리뷰어가 아마 맞을 거야"먼저 코드에 대해 검증하십시오.

위험 신호

  • 읽었다는 증거 없이 "LGTM"
  • 파일:줄 없이, 또는 호출자와 가드를 확인하지 않고 주장된 발견 사항
  • 사양과 품질 발견 사항이 하나의 순위 목록으로 병합됨
  • 정확성 버그 위에 nit이 묻힘
  • 리뷰어에게 작성자의 세션 기록을 제공함
  • 실패하는 테스트 없이 리뷰 발견 사항을 수정함
  • 일부 피드백 항목은 구현하고 다른 항목은 무시함

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

관련 스킬