Skip to content

hashgraph-online/awesome-codex-plugins / plugins/alpoxdev/hypercore/skills/hyper-review

hyper-review

Verified

Use this skill when a change that already exists needs a verdict - review only a diff, a branch, a pull request, or the working tree, with an independent reviewer, a hands-on QA matrix, and a test-quality and code-smell gate, or review and fix the confirmed blockers when the user explicitly asks for repairs. It binds the verdict to the reviewed content, saves `.hyper/review/[slug].md`, and edits no source file unless the user asked to fix. Do not use it for a change that does not exist yet, a design or look review, a deployment failure, a runtime failure to diagnose, or a one-line wording edit.

rules/code-smells.ko.md

View on GitHub
# 코드 냄새

취향이 아니라 측정 가능한 트리거다. 트리거마다 측정 방법, 임계값, 예외가 무엇인지 밝힌다. 측정값을 보고하므로 작성자는 의견이 아니라 숫자에 반박할 수 있다.

## Contents

1. Size
2. Parameters
3. Redundant re-verification
4. Negative-form names
5. Duplication
6. Nesting and control flow
7. Comment and naming hygiene
8. Reporting a trigger

## 1. Size

| 트리거 | 임계값 | 측정 |
|---|---|---|
| 긴 함수 | 한 함수나 메서드의 순수 코드 250줄 초과 | 빈 줄, 주석만 있는 줄, 블록을 닫는 줄만 있는 줄을 뺀 줄 수 |
| 긴 파일 | 소스 파일 하나 800줄 초과 | 빈 줄과 주석만 있는 줄을 뺀 전체 줄 수 |
| 시그니처 뒤 긴 본문 | 서명 뒤 80줄 초과이면서 들여쓰기 세 단계 이상 | 함수 본문 안 들여쓰기 깊이와 순수 줄 수 |
| 넓은 표면 | 모듈 하나에서 내보내거나 공개하는 멤버 20개 초과 | 모듈이 노출하는 선언 수 |

생성 파일, 표, 마이그레이션, 픽스처, 벤더 파일은 예외다. 그렇게 밝히고 넘어간다. 평평한 switch나 조회표라서 긴 함수는 블로커가 아니라 `메모`이고, 변경이 거기에 더하지 않았을 때만 그렇다.

## 2. Parameters

| 트리거 | 임계값 | 측정 |
|---|---|---|
| 매개변수 과다 | 매개변수 세 개 초과 | `self`, `this`, 수신자를 뺀 선언 매개변수 수 |
| 동작을 고르는 불리언 매개변수 | 값이 함수의 동작을 바꾸는 불리언 매개변수 | 두 분기가 다를 때 리터럴 `true`나 `false`를 넘기는 호출 지점 |
| 선택 매개변수 더미 | 선택이거나 기본값이 있는 매개변수 두 개 초과 | 기본값이 있는 매개변수 수 |
| 잡동사니 매개변수 객체 | 필드 다섯 개 초과이고 호출마다 다른 부분집합을 쓰는 객체 | 필드 수와 호출별 부분집합 수 |

예외는 변경이 유지해야 하는 고정 인터페이스다. 콜백 시그니처, 프레임워크 훅, 외부 API. 제약을 이름 붙인다.

수정은 습관적으로 "객체로 감싸기"가 아니다. 매개변수를 지우거나, 함수를 하는 일로 나누거나, 선택을 이름 붙은 함수와 함께 호출자로 옮기는 쪽을 먼저 본다.

## 3. Redundant re-verification

| 트리거 | 임계값 | 측정 |
|---|---|---|
| 같은 값 반복 검증 | 한 호출 경로에서 같은 값에 대한 같은 확인이 두 번 이상 | 값을 진입부터 사용까지 따라가며 확인 횟수를 센다 |
| 실패할 수 없는 방어 확인 | 바로 앞 줄이 존재를 보장하는 값에 대한 null·범위 확인 | 만드는 문장이 같은 블록에 있고 빈 값을 반환할 수 없다 |
| 재파싱·재디코딩 | 같은 입력을 두 번 이상 파싱, 디코딩, 정규화한다 | 한 경로에서 같은 값의 변환 횟수 |
| 이중 조회 | 한 요청에서 같은 원격·데이터베이스 읽기가 두 번 | 한 경로에서 같은 키의 호출 횟수 |

예외는 통제하지 않는 경계다. 공개 함수, 외부 코드의 콜백, 디스크나 네트워크에서 읽은 값. 신뢰 경계에서의 검증은 중복이 아니다.

## 4. Negative-form names

