Skip to content

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

hyper-debug

Verified

Use this skill when a reported runtime failure - a stack trace, a failing test, wrong output, a crash, or an intermittent failure - needs a confirmed cause and a reproduction, plus a minimal fix only when the user authorized one. It reproduces first, tests at least two competing hypotheses against runtime evidence, proves the cause by toggling it, and journals under `.hyper/debug/`. Do not use for a deployment or platform failure, a product-language change request, a new feature plan, or a commit.

rules/flaky-triage.ko.md

View on GitHub
# Flaky Triage

실패가 실행마다 재현되지 않을 때 이 파일을 읽는다. "가끔 실패한다", "매번 다른 테스트가 실패한다", "혼자 돌리면 통과한다", "CI에서만 실패한다"가 모두 해당한다. 간헐성 자체가 증거다. 가설을 세우기 전에 분류하라. 분류만으로 탐색 공간의 대부분이 한 단계에서 사라진다.

## 1. Capture The Signature

정해진 횟수만큼 진단 재실행을 한다. 각 실행은 질문 하나에 답하고, 실행마다 일지에 적는다. 초록을 얻으려고 반복하는 시도가 아니라 진단 실행이다.

| Rerun | 답하는 질문 |
|---|---|
| 방금 실패한 정확한 명령을 다시 | 같은 테스트가 또 실패하는가, 다른 테스트가 실패하는가? |
| 실패한 테스트만 그 하나로 걸러서 | 혼자 돌리면 통과하는가? |
| 이번 실행의 다른 프로세스를 멈춘 조용한 기계에서 전체 범위 | 아무것도 함께 돌지 않을 때 전체가 초록이 되는가? |
| 순서를 섞거나 시드를 명시한 전체 범위 | 특정 순서가 재현하는가? 시드를 기록한다. |

조용한 실행을 만들려고 사용자의 동시 작업을 멈추지 않는다. 이번 실행이 소유한 것만 격리하고, 격리하지 못한 것을 기록한다.

## 2. Classify

| Signature | Classification | Next move |
|---|---|---|
| 같은 테스트가 어디서나, 혼자서도 간헐적으로 실패 | 검사 대상 코드의 실제 경쟁, 또는 비동기 테스트 버그. 고정 대기, await 없는 promise, 폴링 루프 | §4 실제 경쟁. 완료 이벤트 구독이나 시계 주입으로 결정적으로 재현 |
| 매번 다른 테스트나 파일이 실패하고, 각각 혼자서는 통과하며, 조용한 기계에서는 초록 | 동시 실행 사이의 경합 | §3 체크리스트를 돈 뒤 테스트 인프라를 고침 |
| 같은 테스트가 전체 스위트에서만 실패하고 격리하면 초록 | 순서 의존 또는 새는 픽스처 | §4 순서 의존. 기록한 시드로 이분 탐색 |
| CI에서만 실패하고 로컬에서는 절대 실패하지 않음 | 자원 한계(느린 디스크·CPU가 타임아웃에 닿음), 다른 병렬 기본값, 컨테이너 시계, 빠진 서비스 | 같은 제약 아래 로컬에서 재현. 대기가 아니라 신호를 키움 |
| 같은 커밋을 그냥 다시 돌리면 초록 | 여전히 flake다. 무시하기 전에 분류하라. 분류되지 않은 flake는 숨은 버그 보고다 | 경계가 있는 구분 재현을 잡아 기록 |

분류를 만든 재실행과 함께 일지에 적는다. 서명이 어느 행에도 맞지 않으면 그렇다고 적고, 범주를 억지로 고르지 말고 열린 실제 경쟁 가설로 다룬다.

## 3. Contention Checklist

같은 저장소의 동시 실행, 또는 한 체크아웃과 백그라운드 에이전트가 전역 가변 자원을 공유하는 것이 가장 흔한 현대적 원인이다. 실패 창이 아직 열려 있을 때 항목마다 확인한다.

