Handover Generator

---
name: handover-generator
description: "로컬에 저장된 공문서 파일들을 분석하여 업무 인수인계서를 자동 생성합니다. 공문 파일명에서 기관명, 공문번호, 문서유형을 추출하고, 업무 카테고리별로 분류한 뒤, 구조화된 마크다운 인수인계서를 작성합니다. Use when: (1) 인수인계서 작성, (2) 업무 정리, (3) 공문 기반 업무 분석이 필요할 때."
allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Task
---

# Handover Generator (인수인계서 생성기)

## Overview

로컬에 저장된 한국 공공기관 공문서(PDF, HWP, HWPX, XLSX, OZD 등)를 분석하여
차기 담당자를 위한 **구조화된 업무 인수인계서**를 마크다운으로 생성한다.

공문의 **파일명**에 포함된 메타데이터(기관명, 공문번호, 본문/첨부 구분, 제목)를 활용하므로
파일 내용을 열지 않고도 업무 분류와 문서 목록화가 가능하다.

## Input Requirements

작업에 필요한 정보:

| 항목 | 필수 | 기본값 |
|------|------|--------|
| 공문 저장 경로 | ✅ | — |
| 소속 기관 / 학교명 | ✅ | — |
| 부서 / 직책명 | ✅ | — |
| 학년도 / 기간 | ✅ | — |
| 출력 형식 | ❌ | 마크다운(.md) |
| 공문번호 포함 여부 | ❌ | 포함 |
| 메모 섹션 추가 여부 | ❌ | 추가 |

**수집 방식:** 사용자의 첫 메시지에서 추출 가능한 정보는 먼저 추출한다.
부족한 필수 항목만 추가로 질문한다. 4개를 일괄 질문하지 않는다.

예시:
- `"바탕화면의 공문 모음 폴더로 인수인계서 만들어줘"` → 경로 확보, 나머지 3개만 질문
- `"내가 2025학년도에 학생부장으로 상신한 공문이야"` → 학년도·부서·직책 확보, 경로만 질문
- `"C:\공문 폴더에 있는 공문으로 인수인계서 작성해줘. OO고 교무부 2025학년도"` → 전부 확보, 바로 Phase 1 진행

## Workflow

### Phase 0: 환경 확인 (Environment Check)

**목표:** 필수 도구인 Node.js가 설치되어 있는지 확인한다.

```bash
node --version
```

**동작:**
1. 스킬 시작 시 자동으로 `node --version` 명령을 실행한다.
2. Node.js가 설치되어 있고 버전 18 이상인 경우 → Phase 1로 진행한다.
3. Node.js가 없거나 버전이 18 미만인 경우 → 다음 안내 메시지를 출력하고 **스킬을 종료**한다:

```
❌ 이 스킬은 Node.js 18 이상이 필요합니다.

대량의 공문 메타데이터를 처리하기 위해 Node.js 스크립트를 사용합니다.
Claude Code의 Read 도구는 25,000 토큰 제한이 있어 100건 이상의 공문 분석 시
JSON 파일을 직접 읽을 수 없습니다.

설치 방법:

Windows:
  choco install nodejs-lts
  또는 https://nodejs.org/ 에서 다운로드

macOS:
  brew install node

Linux:
  sudo apt install nodejs npm  # Ubuntu/Debian
  sudo dnf install nodejs       # Fedora

설치 후 다시 시도해주세요.
```

**왜 Node.js가 필수인가:**
- 100건 이상의 공문을 처리하면 메타데이터 JSON 파일이 25,000 토큰을 초과한다.
- Read 도구는 토큰 제한으로 대용량 JSON을 읽을 수 없다.
- Node.js 스크립트는 제한 없이 JSON을 파싱하고, 결과만 출력하여 토큰을 절약한다.
- Bash 도구에서 PowerShell 사용 시 `$` 변수 이스케이프 문제가 발생하므로 Node.js가 가장 안정적이다.

### Phase 1: 문서 스캔 및 수집 (Scan)

**목표:** 대상 경로의 모든 공문 파일을 식별하고 메타데이터를 추출한다.

**작업 폴더 구조:**
```
📁 공문 모음/
├── 📁 .handover_workspace/  ← 임시 작업 폴더 (자동 생성)
│   ├── file_list.txt
│   ├── metadata.json
│   ├── categories.json
│   └── (기타 중간 파일)
└── (공문 파일들...)
```
작업 완료 후 최종 인수인계서만 상위 폴더로 복사하고, `.handover_workspace/`는 삭제 여부를 사용자에게 확인한다.

