paper-summarySAFE

영어 논문 PDF → 한국어 번역본·요약본·용어사전 HTML 3종을 만드는 Claude Code 플러그인. 그림·표·수식을 원문 그대로 옮깁니다.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: paper-summary
description: 현재 폴더의 PDF 논문을 읽어 한국어로 (1) 전체 번역본 HTML 과 (2) 핵심 요약본 HTML 두 개를 만든다. 그림·표·수식·그래프를 그대로 가져오고, 두 문서는 서로 클릭 이동할 수 있다. 사용자가 /paper-summary 라고 하거나 "논문 번역/요약 html 만들어줘"라고 할 때 사용. (용어/약어 사전을 따로 만들려면 paper-summary-word 스킬을 쓴다.)
---

# paper-summary

현재 작업 폴더의 PDF 논문을 한국어로 변환한다. 결과는 **2개의 HTML**:

1. **`번역본.html`** — 논문 전체를 빠짐없이 한국어로 번역. 그림/표/수식/그래프를 원문 그대로 포함.
2. **`요약본.html`** — 해결하려는 문제·방법론·결과·결론 등을 카드 형태로 정리한 핵심 요약.

두 파일은 상단 네비게이션으로 서로 **클릭 이동** 가능하다.

> 용어/약어 사전(`용어사전.html`)은 별도 스킬 **`paper-summary-word`** 가 담당한다. 그 스킬을 실행하면 같은 `korean/` 폴더에 사전을 추가하고, 번역본·요약본의 네비게이션에도 용어사전 탭을 끼워 넣는다.

## 폴더 구조 (현재 폴더 기준으로 생성)

**사용자의 작업 폴더에는 `korean/` 하나만 새로 만든다.** 중간 산출물과 원고는
그 안의 숨김 폴더 `.work/` 에 넣어, 폴더를 열었을 때 읽을 것만 보이게 한다.

```
./korean/                  ← 새로 생기는 폴더는 이것 하나뿐
   ├─ 번역본.html           ← 조립기가 생성 (직접 쓰지 않는다)
   ├─ 요약본.html           ← 조립기가 생성 (직접 쓰지 않는다)
   ├─ images/              ← HTML이 참조하는 그림 파일들
   └─ .work/               ← 숨김. 파인더·ls 기본 목록에 안 보인다
       ├─ manifest.json
       ├─ fulltext.txt
       └─ src/             ← ★ 네가 직접 쓰는 원고
           ├─ meta.json
           ├─ body.html    ← 번역본 본문
           └─ summary.html ← 요약 조각들
```
> `.work/` 은 지워도 되는 찌꺼기가 **아니다.** 원고가 여기 있어서, 이걸 지우면 오타 하나
> 고치는 데도 논문을 처음부터 다시 번역해야 한다. 결과 폴더와 함께 남겨 둔다.

**너는 원고 조각만 쓰고, HTML 조립은 스크립트가 한다.** CSS·`<head>`·네비게이션 같은 뼈대를
받아쓰지 않으므로 빠르고, 디자인이 매번 흔들리지 않는다.

---

## 문서 만들기 원칙

보기(CSS·HTML 뼈대)는 `assets/` 에 이미 정해져 있다. **CSS 를 새로 쓰거나 인라인 `style=` 을
덧붙이지 않는다.** 아래는 네가 실행 중에 실제로 결정하는 것들만 다룬다.

- **상자가 아니라 글로 구조를 만든다.** 같은 크기 카드를 늘어놓는 순간 문서가 아니라 대시보드가 된다.
  절은 `<h2>`, 하위 절은 `<h3>`, 짧은 라벨은 `<h4>` 로 낸다.
  `.callout` 은 문서 흐름에서 정말 떼어놓아야 할 내용에만, **한 문서에 3개 이하**로 쓴다.
- **이모지를 아이콘으로 쓰지 않는다.** 제목·라벨·목록 앞에 🎯 💡 ✅ 같은 글자를 붙이지 않는다.
  (템플릿의 다크 모드 아이콘은 그린 SVG 다. 건드리지 말 것.)
- **제목 위에 꼬리표를 달지 않는다.** "핵심 정리" 같은 라벨을 제목 위에 얹지 말고 제목이 직접 말하게 한다.
- **번호를 매기지 않는다.** 01 / 02 / 03 은 순서 자체가 정보일 때만 쓴다.
  단, 원문의 절 번호(3.1 등)는 원문 구조이므로 그대로 살린다.
