korean-jangbu-for

한국 스타트업·1인 법인 대표·프리랜서·개인사업자를 위한 장부 자동 생성 Claude Code 스킬 패키지. 카드명세서 PDF·은행 CSV·영수증을 넣으면 표준 거래내역·계정과목 매핑·재무제표·세무사 전달 CSV가 자동 생성됩니다.

한국 도메인 특화 AI 스페시아이에서 만듭니다. 법률·세무·노무·회계·의료 실무에 쓰는 도구를 오픈소스로 공개하고, 완성 제품은 speciai.kr 에서 운영합니다. → 제품 speciai.kr/services · 커뮤니티 디스코드

라이선스: Apache-2.0 버전: 0.2.0 저자: @kimlawtech (SpeciAI)

설계 원칙

• 입력은 넓게 — 엑셀·은행 CSV·카드 내역·영수증 이미지·세금계산서 PDF
• 출력은 단계적 — 세무용(BS·PL) / 경영용(현금흐름·cash burn)
• 계정체계는 매핑 — 내부 계정(유연) ↔ 국세청 표준계정(고정)
• 보안 Level 2 — 민감정보 마스킹 + 룰 우선 분류 + LLM fallback 최소화

스킬 구성

진입점 1개 + 하위 스킬 6개 + MCP 서버 1개.

스킬	호출	용도
korean-jangbu-for	진입점	번호·문자 메뉴 라우팅
jangbu-connect	직행	CODEF API 자격증명 설정 (BYOK) — 홈택스·은행·카드 자동 수집용
jangbu-import	직행	원본 데이터(엑셀·CSV·이미지·PDF) → 표준 거래내역
jangbu-tag	직행	표준 거래내역 → 계정과목 매핑 (룰 + 학습 + LLM)
jangbu-tax	직행	세무용 BS·PL (국세청 표준계정)
jangbu-dash	직행	경영용 현금흐름·대시보드·카드별 분석
jangbu-jongso	직행	종소세 체크리스트 + 홈택스 다운로드 경로 상세 안내

지원 파일 포맷

유형	확장자
이미지 OCR	PNG · JPG · JPEG · HEIC · HEIF · WEBP · TIFF · TIF · BMP · GIF
PDF	PDF (단·다중 페이지)
엑셀	XLSX · XLS · XLSM
CSV	CSV · TSV (한글 헤더 자동 감지)

HEIC/HEIF(iOS 기본 포맷)는 pip install pillow-heif 추가 설치 필요 (install.sh가 자동 처리).

폴더 일괄 처리: /korean-jangbu-for → [I] 선택 → 폴더 경로 입력 → 혼합된 파일들을 자동 분류·처리.

자동 수집 (BYOK — 사용자 본인 CODEF 키)

사용자가 직접 CODEF developer.codef.io에 무료 가입해 받은 Client ID/Secret을 로컬에 저장하고, 본인 계정으로 홈택스·은행·카드사 데이터를 자동 수집합니다.

• 자격증명은 macOS Keychain 또는 ~/.jangbu/credentials.env(0o600)에만 저장
• 외부 서버 전송 없음
• 개인 개발자 샌드박스 월 1,000건 무료
• 설정: /korean-jangbu-for → [S] → /jangbu-connect
• 실행: /korean-jangbu-for → [F] → 카카오/PASS 간편인증 → 자동 적재

지원 범위:

• 홈택스: 소득금액증명·납세증명·사업자등록·부가세과세표준 증명
• 은행: KB·신한·우리·하나·IBK·NH·카카오뱅크·토스뱅크 거래내역
• 카드: 신한·KB·삼성·현대·롯데·BC·우리·하나·NH 이용내역
• 향후 확장: 건강보험·국민연금·고용산재·증권 매매내역

/korean-jangbu-for      → 1·2·3·4·M·Q·T·X·C·A 번호·문자 메뉴
/jangbu-import       → 원본 데이터 표준화 인터뷰 (7대 카드사 명세서 포함)
/jangbu-tag        → 계정과목 매핑 인터뷰 (룰 + LLM + 학습)
/jangbu-tax      → BS·PL 생성
/jangbu-dash     → 경영 리포트 + 카드별 분석 + 대시보드
/jangbu-jongso   → 종소세 준비 체크리스트 + 자동 생성 서류

카드사 지원 현황

카드사	명세서 PDF 파싱	비고
신한카드	✅ 완전 지원	실전 검증 완료 (313건/74% 분류)
KB국민카드	✅ 범용 파서	테스트 통과, 실전 샘플 대기
삼성카드	✅ 범용 파서	테스트 통과
현대카드	✅ 범용 파서	테스트 통과 (M/X 카드 포함)
롯데카드	✅ 범용 파서	테스트 통과
BC(비씨)카드	✅ 범용 파서	테스트 통과
우리카드	✅ 범용 파서	테스트 통과
하나카드	✅ 범용 파서	테스트 통과

범용 파서 구조: 발급사별 카드 마커 패턴 분기 + 공통 앵커(날짜·금액·사업자번호·상품구분) 추출. 카드사별 특화 파서는 CARD_PARSERS 레지스트리에 추가 등록 가능.

데이터 흐름

[원본 파일]
  ├─ bank.csv, card.csv, books.xlsx
  └─ receipt.jpg, tax_invoice.pdf
        ↓
  [jangbu-mcp-server]
    ├─ ingest_raw        # CSV/엑셀 파서
    ├─ ocr_document      # PaddleOCR (로컬)
    └─ 마스킹 레이어      # 사업자번호·카드번호·계좌번호 토큰화
        ↓
  표준 거래내역 (13개 필드, SQLite)
        ↓
  [jangbu-tag]
    ├─ 룰 기반 (거래처 사전 + MCC + 정규식) → 80%+
    └─ LLM fallback (마스킹된 데이터만) → 나머지
        ↓
  분류 완료 거래내역
        ↓
  ├─ [jangbu-tax]  → BS·PL (국세청 표준계정 매핑)
  └─ [jangbu-dash] → 현금흐름·cash burn·월별 손익

표준 거래내역 스키마

필수 9 + 확장 4.