zoo3323 paper-summary
현재 작업 폴더의 PDF 논문을 한국어로 변환한다. 결과는 2개의 HTML:
번역본.html— 논문 전체를 빠짐없이 한국어로 번역. 그림/표/수식/그래프를 원문 그대로 포함.요약본.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 → 커버리지 같은 표기는
읽는 사람이 뜻을 짐작할 수 없으므로 번역이 아니라 미번역으로 취급한다.
규칙
- 뜻이 드러나는 한국어로 옮긴다. 발음만 옮긴 표기를 결과물에 남기지 않는다.
- 영어 병기는 첫 등장에만. 「제어 장치(harness)」처럼 한 번 병기하고 이후에는 한국어만 쓴다. 섹션 제목·표 머리글·그림 캡션에도 똑같이 적용한다.
- 한 문서 = 한 대역어. 같은 원어를 앞에서는 "궤적", 뒤에서는 "트래젝토리"로 쓰는 혼용이 실제로 자주 났다. 번역을 시작하기 전에 핵심 용어 10~20개의 대역어를 먼저 정해 놓고 끝까지 그 표를 지킨다. (아래 3.5 단계)
- 제목(
{{TITLE_KO}})에는 음차를 절대 쓰지 않는다. 제목만 읽고도 무슨 논문인지 알 수 있어야 한다. (나쁜 예: "실행 궤적에 대한 추론 시점 정합으로서의 하네스") - 마땅한 한국어가 정말 없으면, 음차 대신 영어 원문을 그대로 둔다. 우선순위는
한국어 번역 > 영어 원문 유지 > 음차순이다. 음차는 최후의 선택이다.
판단 기준
그 단어를 처음 보는 한국어 독자가 한글 표기만 보고 뜻을 짐작할 수 있는가?
- 짐작 가능 → 그대로 써도 된다 (모델, 데이터, 토큰, 프롬프트 …)
- 짐작 불가 → 반드시 번역한다 (하네스, 트래젝토리, 커버리지 …)
그대로 써도 되는 예외
- 국내에서 이미 굳어진 말: 모델, 데이터, 데이터셋, 토큰, 프롬프트, 알고리즘, 파라미터, 벡터, 네트워크, 에이전트, 벤치마크, 베이스라인, 워크플로, 파이프라인
- 고유명사는 번역하지 말고 영문 그대로 둔다. 모델명(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. 폴더 생성
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 폴백):
python3 -c "import fitz" 2>/dev/null \
|| pip3 install --quiet pymupdf \
|| pip3 install --quiet --user pymupdf
그다음 추출:
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개를 골라 대역어를 정한다. 위 「번역 원칙」의 판단 기준을 적용하고, 음차로 처리한 단어가 하나라도 있으면 다시 고른다. 정한 표를 사용자에게 한 번 보여준 뒤 번역에 들어간다 — 논문 제목의 번역도 이때 함께 확정한다. 이후 번역본·요약본 전체에서 이 표를 예외 없이 지킨다.
4. korean/.work/src/body.html 작성 — 전체 번역
번역본 본문만 쓴다. <html>·<head>·<style>·네비게이션은 쓰지 않는다 — 조립기가 붙인다.
규칙:
- 요약하지 말고 전부 번역한다. 초록·서론·관련연구·방법·실험·결과·논의·결론·(중요하면 부록)까지 원문 순서대로.
- 섹션 제목은 한국어로 번역한다. 학술 용어는 첫 등장에만 「한국어(English)」로 병기하고 이후에는 한국어만 쓴다. 음차는 쓰지 않는다 (위 「번역 원칙」 참조).
- 그림: 본문 해당 위치에
manifest에 있는<figure><img src="images/p003_img12.png" alt="그림 3"> <figcaption>그림 3. (번역한 캡션)</figcaption></figure>src를 그대로 쓴다. PDF의 모든 주요 그림/그래프/다이어그램을 포함한다. - 표: 텍스트를 읽어 HTML
<table>로 재구성하고 셀 내용을 번역한다.<div class="table-wrap">...</div>로 감싼다. - 수식: MathJax 사용. 인라인은
\( ... \), 디스플레이는\[ ... \]. PDF의 수식을 LaTeX로 정확히 옮긴다. 변수 정의·기호 설명도 번역. - 인용은
<blockquote>..callout은 한 문서에 3개 이하로 아껴 쓴다 (「문서 만들기 원칙」 참조). - 함께
korean/.work/src/meta.json을 쓴다:{"TITLE_KO":"번역한 제목","TITLE_ORIGINAL":"원제", "AUTHORS":"저자 · 소속","VENUE_YEAR":"학회/저널 · 연도 (모르면 —)"}
5. korean/.work/src/summary.html 작성 — 핵심 요약
한 파일에 조각들을 마커로 구분해 이어 쓴다. 마커 줄은 그 자체로 한 줄이어야 한다:
<!--#TLDR-->
<p>한두 문장. 이 페이지에서 가장 무거운 요소다.</p>
<!--#PROBLEM-->
<p>이 논문이 풀려는 문제와 기존 방법의 한계.</p>
<!--#CONTRIBUTION-->
<ul><li>…</li></ul>
<!--#METHOD-->
…
여덟 개 마커를 모두 쓴다(내용이 없으면 <p>해당 없음</p>):
| 마커 | 내용 |
|---|---|
TLDR |
한두 문장 핵심. 여기서 다 말하려 하지 않는다 |
PROBLEM |
풀려는 문제와 기존 한계 |
CONTRIBUTION |
핵심 아이디어·기여 (목록 권장) |
METHOD |
방법. 핵심 수식 1~2개, 핵심 그림 1개까지 인용 가능 |
RESULTS |
주요 실험·정량 결과 (핵심 수치는 표로) |
CONCLUSION |
결론·시사점 |
LIMITATIONS |
한계·향후 과제 |
TERMS |
핵심 용어 정의 (<ul>) |
절 제목은 템플릿이 이미 달아 준다 — 조각 안에 "해결하려는 문제" 같은 제목을 다시 쓰지 않는다.
5.3. 조립
python3 "<base-dir>/scripts/build_html.py" "<base-dir>" "korean/.work/src" "korean"
번역본.html 과 요약본.html 이 만들어진다. 경고가 나오면(치환 안 된 자리, 빈 항목)
원고를 고치고 다시 실행한다 — 같은 명령을 몇 번 실행해도 안전하다.
번역본만 다시 만들려면 summary.html 을, 요약본만이면 body.html 을 잠시 치워도 된다.
5.5. 자가 점검
원고를 훑어 아래를 확인하고, 걸리면 고친 뒤 다시 조립한다.
- 음차: 3.5 의 대역표를 어긴 곳, 「번역 원칙」의 예외 목록에 없는 음차 표기. 특히 제목·소제목·표 머리글·그림 캡션을 본다.
- 이모지: 본문에 아이콘 대신 쓴 이모지가 없는지.
grep -oE '[🎯💡🛠🧪✅⚠📌🔍📊🚀✨]' korean/.work/src/*.html - 카드 남용:
.callout이 문서당 3개를 넘지 않는지.grep -c 'class="callout"' korean/.work/src/body.html - 인라인 스타일:
style=속성이나<style>을 원고에 넣지 않았는지.
6. 마무리 보고
- 생성된 파일 경로를 알려준다:
korean/번역본.html,korean/요약본.html. - 브라우저로 여는 법 안내:
open korean/번역본.html(macOS). - 원고를 고쳐 다시 조립할 수 있음을 알린다. 숨김 폴더이므로 경로를 그대로 적어 준다:
korean/.work/src/를 고치고 5.3 명령을 다시 실행하면 된다고 안내한다. (파인더에서 열려면open korean/.work/src) - 처리한 페이지 수, 포함한 그림 수를 요약.
- 필요하면
paper-summary-word스킬로 용어/약어 사전을 추가할 수 있음을 안내한다.
품질 기준
- 완전성: 번역본은 논문 전체를 담는다. 누락/축약 금지.
- 충실성: 수식·기호·수치를 임의로 바꾸지 않는다. 확실치 않으면 원문 표기 병기.
- 그림 그대로: 추출된 이미지를 재생성하지 말고 원본 PNG를 그대로 임베드한다.
- 자연스러운 한국어: 직역투를 피하되 의미는 정확히.
- 음차 금지: 발음만 한글로 옮긴 표기를 남기지 않는다. 전문용어는 첫 등장에만 영어 병기. 같은 원어에는 문서 전체에서 같은 대역어를 쓴다. (「번역 원칙」 참조)
- 보기는 건드리지 않는다: CSS·템플릿을 고치거나 인라인
style=을 쓰지 않는다. 네비게이션·active 탭·다크 모드 버튼은 템플릿이 이미 맞춰 두었다.
주의
- 이름은 정확히 이대로 쓴다 — 폴더는 영어(
korean,images,.work,src), 결과 파일은 한글(번역본.html,요약본.html). 임의로 바꾸면 네비게이션 링크가 깨진다. - 동일 이름 폴더가 이미 있으면 덮어쓰기 전에 사용자에게 확인한다.
- 그림이 너무 많거나 큰 경우에도 모두 포함하되, 명백한 로고/장식/페이지 배경 크롭은 제외해도 된다.
- 수식 렌더링은 MathJax CDN을 사용하므로 결과 HTML을 열 때 인터넷 연결이 필요하다(오프라인에서는 수식만 렌더링되지 않고 나머지는 정상 표시).