paper2code — arXiv 논문을 인용 근거가 남는 구현 저장소로 바꾸는 에이전트 스킬

paper2code는 일반적인 모델 라이브러리보다 재현성 중심(reproducibility-first) 에이전트 스킬에 가깝다. 입력은 arXiv URL 또는 ID이고, 출력은 README.md, REPRODUCTION_NOTES.md, src/, configs/base.yaml, notebooks/walkthrough.ipynb까지 갖춘 구현 저장소다. 이 프로젝트의 핵심은 “논문 구현” 자체보다 논문에 없는 부분을 숨기지 않고 드러내는 방식에 있다. 즉, 구현 품질을 높이는 동시에 [UNSPECIFIED], [ASSUMPTION], [FROM_OFFICIAL_CODE] 같은 라벨로 불확실성을 외부화한다.

자산 메모
분석 시점에 저장소 내부에서 커밋된 PNG/GIF/UI 스크린샷 자산은 확인되지 않았다. 루트 README.md에도 GIF 자리표시자(placeholder)만 존재한다. 따라서 figures/ 폴더의 이미지는 루트 README, SKILL.md, 파이프라인 문서, worked example 코드/README를 기반으로 충실하게 재구성한 분석용 도해다.

Quick Links

항목	링크
GitHub 저장소	PrathamLearnsToCode/paper2code
핵심 명세	skills/paper2code/SKILL.md
커뮤니티 소개 / 데모	PyTorchKR 소개 글
Worked Example 1	Attention Is All You Need
Worked Example 2	DDPM
예시 논문 1	Attention Is All You Need (1706.03762)
예시 논문 2	Denoising Diffusion Probabilistic Models (2006.11239)

 

공개 Wiki / Discussions는 분석 시점에 별도 엔트리가 드러나지 않았고, 실질적인 프로젝트 설명은 README.md, SKILL.md, pipeline/, guardrails/, worked/ 폴더에 집중되어 있었다.

Key Features

1. 인용 고정(citation anchoring) 코드 생성

paper2code가 가장 돋보이는 지점은 생성 코드가 단순히 “그럴듯한 구현”이 아니라, 논문 문장·표·식과 연결된 구현이 되도록 강제한다는 점이다. 예를 들어 설정값은 “§3.1, Table 3”처럼 근거를 남기고, 구현 중 빈칸은 그냥 메우지 않고 [UNSPECIFIED]로 표기한다. 이 구조는 나중에 코드 리뷰나 재현성 검증을 할 때 매우 강력하다.

특히 Transformer worked example에서는 d_model=512, n_heads=8, d_ff=2048처럼 논문에 명시된 값은 인용 근거를 달고, LayerNorm epsilon, max_seq_len처럼 애매한 부분은 불확실성 라벨로 분리한다.

 

 

캡션: worked example 코드 스타일을 재구성한 이미지다. 논문에 명시된 값은 섹션/표 인용으로 연결하고, 미명시 항목은 [UNSPECIFIED]로 외부화하는 paper2code의 핵심 방식을 보여준다.

분석 포인트: 이 프로젝트는 “코드를 생성하는 모델”보다 “생성된 코드의 provenance를 남기는 규율”에 더 가깝다.

2. 불확실성을 산출물로 남기는 REPRODUCTION_NOTES

보통 논문 구현은 코드만 보면 꽤 그럴듯하지만, 실제로는 어떤 값이 논문에서 왔는지, 어떤 값이 구현자의 상상인지 추적하기 어렵다. paper2code는 이를 REPRODUCTION_NOTES.md로 분리해 해결한다. 이 문서는 구현 후 생기는 애매함을 부록처럼 취급하지 않고, 프로젝트의 일급 산출물로 만든다.

Transformer 예시에서는 LayerNorm epsilon, weight initialization, max sequence length가 미명시 항목으로 정리되고, DDPM 예시에서는 gradient clipping, U-Net channel multipliers, expected FID 차이 같은 부분이 “공식 코드에서 가져온 것인지 / 논문에 없는 것인지”까지 구분된다. 이 방식은 단순한 README보다 훨씬 재현성 친화적이다.

 

 

캡션: REPRODUCTION_NOTES.md와 review.md 계열 아티팩트를 바탕으로 재구성한 이미지다. 애매한 구현 포인트를 “선택값 / 대안 / 출처 / 노트”로 분리하는 paper2code의 회계 방식을 보여준다.

분석 포인트: 논문 구현에서 중요한 것은 정답을 가장 빨리 쓰는 것이 아니라, 어디가 확정이고 어디가 추정인지 분리하는 일이다. paper2code는 그 분리를 문서화 레벨에서 강제한다.

