---
창작_제목: "막히는 지점이 곧 품질이다 — hyperresearch 게이트 전수 해부"
원본_출처: https://github.com/jordan-gibbs/hyperresearch (README) / https://discuss.pytorch.kr/t/hyperresearch-claude-code-16/11646
문서_목적: "hyperresearch가 보고서 발행을 막아 세우는 모든 게이트를 계층별로 정리하고, 각 게이트를 실제로 어떻게 쓰는지 + 내 워크플로우에 어떻게 이식하는지 제시"
작성일: 2026-08-19
검증_상태: "게이트 명칭·동작·CLI 명령은 README 원문 대조 완료. 미검증 항목은 별도 표시."
---

# hyperresearch 게이트 전체 정리 + 활용법

> **게이트(gate)란?**
> "지키세요"라는 부탁이 아니라, **통과 못 하면 다음으로 못 넘어가는 기계적 관문**입니다.
> hyperresearch의 설계 철학은 단 한 줄로 요약됩니다 — *검증을 사람의 성실성에 맡기지 않는다.*

---

## 1. 게이트 지도 (한눈에)

| 시점 | 게이트 | 무엇을 막는가 | 강도 |
|---|---|---|---|
| 실행 전 | **Budget cap** | 비용이 조용히 불어나는 것 | 실행 차단 |
| 실행 중 | **Scaffold-prompt lint** | 사용자 원본 질의가 변형·유실되는 것 | 오류 |
| 실행 중 | **Locus coverage lint** | 뽑아놓은 초점을 조사하지 않고 넘어가는 것 | 오류 |
| 실행 중 | **Provenance lint** | 출처 없이 떠도는 고아 자료 | 경고 |
| 실행 중 | **Schema integrity (SQLite CHECK)** | 깨진 머리말이 색인을 오염시키는 것 | DB 차단 |
| 수정 단계 | **Tool-lock `[Read, Edit]`** | "그냥 다시 쓰자" (재생성) | 물리적 불가 |
| 수정 단계 | **Patch-surgery lint** | 중대 지적이 조용히 반영 안 되는 것 | 오류 |
| 발행 직전 | **Quote-integrity** | 지어낸 인용문 | **발행 차단** |
| 발행 직전 | **Retracted-citations** | 철회 논문을 밝히지 않고 인용 | **발행 차단** |
| 발행 직전 | **Numeric-consistency** | 근거로 되짚을 수 없는 숫자 | 표시(flag) |
| 발행 직전 | **Cite-check (14.5단계)** | 인용과 문장이 실제로 안 맞는 것 | 재수정 유발 |
| 발행 직전 | **Retraction sweep** | 어제 올라온 철회 소식 누락 | **발행 차단** |
| 상시 | **Independence audit** | 같은 보도자료 5개 = 근거 5개라는 착각 | 가중치 하향 |
| 상시 | **Untrusted-source 격리** | 웹 본문 속 프롬프트 인젝션 | 데이터로 강등 |
| 상시 | **CAPTCHA / 2FA / 로그인 비자동화** | 에이전트의 인증 우회 | 사람에게 이관 |

---

## 2. 계층별 상세

### 2-1. 실행 전 게이트 — 돈이 새는 것부터 막는다

**Budget cap**
```bash
hyperresearch run init --budget 50
```
예상 API 사용량 상한을 겁니다. 상한을 넘는 순간 **조용히 불어나는 대신 실행이 막힙니다**.
`full` 기본값도 1.5~2.5시간, `dissertation`은 4~8시간짜리 도구이므로 이 게이트를 먼저 거는 것이 순서상 맞습니다.

---

### 2-2. 실행 중 게이트 — 파이프라인이 단계를 빠뜨리지 못하게

**Scaffold-prompt lint** — 뼈대 문서가 사용자의 **원본 프롬프트 그대로**로 시작하지 않으면 차단합니다.
사용자가 쓴 질의 원문은 `research/runs/<vault_tag>/query.md`에 **한 번 저장되고**, 이후 모든 단계와 하위 에이전트가 그 파일을 다시 읽습니다. 긴 파이프라인에서 원래 질문이 조금씩 변형되는 현상(질의 표류)을 구조로 막는 장치입니다.