| 트리거 | 측정 | 이유 |
|---|---|---|
| 부정형 불리언 이름 | `not`, `no`, `never`, `disable`로 시작하거나 `Disabled`, `Off`, `Excluded`로 끝나는 식별자 | 호출 지점마다 이중 부정으로 읽어야 한다 |
| 이중 부정 | `!notReady`, `if not disabled`처럼 부정이 둘인 조건 | 읽는 사람이 진릿값을 두 번 계산한다 |
| 긍정 기본값에 부정 접두 | 캐시가 켜져 있다는 뜻의 `noCache = false` | 문서 없이 기본값을 읽을 수 없다 |
| 동작의 부재를 말하는 이름 | `doNotRetry`, `skipValidation`, `withoutLogging` | 일어나지 않는 일을 이름 붙여 긍정 경로가 이름 없이 남는다 |

외부 API나 전송 형식의 이름은 예외다. `메모`로 보고 경계에서는 이름을 유지하며, 프로젝트 자체 코드 안에서만 이름을 바꾼다.

## 5. Duplication

| 트리거 | 임계값 | 측정 |
|---|---|---|
| 복사 블록 | 의미 있는 줄 10줄 초과가 식별자만 달라진 채 두 번 | 각 사본의 줄 수 |
| 평행 구조 | 식 하나만 다른 같은 모양의 함수가 각각 20줄 초과 | 제어 흐름 비교 |
| 기존 동작의 두 번째 구현 | 변경이 프로젝트에 이미 있는 것을 다시 구현한다 | 기존 위치를 이름 붙인다 |

10줄 미만 중복은 자동 발견 사항이 아니다. 세 줄짜리 블록 둘은 추상화보다 읽기 쉽다. 줄 수를 보고해 트레이드오프가 보이게 한다.

## 6. Nesting and control flow

| 트리거 | 임계값 | 측정 |
|---|---|---|
| 깊은 중첩 | 한 함수 안 조건문 중첩 세 단계 이상 | 조건문의 최대 들여쓰기 깊이 |
| 긴 조건 사슬 | 한 값에 대한 `else if` 분기 네 개 초과 | 분기 수 |
| 루프의 여러 출구 | 한 루프 안에서 서로 겹치는 `break`, `return`, `continue`가 두 개 이상 | 출구마다 추적 |
| 삼킨 오류 | 빈 catch, 기록하고 계속하는 catch, 실패 대신 기본값 반환 | 모든 catch와 오류 반환 호출 검사 |

파서, 상태 기계, 표 기반 디스패처는 모양이 문제를 그대로 반영할 때 중첩·사슬 트리거의 예외다.

## 7. Comment and naming hygiene

| 트리거 | 측정 |
|---|---|
| 코드를 되풀이하는 주석 | 이유를 더하지 않고 다음 줄을 바꿔 말한다 |
| 낡은 주석 | 코드가 더는 하지 않는 동작을 설명한다 |
| 주석 처리한 코드 | 설명 없이 주석 표시로 꺼 둔 코드 블록 |
| 디버그 잔여물 | 작성자만을 위해 남은 print, log, trace |
| 이 프로젝트에서 표준이 아닌 약어 | 모듈에서 뜻이 분명하지 않은 짧은 이름 |

## 8. Reporting a trigger

```text
Smell: 긴 함수 | 순수 287줄 | billing.ts:41-330 | should fix
Smell: 매개변수 네 개 | buildInvoice(a, b, c, d) | billing.ts:88 | should fix
Smell: 중복 재검증 | :92와 :101에서 같은 amount 검증 | should fix
Smell: 부정형 이름 | `noRetry`를 :140에서 `if (!noRetry)`로 사용 | note
```

심각도:

- `blocker`: 트리거가 실제 결함을 가린다. 삼킨 오류, 깨진 계약을 가릴 방어 확인, 금액이나 권한 규칙의 중복.
- `should fix`: 임계값을 넘었고 수정이 국소적이다.
- `note`: 프로젝트 관례가 그 모양을 설명한다.

임계값은 지침이다. 프로젝트 관례, 언어 관용, 명시된 제약이 여기 숫자보다 우선하고, 보고서는 어느 것이 적용됐는지 적는다.

## Sources

> Checked 2026-11-10.

| Claim | Source |
|---|---|
| 250줄 함수 트리거 | `dbc-hbin/omp-ulw@74df40f programming/references/code-smells.md` (메커니즘 참조, 다시 씀) |
| 매개변수 세 개 초과 트리거 | 같은 출처, 다시 씀 |
| 중복 재검증 트리거 | 같은 출처, 다시 씀 |
| 부정형 이름 트리거 | 같은 출처, 다시 씀 |
| 나머지 크기, 중복, 중첩, 위생 트리거 | 이 패키지가 고른 설계 |
| 숫자를 프로젝트 관례가 앞설 수 있는 지침으로 본다 | 이 패키지가 고른 설계 |

### Evidence grade

출처의 네 트리거는 `MECHANISM`이다. 나머지 표와 임계값은 `LOCAL`이다. 어느 숫자도 측정된 최적값이 아니며, 발견 사항에 반박할 수 있도록 고른 임계값이다.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 197kUpdated Claude CodeCodexVerifiedInstall