**중요:** 이 단계에서는 반드시 Node.js 스크립트(`.mjs`)를 사용하여 메타데이터를 추출한다.

```
Glob → 파일 목록 수집 → Node.js 스크립트로 메타데이터 추출
```

1. `.handover_workspace/` 폴더를 생성한다.
2. 사용자가 제공한 경로(및 하위 디렉토리)를 재귀 스캔한다.
3. Node.js 스크립트를 작성하여 파일명에서 정규표현식으로 메타데이터를 추출한다:

```javascript
정규표현식: /\(([^-]+)-(\d+)\s+\((본문|첨부)\)\)/

// ⚠️ 제목 추출 시 주의: 마지막 괄호 ")" 다음부터 추출해야 함
const afterPattern = fileName.lastIndexOf(')') + 1;  // 첫 번째가 아닌 마지막!
const titleWithExt = fileName.substring(afterPattern).trim();
const title = titleWithExt.substring(0, titleWithExt.lastIndexOf('.'));
```

추출 필드:
- **기관명** (organization): 그룹 1 (예: `OO고등학교`)
- **공문번호** (docNumber): 그룹 2 (예: `22206`)
- **문서유형** (docType): 그룹 3 (`본문` 또는 `첨부`)
- **제목** (title): 마지막 괄호 `)` 뒤의 텍스트 (확장자 제외)

4. 패턴 미매칭 파일도 별도로 기록한다 (수동 확인 대상).
5. **연도 그룹 분리**를 수행한다 (아래 참조).

**폴더 구조 무관:** 파일이 폴더별로 정리되어 있든, 단일 폴더에 모여 있든 동일하게 동작한다.
파일명 자체에 모든 필요한 메타데이터가 포함되어 있기 때문이다.

#### 연도 그룹 분리

공문번호는 **기관 내부 결재 순번**이며, 매년 1번부터 다시 시작된다.
따라서 공문번호의 크기만으로 시간순을 판단하면 연도가 바뀌는 시점에서 순서가 뒤집힌다.
(예: 2025년 마지막 공문 22390번 → 2026년 첫 공문 25번)

이를 보정하기 위해, Phase 1 완료 후 다음 절차로 연도 그룹을 분리한다:

**1단계 — 급락 탐지:**
전체 공문번호를 오름차순 정렬한 뒤, 인접한 두 번호 사이에서
"큰 번호 뒤에 현저히 작은 번호가 뒤따르는 지점"을 찾는다.
구체적으로, 정렬 후 마지막(최대) 번호 이후에 처음(최소) 번호가 오는 패턴이
곧 연도 경계다. 실질적 판별 기준:
- 최대 번호 대비 10% 이하로 급감하는 번호 집단이 존재하면 연도 리셋으로 판단한다.
- 단순한 번호 공백(1173→3162 등)과 구별해야 한다. 번호 공백은 "증가 방향의 갭"이고,
  연도 리셋은 "최댓값 부근에서 최솟값 부근으로의 급락"이다.

**2단계 — 제목 속 연도로 보정:**
파일명에 `20XX학년도` 또는 `20XX년`이 포함된 경우, 해당 연도 정보를 추출한다.
급락 탐지 결과와 제목 속 연도가 충돌하면, **제목 속 연도를 우선**한다.
(예: 번호 413이 급락 그룹이지만 제목에 "2026학년도"가 있으면 → 2026년으로 확정)

**3단계 — 연도 라벨 부여:**
각 공문에 연도 라벨(예: `2025`, `2026`)을 부여한다.
이후 Phase 2~4에서 시간순 정렬 시, **연도 라벨 → 공문번호** 순으로 정렬한다.
같은 연도 내에서는 공문번호 오름차순 ≈ 시간순이 유효하다.

### Phase 2: 업무 분류 (Categorize)

**목표:** 공문 제목과 공문번호를 기반으로 업무 카테고리를 자율적으로 도출한다.

**중요:** 이 단계에서도 Node.js 스크립트(`.mjs`)를 사용하여 카테고리 분석을 수행한다.

