Oh My Paper 완전 가이드: 문헌 리서치부터 논문 출판까지, 단 하나의 터미널로 전부 해결

20분 만에 시작｜5개 Agent 협업 + 34개 연구 스킬｜Claude Code를 당신만의 전용 연구 실험실로

---

프로젝트 소개

Oh My Paper 는 오픈소스 Claude Code 플러그인으로, 해결하는 문제는 아주 명확합니다. Claude Code는 코드를 작성하는 데 도움을 줄 수 있지만, 연구는 코드를 쓰는 것만으로 끝나지 않습니다. 문헌 리서치, 혁신 포인트 평가, 실험 설계, 논문 작성, 인용 형식/근거 검증 같은 단계도 필요하고, 그런데 이 모든 과정이 자연스럽게 이어지게 해주는 좋은 도구가 없었습니다.

Oh My Paper는 Claude Code에 구조화된 연구 워크플로우 파이프라인을 장착합니다. 5개의 전담 Agent 역할이 각자의 영역을 담당하고, 34개의 연구 스킬은 필요할 때마다 로드되며, 백그라운드 Hook이 프로젝트 상태를 자동으로 기억합니다. 설치 후에는 Claude Code를 열 때마다 “오늘 어떤 역할로 작업할까요?”라고 물어보고, 해당 기억 파일을 자동으로 불러와 마지막 중단 지점부터 이어갑니다. 이 과정에는 GUI가 필요 없고, 모든 조작은 터미널에서 처리됩니다.

---

목표 독자 유형

이 글은 아래와 같은 개발자를 대상으로 합니다.

• 1~5년 개발 경험이 있고, 논문 작성/연구를 하고 있거나 이미 겪어본 적이 있는 분
• AI로 연구를 보조하고 싶지만, 여러 도구 사이를 오가며 전환하는 걸 원치 않는 분
• Agent 협업 방식, 멀티 역할의 기억(컨텍스트) 격리 같은 개념에 관심이 있고 실제 사례를 보고 싶은 분

이미 CV, NLP, 시스템 아키텍처처럼 명확한 연구 방향이 있거나, 회사에서 내부 기술 리서치를 진행 중이라면 Oh My Paper의 파이프라인이 모두 잘 맞습니다.

---

핵심 의존성과 환경

시작하기 전에 환경이 아래 조건을 만족하는지 확인하세요.

---

전체 프로젝트 구조 트리

/omp:setup을 실행한 뒤 프로젝트 디렉터리 구조는 아래와 같습니다.

my-research/
├── paper/                     # LaTeX 논문 작업 영역
│   ├── main.tex
│   ├── sections/              # 각 챕터 .tex 파일
│   └── refs/                   # 참고문헌 .bib 파일
├── experiment/                # 실험 코드와 스크립트
├── survey/                   # 문헌 리서치 산출물
├── ideation/                 # 혁신 포인트와 평가 결과
├── promotion/                # 슬라이드, Demo, 홍보 자료
├── skills/                   # 프로젝트 로컬 커스텀 스킬
├── .pipeline/
│   ├── tasks/
│   │   └── tasks.json        # 모든 단계에 걸친 작업 트리
│   ├── docs/
│   │   └── research_brief.json
│   └── memory/               # Agent 기억 파일
│       ├── project_truth.md   # 프로젝트 기준 + 진행 로그
│       ├── orchestrator_state.md
│       ├── execution_context.md
│       ├── experiment_ledger.md
│       ├── result_summary.md
│       ├── review_log.md
│       ├── literature_bank.md
│       ├── agent_handoff.md
│       └── decision_log.md
├── .claude/
│   └── settings.json         # SessionStart hook 등록
├── CLAUDE.md
└── AGENTS.md

---

단계별 설치 방법

1단계: 플러그인 마켓 추가

Claude Code에서 아래 명령을 실행해 Oh My Paper 플러그인 마켓 주소를 등록합니다.

/plugin marketplace add LigphiDonk/Oh-my--paper

이 단계는 전체 저장소를 클론할 필요가 없으며, Claude Code가 플러그인 마켓에서 플러그인 목록을 가져옵니다.

2단계: 플러그인 설치