- **공유 임시 루트** — 실행마다 고유한 디렉터리가 아니라 고정 경로에서 파생한 캐시·샌드박스 디렉터리. 두 실행이 같은 트리를 읽고 쓴다.
- **고정 포트** — 하드코딩된 수신 포트. 두 스위트가 바인딩을 다투고, 진 쪽은 마침 돌던 파일에서 연결 오류를 낸다.
- **전역 환경·설정 변경** — 테스트가 닷파일, 공유 설정, 프로세스 밖 상태를 써서 다른 실행이 읽게 한다.
- **공유 컨테이너·데이터베이스** — 같은 컨테이너 이름, 같은 스키마, 같은 볼륨.
- **캐시와 잠금** — 패키지 매니저 캐시, lockfile, 인덱스 경합.

살아 있을 때 잡아 둘 증거: 포트의 리스너, 공유 임시 경로의 목록, 동시 실행자를 보여 주는 프로세스 목록.

## 4. Fix Policy By Classification

- **경합** → 개별 테스트가 아니라 테스트 인프라를 고친다. 스위트 전역 자원을 실행마다 네임스페이스로 나눈다. 고유 임시 디렉터리, 임시 포트, 고유 컨테이너 이름이다. 기준은 이 저장소의 두 체크아웃이 동시에 스위트를 돌려도 서로 방해하지 않는 것이다.
- **순서 의존** → 기록한 시드로 새는 픽스처를 찾고, teardown에서 초기화하고, 기록한 실패 순서를 결정적으로 검증한 뒤, 최종 검사에 셔플 범위를 남긴다.
- **실제 경쟁** → 정상 가설 루프로 돌아간다. 더 긴 대기 대신 완료 이벤트 구독이나 주입한 시계로 경쟁을 결정적으로 재현하는 실패 우선 테스트와 함께 수정을 낸다.

## 5. Forbidden Fixes

아래 네 가지는 분류와 무관하게 간헐 실패의 해법으로 금지한다. 모두 버그 보고를 없애지 않고 숨긴다.

1. **재시도 래퍼** — 통과할 때까지 테스트를 다시 돌리는 데코레이터, 루프, 러너 수준 재시도.
2. **더 긴 대기** — flake 빈도를 낮추려고 고정 대기를 늘리거나 지연을 더하거나 타임아웃을 올리는 것.
3. **격리** — 테스트를 건너뛰기 집합이나 "알려진 flaky" 집합으로 옮기거나 게이트에서 빼는 것.
4. **테스트 삭제** — 테스트를 지우거나, 실패할 수 없을 때까지 단언을 약화하는 것.

분류했지만 고치지 않은 flake는 숨길 것이 아니라 보고할 발견이다. 서명, 증거, 분류, 열어 둔 이유를 일지에 적고 마무리 보고에서 말한다.

## 6. Cleanup

추가 재실행 산출물, 임시 시드, 이 분류가 더한 probe를 제거한다. 진단 실행을 위해 러너 설정을 바꿨으면 되돌린다.

## Sources

> Checked 2026-11-09.

| Claim | Source |
|---|---|
| 경합·순서 의존·실제 경쟁의 구분과 서명 표 | `dbc-hbin/omp-ulw@74df40f debugging/references/methodology/03-flaky-triage.md` (mechanism reference, re-authored) |
| 경합 체크리스트와 실행별 자원 네임스페이스 | `dbc-hbin/omp-ulw@74df40f debugging/references/methodology/03-flaky-triage.md` (mechanism reference, re-authored) |
| 재시도 래퍼, 더 긴 대기, 격리, 테스트 삭제를 금지 수정으로 | `dbc-hbin/omp-ulw@74df40f debugging/references/methodology/03-flaky-triage.md` (mechanism reference, re-authored) |
| 분류했지만 고치지 않은 flake는 보고하고 숨기지 않기 | `dbc-hbin/omp-ulw@74df40f debugging/references/methodology/03-flaky-triage.md` (mechanism reference, re-authored) |

### Evidence grade

`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