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:\공문 폴더에 있는 공문으로 인수인계서 작성해줘. 인창고 교무부 2025학년도" → 전부 확보, 바로 Phase 1 진행

Workflow

Phase 0: 환경 확인 (Environment Check)

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

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 스크립트를 작성하여 파일명에서 정규표현식으로 메타데이터를 추출한다:

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

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

추출 필드:

• 기관명 (organization): 그룹 1 (예: 인창고등학교)
• 공문번호 (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 필드도 반드시 포함해야 한다:

   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부 후반부 (카테고리 6N) + 36부 + 부록

각 섹션 작성 시:

• 공문번호를 연도 라벨 → 공문번호 순으로 나열하여 업무 흐름이 드러나게 한다.
• 반복 패턴(계획→수정→결과)은 절차로 명시한다.
• [작성자 메모] 섹션은 인용문 블록(>)으로 비워둔다.
• 부록의 공문 색인은 연도 라벨 → 공문번호 순으로 정렬한 테이블로 작성한다.
• 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 설치 여부를 확인한다:

pandoc --version

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

winget install pandoc

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

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 — 인수인계서 표준 구조 상세 + 노션 호환 마크다운 규칙