/plugin install omp@oh-my-paper

설치 후 /plugin로 확인합니다.

/plugin
# 예상 출력에 다음이 포함되어야 함: omp @ oh-my-paper, Status: Enabled

3단계: Claude Code 재시작

현재 Claude Code 창을 완전히 닫고, 다시 여세요.

4단계: 연구 프로젝트 초기화

연구 프로젝트 디렉터리로 이동한 뒤 다음을 실행합니다.

/omp:setup

이 명령은 세 가지 일을 합니다.

1. .pipeline/ 디렉터리 및 모든 하위 디렉터리와 기억 파일 생성
2. .claude/settings.json에 SessionStart hook 등록
3. 기본 tasks.json과 research_brief.json 생성

초기화가 끝나면 디렉터리 구조는 위의 “전체 프로젝트 구조 트리”와 동일합니다.

설치 성공 여부 확인

초기화된 프로젝트 디렉터리에서 Claude Code를 다시 열면, Claude가 역할 선택 메뉴를 띄우고 “오늘은 어떤 역할로 시작할까요?”라고 질문해야 합니다. 이것이 보이면 설치가 모두 성공한 것입니다.

---

5단계 연구 파이프라인 상세

Oh My Paper는 전체 연구 과정을 5단계로 나누고, 각 단계는 한 가지 명령과 추천 스킬 세트에 대응됩니다.

1단계｜Survey: 문헌 리서치

실행 명령:

/omp:survey

이 단계에서 하는 일: Claude가 사용자의 연구 방향에 맞는 관련 논문을 찾아, 초록과 핵심 정보를 추출한 뒤 최종적으로 literature_bank.md에 정리합니다.

자주 쓰는 스킬:

• paper-finder — ArXiv, Semantic Scholar에서 관련 작업 검색
• paper-analyzer — 논문의 핵심 기여, 방법, 한계 추출
• biorxiv-database — 생물의학 분야라면 BioRxiv 검색

핵심 산출물 파일: survey/literature_bank.md

일반적인 워크플로우:

사용자: /omp:survey
→ Claude가 연구 방향 키워드를 질문
→ 자동 검색 → 문헌 카드 정리 → literature_bank.md에 기록
→ 문헌 리서치 요약을 보여줘서 추가가 필요한지 확인할 수 있게 함

2단계｜Ideation: 혁신 포인트 생성

실행 명령:

/omp:ideate

1단계의 문헌 리서치 결과를 바탕으로 Claude가 잠재적인 혁신 포인트를 생성하고, 각각의 실현 가능성을 하나씩 평가합니다.

자주 쓰는 스킬:

• inno-idea-generation — 대규모 혁신 포인트 브레인스토밍
• inno-idea-eval — novelty, feasibility, impact의 3개 차원에서 점수화
• research-idea-convergence — 2~3개의 가장 유망한 방향으로 수렴

핵심 산출물 파일: ideation/ 디렉터리 아래 평가 결과

3단계｜Experiment: 실험 설계와 실행

실행 명령:

/omp:experiment

이 단계는 범위가 가장 넓습니다. 실험 설계, 평가 코드 작성, 로컬 또는 원격 실행, 결과 분석까지 포함합니다.

자주 쓰는 스킬:

• inno-experiment-dev — 실험 코드 골격 생성
• research-experiment-driver — 실험 반복(이터레이션) 루프 관리
• remote-experiment — SSH로 원격 GPU 노드에서 실행(“원격 실험” 챕터 참고)

핵심 산출물 파일: experiment/ 디렉터리 + experiment_ledger.md(실험 이력 기록)

4단계｜Publication: 논문 섹션 작성

실행 명령:

/omp:write

실험 결과를 논문 텍스트로 변환하고, 도표/그림과 제목을 생성하며, LaTeX 파일을 관리합니다.

자주 쓰는 스킬:

• inno-paper-writing — 범용 논문 섹션 생성
• ml-paper-writing — 머신러닝/AI 방향 논문 템플릿
• scientific-writing — 학술 작성 규범(시제, 표현, 구조)
• inno-figure-gen — 그림 생성 코드 생성(Matplotlib, Plotly)
• inno-reference-audit — 인용 형식이 규격을 따르는지 자동 점검

