급여대장 및 원천세신고 · git:20261103.ee2ee00 · 2026-11-03 · sha256 6000ce98efc70066
급여대장 및 원천세신고 git:20261103.ee2ee00A
Immutable. This exact content never changes and is served at /api/v1/blob/6000ce98efc70066.
---
name: 급여대장 및 원천세신고
description: 급여대장 엑셀이나 인사카드 · 급여계약 · 항목규칙 csv 가 든 폴더(또는 Google Drive 폴더 · 파일 링크)를 받아 원천징수이행상황신고서 집계표 · 신고값과 홈택스 전자신고 파일(C103900)을 만들고 형식검증 22개를 통과시킨다. 그 달 퇴사자의 퇴직금 · 퇴직소득세 · 중도퇴사 정산과 강사료 같은 기타소득도 같은 신고에 넣는다. 요율 · 간이세액표 · 비과세 한도 · 세율 · 기한은 근거목록에 조문과 TaxDoctor 스냅샷으로 적혀 있고, 최신화 명령이 판이 바뀌었거나 시행예정 개정이 있는 값을 찾는다. "급여대장 및 원천세신고", "원천세 신고", "원천징수이행상황신고서", "인사카드로 급여대장", "급여대장 만들어", "급여대장으로 원천세", "원천세 전자신고 파일", "C103900", "홈택스 업로드 파일", "퇴직금 계산", "중도퇴사 정산", "강사료 원천징수", "기타소득 원천징수", "근로계약서 검토", "원천세 최신화", "요율 최신화" 가 나오면 쓴다.
---
# 급여대장 및 원천세신고
급여 자료가 든 폴더 하나로 그 달 원천세 신고 파일까지 만든다. 계산은 스크립트가 하고, Claude 는 자료를 모으고 사람이 정할 것을 묻고 결과를 표로 보인다.
```
급여대장 엑셀 ─────────────┐
인사카드 · 급여계약 · 항목규칙 csv → 급여대장 ─┤
퇴사(퇴직금 · 중도정산) · 기타소득 → 추가행 ──┤
회사기초정보 엑셀 ──────────┘
→ 원천징수 집계표 · 신고값 → 전자신고 파일 YYYYMMDDC103900.01 → 형식검증 22개
```
모든 명령은 이 스킬 폴더에서 `python scripts/실행.py <명령>` 으로 부른다. 결과는 표로 옮겨 보이고, 금액을 다시 계산하지 않는다.
## 처음 쓸 때
공개 저장소의 이 스킬에는 샘플 자료와 시험 코드가 없다. 자기 회사 한 달 자료로 「1. 자료 받기」부터 시작한다. 샘플 자료(`examples/샘플회사`)가 들어 있는 판이면 `python scripts/실행.py 샘플 <작업 폴더>` 로 가상 회사 2026년 7월을 끝까지 돌려 본다(납부할 소득세 797,470원 · 위택스 지방소득세 79,760원 · 형식검증 22개 통과). 엑셀이 있는 윈도우에서는 집계표 재계산에 1분 안팎 걸린다. `--재계산생략` 을 붙이면 몇 초에 끝난다.
## 1. 자료 받기
**로컬 폴더나 파일이면 바로 2로 간다.**
**Google Drive 링크면 먼저 내려받는다.** 스크립트는 Drive 에 접속하지 않는다.
1. `python scripts/실행.py 링크 <링크>` 로 폴더인지 파일인지와 id 를 본다.
2. 세션의 Google Drive 커넥터로 받는다. 폴더면 `search_files` 에 `parentId = '<id>'` 를 주어 파일 목록을 얻고 하위 폴더(받은자료 · 이번달사건)도 한 번 더 내려간다. 파일마다 `download_file_content` 를 부른다. 구글 시트는 `exportMimeType` 을 `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` 로 준다.
3. 받은 base64 문자열을 파일로 저장하고 `python scripts/실행.py 풀기 <글 파일> <저장 경로>` 로 원래 파일을 만든다. Drive 의 폴더 구조와 파일 이름을 그대로 쓴다.
4. 그 로컬 폴더로 2를 한다.
파일 내용이 base64 로 대화에 실려 오가므로 파일이 크거나 많으면 느리다. 엑셀 몇 개를 넘으면 사용자에게 Drive 에서 폴더째 내려받아 그 로컬 경로를 달라고 한다.
커넥터가 없거나 파일이 안 보이면 그 사실을 말하고 로컬 폴더 경로를 달라고 한다. 남이 공유한 폴더는 사용자가 한 번 연 파일만 커넥터 검색에 나온다. 몇 개만 보이면 빠진 파일 이름을 말하고, 사용자가 브라우저에서 열어 보거나 내려받아 폴더로 주게 한다.
## 2. 폴더 보기
`신고` 명령은 출력 첫머리에 찾은 자료를 적는다. 찾는 자료는 아래 표와 같다.
| 자료 | 이름 | 없으면 |
|---|---|---|
| 급여대장 | 파일 이름에 `급여대장` · `payroll` 이 든 엑셀. 이름의 `2026-07` 로 달을 안다 | 아래 csv 셋으로 만든다 |
| 인사카드 · 급여계약 · 항목규칙 | `hr_card.csv` · `pay_contract.csv` · `pay_item_rule.csv`(또는 `인사카드.csv` · `급여계약.csv` · `항목규칙.csv`) | 급여대장도 없으면 멈춘다 |
| 회사기초정보 | 이름에 `회사기초정보` 가 든 엑셀 | 빈 틀을 만들고 멈춘다(3) |
| 추가행 | `추가행_YYYY-MM.json` | 대장만 집계한다 |
| 기타소득 목록 | 이름에 `기타소득` 이 든 csv | 기타소득 없음 |
| 일용 근태 | 이름에 `근태` 와 달(`근태_2026-10.xlsx`)이 든 엑셀. 시트 「근태기록」, 열 일자 · 사번 · 일급 | 일용은 그 달 근태가 없는 사람으로 보고 대장에서 뺀다 |
급여대장은 회사마다 열 이름이 달라도 읽는다. 성명(이름 · 소득자) · 총지급액(지급총액 · 지급계 · 지급액) · 소득세(근로소득세 · 갑근세 · 원천징수세액) · 지방소득세(주민세) · 구분(고용형태 · 소득코드)을 별칭으로 맞춘다. 성명 · 총지급액 · 소득세 가운데 하나라도 못 찾으면 멈추고 머리행을 보인다. 그 열 이름을 받아 다시 돌린다. 자가운전보조금 열은 지급명세서 면제 비과세라 총지급액에서 뺀다.
급여대장이 여러 달이면 신고할 귀속 달을 묻는다(`--연월 2026-07`). 귀속과 지급 달이 다르면 `--지급연월` 을 준다.
## 3. 회사기초정보가 없으면
빈 틀(`회사기초정보_작성.xlsx`)을 만들고 멈춘다. 멈출 때 물을 것 여덟 가지를 출력한다. 여덟 가지를 한 메시지로 묻고, 답을 노란 셀에 적어 다시 돌린다. 홈택스 로그인 ID 가 예시 값이면 실제 ID 로 바꿔야 접수된다. 다음 달에는 「지난달과 같습니까」 한 번만 확인한다. 항목 설명은 `references/입력항목.md`.
## 4. 그 달 퇴사자가 있으면
```
python scripts/실행.py 퇴사 <폴더> --사번 E002 --퇴사일 2026-07-31 --월통상임금 3600000
```
- 입사일 · 생년월일은 인사카드에서 읽는다. 없으면 `--입사일` · `--생년월일` 로 받는다.
- **월 통상임금은 사람이 확인한 값을 받는다.** 기본급으로 대신하지 않는다. 퇴사 통보나 인사 기록에 있으면 그 값을 쓰고, 없으면 묻는다.
- 1월(그해 입사자는 입사월)부터 퇴사월까지 급여대장을 csv 셋으로 만들어 중도정산한다. 소득공제 신고서를 내지 않았으면 본인 기본공제와 표준세액공제만 적용한다. 냈으면 `--소득공제신고 <JSON>` 으로 다시 돌린다.
- 결과에서 퇴직금을 평균임금 기준 · 통상임금 기준으로 나란히 보이고, 퇴직소득세 · 중도정산 세액 · 신고 기한 · 되물을 것을 표로 옮긴다. 되물을 것 가운데 자료에 답이 있는 것은 뺀다.
- 퇴직금은 A22 에 적는다(A21 란은 연금계좌취급자가 적는다, 서식 작성방법). 퇴사일 현재 55세 미만이면 IRP 이전이라 소득세 0(소득세법 §146②), 55세 이상이면 현금 수령으로 퇴직소득세를 뗀다. 결과는 `신고_YYYY-MM/추가행_YYYY-MM.json` 에 남고 신고가 함께 읽는다.
## 5. 기타소득(강사료 · 자문료)이 있으면
```
python scripts/실행.py 기타 <폴더> [--목록 기타소득_지급목록.csv]
```
목록 열은 성명 · 종류 · 지급액 · 지급일 · 계속반복 · 비고. 지급일의 달이 신고 달이다. 달이 섞이면 멈춘다. 계속반복이 Y 면 사업소득이라 멈추고, 소득 구분을 다시 정해 달라고 한다. 강연료 · 인적용역 · 자문료는 A59, 나머지는 A42.
## 6. 신고 파일 만들기
```
python scripts/실행.py 신고 <폴더> --연월 2026-07
```
보고에 넣을 것.
1. 소득코드별 인원 · 총지급액 · 소득세 표. 가감계(A10 · A20 · A30 · A40)와 A99 를 함께 보인다.
2. 납부할 소득세, 위택스 지방소득세, 납부 기한(다음 달 10일, 토 · 일이면 다음 영업일).
3. 형식검증 통과 수. **형식검증은 파일 형식만 본다.** 세액과 소득 구분이 맞는지는 보지 않는다고 함께 적는다.
4. 확인사항 가운데 정하지 않은 것(기타소득 필요경비, 전월미환급세액, 중도퇴사 환급 등).
급여대장을 csv 로 만들었으면 급여대장 확인필요(요약의 `급여대장확인`, 국외 근무 건강보험 · 월 중 입퇴사 일할 등)와 대장에서 뺀 사람(`급여대장뺀사람`, 퇴사 · 입사 전 · 그 달 지급 없음)도 함께 보인다.
5. 사람이 할 일. 홈택스 전자파일 변환 · 제출, 위택스 지방소득세 신고, 4대보험 상실 · 취득 신고, 명세서 발송.
종료코드 1 이면 형식검증 실패라 파일을 넘기지 않는다. 2 면 확인할 것이 있어 멈춘 것이다. 표준오류에 나온 문장을 그대로 사용자에게 묻는다.
## 7. 근로계약서 검토
```
python scripts/실행.py 계약서 <근로계약서.docx> --입사일 2026-08-01
```
필수 기재 사항 누락, 위법 조항(위약 예정 · 강제 저금 · 포괄임금 등), 대안 문구, 4대보험 취득 신고 기한이 결과에 나온다. 스킬이 짚지 않은 조항은 고치지 않고 그 사실만 적는다. 수습 감액은 3개월 · 90% 숫자만 보고, 시간급으로 바꿔 최저임금과 견주지 않는다.
## 출력
`<폴더>/신고_YYYY-MM/` 안에 생긴다. 원본 폴더의 파일은 고치지 않는다.
| 파일 | 내용 |
|---|---|
| `급여대장/급여대장_YYYY-MM.xlsx · .json` | csv 셋으로 만든 대장. 과세표준 시트가 소득세 · 국민연금 · 건강보험 · 고용보험 과세표준을 따로 보인다 |
| `추가행_YYYY-MM.json` · `퇴사_<사번>.json` | 퇴사 · 기타소득 결과 |
| `결과/원천징수집계_YYYYMM.xlsx` | 지급내역 · 집계 · 신고서 · 확인사항. 숫자는 수식이다 |
| `결과/신고값_YYYYMM.json` | 전자파일 입력 |
| `결과/전자파일/YYYYMMDDC103900.01` | 홈택스 업로드 파일(cp949 고정길이) |
| `결과/요약.json` · `실행기록.txt` | 보고에 쓸 값과 전체 출력 |
## 근거목록과 최신화
요율 · 간이세액표 · 비과세 한도 · 세율 · 공제액 · 신고 기한 · 소득코드는 `references/근거목록.json` 에 값마다 근거 조문 · 별표, TaxDoctor 원천 스냅샷 id, 시행일, 조문 마지막 개정일, 등급이 적혀 있다. 시험 코드(`tests/`)가 있는 판에서는 `test_근거목록.py` 가 근거목록의 값과 엔진 코드의 값이 같은지 본다.
사용자가 「최신화」 · 「요율 최신화」 · 「법 바뀐 것 있나」 를 말하면 `references/최신화.md` 순서대로 한다.
1. `python scripts/최신화.py 목록` 으로 조회할 조문 · 별표를 받는다.
2. TaxDoctor 로 하나씩 읽는다. 세법 조문은 `get_article`, 별표는 `get_annex`, 비세법 참조 법령(국민연금법 · 근로기준법 등)은 `get_reference_article`, 시행예정은 `list_upcoming` 과 `get_amendments`. TaxDoctor 에 없는 법령(최저임금법 · 시행규칙)은 korean-law 로 읽는다.
3. 조회 결과를 JSON 으로 적고 `python scripts/최신화.py 비교 --조회 <파일> --보고 <md>` 를 돌린다. 변경 0건이어도 보고한다.
4. **값은 자동으로 바꾸지 않는다.** 고칠 후보마다 근거 원문과 바뀔 값을 보이고 확인받는다. 확인받은 뒤 엔진 코드와 근거목록 값을 함께 고치고, 시험 코드가 있으면 `python -m pytest -q tests` 를 돌린다. 판만 바뀌고 값이 그대로면 `최신화.py 반영` 으로 판 기록만 고친다.
국민연금 기준소득월액 상한 · 하한처럼 고시로 정하는 값과 국세청 규격서는 TaxDoctor 와 korean-law 에 없다. 보고에 「사람 확인」 으로 남긴다.
## 노무 질문
계산이 아닌 노무 질문(수습 감액이 되는지, 프리랜서가 근로자인지, 해고 예고 등)은 같은 저장소의 [법령검토](../법령검토/SKILL.md) 스킬로 답한다. 이 스킬은 조문을 해석해 결론을 내지 않는다. 근로자인지처럼 사실을 따져야 하는 결론은 판례 기준과 자료의 사실을 나란히 놓고 사람에게 넘긴다.
## 하지 않는 것
- **월 중 입사 · 퇴사의 일할 계산.** 한 달치로 계산하고 확인사항에 적는다. 사람이 일할 금액을 정해 대장을 고친 뒤 다시 돌린다.
- **퇴직연금(DB · DC) 가입자의 퇴직금, 미사용 연차수당.** 퇴직금제도 기준으로만 계산한다.
- **국외 근무자의 건강보험료 경감 · 면제.** 전액으로 계산하고 확인사항에 적는다.
- **근로자인지 판단.** 3.3% 사업소득자의 근로자성은 사람이 판단한다.
- **부표(C103901)가 필요한 소득(이자 · 배당 · 법인원천), 연말정산 A04 · A05 · A06, 수정 · 기한후 신고의 조정, 반기납부 상세.** 해당하면 멈추고 알린다.
- **지방소득세 파일, 홈택스 · 위택스 제출, 4대보험 신고, 명세서 발송.** 사람이 한다.
## 검증한 범위
- 가상 회사 자료로 단계별 스킬을 따로 돌린 결과와 금액을 대조했고, 전자파일은 바이트 단위로 같았다. 샘플 자료와 시험 코드는 공개 저장소에 싣지 않는다.
- 간이세액표는 소득세법 시행령 별표 2(2026-02-27 개정, 2026-03-01 시행)를 옮긴 것이다. 2026 귀속 중도정산은 2025 귀속 공제 · 세율을 그대로 쓴 값이고, 그 조문들이 2026-07-01 판과 같은지는 근거목록에 적었다.
- 전자파일 규격은 국세청 「원천세이행상황신고서 전산매체제출요령」(2026-05-16)이다. 형식검증 22개는 그 규격의 형식 규칙이고, 홈택스 내용검증과 같지 않다. 집계표의 항목 배치를 별지 서식과 대조한 범위는 `references/서식근거.md` 7절에 있다.
- 결과는 검토용이다. 신고 전 판단은 담당 세무사 · 회계사가 한다.
## 폴더
| 경로 | 내용 |
|---|---|
| `scripts/실행.py` · `입력.py` · `최신화.py` | 진입점, 자료 찾기 · Drive 링크, 근거목록 비교 |
| `모듈/급여대장` | 인사카드 · 급여계약 · 항목규칙 → 급여대장. 과세표준을 제도마다 따로 만든다 |
| `모듈/원천징수이행상황신고서` | 대장 읽기 · 소득코드별 집계 · 집계표 · 확인사항 · 기한 |
| `모듈/원천세전자파일` | C103900 생성기 · 형식검증기 · 회사기초정보 틀 · 규격 JSON |
| `모듈/입퇴사처리` | 계약서 검토 · 퇴직금 · 중도정산 · 기타소득 |
| `모듈/원천세` | 요율 · 간이세액표 · 원천징수 판정 · 퇴직소득세 · 연말정산 엔진 |
| `examples/샘플회사` | 가상 회사 자료. 공개 저장소에는 없다 |
| `references/` | 근거목록 · 최신화 순서 · 서식 근거 · 회사기초정보 항목 |