3. 부록·표·수식·각주까지 파고드는 논문 수집 단계

fetch_paper.py와 extract_structure.py를 보면, 이 프로젝트는 단순히 arXiv PDF를 내려받아 텍스트로 긁는 수준에 머물지 않는다. 먼저 arXiv ID를 정규화하고, 메타데이터를 수집한 뒤, PDF 파싱이 실패하면 pdfplumber, 더 실패하면 ar5iv HTML로 후퇴한다. 이후 섹션, 알고리즘 블록, 식, 표, 각주를 분리한다.

이 설계는 중요하다. 실제로 재현성이 필요한 정보는 본문보다 부록, 표, 각주, 공식 코드 링크에 숨어 있는 경우가 많다. paper2code는 이 문제를 “모델이 알아서 읽겠지”가 아니라, 파싱 전략 자체를 다중 단계로 구성해 대응한다.

분석 포인트: 의료 AI와 Bioinformatics 논문은 부록 의존도가 높기 때문에, 이 프로젝트의 가치 중 상당 부분은 생성 모델보다도 이 획득(acquisition) 레이어에서 나온다.

4. 논문 유형별 스코프 제어(scope enforcement)

paper2code는 모든 논문을 같은 방식으로 구현하지 않는다. contribution_identification과 scope_enforcement 규칙을 보면, 논문을 다음처럼 분류한 뒤 핵심 기여 한 개를 중심으로 구현 범위를 정한다.

• Architecture paper
• Training / loss paper
• Inference paper
• Dataset / benchmark paper
• Theoretical + empirical paper
• System / engineering paper

이 구분은 worked example에서 가장 잘 드러난다. Transformer 예시는 아키텍처 논문이므로 전체 Transformer stack, label smoothing, learning-rate schedule까지 구현한다. 반면 DDPM 예시는 훈련 방법 논문이므로 U-Net 자체의 독창성보다 L_simple, forward/reverse process, sampling algorithm에 초점을 맞춘다. 즉, paper2code는 “논문처럼 보이는 전체 repo”를 만드는 것이 아니라, 논문이 실제로 기여한 부분을 중심으로 최소 충분 구현을 만든다.

5. 환각 방지를 문서 레벨에서 설계한 가드레일

이 저장소의 품질은 코드 양보다 guardrails/ 폴더가 설명해 준다. hallucination_prevention.md는 논문·부록·공식 코드·널리 알려진 재현 논문 외 근거가 없다면 명시적으로 UNSPECIFIED로 남기라고 지시한다. badly_written_papers.md는 논문이 애매하게 쓰여 있어도 조용히 추정하지 말라고 못 박는다. scope_enforcement.md는 논문 유형에 맞지 않는 주변 구현을 덧붙이지 못하게 막는다.

이 규율은 단순한 프롬프트 팁이 아니라, 에이전트 실행 정책(policy pack)이다. 결과적으로 paper2code는 “성능 좋은 모델”보다 “잘 통제된 에이전트”에 가깝다.

6. 교육용 walkthrough notebook 자동 생성

5단계 파이프라인의 마지막은 notebook 생성이다. 이 notebook은 예쁘게 시각화하는 데 목적이 있지 않다. 대신 논문 일부를 인용하고, 그 대응 코드를 바로 아래에 붙인 뒤, toy CPU 텐서로 sanity check를 수행한다. 즉, 구현 저장소를 바로 쓰기 위한 문서라기보다 사람이 검증 가능한 학습/이해 자료까지 함께 만든다.

 

 

캡션: 05_walkthrough_notebook.md의 규칙을 토대로 재구성한 이미지다. paper excerpt → inline code → toy CPU check라는 교육용 notebook 패턴을 요약한다.

분석 포인트: 오픈소스 재현 프로젝트 대부분은 “코드만 던지고 끝”나기 쉽다. paper2code는 “검증 가능한 설명 자료”를 강제로 포함시킨다는 점에서 온보딩 비용을 낮춘다.

7. 다중 모드 / 다중 프레임워크 지원

이 스킬은 하나의 출력 형식만 강제하지 않는다.

• 기본 프레임워크: PyTorch
• 대체 프레임워크: JAX, NumPy
• 모드: minimal, full, educational

minimal은 핵심 기여 구현에 집중하고, full은 데이터/학습 파이프라인까지 넓히며, educational은 주석과 notebook을 더 풍부하게 붙인다. 이 차이는 단순 편의 기능이 아니라, 논문 구현의 목적이 “재현”인지 “학습”인지에 따라 필요한 산출물이 다르다는 점을 정확히 반영한다.