핵심 산출물 파일: paper/ 디렉터리 아래 LaTeX 파일

5단계｜Promotion: 성과 홍보

실행 명령:

/omp:plan
# Promotion 단계에서는 데모 자료 제작과 관련된 스킬을 선택하세요

논문 성과를 데모용 슬라이드, 기술 블로그, Grant 제안서 등으로 전환합니다.

자주 쓰는 스킬:

• making-academic-presentations — 학술 리포트 PPT 생성
• inno-grant-proposal — 자금 지원 신청서 작성
• inno-rclone-to-overleaf — 로컬 LaTeX를 Overleaf로 자동 동기화

---

5개의 주요 Agent 역할과 기억 격리 메커니즘

이것이 Oh My Paper의 가장 핵심적인 설계 철학입니다.

Agent 역할 요약

기억 격리 원리

각 역할은 자기 책임 범위에 해당하는 기억 파일만 읽고/쓸 수 있으며, 다른 역할의 내부 상태는 볼 수 없습니다. 이 설계의 핵심 장점은 컨텍스트 오염 방지입니다. 예를 들어 Paper Writer는 Experiment Driver의 중간 디버깅 결과를 보지 못하고, Literature Scout는 실험 데이터를 먼저 봄으로써 문헌 평가에 선입견이 생기는 일을 막습니다.

역할 간에는 두 가지 “공용 영역”을 통해 통신합니다.

tasks.json         ← 모든 역할이 읽고/쓰며, 작업 완료 상태를 기록
project_truth.md   ← 모든 역할이 추가로 기록하며, 프로젝트 전체 진행을 남김

자동 상태 동기화

가장 중요한 설계 디테일입니다. Conductor는 각 하위 작업이 끝날 때마다 자동으로 이 두 공용 파일을 업데이트하며, 사용자가 수동으로 상기시킬 필요가 없습니다.

하위 작업 완료
  → Conductor가 tasks.json에서 해당 작업을 done으로 자동 표시
  → Conductor가 project_truth.md에 진행 로그를 자동으로 추가
    → 다음 세션에서 두 파일을 읽어, 중단 지점부터 자동으로 이어감

---

34개 연구 스킬 빠른 정리

Oh My Paper에는 연구 전 과정을 커버하는 34개의 연구 스킬이 내장되어 있습니다. 아래는 카테고리별로 정리해 필요할 때 바로 찾을 수 있게 했습니다.

문헌 유형

• paper-finder — 여러 데이터베이스에서 논문 검색
• paper-analyzer — 논문 핵심 기여 추출
• paper-image-extractor — PDF에서 그림/도표 추출
• research-literature-trace — 특정 논문의 인용 관계(인용 체인) 추적
• biorxiv-database — BioRxiv 전용 검색
• dataset-discovery — 관련 데이터셋 발견

리서치 및 아이디어 유형

• inno-deep-research — 심층 연구 모드
• gemini-deep-research — Gemini 심층 연구 통합
• inno-code-survey — 코드 구현 리서치
• inno-idea-generation — 혁신 포인트 대량 생성
• inno-idea-eval — 혁신 포인트 다차원 평가
• research-idea-convergence — 최적 방향으로 수렴

실험 유형

• inno-experiment-dev — 실험 코드 생성
• inno-experiment-analysis — 실험 결과 분석
• research-experiment-driver — 반복형 실험 관리
• remote-experiment — 원격 GPU 실험 루프

작성 유형

• inno-paper-writing — 범용 논문 섹션
• ml-paper-writing — ML/AI 방향 논문
• scientific-writing — 학술 작성 규범
• inno-figure-gen — 도표/그림 생성
• inno-reference-audit — 인용 형식 검토
• research-paper-handoff — Agent 간 인계 규칙

기획 및 리뷰 유형

• inno-pipeline-planner — 파이프라인 기획
• research-pipeline-planner — 연구 단계 기획
• inno-paper-reviewer — 논문 품질 평가
• inno-prepare-resources — 리소스 준비 체크리스트
• inno-rclone-to-overleaf — Overleaf 동기화

데모 및 제안 유형

• making-academic-presentations — 학술 보고서 PPT
• inno-grant-proposal — 자금 지원 신청서