1. Phase 1에서 생성된 메타데이터 JSON을 Node.js 스크립트로 읽는다.
2. 같은 공문번호의 본문+첨부를 그룹핑한다.

   **⚠️ 중요:** 그룹핑 시 `organization` 필드도 반드시 포함해야 한다:
   ```javascript
   docGroups[key] = {
     organization: doc.organization,  // ← 필수! 누락하면 "undefined" 출력
     docNumber: doc.docNumber,
     yearLabel: doc.yearLabel,
     title: doc.title,
     files: []
   };
   ```

3. Phase 1에서 부여한 **연도 라벨 → 공문번호** 순으로 정렬하여 업무 흐름을 파악한다.
4. 공문 제목의 의미를 분석하여 업무 카테고리를 자율적으로 도출한다.
5. 반복 패턴을 식별한다 (계획→수정→재수정, 위원회 구성→개회→결과 등).
6. 인접 공문번호의 문서들을 묶어 맥락을 보강한다.

**분류 결과를 사용자에게 제시하고 확인을 받는다:**

```
"공문을 분석한 결과, 다음 N개의 업무 카테고리로 분류했습니다:
 I. [카테고리명] — N건
 II. [카테고리명] — N건
 ...
카테고리 구성을 수정하시겠습니까?"
```

사용자가 승인하면 Phase 3으로 진행한다.
카테고리 병합/분리/명칭 변경 요청이 있으면 반영 후 재확인한다.

### Phase 3: 구조 설계 (Plan)

**목표:** 인수인계서의 목차와 구조를 확정한다.

표준 구조:

```
# {학년도} {부서명} 업무 인수인계서

## 1부. 개요
### 기관 정보 / 업무 영역 요약 (표) / 문서 작성 기준

## 2부. 업무영역 상세
### I. [카테고리 1]        ← 로마자 넘버링

**업무 설명**

(설명 내용)

**세부 업무 및 절차**

**1. 항목명**
- 불렛 내용
- 불렛 내용

**2. 항목명**
- 불렛 내용

**관련 공문**

- 공문 목록

**[작성자 메모]**

> ⚠️ **유의사항**
>
> -
> -

### II. [카테고리 2]
... (동일 구조 반복)

## 3부. 위원회 및 협의체
## 4부. 대외 발송 문서 (가정통신문 등)
## 5부. 예산 관련 사항
## 6부. 후임자를 위한 유의사항
## 부록. 공문 색인 (전체 목록 표)
```

사용자에게 구조를 확인받은 뒤 Phase 4로 진행한다.

### Phase 4: 문서 작성 (Write)

**목표:** 인수인계서를 작성한다.

작성 순서:
1. 1부 개요 + 2부 전반부 (카테고리 1~5)
2. 2부 후반부 (카테고리 6~N) + 3~6부 + 부록

각 섹션 작성 시:
- 공문번호를 **연도 라벨 → 공문번호** 순으로 나열하여 업무 흐름이 드러나게 한다.
- 반복 패턴(계획→수정→결과)은 절차로 명시한다.
- `[작성자 메모]` 섹션은 인용문 블록(`>`)으로 비워둔다.
- 부록의 공문 색인은 **연도 라벨 → 공문번호** 순으로 정렬한 테이블로 작성한다.
- **1.2 업무 영역 요약** 작성 시: "주요 내용" 칼럼에 카테고리별 실질적 설명을 포함한다.
  (예: "선거관리·회의운영·행사기획·예산집행", "상급기관 요청 실태조사·통계자료 제출" 등)

**마크다운 작성 규칙 (노션 호환 — 필수 준수):**

`references/output_structure.md`의 "마크다운 작성 규칙" 섹션을 반드시 따른다. 핵심 요약:

1. **빈 줄 필수**: 텍스트와 불렛/넘버링 리스트 사이에 반드시 빈 줄 1개 삽입.
   빈 줄이 없으면 노션 Import 시 soft break로 처리되어 불렛이 렌더링되지 않음.