8. Worked example + human review로 품질을 검증

저장소 자체는 크지 않지만, worked/attention_is_all_you_need, worked/ddpm, review.md를 통해 실제 예시와 수작업 리뷰를 제공한다. 이 구조가 좋은 이유는 두 가지다.

1. 에이전트가 만든 산출물의 기대 품질을 구체적으로 보여준다.
2. “무엇을 구현했고 무엇을 의도적으로 비워 두었는지”를 예시로 설명한다.

Transformer 예시는 출력 shape (2, 15, vocab_size)를 sanity check로 보여주고, DDPM 예시는 (2, 3, 32, 32) shape를 통해 최소 작동성을 확인한다. 동시에 DDPM review는 논문 수치와 실제 기대 FID가 다를 수 있음을 정직하게 경고한다.

 

 

캡션: 저장소 내부 worked example들을 재구성한 비교 이미지다. Transformer는 아키텍처 논문, DDPM은 훈련 절차 논문으로 다르게 스코프가 잡히는 점을 보여준다.

분석 포인트: 이 프로젝트는 “무조건 paper SOTA를 재현한다”가 아니라, “재현 가능한 최소 작업물과 그 한계를 정직하게 문서화한다”는 쪽에 더 가깝다.

Tech Stack

범주	스택	버전 / 상태	비고
에이전트 진입점	npx skills add 기반 설치	버전 고정 없음	Claude Code / 호환 에이전트에 스킬 추가
핵심 구현 언어	Python	저장소에 명시적 버전 고정 없음	GitHub language mix 기준 주력 언어
보조 산출물	Jupyter Notebook	저장소에 명시적 버전 고정 없음	walkthrough notebook 생성
논문 파싱 의존성	pymupdf4llm, pdfplumber, requests, pyyaml	SKILL 문서상 설치 예시만 존재	PDF/HTML 획득 및 구조 추출
출력 프레임워크	PyTorch, JAX, NumPy	PyTorch 기본, JAX/NumPy 선택 가능	paper type과 mode에 따라 산출물 달라짐
Worked example runtime	torch>=2.0.0, numpy>=1.24.0, pyyaml>=6.0	예제 requirements에 명시	실제 샘플 repo 실행 기준
지식 베이스	transformer_components.md, training_recipes.md, loss_functions.md, paper_to_code_mistakes.md	정적 문서	에이전트가 자주 틀리는 구현 지점 보정

 

 

캡션: 실제 폴더 구조를 바탕으로 재구성한 저장소 해부도다. 이 프로젝트는 대규모 코드베이스가 아니라, 에이전트 정책·지식·템플릿·예시를 조합한 구조다.

소스 구조 해설

디렉터리	역할
pipeline/	5단계 실행 절차 정의
guardrails/	환각 방지, 스코프 통제, 애매한 논문 대응 규칙
knowledge/	Transformer, loss, training recipe, 구현 실수 패턴에 대한 사전 지식
scaffolds/	생성 repo에 주입될 템플릿
scripts/	논문 획득 및 구조 추출용 보조 스크립트
worked/	실제 출력 예시와 검토 기준
review.md	예시 구현 품질에 대한 사람 관점 리뷰

Architecture

 

 

캡션: 루트 README.md의 ASCII 다이어그램을 시각적으로 재구성한 이미지다. 입력은 arXiv URL이고, 출력은 citation-anchored implementation repository다.

paper2code의 아키텍처는 화려한 서빙 인프라보다 문서화된 단계 실행에 초점이 맞춰져 있다. 전체 흐름은 다음과 같다.

1. Paper acquisition
   arXiv ID 정규화, PDF/HTML 획득, 섹션/표/수식/각주 추출, 공식 코드 링크 탐색
2. Contribution identification
   논문의 핵심 기여를 하나로 압축하고, 논문 유형을 분류해 구현 범위를 결정
3. Ambiguity audit
   논문에 없는 구현 세부를 SPECIFIED / PARTIALLY_SPECIFIED / UNSPECIFIED로 구분
4. Code generation
   설정, 모델, 손실, 데이터, 학습, 평가, README, notes, requirements를 생성
5. Walkthrough notebook
   논문 발췌 + 대응 코드 + toy CPU check를 묶은 설명형 notebook 생성

 