Agent 스케줄링 유형

• claude-code-dispatch — Claude Code 하위 작업 스케줄링
• codex-dispatch — Codex 병렬 처리 스케줄링

분야별 전용 유형

• academic-researcher — 범용 학술 연구
• bioinformatics-init-analysis — 생물정보학 분석
• research-news — 연구 분야 최신 동향 추적

스킬은 필요할 때 로드되며, /omp:survey를 실행하면 Claude가 관련 스킬을 자동으로 추천합니다. 또한 skills/ 디렉터리에 커스텀 스킬을 추가할 수도 있습니다.

---

대표 워크플로우: 전체 시연

AI 방향 논문을 예로 들어, 5단계 파이프라인을 처음부터 끝까지 완전히 실행해봅니다.

Step 1: 프로젝트 초기화

# 연구 디렉터리로 이동
cd ~/research/my-paper

# Claude Code에서:
/omp:setup
# 출력: .pipeline/ 이 생성되고 SessionStart hook이 등록됨

Step 2: 문헌 리서치

# Claude Code에서:
/omp:survey
# → Claude가 묻습니다: “당신의 연구 방향은 무엇인가요?”
# → 입력: LLM reasoning, chain-of-thought prompting
# → Claude가 ArXiv/Semantic Scholar를 자동 검색
# → 관련 작업 20편 이상을 survey/literature_bank.md에 정리
# → 리서치 요약을 출력해, 추가가 필요한지 확인

Step 3: 혁신 포인트 생성

/omp:ideate
# → Claude가 literature_bank.md를 읽음
# → 잠재 혁신 포인트 8개 생성
# → 각 포인트를 novelty / feasibility / impact 세 가지 차원에서 점수화
# → 2개 방향으로 수렴하여 research_brief.json에 기록

Step 4: 실험 설계 및 실행

/omp:experiment
# → Claude가 research_brief.json을 읽음
# → 실험 설계(베이스라인, 비교 방법, 평가 지표)
# → experiment/ 디렉터리에 실험 코드 생성
# → 로컬 평가를 실행하고 지표 결과를 분석
# → 결과를 experiment_ledger.md에 기록

원격 GPU 노드에서 실행이 필요하다면:

# 원격 계산 노드 설정( experiment/ 디렉터리 아래에 compute-config.json 생성 )
{
  "host": "gpu-server.example.com",
  "user": "researcher",
  "key_path": "~/.ssh/id_rsa",
  "remote_dir": "/home/researcher/experiments"
}

# Claude Code에서:
/omp:experiment
# → Claude가 compute-config.json을 감지
# → remote-experiment 스킬 사용
# → rsync로 코드를 원격에 전송 → SSH 실행 → 결과를 다시 가져옴
# → metrics를 자동 파싱해 experiment_ledger.md에 기록

Step 5: 논문 섹션 작성

/omp:write
# → Claude가 experiment_ledger.md + literature_bank.md를 읽음
# → Introduction / Method / Experiment 각각의 .tex 섹션 생성
# → 그림 생성(Matplotlib 스크립트)을 수행하고 paper/figures/로 컴파일
# → 인용 검토: .bib 파일 포맷을 확인

Step 6: 동료 심사

/omp:review
# → Claude가 Reviewer 역할로 읽기 수행
# → 논리적 일관성, 방법 설명의 명확성, 실험 비교의 충분성 점검
# → 수정 권장사항을 포함한 review_log.md 출력
# → 권장사항에 따라 수정한 뒤, 통과할 때까지 다시 /omp:review 실행

Step 7: Overleaf로 동기화

# skills/ 디렉터리에서 Overleaf 동기화 설정
# inno-rclone-to-overleaf 스킬 사용
# Claude가 로컬 paper/ 디렉터리를 Overleaf 프로젝트에 자동 동기화

---

원격 실험 상세

GPU 연산이 필요한 실험이라면 Oh My Paper는 전체 원격 실험 루프를 지원합니다.

아키텍처 흐름

