kiwi-paper

# 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/` 디렉토리의 예제가 변경된 스킬과 일관성 있는지 확인

### 예제 추가 시

1. `examples/` 디렉토리에 새 마크다운 파일 생성
2. 파일명은 원 논문/서적의 영문 제목을 kebab-case로: `paper-title.md`
3. 예제는 SKILL.md에 정의된 모든 스타일 규칙을 준수해야 함
4. 반드시 포함할 요소: ~~취소선~~, 각주, 여담 섹션, 외부 링크, 표

### 새 기능 추가 시

- SKILL.md의 `allowed-tools` 목록 업데이트 필요 여부 확인
- 새 섹션이나 규칙을 추가할 때는 기존 패턴과 일관성 유지
- 유머 관련 규칙 변경 시 예제도 함께 업데이트

## 코드 컨벤션

### 마크다운 스타일

- 헤딩: ATX 스타일 (`#`, `##`, `###`)
- 리스트: `-` (하이픈)
- 코드블록: 백틱 3개 + 언어 지정
- 취소선: `~~텍스트~~`
- 각주: `[^숫자]` 및 `[^숫자]: 내용`
- 표: GitHub Flavored Markdown 표 문법
- 수식: LaTeX (`$...$`, `$$...$$`)

### 한국어 작성 규칙

- 번역체 금지: "~하는 것은 ~하다는 것을 의미한다" ✗
- 자연스러운 구어체: "~인 셈이다", "~라고 보면 된다" ✓
- AI 특유의 나열 금지: "첫째~, 둘째~, 셋째~" ✗
- 문장 길이 다양하게: 긴 문장과 짧은 문장을 섞어 리듬감 만들기
- 과잉 수식 금지: "매우 중요한", "획기적인" 남발 ✗

## 테스트 기준

예제 출력물의 품질을 검증할 때 확인할 항목:

- [ ] 학술적 정확성: 원문의 핵심 내용이 왜곡 없이 전달되는가
- [ ] ~~취소선~~ 밀도: 섹션당 3-5개 수준인가
- [ ] 각주 활용: 출처 각주와 유머 각주가 균형 잡혀 있는가
- [ ] 여담 섹션: 최소 5개 이상의 흥미로운 항목이 있는가
- [ ] 외부 링크: 최소 5개 이상의 유효한 링크가 있는가
- [ ] 자연스러움: AI가 쓴 티가 나지 않는 자연스러운 한국어인가
- [ ] 계층 구조: 3단계 이상의 헤딩 계층이 적절히 사용되었는가

## 참고 자료

- [나무위키 문법 도움말](https://namu.wiki/w/나무위키:문법%20도움말)
- [나무위키에서의 취소선 사용](https://namu.wiki/w/취소선/나무위키에서의%20사용)
- [GitHub Flavored Markdown Spec](https://github.github.com/gfm/)