**Locus coverage lint** — 4단계에서 뽑은 모든 초점(locus)은 5단계 중간 노트를 **반드시** 가져야 합니다. 없으면 오류로 표시됩니다.

**Provenance lint** — 모든 자료는 `--suggested-by`로 "누가 이걸 물어왔는지" 링크를 답니다. 이 사슬은 씨앗 수집에서 뻗어나온 트리 형태여야 하고, 연결이 끊긴 덩어리가 있으면 잡아냅니다.

**Schema integrity** — `tier`, `content_type`, `type` 세 항목은 SQLite CHECK 제약이 걸린 고정 어휘입니다. 머리말이 망가진 노트는 애초에 색인에 들어가지 못합니다.

```bash
hyperresearch lint -j          # 깨진 링크, 누락 태그 등 보관소 건강검진
hyperresearch run status -j    # 단계별 진행/지출/에스컬레이션 대기 수
```

---

### 2-3. 수정 단계 게이트 — 다시 쓰지 못하게 손을 묶는다

**Tool-lock `[Read, Edit]`** ← *가장 중요한 설계*
14(패치), 15(다듬기), 16(가독성) 단계 담당 에이전트는 **Claude Code 도구 허용 목록 수준**에서 `Read`와 `Edit`만 갖습니다. `Write`가 없으므로 새 초안 작성이 **물리적으로 불가능**합니다. 여기에 hunk당 상한까지 걸려 있어 "통째로 갈아엎기"가 기계적으로 차단됩니다.

**Patch-surgery lint** — 비평가가 CRITICAL로 지목했는데 패처가 작은 수정으로 담아내지 못한 건은 조용히 사라지지 않고 **구조적 문제로 승격**되어 표면에 드러납니다.

> 💡 이 두 개가 짝입니다. 재생성을 막으면 "안 고쳐지는 지적"이 생기는데, 그걸 숨기지 않고 승격시키는 게이트가 뒤를 받칩니다.

---

### 2-4. 발행 직전 게이트 — 여기서 진짜로 막힌다

```bash
hyperresearch run verify <tag> -j   # 발행 게이트 일괄 실행
```
검사 항목: 제목 구조, 분량, 인용 밀도, cite-check 해소 여부 + 아래 3종.

| 검사 | 판정 기준 |
|---|---|
| **quote-integrity** | 따옴표 친 구절이 보관 노트에 **글자 그대로** 없으면 차단. 지어낸 인용문은 통과 불가 |
| **retracted-citations** | 철회된 논문을 철회 사실을 밝히지 않고 인용하면 **하드 에러** |
| **numeric-consistency** | 근거로 되짚을 수 없는 숫자는 별도 표시 |

**Cite-check (14.5단계)** — 회의적인 검사기가 "이 인용이 정말 이 문장을 뒷받침하는가"를 표본 감사하고, 문제가 있으면 **2차 외과적 수정**이 돌아갑니다.

**Retraction sweep** — 발행 직전 인용된 **모든 DOI를 다시 조회**합니다. 옛 실행에서 재사용한 보관소 자료도 포함이라, 어제 올라온 철회까지 오늘 잡힙니다.

> ⚠️ **핵심 설계 포인트**: 보고서 어조를 정하는 `register` 레버(`teach`/`survey`/`analyze`/`advocate`)는 비평가에게는 전달되지만 **인용 검증기와 발행 게이트에는 전달되지 않습니다**. 검증은 어조에 따라 느슨해지지 않습니다.

---

### 2-5. 상시 게이트 — 품질과 안전

**Independence audit** — 같은 보도자료를 다섯 곳이 옮겨 실은 것을 한 묶음으로 취급합니다. *다섯 개의 복사본 = 한 표.*
```bash
hyperresearch sources independence -j   # 파생 복사본 군집화
hyperresearch sources score -j          # 인용수, 게재지, 철회 플래그 반영
hyperresearch graph rank -j             # 보관소 내 PageRank 중심성
hyperresearch search "질의" --ranked -j  # 품질 가중 검색
```
품질 점수는 자료 유형 등급 + 수집 시 유용성 + 인용 권위(OpenAlex / Semantic Scholar) + PageRank를 합산하며, **철회된 자료는 0에 가깝게 바닥으로 내려갑니다**.