로컬에서 설계
  → 실험 코드 생성
    → 원격 서버로 rsync 동기화
      → 원격 노드에 SSH 로그인
        → GPU에서 실험 실행
          → metrics 로그를 가져오기
            → 로컬에서 지표 파싱
              → 임계값 도달 여부 판단
                → 반복 최적화 / 실험 종료

원격 노드 구성

experiment/ 디렉터리 아래에 compute-config.json을 생성합니다.

{
  "host": "your-gpu-server.com",
  "user": "researcher",
  "ssh_key": "~/.ssh/id_rsa",
  "remote_workspace": "/home/researcher/omp-experiments",
  "max_iterations": 5,
  "success_threshold": {
    "accuracy": 0.92,
    "latency_ms": 200
  }
}

원격 실험 실행

# Claude Code에서:
/omp:experiment
# → compute-config.json 감지
# → 자동 실행: 코드 동기화 → SSH 실행 → 결과를 가져오기
# → 지표가 목표에 미치지 못하면 초매개변수 조정 후 재실행(최대 max_iterations회)
# → 최종 결과를 experiment_ledger.md에 기록

---

Codex 작업 위임

어떤 실험이 대량의 반복 코드 생성이 필요하다면(예: 서로 다른 초매개변수 설정 10세트를 실행해야 하는 경우), Conductor가 작업을 Codex로 위임해 병렬 처리할 수 있습니다.

/omp:delegate
# → Conductor가 현재 작업 컨텍스트를 읽음
# → 전체 컨텍스트가 포함된 Codex 프롬프트 생성
# → 새로운 터미널에서 복사해 실행: codex "..."
# → Codex가 독립된 터미널에서 실행
# → 완료 후 agent_handoff.md에 CODEX_DONE 신호 기록
# → Conductor가 신호를 감지하면 결과를 자동으로 읽고 tasks.json을 업데이트

이 설계의 장점은 다음과 같습니다. Claude Code와 Codex가 서로 다른 터미널에서 동시에 실행되므로, 로컬 Claude Code가 점유되지 않아 문헌 정리 같은 다른 작업을 동시에 진행할 수 있습니다.

---

자주 발생하는 문제 해결

Q1: /omp:setup 후 Claude Code를 열어도 역할 선택 프롬프트가 보이지 않음

원인: SessionStart hook이 올바르게 등록되지 않았습니다.

점검 방법:

1. 프로젝트 디렉터리에 .claude/settings.json이 존재하는지 확인
2. 해당 파일에 hooks 설정 섹션이 포함되어 있는지 확인

cat .claude/settings.json
# "hooks": { "SessionStart": [...] } 필드가 있는지 확인

없다면 /omp:setup을 다시 실행해 초기화하고, Claude Code가 완전히 재시작되었는지 확인하세요.

---

Q2: 플러그인 설치는 성공했는데 /omp:survey 같은 명령이 「명령을 인식할 수 없습니다」로 표시됨

원인: 플러그인이 올바르게 로드되지 않았거나 Claude Code를 재시작해야 합니다.

해결 단계:

# 1. 제거 후 재설치
/plugin uninstall omp
/plugin install omp@oh-my-paper

# 2. Claude Code를 완전히 재시작(모든 창 닫기)

# 3. 플러그인 상태 확인
/plugin

---

Q3: Literature Scout이 찾는 논문이 너무 적어 검색 범위를 넓히고 싶음

원인: 초기 키워드가 너무 구체적이라 검색 결과가 제한됩니다.

해결 방법:

/omp:survey 실행 시 여러 동의어와 상위 개념을 함께 제시합니다:
입력: “LLM reasoning, chain-of-thought, CoT, deliberate reasoning, LLM planning”
단, “LLM reasoning”만 입력하지 마세요.

또한 skills/paper-finder.md에서 추가 데이터베이스 소스(예: ACL Anthology, ICLR 공식 페이지)를 넣을 수도 있습니다.

---

Q4: Paper Writer가 생성한 실험 설명과 실제 결과가 일치하지 않음

원인: Experiment Driver와 Paper Writer 사이에 최신 experiment_ledger.md가 제때 동기화되지 않았습니다.

해결 방법:

매 실험 반복이 끝난 뒤 Paper Writer가 작업을 시작하기 전에 /omp:plan을 먼저 실행해 Conductor가 전역 상태를 동기화하도록 하세요. 그래야 Paper Writer가 최신 결과를 읽게 됩니다.