- **표는 표로.** 두 개 이상의 값을 나란히 비교하는 내용은 목록이 아니라 `<table>` 로 낸다.
  수치는 표에서 자리를 맞춰 정렬되므로 단위·자릿수를 원문대로 유지한다.
- **강조는 굵기로.** 색깔 배경이나 큰 글씨로 문장을 강조하지 않는다. `<strong>` 이면 충분하다.
- **요약본의 리드(`TLDR`)가 그 페이지에서 가장 무거운 요소다.** 한두 문장으로 끝내고,
  거기서 다 말하려 하지 않는다. 나머지는 아래 절들이 받는다.

---

## 번역 원칙 — 음차(발음만 한글로 옮기기) 금지 ★

이 스킬의 가장 흔한 실패는 **영어 단어의 뜻은 옮기지 않고 발음만 한글로 적는 것**이다.
`harness → 하네스`, `trajectory → 트래젝토리`, `coverage → 커버리지` 같은 표기는
읽는 사람이 뜻을 짐작할 수 없으므로 **번역이 아니라 미번역**으로 취급한다.

### 규칙

1. **뜻이 드러나는 한국어로 옮긴다.** 발음만 옮긴 표기를 결과물에 남기지 않는다.
2. **영어 병기는 첫 등장에만.** 「제어 장치(harness)」처럼 한 번 병기하고 이후에는 한국어만 쓴다.
   섹션 제목·표 머리글·그림 캡션에도 똑같이 적용한다.
3. **한 문서 = 한 대역어.** 같은 원어를 앞에서는 "궤적", 뒤에서는 "트래젝토리"로 쓰는 혼용이
   실제로 자주 났다. 번역을 시작하기 전에 **핵심 용어 10~20개의 대역어를 먼저 정해 놓고**
   끝까지 그 표를 지킨다. (아래 3.5 단계)
4. **제목(`{{TITLE_KO}}`)에는 음차를 절대 쓰지 않는다.** 제목만 읽고도 무슨 논문인지 알 수 있어야 한다.
   (나쁜 예: "실행 궤적에 대한 추론 시점 정합으로서의 하네스")
5. **마땅한 한국어가 정말 없으면, 음차 대신 영어 원문을 그대로 둔다.** 우선순위는
   `한국어 번역 > 영어 원문 유지 > 음차` 순이다. 음차는 최후의 선택이다.

### 판단 기준

> 그 단어를 **처음 보는 한국어 독자**가 한글 표기만 보고 뜻을 짐작할 수 있는가?

- 짐작 가능 → 그대로 써도 된다 (모델, 데이터, 토큰, 프롬프트 ...)
- 짐작 불가 → 반드시 번역한다 (하네스, 트래젝토리, 커버리지 ...)

### 그대로 써도 되는 예외

- **국내에서 이미 굳어진 말**: 모델, 데이터, 데이터셋, 토큰, 프롬프트, 알고리즘, 파라미터,
  벡터, 네트워크, 에이전트, 벤치마크, 베이스라인, 워크플로, 파이프라인
- **고유명사는 번역하지 말고 영문 그대로 둔다.** 모델명(GPT-5, Claude, DeepSeek-V3),
  데이터셋·벤치마크명(SWE-bench Verified, MMLU), 기법 고유명(LoRA, Transformer),
  라이브러리명(PyTorch). 억지로 한국어로 옮기면 오히려 원문을 찾을 수 없게 된다.

### 대역어 참고표