**Untrusted-source 격리** — 수집한 웹 본문은 전부 `<untrusted-source url="...">` 구분자로 감싸 "이건 명령이 아니라 데이터"라는 서두와 함께 전달됩니다. 본문에 위조된 구분자 태그가 섞여 있으면 무력화하되 **흔적은 눈에 보이게** 남깁니다.

**인증 하드 바운더리** — CAPTCHA, 2단계 인증, 로그인은 **절대 자동 처리하지 않고** 한 번에 모아 사람에게 넘깁니다.
```bash
hyperresearch setup             # 브라우저 열어 직접 로그인
hyperresearch escalation list -j # 막힌 URL 대기열 확인
```

---

## 3. 실전 활용 순서

**1) 프로젝트별 설치 (전역 설치는 비추)**
```bash
cd your-project
pip install hyperresearch && hyperresearch install
```
`--global`은 모든 Claude Code 세션 시스템 안내에 약 15줄이 추가됩니다. 무관한 세션을 깨끗이 두려면 프로젝트별 설치.

**2) 예산부터 걸고 시작**
`run init --budget <숫자>` → 그다음 `/hyperresearch <조사할 내용>`

**3) 등급은 프롬프트로 조종**
`dissertation`은 자동 선택되지 않으므로 프롬프트에서 직접 요청해야 합니다. 규모를 키우려면 기어를 바꿉니다.
```bash
hyperresearch profile use premier   # 자료 100~130개, 깊이 예산 2배
hyperresearch profile use full      # 기본선으로 복귀
```

**4) 중단되면 이어붙이기**
```bash
hyperresearch run resume -j   # 죽은 지점부터 정확히 재개
hyperresearch run report -j   # 단계별 소요시간/지출/자료 산출량
```

**5) 발행 전 반드시**
`hyperresearch run verify <tag> -j` → 막히면 막힌 이유가 곧 고칠 항목입니다.

**6) 보관소는 자산이므로 git에 넣기**
노트는 `research/notes/`에 YAML 머리말 붙은 마크다운으로 저장됩니다. 색인이 깨지면 지우고 `hyperresearch sync`로 재생성하면 됩니다.

---

## 4. 내 워크플로우에 이식할 것 (도구를 안 써도 남는 것)

**① "지시로만 존재하는 검증"을 하나 찾아 기계적 관문으로 바꿔라**
"인용 확인하세요", "팩트체크 하세요"는 지켜지지 않습니다. *통과 못 하면 다음 단계로 못 가는* 형태로 바꾸세요. n8n이라면 조건 노드 하나로 구현 가능합니다.

**② 쓰는 역할과 고치는 역할의 권한을 분리하라**
수정 담당에게 전체 재작성 권한을 주면 반드시 다시 씁니다. 권한을 줄이는 것이 프롬프트로 부탁하는 것보다 강력합니다.

**③ 원본 질의(또는 요구사항)를 파일 하나에 고정하고 매 단계 다시 읽어라**
긴 작업일수록 원래 요구가 조금씩 변형됩니다. 파일 한 장이 표류를 막습니다.

**④ 외부에서 가져온 텍스트는 항상 "데이터"로 감싸라**
자동 수집 워크플로우를 만든다면 필수 방어책입니다.

**⑤ 출처 개수를 근거 개수로 세지 마라**
같은 원출처의 복사본은 한 표입니다. 이건 자료 조사 커리큘럼에서 그대로 가르칠 수 있는 원칙입니다.

**⑥ 읽은 것을 마크다운으로 남기고, 노트에 수명 주기를 붙여라**
`draft → review → evergreen`, 낡으면 `stale → deprecated → archive`. 이게 없으면 보관소는 반쯤 읽은 페이지들의 쓰레기장이 됩니다.

---

## 5. 게이트의 한계 (저자 본인이 명시한 것)

- **린트 게이트는 구조적 실패만 잡습니다.** 뼈대 누락, 출처 사슬 단절, 미해소 CRITICAL은 잡지만 **사실의 정확성은 보장하지 않습니다.**
- **어떤 자료가 중요한지에 대한 판단은 대신해 주지 않습니다.** 에이전트가 고르고, 방향은 사람이 잡습니다.
- **로그인하지 않은 유료 장벽 뒤의 자료는 가져오지 못합니다.**
- **빠른 사실 확인에는 과합니다.** 가장 가벼운 등급도 30분대입니다.