kiwi-paper AGENTS.md

AGENTS.md — kiwi-paper

이 문서는 AI 코딩 에이전트(Claude Code, OpenCode, Codex 등)가 이 프로젝트에서 작업할 때 참고하는 가이드입니다.

프로젝트 개요

kiwi-paper는 학술 논문 PDF나 전공 서적을 나무위키 스타일의 마크다운 문서로 변환하는 Claude Code 스킬입니다.

• 스킬 정의: SKILL.md (프로젝트 루트 및 ~/.claude/skills/kiwi-paper/)
• 예제 출력: examples/ 디렉토리
• 설치 스크립트: install.sh

핵심 컨셉

나무위키 스타일이란?

나무위키는 한국의 대표적인 위키 플랫폼으로, 다음과 같은 독특한 문체를 가집니다:

• 취소선: 유머를 전달하는 핵심 장치. 진짜 내용 옆에 농담을 취소선으로 표시
• 여담 섹션: 본문 끝에 관련 트리비아, 뒷이야기를 모아두는 섹션
• 각주 유머: 각주에 출처뿐 아니라 드립을 숨겨두는 문화
• 구어체 톤: 백과사전과 달리 편하고 재미있는 말투
• 괄호 코멘터리: (이런 식으로 중간에 편집자 의견을 삽입)

4단계 파이프라인

1. 초안 작성 (Draft): PDF 내용을 나무위키 스타일로 변환
2. 다듬기 (Refine): 구조, 유머 밸런스, 링크를 보강
3. 휴머나이즈 (Humanize): AI가 쓴 티를 제거하고 자연스러운 한국어로 다듬기
4. HTML 렌더링 (Render): 마크다운을 나무위키 스타일 HTML로 변환

디렉토리 구조

kiwi-paper/
├── AGENTS.md          # 이 파일 — AI 에이전트 가이드
├── SKILL.md           # 스킬 정의 (핵심 파일)
├── README.md          # 프로젝트 소개
├── LICENSE            # MIT 라이선스
├── install.sh         # 스킬 + 렌더러 설치 스크립트
├── .gitignore
├── examples/
│   └── attention-is-all-you-need.md  # 예제 출력
└── renderer/          # Markdown → HTML 렌더러
    ├── package.json   # ESM 패키지 (Node.js >= 20)
    └── src/
        ├── render.mjs    # CLI 엔트리 포인트
        └── template.mjs  # HTML 템플릿 (CSS/JS 인라인)

에이전트별 작업 가이드

렌더러 작업 시

1. renderer/ 디렉토리는 독립 Node.js 패키지 (ESM, "type": "module")
2. 엔트리 포인트: renderer/src/render.mjs — CLI (-i, -o 필수 옵션)
3. 템플릿: renderer/src/template.mjs — renderPage(), renderIndexPage() export
4. 의존성 변경 시 cd renderer && npm install 필요
5. 테스트: node renderer/src/render.mjs -i examples/ -o dist/

CLI 인터페이스:

node render.mjs -i <path|url...> -o <dir> [--title <str>] [--no-toc] [--single]

파이프라인: marked (GFM) → footnotes → KaTeX (서버사이드) → Shiki (듀얼 테마) → heading IDs → .md→.html 링크 변환

스킬 수정/개선 시

1. SKILL.md를 읽고 현재 스킬 정의를 파악
2. 수정이 필요한 부분을 변경
3. 반드시 프로젝트 루트의 SKILL.md와 ~/.claude/skills/kiwi-paper/SKILL.md 양쪽을 동기화
4. examples/ 디렉토리의 예제가 변경된 스킬과 일관성 있는지 확인