| 원어 | ❌ 음차 | ✅ 권장 번역 |
|---|---|---|
| harness | 하네스 | 제어 장치 / 실행 통제 장치 |
| trajectory | 트래젝토리 | 궤적 |
| coverage | 커버리지 | 적용 범위 / 포괄 범위 |
| chunk | 청크 | 덩어리 / 조각 (문서 분할이면 "본문 조각") |
| instance | 인스턴스 | 문제 사례 / 사례 (벤치마크 문항을 뜻할 때) |
| enterprise | 엔터프라이즈 | 기업용 |
| deep research | 딥리서치 | 심층 조사 |
| premature commitment | 프리마추어 커밋먼트 | 성급한 확정 |
| progressive disclosure | 프로그레시브 디스클로저 | 점진적 공개 |
| alignment | 얼라인먼트 | 정합 / 정렬 |
| rollout | 롤아웃 | 시행 / 전개 |
| guardrail | 가드레일 | 안전장치 |
| fallback | 폴백 | 대체 동작 / 차선책 |
| overhead | 오버헤드 | 추가 비용 / 부담 |
| latency | 레이턴시 | 지연 시간 |
| throughput | 스루풋 | 처리량 |
| ablation study | 어블레이션 | 구성요소 제거 실험 |
| retrieval | 리트리벌 | 검색 / 인출 |
| ground truth | 그라운드 트루스 | 기준 정답 |
| robustness | 로버스트니스 | 견고성 |
| scalable | 스케일러블 | 확장 가능한 |
| orchestration | 오케스트레이션 | 조율 / 총괄 제어 |
| backtracking | 백트래킹 | 되짚어 가기 / 역추적 |

표에 없는 단어도 같은 기준으로 판단한다. 이 표는 예시일 뿐 전부가 아니다.

---

## 실행 절차

### 0. 대상 PDF 찾기
- 인자(`$ARGUMENTS`)로 파일 경로가 주어지면 그것을 사용.
- 없으면 현재 폴더의 `*.pdf`를 찾는다.
  - 1개면 그걸 사용. 여러 개면 목록을 보여주고 **어떤 PDF인지 사용자에게 묻는다**.
  - 0개면 "현재 폴더에 PDF가 없습니다"라고 알리고 종료.

### 1. 폴더 생성
```bash
mkdir -p korean/images korean/.work/src
```

### 2. 의존성 확인 & 추출 실행
스킬 디렉토리의 추출 스크립트 `scripts/extract_pdf.py` 를 쓴다.
**스킬 호출 시 함께 표시되는 "Base directory for this skill" 경로를 기준**으로 잡는다.
(예: `<base-dir>/scripts/extract_pdf.py`. 절대 `~/.claude/skills/...` 로 추측하지 말 것 —
플러그인으로 설치되면 `~/.claude/plugins/cache/...` 아래에 있다.)

PyMuPDF가 필요하다. 먼저 시도하고, 없으면 설치(외부 관리 환경이면 `--user` 폴백):
```bash
python3 -c "import fitz" 2>/dev/null \
  || pip3 install --quiet pymupdf \
  || pip3 install --quiet --user pymupdf
```
그다음 추출:
```bash
python3 "<base-dir>/scripts/extract_pdf.py" \
  "<PDF경로>" "korean/.work" "korean/images"
```
- stdout 으로 `{"ok":true, n_pages, n_raster, n_vector, title, manifest, fulltext}` JSON 이 나온다.
- 결과: `korean/.work/manifest.json`(페이지별 텍스트 + 사용 가능한 이미지 목록), `korean/.work/fulltext.txt`,
  그리고 `korean/images/*.png`.
- `PYMUPDF_MISSING` 이 나오면 위 설치 명령 재시도. pip 도 막혀 있으면 사용자에게 알리고 어떻게 할지 확인한다.

### 3. 논문 내용 파악
- **Read 툴로 PDF 자체를 직접 읽는다** (페이지가 이미지로 렌더링되어 그림/표/레이아웃을 눈으로 확인 가능).
  긴 논문이면 `pages` 인자로 나눠 읽는다.
- `korean/.work/fulltext.txt` 로 정확한 텍스트(수식·기호 포함)를 대조한다.
- `korean/.work/manifest.json` 으로 **어떤 그림 파일이 어느 페이지에 있는지** 파악한다.
  각 이미지에는 `src`(예: `images/p003_img12.png`), `type`(raster=사진/스캔, vector=그래프/도표 크롭), `page`, 크기, vector는 `bbox`가 있다.
- PDF를 보며 manifest의 이미지가 본문의 어느 Figure인지 매칭한다. (vector 크롭은 잘리거나 중복될 수 있으니, PDF에서 본 실제 그림과 대조해 적절한 것만 고른다.)


### 3.5. 용어 대역표 먼저 확정 (번역 시작 전 필수)
번역을 쓰기 전에, 이 논문에서 반복되는 **핵심 용어 10~20개**를 골라 대역어를 정한다.
위 「번역 원칙」의 판단 기준을 적용하고, 음차로 처리한 단어가 하나라도 있으면 다시 고른다.
정한 표를

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (1)

Gates applied: no_behavioural_pass, no_license.