/omp:plan
# → Conductor가 현재 tasks.json 상태를 표시
# → experiment 작업이 done으로 표시되었는지 확인
# → 그 다음 /omp:write 실행

---

Q5: 원격 실험에서 rsync 동기화 실패, permission denied가 표시됨

원인: SSH 키 권한이 올바르지 않거나, 원격 디렉터리가 존재하지 않습니다.

점검 단계:

# 1. 로컬 SSH 키 권한 확인
chmod 600 ~/.ssh/id_rsa

# 2. SSH 연결 테스트(비밀번호 로그인 없음)
ssh -i ~/.ssh/id_rsa [email protected] "echo ok"

# 3. 원격 디렉터리가 존재하는지 확인
ssh [email protected] "mkdir -p /home/researcher/omp-experiments"

# 4. compute-config.json의 remote_workspace 경로가 올바른지 확인

---

Q6: Codex 위임 후 Conductor가 계속 CODEX_DONE 신호를 기다림

원인: Codex 실행이 끝난 뒤 agent_handoff.md에 올바르게 기록되지 않았습니다.

해결 방법:

1. Codex가 실행된 터미널이 정상 종료됐는지 확인
2. .pipeline/memory/agent_handoff.md의 맨 끝에 다음 한 줄을 수동으로 추가:

CODEX_DONE
result: [여기에 Codex의 출력 결과를 입력]

1. 그런 다음 Claude Code에서 현재 워크플로우를 이어가세요.

---

확장 읽기 및 고급 방향

1. 스킬 확장(커스텀 스킬)

Oh My Paper는 프로젝트 로컬 skills/ 디렉터리에 커스텀 스킬을 추가하는 것을 지원합니다. 생성 형식은 아래와 같습니다.

---
name: my-custom-skill
description: 특정 연구 분야를 위한 커스텀 분석 워크플로우
stage: survey  # 선택: survey | ideation | experiment | write | review
---

# 스킬 제목

## 실행 단계
1. 컨텍스트 파일 읽기 ...
2. 특정 작업 수행 ...

등록 후 /omp:survey 같은 명령을 실행하면 Claude가 관련 커스텀 스킬을 자동으로 추천합니다.

2. 멀티 Agent 협업 고급 활용

동시에 여러 연구 방향을 진행하고 있다면, 서로 다른 하위 디렉터리에서 각각 /omp:setup을 실행하세요. 각 서브 프로젝트는 독립된 .pipeline/과 Agent 팀을 가집니다. Conductor 역할은 서브 프로젝트 전체의 개요와 조정을 담당합니다.

3. Overleaf 협업 워크플로우

inno-rclone-to-overleaf 스킬로 로컬 논문을 Overleaf에 동기화한 뒤에는, 지도교수가 Overleaf에서 바로 코멘트를 달 수 있습니다. 수정이 완료되면 다시 로컬로 동기화하면 됩니다. 전체 과정에서 수동 업로드/다운로드가 필요 없습니다.

4. 다른 LLM 백엔드 연결

Oh My Paper 자체는 Claude Code에만 의존하지만, 실험 단계에서는 서로 다른 LLM을 설정해 비교 평가를 할 수 있습니다. experiment/ 디렉터리 아래에 모델 구성 파일을 만드세요.

# experiment/model_configs.py
llm_configs = {
    "claude-sonnet": {"provider": "anthropic", "model": "claude-3-5-sonnet"},
    "gpt-4o": {"provider": "openai", "model": "gpt-4o"},
    "gemini-pro": {"provider": "google", "model": "gemini-1.5-pro"},
}

그리고 실험 코드에서 이 설정을 불러와 가로(횡) 비교에 사용합니다.

5. 최신 연구 동향 추적

research-news 스킬로 ArXiv의 최신 제출물을 정기적으로 스캔해, 연구 방향과 관련된 새로운 논문을 선별하고 literature_bank.md를 자동으로 업데이트할 수 있습니다. cron 예약 작업과 함께 사용하면 매주 자동으로 리서치 문헌 라이브러리를 업데이트하도록 구성할 수 있습니다.