2. **h 태그는 위계 전용**: 섹션 내 세부 항목은 h 태그 대신 `**볼드 넘버링**` + 불렛.
   h4(####) 아래에 h5나 추가 h4를 사용하지 않는다.
3. **카테고리 넘버링은 로마자**: `### I.`, `### II.`, `### III.` ...
   본문 내 아라비아 숫자(1, 2, 3)와의 충돌을 방지.
4. **유의사항은 인용 블록**: `> ⚠️ **유의사항**` + `>` 빈 줄 + `> - 항목`.
   본문 흐름과 시각적으로 분리.
5. **표 셀 내 항목은 가운데점**: 노션은 표 안 `<br>` 미지원.
   여러 항목을 `·`로 구분한다.

### Phase 4.5: docx 변환 (선택)

**조건:** 사용자가 docx 출력을 요청한 경우에만 실행한다. 요청이 없으면 건너뛴다.

1. pandoc 설치 여부를 확인한다:

```bash
pandoc --version
```

2. 미설치 시 자동 설치한다:

```bash
winget install pandoc
```

3. 마크다운을 docx로 변환한다:

```bash
pandoc "{파일명}.md" -o "{파일명}.docx"
```

- 마크다운 원본(.md)은 항상 보존한다. docx는 추가 산출물이다.
- 변환 실패 시 마크다운이 이미 완성되어 있으므로, 오류를 보고하고 계속 진행한다.

### Phase 5: 검증 (Verify)

**목표:** 누락 문서가 없는지 교차 검증한다.

**중요:** 이 단계에서도 Node.js 스크립트(`.mjs`)를 사용하여 검증을 수행한다.

```
Node.js 스크립트 → 원본 파일 목록 vs 인수인계서 내 공문번호 비교
```

1. Node.js 스크립트를 작성하여 Phase 1 메타데이터 JSON에서 전체 공문번호 목록을 추출한다.
2. 작성된 인수인계서에서 언급된 공문번호를 정규표현식으로 추출한다.
3. 차집합(= 누락 문서)이 있으면 해당 섹션에 추가한다.
4. 부록 색인 테이블도 동기화한다.
5. 검증 결과를 사용자에게 보고한다 (총 문서 수, 누락 문서 수, 타입 오류 등).

## Output

| 항목 | 값 |
|------|-----|
| 파일명 | `{학년도}_{부서명}_인수인계서.md` (docx 요청 시 `.docx`도 함께 생성) |
| 위치 | 공문 저장 경로의 상위 디렉토리 |
| 중간 파일 | `.handover_workspace/` 폴더에 저장 (작업 완료 후 삭제 여부 확인) |
| 인코딩 | UTF-8 |
| docx 변환 | 선택 사항. pandoc 필요 (미설치 시 자동 설치) |

**파일 정리:**
- 최종 인수인계서 1개만 상위 폴더에 생성
- 중간 산출물은 모두 `.handover_workspace/`에 격리
- 작업 완료 후 사용자에게 작업 폴더 삭제 여부 확인

## Commands

| 사용자 입력 | 동작 |
|---|---|
| `"인수인계서 작성"` / `"인수인계서 만들어줘"` | 경로 확인 후 전체 워크플로 실행 (마크다운) |
| `"인수인계서를 docx로 만들어줘"` | 마크다운 생성 후 docx로 추가 변환 |
| `"공문 분석해줘"` | Phase 1~2만 실행 (분류 결과 보고) |
| `"인수인계서 검증"` | 기존 인수인계서와 공문 목록 교차 검증 |

## Performance Notes

### 폴더 구조와 성능

공문이 폴더별로 정리되어 있든, 단일 폴더에 전부 들어 있든 **작업 품질에 유의미한 차이는 없다.**

- **파일명 기반 분석**: 이 워크플로는 파일 내용이 아닌 **파일명의 메타데이터**로 동작한다.
  공문번호, 기관명, 본문/첨부 구분이 파일명에 모두 포함되어 있으므로
  폴더 구조는 추가 정보를 제공하지 않는다.
- **Glob 패턴**: `**/*` 재귀 검색으로 하위 구조와 무관하게 전체 파일을 수집한다.
- **분류 로직**: 제목 키워드와 공문번호 그룹핑으로 카테고리를 결정하며,
  이는 폴더 경로가 아닌 파일명에서 수행된다.

따라서 공문 정리(document-organizer 스킬)는 **사람의 편의를 위한 것**이지,
이 스킬의 전제 조건이 아니다.

### 대규모 문서 처리

100건 이상의 공문을 처리할 경우:
- Phase 1(스캔)과 Phase 2(분류)에서 Task(Explore) 서브 에이전트를 활용하면
  메인 컨텍스트 소모를 줄일 수 있다.
- Phase 4(작성)는 문서 길이상 분할 작성이 필요하다 (Write 도구의 실용적 한계).
- Phase 5(검증)는 반드시 별도 서브 에이전트로 실행하여 독립적 검증을 보장한다.

## Reference

- `references/output_structure.md` — 인수인계서 표준 구조 상세 + 노션 호환 마크다운 규칙