korean-jangbu-for
한국 스타트업, 1인 법인, 프리랜서, 개인 사업자를 위한 장부 자동 생성 Claude Code 스킬. 카드명세서 PDF·은행 CSV → 재무제표·세무사 전달 CSV 자동 생성. Level 2 민감정보 마스킹 적용.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/kimlawtech--korean-jangbu-for)HTML
<a href="/listings/kimlawtech--korean-jangbu-for"><img src="/api/listings/kimlawtech--korean-jangbu-for/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
1. 한 줄 설치
mkdir -p ~/.claude/skills && cd ~/.claude/skills && \ git clone https://github.com/kimlawtech/korean-jangbu-for.git && \ bash korean-jangbu-for/scripts/install.sh
자동으로: - poppler 확인·설치 (`brew install poppler`) - Python 가상환경 + 의존성 설치 - macOS면 Vision 프레임워크 / Linux면 PaddleOCR 자동 선택 - SQLite 초기화 + 시드 주입 (계정 47개 + 룰 46개) - 6개 스킬 심볼릭 링크 생성
2. MCP 서버 등록
claude mcp add jangbu-mcp -- \ ~/.claude/skills/korean-jangbu-for/mcp-server/.venv/bin/python -m jangbu_mcp
3. 설치 검증 (선택)
bash ~/.claude/skills/korean-jangbu-for/scripts/verify.sh
4. Claude Code 재시작 후 사용
/korean-jangbu-for
메뉴가 뜨면 성공.
요구사항
- **macOS** (Vision OCR 추가 다운로드 없음) 또는 **Linux** (PaddleOCR ~500MB) - **Python 3.11+** - **Homebrew** (poppler 자동 설치용) - **Claude Code** 설치됨
문제 해결
| 증상 | 해결 | |------|------| | `brew` 없음 | `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` | | Python 3.13에서 PaddleOCR 실패 | 무시 가능 — macOS는 Vision 사용 (install.sh 자동 처리) | | `jangbu-mcp` 도구 안 보임 | Claude Code 완전 재시작 후 `claude mcp list` 확인 | | 직접 MCP 서버 실행 테스트 | `~/.claude/skills/korean-jangbu-for/mcp-server/.venv/bin/python -m jangbu_mcp` |
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 340 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # korean-jangbu-for
- [](https://opensource.org/licenses/Apache-2.0)
- 
- 
- [](https://discord.gg/hqdGsY7UpH)
- 한국 스타트업·1인 법인 대표·프리랜서·개인사업자를 위한 장부 자동 생성 Claude Code 스킬 패키지.
- 카드명세서 PDF·은행 CSV·영수증을 넣으면 표준 거래내역·계정과목 매핑·재무제표·세무사 전달 CSV가 자동 생성됩니다.
- > 한국 도메인 특화 AI **스페시아이**에서 만듭니다.
- > 법률·세무·노무·회계·의료 실무에 쓰는 도구를 오픈소스로 공개하고,
- > 완성 제품은 [speciai.kr](https://speciai.kr) 에서 운영합니다.
- > → 제품 [speciai.kr/services](https://speciai.kr/services) · 커뮤니티 [디스코드](https://discord.gg/hqdGsY7UpH)
- **라이선스**: Apache-2.0
- **버전**: 0.2.0
- **저자**: [@kimlawtech](https://github.com/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](https://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.
- | 필드 | 타입 | 필수 | 설명 | 예시 |
- |---|---|---|---|---|
- | `transaction_id` | str (UUID) | 필수 | 내부 고유 ID | `tx_01HW...` |
- | `date` | date | 필수 | 거래일 | `2026-04-15` |
- | `amount` | decimal(18,2) | 필수 | 절대값 | `1500000.00` |
- | `currency` | str (ISO 4217) | 필수 | 통화코드 | `KRW` |
- | `direction` | enum | 필수 | `inflow`/`outflow` | `outflow` |
- | `counterparty` | str | 필수 | 상대방명(정규화) | `구글코리아` |
- | `description` | str | 필수 | 정규화 적요 | `Google Ads 광고비` |
- | `source` | enum | 필수 | `bank`/`card`/`manual`/`ocr` | `card` |
- | `source_ref` | str | 필수 | 원본 식별자(중복 제거) | `20260415-APPR-88421` |
- | `raw_description` | str | 확장 | 원문 적요 | `GOOGLE*ADS 1234` |
- | `account_id` | str | 확장 | 내부 계좌/카드 ID | `acct_shinhan_001` |
- | `matched_account` | str | 확장 | 매핑된 계정과목 | `광고선전비` |
- | `confidence` | float (0~1) | 확장 | 분류 신뢰도 | `0.92` |
- ## 보안 모델 (Level 2)
- - **토큰화 대상**: 사업자번호·주민번호·카드번호·계좌번호·`account_id`
- - **원본 유지**: `date`, `amount`, `currency`, `direction`, `source`
- - **부분 마스킹**: `counterparty`·`description`·`raw_description` (번호류만 토큰 치환)
- - **LLM 미경유 작업**: 룰 분류·BS/PL 생성·OCR 텍스트 추출
- - **LLM 경유 작업**: 룰 실패한 분류 건만, 마스킹된 뷰로 전달
- - **감사 로그**: 모든 MCP 도구 호출 기록(append-only)
- ## 저장소 레이아웃
- ```
- ~/.jangbu/
- ├── raw/
- │ ├── imports/ # 엑셀·CSV 원본
- │ └── ocr/ # 영수증·세금계산서 이미지·PDF
- ├── finance.db # SQLite: transactions, mappings, classifications
- ├── tokens.db # SQLite: 토큰↔원본 매핑 (권한 분리)
- └── audit.log # append-only 감사 로그
- ```
- ## OCR 파이프라인
- PaddleOCR 로컬 실행 → 룰 기반 구조화 → LLM fallback.
- 1. **PaddleOCR (PP-OCRv4 한국어 모델)** — 텍스트 + 좌표 추출, 외부 전송 없음
- 2. **문서 유형별 파서**
- - `receipt`: 상호·사업자번호·날짜·합계·공급가액·부가세
- - `tax_invoice`: 공급자·공급받는자·품목·공급가액·세액·작성일자
- - `bank_statement_scan`: 거래일·적요·금액·잔액
- 3. **LLM fallback** — 파서 실패 시 마스킹된 텍스트만 전달해 구조화
- ## 설치 (3분)
- ### 1. 한 줄 설치
- ```bash
- mkdir -p ~/.claude/skills && cd ~/.claude/skills && \
- git clone https://github.com/kimlawtech/korean-jangbu-for.git && \
- bash korean-jangbu-for/scripts/install.sh
- ```
- 자동으로:
- - poppler 확인·설치 (`brew install poppler`)
- - Python 가상환경 + 의존성 설치
- - macOS면 Vision 프레임워크 / Linux면 PaddleOCR 자동 선택
- - SQLite 초기화 + 시드 주입 (계정 47개 + 룰 46개)
- - 6개 스킬 심볼릭 링크 생성
- ### 2. MCP 서버 등록
- ```bash
- claude mcp add jangbu-mcp -- \
- ~/.claude/skills/korean-jangbu-for/mcp-server/.venv/bin/python -m jangbu_mcp
- ```
- ### 3. 설치 검증 (선택)
- ```bash
- bash ~/.claude/skills/korean-jangbu-for/scripts/verify.sh
- ```
- ### 4. Claude Code 재시작 후 사용
- ```
- /korean-jangbu-for
- ```
- 메뉴가 뜨면 성공.
- ### 요구사항
- - **macOS** (Vision OCR 추가 다운로드 없음) 또는 **Linux** (PaddleOCR ~500MB)
- - **Python 3.11+**
- - **Homebrew** (poppler 자동 설치용)
- - **Claude Code** 설치됨
- ### 문제 해결
- | 증상 | 해결 |
- |------|------|
- | `brew` 없음 | `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` |
- | Python 3.13에서 PaddleOCR 실패 | 무시 가능 — macOS는 Vision 사용 (install.sh 자동 처리) |
- | `jangbu-mcp` 도구 안 보임 | Claude Code 완전 재시작 후 `claude mcp list` 확인 |
- | 직접 MCP 서버 실행 테스트 | `~/.claude/skills/korean-jangbu-for/mcp-server/.venv/bin/python -m jangbu_mcp` |
- ## 대상 사용자
- - 스타트업 대표 — 기장 맡기기 전 내부 재무 가시성 확보
- - 1인 법인 — 법인세 신고 연결 + 월별 현금흐름 파악
- - 세무사무소 주니어 — 고객 raw 데이터 정리 반복 업무 단축
- ## 법적 면책
- 본 스킬이 생성하는 재무제표는 **참고용 초안**이며, 공인회계사 감사·세무사 검토를 대체하지 않습니다.
- - 외감 대상(자산 120억 이상 등)은 **공인회계사 감사 필수**
- - 법인세 신고 전 **세무사 검토 필수**
- - 일반기업회계기준(K-GAAP)의 간소화 버전이며 모든 주석을 포함하지 않습니다
- ## 커뮤니티 — SpeciAI
- 한국 법률 AI 허브 **SpeciAI** 디스코드에서 만들어요.
- 창업자·개발자·변호사·세무사·회계사가 모여 계약·노동·투자·지재권·세무 이슈를 AI로 푸는 커뮤니티입니다.
- ### 여기서 바로 물어볼 수 있어요
- **스킬 사용 관련**
- - 이 스킬 설치·실행 중 막히는 부분 → 스샷 올리면 바로 답변
- - OCR 오인식·파싱 실패 사례 공유 → 다음 버전 룰에 반영
- - CODEF 연동·간편인증 에러 트러블슈팅
- - 특정 카드사·은행 CSV 포맷 질문
- - "내 경우엔 이런 계정으로 처리하는 게 맞나?" 실무 질문
- **세무·회계 실무**
- - 종소세(5월)·법인세(3월)·부가세(분기) 신고 전 체크 질문
- - "이 거래를 접대비·복리후생비 어디로 넣어야 하나?"
- - 세무사랑·더존 호환 CSV 포맷 팁
- - 프리랜서 3.3% 원천징수 관련 이슈
- **법률·계약 실무** (다른 `korean-*` 스킬 연동)
- - `korean-contracts` — 근로·프리랜서·외주 계약서 작성 질문
- - `korean-privacy-terms` — 처리방침·이용약관 관련
- - `korean-patent-diagram` — 특허 도면 생성
- **아이디어·기능 요청**
- - "이런 스킬 있으면 좋겠는데" 제안
- - 버그 리포트 · PR 환영
- - 실제 사용 사례 공유
- ### 활동 내용
- - **신규 스킬 출시 공지** · 업데이트 체인지로그
- - **실전 Q&A 채널** — 익명 질문 가능
- - **법령 업데이트 반영 공지** (개정 때마다 스킬 자동 업데이트)
- - **오픈소스 기여자 소통**
- **초대 링크**: [discord.gg/hqdGsY7UpH](https://discord.gg/hqdGsY7UpH)
- ## 기여
- Pull Request 환영합니다. 특히 필요한 영역:
- - 카드사별 특화 파서 (KB·삼성·현대·롯데·BC·우리·하나)
- - 5대 은행 CSV 포맷 실데이터 검증·보강
- - 계정과목 분류 룰 확장 (업종별 특화)
- - 분개 엔진 MVP (복식부기 기반 정식 BS)
- ## 저자
- 운영: **[@kimlawtech](https://github.com/kimlawtech)** — [SpeciAI](https://discord.gg/hqdGsY7UpH)
- 한국 법률 AI 허브 SpeciAI를 운영하며 한국 사업자를 위한 계약서·처리방침·약관·장부·세무 자동화 Claude Code 스킬을 만들고 있습니다.
- **관련 스킬 패키지**
- - [`korean-contracts`](https://github.com/kimlawtech/korean-contracts) — 근로계약·프리랜서·외주·연봉갱신 등 9종 계약서
- - [`korean-privacy-terms`](https://github.com/kimlawtech/korean-privacy-terms) — 처리방침·이용약관 (PIPA·GDPR·CCPA)
- - [`korean-patent-diagram`](https://github.com/kimlawtech/korean-patent-diagram) — 특허 도면 자동 생성
- - **`korean-jangbu-for`** — 장부·재무제표·세무사 전달 (이 패키지)
- ## License
- **Apache License 2.0** — 자세한 내용은 [LICENSE](./LICENSE) 참조.
- Copyright 2026 kimlawtech (SpeciAI).
- ## Disclaimer
- 본 스킬이 생성하는 재무제표는 **참고용 초안**이며 공인회계사 감사·세무사 검토를 대체하지 않습니다.
- 실제 법인세·종합소득세 신고 전 반드시 세무사 검토를 받으세요.
- 자세한 면책 고지는 [DISCLAIMER.md](./DISCLAIMER.md) 참조.
- ---
- Built with [Claude Code](https://claude.com/claude-code) by [@kimlawtech](https://github.com/kimlawtech).
- ---
- ## 만든 곳
- [스페시아이](https://speciai.kr)는 법률·세무·노무·회계·의료 실무에 쓰는
- 도메인 특화 AI를 만듭니다. 한국능률협회와 AI 교육과정을 공동 개설했고,
- 전문직 세미나에 누적 500명 이상이 참여했습니다.
- - 제품 전체 — <https://speciai.kr/services>
- - Claude Code 플러그인 (법무·노무·세무 자문) — <https://speciai.kr/plugin>
- - 전문직 AI 세미나 (월 1회) — <https://speciai.kr/seminar>
- - 커뮤니티 — <https://discord.gg/hqdGsY7UpH>
- ### 개발팀으로 쓰신다면
- DevCowork — 화면설계서 기반 구현·코드리뷰, 커밋·토큰·DORA 지표 추적
- → <https://devcowork.speciai.team>
- ### 함께 만든 오픈소스
- | 저장소 | 내용 | |
- |---|---|---|
- | [korean-privacy-terms](https://github.com/kimlawtech/korean-privacy-terms) | 처리방침·이용약관 자동 생성 | 573★ |
- | [korean-contracts](https://github.com/kimlawtech/korean-contracts) | 한국 계약서 9종 | 61★ |
- | [korean-patent-diagram](https://github.com/kimlawtech/korean-patent-diagram) | 특허 도면 자동 생성 (KIPO 규격) | 18★ |
- | [korean-certified-mail](https://github.com/kimlawtech/korean-certified-mail) | 내용증명 14종 | 9★ |
- | [korean-domain-agent](https://github.com/kimlawtech/korean-domain-agent) | 도메인 특화 LLM 에이전트 킷 | 5★ |
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.