git:20261102.0dea877 to git:20261102.4a84def

- description: 급여대장 엑셀이나 인사카드 · 급여계약 · 항목규칙 csv 가 든 폴더(또는 Google Drive 폴더 · 파일 링크)를 받아 원천징수이행상황신고서 집계표 · 신고값과 홈택스 전자신고 파일(C103900)을 만들고 형식검증 22개를 통과시킨다. 그 달 퇴사자의 퇴직금 · 퇴직소득세 · 중도퇴사 정산과 강사료 같은 기타소득도 같은 신고에 넣는다. 요율 · 간이세액표 · 비과세 한도 · 세율 · 기한은 근거목록에 조문과 TaxDoctor 스냅샷으로 적혀 있고, 최신화 명령이 판이 바뀌었거나 시행예정 개정이 있는 값을 찾는다. "원천세 신고", "원천징수이행상황신고서", "급여대장으로 원천세", "원천세 전자신고 파일", "C103900", "홈택스 업로드 파일", "퇴직금 계산", "중도퇴사 정산", "강사료 원천징수", "기타소득 원천징수", "근로계약서 검토", "원천세 최신화", "요율 최신화" 가 나오면 쓴다.

- # 원천세신고

-

- 급여 자료가 든 폴더 하나로 그 달 원천세 신고 파일까지 만든다. 계산은 스크립트가 하고, Claude 는 자료를 모으고 사람이 정할 것을 묻고 결과를 표로 보인다.

-

- ```

- 급여대장 엑셀 ─────────────┐

- 인사카드 · 급여계약 · 항목규칙 csv → 급여대장 ─┤

- 퇴사(퇴직금 · 중도정산) · 기타소득 → 추가행 ──┤

- 회사기초정보 엑셀 ──────────┘

- → 원천징수 집계표 · 신고값 → 전자신고 파일 YYYYMMDDC103900.01 → 형식검증 22개

- ```

-

- 모든 명령은 이 스킬 폴더에서 `python scripts/실행.py <명령>` 으로 부른다. 결과는 표로 옮겨 보이고, 금액을 다시 계산하지 않는다.

-

- ## 처음 쓸 때

-

- `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-07`). 귀속과 지급 달이 다르면 `--지급연월` 을 준다.

-

- ## 3. 회사기초정보가 없으면

-

- 빈 틀(`회사기초정보_작성.xlsx`)을 만들고 멈춘다. 멈출 때 물을 것 여덟 가지를 출력한다. 여덟 가지를 한 메시지로 묻고, 답을 노란 셀에 적어 다시 돌린다. 홈택스 로그인 ID 가 예시 값이면 실제 ID 로 바꿔야 접수된다. 다음 달에는 「지난달과 같습니까」 한 번만 확인한다. 항목 설명은 `references/입력항목.md`.

-

- ## 4. 그 달 퇴사자가 있으면

-

- ```

- python scripts/실행.py 퇴사 <폴더> --사번 E002 --퇴사일 2026-07-31 --월통상임금 3600000

- ```

-

- - 입사일 · 생년월일은 인사카드에서 읽는다. 없으면 `--입사일` · `--생년월일` 로 받는다.

- - **월 통상임금은 사람이 확인한 값을 받는다.** 기본급으로 대신하지 않는다. 퇴사 통보나 인사 기록에 있으면 그 값을 쓰고, 없으면 묻는다.

- - 1월부터 퇴사월까지 급여대장을 csv 셋으로 만들어 중도정산한다. 소득공제 신고서를 내지 않았으면 본인 기본공제와 표준세액공제만 적용한다. 냈으면 `--소득공제신고 <JSON>` 으로 다시 돌린다.

- - 결과에서 퇴직금을 평균임금 기준 · 통상임금 기준으로 나란히 보이고, 퇴직소득세 · 중도정산 세액 · 신고 기한 · 되물을 것을 표로 옮긴다. 되물을 것 가운데 자료에 답이 있는 것은 뺀다.

- - 퇴사일 현재 55세 미만이면 IRP 이전(A21), 55세 이상이면 현금 수령(A22)으로 적는다. 결과는 `신고_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. 확인사항 가운데 정하지 않은 것(기타소득 필요경비, 전월미환급세액, 중도퇴사 환급 등).

- 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대보험 신고, 명세서 발송.** 사람이 한다.

-

- ## 검증한 범위

-

- - 샘플회사(가상) 2026년 7월(상용 5 · 사업 1 · 퇴사 1 · 강연료 1)은 단계별 스킬로 따로 돌린 결과와 금액이 같고, 전자파일은 바이트 단위로 같다. 시험은 `python -m pytest -q tests`.

- - 간이세액표는 소득세법 시행령 별표 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/` | 근거목록 · 최신화 순서 · 서식 근거 · 회사기초정보 항목 |