Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kimlawtech--korean-jangbu-for/badge.svg)](/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

i

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)

  1. # korean-jangbu-for
  2. [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
  3. ![Claude Code](https://img.shields.io/badge/Claude_Code-Skill-orange)
  4. ![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB)
  5. [![Discord](https://img.shields.io/badge/Discord-SpeciAI-5865F2)](https://discord.gg/hqdGsY7UpH)
  6. 한국 스타트업·1인 법인 대표·프리랜서·개인사업자를 위한 장부 자동 생성 Claude Code 스킬 패키지.
  7. 카드명세서 PDF·은행 CSV·영수증을 넣으면 표준 거래내역·계정과목 매핑·재무제표·세무사 전달 CSV가 자동 생성됩니다.
  8. > 한국 도메인 특화 AI **스페시아이**에서 만듭니다.
  9. > 법률·세무·노무·회계·의료 실무에 쓰는 도구를 오픈소스로 공개하고,
  10. > 완성 제품은 [speciai.kr](https://speciai.kr) 에서 운영합니다.
  11. > → 제품 [speciai.kr/services](https://speciai.kr/services) · 커뮤니티 [디스코드](https://discord.gg/hqdGsY7UpH)
  12. **라이선스**: Apache-2.0
  13. **버전**: 0.2.0
  14. **저자**: [@kimlawtech](https://github.com/kimlawtech) (SpeciAI)
  15. ## 설계 원칙
  16. - **입력은 넓게** — 엑셀·은행 CSV·카드 내역·영수증 이미지·세금계산서 PDF
  17. - **출력은 단계적** — 세무용(BS·PL) / 경영용(현금흐름·cash burn)
  18. - **계정체계는 매핑** — 내부 계정(유연) ↔ 국세청 표준계정(고정)
  19. - **보안 Level 2** — 민감정보 마스킹 + 룰 우선 분류 + LLM fallback 최소화
  20. ## 스킬 구성
  21. 진입점 1개 + 하위 스킬 6개 + MCP 서버 1개.
  22. | 스킬 | 호출 | 용도 |
  23. |------|------|------|
  24. | `korean-jangbu-for` | 진입점 | 번호·문자 메뉴 라우팅 |
  25. | `jangbu-connect` | 직행 | CODEF API 자격증명 설정 (BYOK) — 홈택스·은행·카드 자동 수집용 |
  26. | `jangbu-import` | 직행 | 원본 데이터(엑셀·CSV·이미지·PDF) → 표준 거래내역 |
  27. | `jangbu-tag` | 직행 | 표준 거래내역 → 계정과목 매핑 (룰 + 학습 + LLM) |
  28. | `jangbu-tax` | 직행 | 세무용 BS·PL (국세청 표준계정) |
  29. | `jangbu-dash` | 직행 | 경영용 현금흐름·대시보드·카드별 분석 |
  30. | `jangbu-jongso` | 직행 | 종소세 체크리스트 + 홈택스 다운로드 경로 상세 안내 |
  31. ## 지원 파일 포맷
  32. | 유형 | 확장자 |
  33. |------|--------|
  34. | 이미지 OCR | PNG · JPG · JPEG · HEIC · HEIF · WEBP · TIFF · TIF · BMP · GIF |
  35. | PDF | PDF (단·다중 페이지) |
  36. | 엑셀 | XLSX · XLS · XLSM |
  37. | CSV | CSV · TSV (한글 헤더 자동 감지) |
  38. HEIC/HEIF(iOS 기본 포맷)는 `pip install pillow-heif` 추가 설치 필요 (install.sh가 자동 처리).
  39. **폴더 일괄 처리**: `/korean-jangbu-for` → `[I]` 선택 → 폴더 경로 입력 → 혼합된 파일들을 자동 분류·처리.
  40. ## 자동 수집 (BYOK — 사용자 본인 CODEF 키)
  41. 사용자가 직접 [CODEF developer.codef.io](https://developer.codef.io)에 무료 가입해 받은 Client ID/Secret을 로컬에 저장하고, 본인 계정으로 홈택스·은행·카드사 데이터를 자동 수집합니다.
  42. - **자격증명은 macOS Keychain 또는 `~/.jangbu/credentials.env`(0o600)에만 저장**
  43. - **외부 서버 전송 없음**
  44. - **개인 개발자 샌드박스 월 1,000건 무료**
  45. - 설정: `/korean-jangbu-for` → `[S]` → `/jangbu-connect`
  46. - 실행: `/korean-jangbu-for` → `[F]` → 카카오/PASS 간편인증 → 자동 적재
  47. 지원 범위:
  48. - **홈택스**: 소득금액증명·납세증명·사업자등록·부가세과세표준 증명
  49. - **은행**: KB·신한·우리·하나·IBK·NH·카카오뱅크·토스뱅크 거래내역
  50. - **카드**: 신한·KB·삼성·현대·롯데·BC·우리·하나·NH 이용내역
  51. - **향후 확장**: 건강보험·국민연금·고용산재·증권 매매내역
  52. ```
  53. /korean-jangbu-for → 1·2·3·4·M·Q·T·X·C·A 번호·문자 메뉴
  54. /jangbu-import → 원본 데이터 표준화 인터뷰 (7대 카드사 명세서 포함)
  55. /jangbu-tag → 계정과목 매핑 인터뷰 (룰 + LLM + 학습)
  56. /jangbu-tax → BS·PL 생성
  57. /jangbu-dash → 경영 리포트 + 카드별 분석 + 대시보드
  58. /jangbu-jongso → 종소세 준비 체크리스트 + 자동 생성 서류
  59. ```
  60. ## 카드사 지원 현황
  61. | 카드사 | 명세서 PDF 파싱 | 비고 |
  62. |--------|---------------|------|
  63. | 신한카드 | ✅ 완전 지원 | 실전 검증 완료 (313건/74% 분류) |
  64. | KB국민카드 | ✅ 범용 파서 | 테스트 통과, 실전 샘플 대기 |
  65. | 삼성카드 | ✅ 범용 파서 | 테스트 통과 |
  66. | 현대카드 | ✅ 범용 파서 | 테스트 통과 (M/X 카드 포함) |
  67. | 롯데카드 | ✅ 범용 파서 | 테스트 통과 |
  68. | BC(비씨)카드 | ✅ 범용 파서 | 테스트 통과 |
  69. | 우리카드 | ✅ 범용 파서 | 테스트 통과 |
  70. | 하나카드 | ✅ 범용 파서 | 테스트 통과 |
  71. 범용 파서 구조: **발급사별 카드 마커 패턴 분기 + 공통 앵커(날짜·금액·사업자번호·상품구분) 추출**.
  72. 카드사별 특화 파서는 `CARD_PARSERS` 레지스트리에 추가 등록 가능.
  73. ## 데이터 흐름
  74. ```
  75. [원본 파일]
  76. ├─ bank.csv, card.csv, books.xlsx
  77. └─ receipt.jpg, tax_invoice.pdf
  78. ↓
  79. [jangbu-mcp-server]
  80. ├─ ingest_raw # CSV/엑셀 파서
  81. ├─ ocr_document # PaddleOCR (로컬)
  82. └─ 마스킹 레이어 # 사업자번호·카드번호·계좌번호 토큰화
  83. ↓
  84. 표준 거래내역 (13개 필드, SQLite)
  85. ↓
  86. [jangbu-tag]
  87. ├─ 룰 기반 (거래처 사전 + MCC + 정규식) → 80%+
  88. └─ LLM fallback (마스킹된 데이터만) → 나머지
  89. ↓
  90. 분류 완료 거래내역
  91. ↓
  92. ├─ [jangbu-tax] → BS·PL (국세청 표준계정 매핑)
  93. └─ [jangbu-dash] → 현금흐름·cash burn·월별 손익
  94. ```
  95. ## 표준 거래내역 스키마
  96. 필수 9 + 확장 4.
  97. | 필드 | 타입 | 필수 | 설명 | 예시 |
  98. |---|---|---|---|---|
  99. | `transaction_id` | str (UUID) | 필수 | 내부 고유 ID | `tx_01HW...` |
  100. | `date` | date | 필수 | 거래일 | `2026-04-15` |
  101. | `amount` | decimal(18,2) | 필수 | 절대값 | `1500000.00` |
  102. | `currency` | str (ISO 4217) | 필수 | 통화코드 | `KRW` |
  103. | `direction` | enum | 필수 | `inflow`/`outflow` | `outflow` |
  104. | `counterparty` | str | 필수 | 상대방명(정규화) | `구글코리아` |
  105. | `description` | str | 필수 | 정규화 적요 | `Google Ads 광고비` |
  106. | `source` | enum | 필수 | `bank`/`card`/`manual`/`ocr` | `card` |
  107. | `source_ref` | str | 필수 | 원본 식별자(중복 제거) | `20260415-APPR-88421` |
  108. | `raw_description` | str | 확장 | 원문 적요 | `GOOGLE*ADS 1234` |
  109. | `account_id` | str | 확장 | 내부 계좌/카드 ID | `acct_shinhan_001` |
  110. | `matched_account` | str | 확장 | 매핑된 계정과목 | `광고선전비` |
  111. | `confidence` | float (0~1) | 확장 | 분류 신뢰도 | `0.92` |
  112. ## 보안 모델 (Level 2)
  113. - **토큰화 대상**: 사업자번호·주민번호·카드번호·계좌번호·`account_id`
  114. - **원본 유지**: `date`, `amount`, `currency`, `direction`, `source`
  115. - **부분 마스킹**: `counterparty`·`description`·`raw_description` (번호류만 토큰 치환)
  116. - **LLM 미경유 작업**: 룰 분류·BS/PL 생성·OCR 텍스트 추출
  117. - **LLM 경유 작업**: 룰 실패한 분류 건만, 마스킹된 뷰로 전달
  118. - **감사 로그**: 모든 MCP 도구 호출 기록(append-only)
  119. ## 저장소 레이아웃
  120. ```
  121. ~/.jangbu/
  122. ├── raw/
  123. │ ├── imports/ # 엑셀·CSV 원본
  124. │ └── ocr/ # 영수증·세금계산서 이미지·PDF
  125. ├── finance.db # SQLite: transactions, mappings, classifications
  126. ├── tokens.db # SQLite: 토큰↔원본 매핑 (권한 분리)
  127. └── audit.log # append-only 감사 로그
  128. ```
  129. ## OCR 파이프라인
  130. PaddleOCR 로컬 실행 → 룰 기반 구조화 → LLM fallback.
  131. 1. **PaddleOCR (PP-OCRv4 한국어 모델)** — 텍스트 + 좌표 추출, 외부 전송 없음
  132. 2. **문서 유형별 파서**
  133. - `receipt`: 상호·사업자번호·날짜·합계·공급가액·부가세
  134. - `tax_invoice`: 공급자·공급받는자·품목·공급가액·세액·작성일자
  135. - `bank_statement_scan`: 거래일·적요·금액·잔액
  136. 3. **LLM fallback** — 파서 실패 시 마스킹된 텍스트만 전달해 구조화
  137. ## 설치 (3분)
  138. ### 1. 한 줄 설치
  139. ```bash
  140. mkdir -p ~/.claude/skills && cd ~/.claude/skills && \
  141. git clone https://github.com/kimlawtech/korean-jangbu-for.git && \
  142. bash korean-jangbu-for/scripts/install.sh
  143. ```
  144. 자동으로:
  145. - poppler 확인·설치 (`brew install poppler`)
  146. - Python 가상환경 + 의존성 설치
  147. - macOS면 Vision 프레임워크 / Linux면 PaddleOCR 자동 선택
  148. - SQLite 초기화 + 시드 주입 (계정 47개 + 룰 46개)
  149. - 6개 스킬 심볼릭 링크 생성
  150. ### 2. MCP 서버 등록
  151. ```bash
  152. claude mcp add jangbu-mcp -- \
  153. ~/.claude/skills/korean-jangbu-for/mcp-server/.venv/bin/python -m jangbu_mcp
  154. ```
  155. ### 3. 설치 검증 (선택)
  156. ```bash
  157. bash ~/.claude/skills/korean-jangbu-for/scripts/verify.sh
  158. ```
  159. ### 4. Claude Code 재시작 후 사용
  160. ```
  161. /korean-jangbu-for
  162. ```
  163. 메뉴가 뜨면 성공.
  164. ### 요구사항
  165. - **macOS** (Vision OCR 추가 다운로드 없음) 또는 **Linux** (PaddleOCR ~500MB)
  166. - **Python 3.11+**
  167. - **Homebrew** (poppler 자동 설치용)
  168. - **Claude Code** 설치됨
  169. ### 문제 해결
  170. | 증상 | 해결 |
  171. |------|------|
  172. | `brew` 없음 | `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` |
  173. | Python 3.13에서 PaddleOCR 실패 | 무시 가능 — macOS는 Vision 사용 (install.sh 자동 처리) |
  174. | `jangbu-mcp` 도구 안 보임 | Claude Code 완전 재시작 후 `claude mcp list` 확인 |
  175. | 직접 MCP 서버 실행 테스트 | `~/.claude/skills/korean-jangbu-for/mcp-server/.venv/bin/python -m jangbu_mcp` |
  176. ## 대상 사용자
  177. - 스타트업 대표 — 기장 맡기기 전 내부 재무 가시성 확보
  178. - 1인 법인 — 법인세 신고 연결 + 월별 현금흐름 파악
  179. - 세무사무소 주니어 — 고객 raw 데이터 정리 반복 업무 단축
  180. ## 법적 면책
  181. 본 스킬이 생성하는 재무제표는 **참고용 초안**이며, 공인회계사 감사·세무사 검토를 대체하지 않습니다.
  182. - 외감 대상(자산 120억 이상 등)은 **공인회계사 감사 필수**
  183. - 법인세 신고 전 **세무사 검토 필수**
  184. - 일반기업회계기준(K-GAAP)의 간소화 버전이며 모든 주석을 포함하지 않습니다
  185. ## 커뮤니티 — SpeciAI
  186. 한국 법률 AI 허브 **SpeciAI** 디스코드에서 만들어요.
  187. 창업자·개발자·변호사·세무사·회계사가 모여 계약·노동·투자·지재권·세무 이슈를 AI로 푸는 커뮤니티입니다.
  188. ### 여기서 바로 물어볼 수 있어요
  189. **스킬 사용 관련**
  190. - 이 스킬 설치·실행 중 막히는 부분 → 스샷 올리면 바로 답변
  191. - OCR 오인식·파싱 실패 사례 공유 → 다음 버전 룰에 반영
  192. - CODEF 연동·간편인증 에러 트러블슈팅
  193. - 특정 카드사·은행 CSV 포맷 질문
  194. - "내 경우엔 이런 계정으로 처리하는 게 맞나?" 실무 질문
  195. **세무·회계 실무**
  196. - 종소세(5월)·법인세(3월)·부가세(분기) 신고 전 체크 질문
  197. - "이 거래를 접대비·복리후생비 어디로 넣어야 하나?"
  198. - 세무사랑·더존 호환 CSV 포맷 팁
  199. - 프리랜서 3.3% 원천징수 관련 이슈
  200. **법률·계약 실무** (다른 `korean-*` 스킬 연동)
  201. - `korean-contracts` — 근로·프리랜서·외주 계약서 작성 질문
  202. - `korean-privacy-terms` — 처리방침·이용약관 관련
  203. - `korean-patent-diagram` — 특허 도면 생성
  204. **아이디어·기능 요청**
  205. - "이런 스킬 있으면 좋겠는데" 제안
  206. - 버그 리포트 · PR 환영
  207. - 실제 사용 사례 공유
  208. ### 활동 내용
  209. - **신규 스킬 출시 공지** · 업데이트 체인지로그
  210. - **실전 Q&A 채널** — 익명 질문 가능
  211. - **법령 업데이트 반영 공지** (개정 때마다 스킬 자동 업데이트)
  212. - **오픈소스 기여자 소통**
  213. **초대 링크**: [discord.gg/hqdGsY7UpH](https://discord.gg/hqdGsY7UpH)
  214. ## 기여
  215. Pull Request 환영합니다. 특히 필요한 영역:
  216. - 카드사별 특화 파서 (KB·삼성·현대·롯데·BC·우리·하나)
  217. - 5대 은행 CSV 포맷 실데이터 검증·보강
  218. - 계정과목 분류 룰 확장 (업종별 특화)
  219. - 분개 엔진 MVP (복식부기 기반 정식 BS)
  220. ## 저자
  221. 운영: **[@kimlawtech](https://github.com/kimlawtech)** — [SpeciAI](https://discord.gg/hqdGsY7UpH)
  222. 한국 법률 AI 허브 SpeciAI를 운영하며 한국 사업자를 위한 계약서·처리방침·약관·장부·세무 자동화 Claude Code 스킬을 만들고 있습니다.
  223. **관련 스킬 패키지**
  224. - [`korean-contracts`](https://github.com/kimlawtech/korean-contracts) — 근로계약·프리랜서·외주·연봉갱신 등 9종 계약서
  225. - [`korean-privacy-terms`](https://github.com/kimlawtech/korean-privacy-terms) — 처리방침·이용약관 (PIPA·GDPR·CCPA)
  226. - [`korean-patent-diagram`](https://github.com/kimlawtech/korean-patent-diagram) — 특허 도면 자동 생성
  227. - **`korean-jangbu-for`** — 장부·재무제표·세무사 전달 (이 패키지)
  228. ## License
  229. **Apache License 2.0** — 자세한 내용은 [LICENSE](./LICENSE) 참조.
  230. Copyright 2026 kimlawtech (SpeciAI).
  231. ## Disclaimer
  232. 본 스킬이 생성하는 재무제표는 **참고용 초안**이며 공인회계사 감사·세무사 검토를 대체하지 않습니다.
  233. 실제 법인세·종합소득세 신고 전 반드시 세무사 검토를 받으세요.
  234. 자세한 면책 고지는 [DISCLAIMER.md](./DISCLAIMER.md) 참조.
  235. ---
  236. Built with [Claude Code](https://claude.com/claude-code) by [@kimlawtech](https://github.com/kimlawtech).
  237. ---
  238. ## 만든 곳
  239. [스페시아이](https://speciai.kr)는 법률·세무·노무·회계·의료 실무에 쓰는
  240. 도메인 특화 AI를 만듭니다. 한국능률협회와 AI 교육과정을 공동 개설했고,
  241. 전문직 세미나에 누적 500명 이상이 참여했습니다.
  242. - 제품 전체 — <https://speciai.kr/services>
  243. - Claude Code 플러그인 (법무·노무·세무 자문) — <https://speciai.kr/plugin>
  244. - 전문직 AI 세미나 (월 1회) — <https://speciai.kr/seminar>
  245. - 커뮤니티 — <https://discord.gg/hqdGsY7UpH>
  246. ### 개발팀으로 쓰신다면
  247. DevCowork — 화면설계서 기반 구현·코드리뷰, 커밋·토큰·DORA 지표 추적
  248. → <https://devcowork.speciai.team>
  249. ### 함께 만든 오픈소스
  250. | 저장소 | 내용 | |
  251. |---|---|---|
  252. | [korean-privacy-terms](https://github.com/kimlawtech/korean-privacy-terms) | 처리방침·이용약관 자동 생성 | 573★ |
  253. | [korean-contracts](https://github.com/kimlawtech/korean-contracts) | 한국 계약서 9종 | 61★ |
  254. | [korean-patent-diagram](https://github.com/kimlawtech/korean-patent-diagram) | 특허 도면 자동 생성 (KIPO 규격) | 18★ |
  255. | [korean-certified-mail](https://github.com/kimlawtech/korean-certified-mail) | 내용증명 14종 | 9★ |
  256. | [korean-domain-agent](https://github.com/kimlawtech/korean-domain-agent) | 도메인 특화 LLM 에이전트 킷 | 5★ |

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.