캡션: SKILL.md와 `pipeline/.md`를 토대로 재구성한 5단계 실행 흐름도다. 하단의 guardrails, knowledge, scaffolds, worked examples가 전 단계를 가로지르는 제어 레이어로 작동한다.*

아키텍처적 해석

이 프로젝트를 “논문 → 코드 변환기”라고만 보면 절반만 본 것이다. 실제 핵심은 아래 세 층이 함께 맞물린다는 점이다.

• Pipeline: 해야 할 일을 순서대로 강제한다.
• Guardrails: 해서는 안 될 추정과 과잉 구현을 막는다.
• Knowledge + Scaffolds: 자주 필요한 정답 패턴과 출력 템플릿을 제공한다.

즉, paper2code는 거대한 모델이 아니라 작은 정책 엔진 + 지식 베이스 + 템플릿 시스템으로 설계돼 있다. 이 때문에 코드량은 작지만, 산출물 규격은 꽤 일관적이다.

Usage & Setup

일반 사용 경로는 로컬 패키지 설치가 아니라, 에이전트 스킬로 등록하는 방식이다.

npx skills add PrathamLearnsToCode/paper2code/skills/paper2code
claude

사용 예시는 다음과 같다.

# 기본 사용
/paper2code https://arxiv.org/abs/1706.03762

# 프레임워크 전환
/paper2code https://arxiv.org/abs/2006.11239 --framework jax

# 전체 파이프라인 생성
/paper2code 2106.09685 --mode full

# 교육용 주석 + notebook 강화
/paper2code https://arxiv.org/abs/2010.11929 --mode educational

내부 파이프라인 문서에는 논문 파싱 의존성 설치 예시도 제공된다.

pip install pymupdf4llm pdfplumber requests pyyaml

 

 

캡션: 루트 README의 설치 및 사용 예시를 바탕으로 재구성한 이미지다. 스킬 설치, 프레임워크 전환, full/educational 모드 사용법을 한 화면에 요약했다.

생성 결과물

기본 출력 구조는 다음과 같다.

{paper_slug}/
├── README.md
├── REPRODUCTION_NOTES.md
├── requirements.txt
├── src/
│   ├── model.py
│   ├── loss.py
│   ├── train.py
│   ├── data.py
│   ├── evaluate.py
│   └── utils.py
├── configs/
│   └── base.yaml
└── notebooks/
    └── walkthrough.ipynb

educational 모드에서는 주석과 설명이 더 많아지고, 경우에 따라 PAPER_GUIDE.md 같은 보조 문서가 추가된다. full 모드는 데이터/학습 파이프라인을 더 넓게 포함한다. 반대로 minimal은 논문의 핵심 기여만 남기려는 모드다.

실제 실행성 관점

worked example를 기준으로 보면, 산출물은 “논문 수준 대규모 실험”보다는 로컬 sanity check가 가능한 최소 동작 구현을 우선한다.

• Transformer 예시: output.shape == (2, 15, vocab_size)
• DDPM 예시: predicted_noise.shape == (2, 3, 32, 32)

이 점은 장점이자 한계다. 초기 검증과 교육에는 좋지만, 논문 수치 재현까지는 추가 실험 환경과 데이터 파이프라인이 필요할 수 있다.

Personal Insights

의료 AI 관점

paper2code는 의료 AI 논문 재현에서 특히 알고리즘 핵심을 빠르게 골격화하는 데 강하다. 의료 논문은 본문보다 부록, 학습 레시피, 전처리 부록, 구현 노트에 중요한 정보가 숨어 있는 경우가 많다. 이 프로젝트의 acquisition 단계와 ambiguity audit는 이런 논문 구조와 잘 맞는다.

다만 실제 의료 AI 재현에는 다음 요소가 더 필요하다.

• DICOM / NIfTI / pathology slide 같은 도메인 데이터 로더 템플릿
• 환자 단위 split 검증 규칙
• calibration, subgroup analysis, external validation 같은 평가 템플릿
• 개인정보 / 규제 추적을 위한 experiment card

즉, paper2code는 의료 AI용 논문 구현 골격으로는 적합하지만, 임상 데이터 거버넌스나 규제형 문서화까지 바로 해결해 주지는 않는다. 의료 분야로 확장하려면 knowledge/와 scaffolds/에 도메인별 규칙 세트를 추가하는 방식이 현실적이다.

Bioinformatics 관점

Bioinformatics에서도 강점은 분명하다. 모델 논문, sequence model, molecular diffusion, protein representation 같은 분야에서는 “핵심 수식과 구조를 구현 가능한 뼈대”로 바꾸는 속도가 빠를 것이다. 특히 부록과 공식 코드 의존성이 큰 논문에서 paper2code의 정직한 provenance 표기는 유용하다.

하지만 Bioinformatics 파이프라인은 코드만으로 끝나지 않는다.

• FASTQ / BAM / VCF / AnnData / HDF5 등 포맷별 입출력 규칙
• reference genome / annotation version 관리
• normalization, batch correction, leakage 방지 규칙
• Snakemake / Nextflow / Conda 같은 워크플로 오케스트레이션
• 생존분석, ranking metric, enrichment analysis 같은 도메인 평가

따라서 Bioinformatics에 바로 적용하려면, 현재의 범용 data.py 템플릿만으로는 부족하다. 오히려 paper2code를 “논문 메서드 구현기”로 쓰고, 데이터/워크플로 계층은 도메인 전용 scaffolds로 교체하는 전략이 적절하다.

Autonomous Agent 관점

자율 에이전트 설계 관점에서 보면, paper2code는 매우 교과서적인 구조를 갖고 있다.

• 계획(Plan): pipeline/이 단계 순서를 명시
• 안전(Safety): guardrails/가 허용/금지 행동을 규정
• 메모리/지식(Memory): knowledge/가 반복 실수를 줄이는 참조 규칙 제공
• 행동(Action): scaffolds/가 실제 산출물 형식을 고정
• 평가(Evaluation): worked/와 review.md가 기대 품질을 예시로 제공

이 조합은 최근 에이전트 시스템에서 자주 보이는 “거대 모델 + 짧은 프롬프트”보다 훨씬 견고하다. 특히 환각을 모델 성능 문제가 아니라 시스템 설계 문제로 다룬다는 점이 좋다.

다만 다음 단계가 아직 남아 있다.

• 생성 repo를 자동 실행해 보는 test harness
• 공식 코드와 생성 코드의 구조적 diff 비교
• runtime error 후 self-healing loop
• benchmark paper set에 대한 자동 회귀 평가
• 결과 메트릭을 읽고 재시도하는 execution-feedback loop

즉, paper2code는 이미 좋은 analysis-and-synthesis agent지만, 앞으로는 execution-and-repair agent로 확장될 여지가 크다.

종합 판단

paper2code의 가치는 “논문을 한 번에 완벽 재현한다”는 데 있지 않다. 더 정확히는, 논문 구현에서 무엇이 사실이고 무엇이 추정인지 드러내는 재현성 스캐폴드를 빠르게 만드는 데 있다. 이 점 때문에 의료 AI, Bioinformatics, Autonomous Agent 개발 모두에서 출발점으로서의 가치가 높다. 반면 실제 실험 자동화, 도메인 데이터 파이프라인, 장기 벤치마크 재현은 아직 별도의 계층이 필요하다.

조사 범위 및 한계

이번 분석에서 실제로 확인한 범위

• 루트 README.md
• skills/paper2code/SKILL.md
• pipeline/01~05_*.md
• guardrails/hallucination_prevention.md
• guardrails/scope_enforcement.md
• guardrails/badly_written_papers.md
• knowledge/transformer_components.md
• knowledge/training_recipes.md
• knowledge/loss_functions.md
• knowledge/paper_to_code_mistakes.md
• scripts/fetch_paper.py
• scripts/extract_structure.py
• scaffolds/*.py, *.md, *.yaml
• worked/attention_is_all_you_need/*
• worked/ddpm/*
• worked/review.md
• 커뮤니티 소개 글(PyTorchKR)

확인되지 않은 항목

• 공개 Wiki 문서
• 공개 Discussions 스레드
• 커밋된 실제 PNG/GIF/UI 스크린샷 자산

위 세 항목은 분석 시점에 공개 리포지토리 화면 및 파일 구조에서 유의미한 콘텐츠를 확인하지 못했다.

Figures Index

파일명	설명하는 기능 / 섹션
figures/citation_anchor_code.png	논문 근거가 남는 코드 생성 방식
figures/reproduction_notes_excerpt.png	불확실성 회계와 REPRODUCTION_NOTES
figures/walkthrough_notebook_pattern.png	교육용 notebook 생성 패턴
figures/worked_examples_overview.png	논문 유형별 스코프 차이와 worked example
figures/repo_tree.png	저장소 구조와 정책/템플릿 중심 설계
figures/architecture_overview.png	입력→출력 아키텍처 개요
figures/pipeline_five_stage.png	5단계 실행 흐름 및 교차 제어 레이어
figures/usage_commands.png	설치 및 사용 커맨드 요약