공식 수록형식 문서를 AI에게 먹여 만든 '종합소득세 신고도우미' — 구축 방법론

공식 수록형식 문서를 AI에게 먹여 만든 '종합소득세 신고도우미' — 구축 방법론

📝 한줄 요약

세무 실무자가 국세청 공식 변환파일 수록형식 문서와 신고 매뉴얼, 그리고 전자신고데이터를 확인하여 입력값을 받아 홈택스에 올릴 전자신고 변환파일을 만들어주는 데스크탑 앱(.exe)을 구축했다.

바쁘시면 이것만 읽어도 돼요:

• 무엇을: 종합소득세 전자신고용 변환파일(고정길이 레코드)을 생성하는 마법사형 데스크탑 앱.

• 어떻게 시작: "코드 짜줘"가 아니라 공식 수록형식 문서 + 신고 매뉴얼을 먼저 AI에게 읽혔다. 스펙이 근거다.

• 핵심 방법론: ① 공식 문서로 스펙을 고정 → ② 마법사 골격 먼저 → ③ 신고 방식별 분기 → ④ 더미를 실제 스펙으로 교체 → ⑤ 실측으로 검증.

• 제일 큰 함정: AI가 처음엔 변환파일을 TODO 더미로 채워놨다. 겉보기엔 되는데 실제 홈택스 규격이 아니었다. 이걸 잡는 게 진짜 일이었다.

• 결과: 신고 방식 선택 → 단계별 입력 → 홈택스 업로드용 변환파일 출력까지 도는 실행파일.

🎯 이런 분들께 도움돼요

• 정형 양식(전자신고·전자세금계산서·각종 변환파일)을 반복 작성하는 실무자

• "공식 스펙 문서는 있는데 프로그램이 없어서" 수작업하는 분

• 비개발자인데 공식 문서 기반으로 정확한 도구를 만들고 싶은 분

• AI로 만든 결과물이 "되는 것처럼 보이는데 실제론 틀린" 경험을 한 분

😫 문제 상황 (Before)

종합소득세 전자신고를 하려면 정해진 변환파일 형식에 맞춰 데이터를 만들어야 한다. 이건 사람이 읽는 표가 아니라, 자리마다 길이가 정해진 고정길이 레코드 — 한 글자만 어긋나도 홈택스가 안 받는 까다로운 규격이다.

문제는:

• 신고 방식(복식부기·간편장부·기준경비율·금융소득)마다 필요한 입력이 다르다.

• 한 번 틀리면 어디서 틀렸는지 찾기도 어렵다.

그래서 원한 건 — 공식 스펙 그대로, 입력만 하면 변환파일을 정확히 뱉어주는 도구. 단, 내 컴퓨터에서 도는 데스크탑 앱으로(민감한 세무 데이터를 웹에 안 올리려고).

🛠️ 사용한 도구

• AI 코딩 파트너(Hermes 기반): 회사 노트북(윈도우)에서 SSH로 연결해 함께 작업

• Electron: 데스크탑 앱 프레임워크 (웹 기술로 만들되 .exe로 실행)

• 입력 자료: 국세청 공식 변환파일 수록형식 문서(docx) + 신고 방식별 매뉴얼(PDF) + 시중 erp 업체의 자동생성 파일의 분석 한 자료

• 🔒 로컬 전용(hermes desktop llm nemotron ultra free 사용): 세무 데이터는 외부로 안 나가고 내 컴퓨터에서만 처리.

🔧 구축 방법론 (핵심)

이 프로젝트의 진짜 가치는 결과물보다 순서였다. "AI야 종소세 프로그램 짜줘"로 시작했으면 그럴듯한 가짜가 나왔을 거다. 다섯 단계로 갔다.

1단계 — "코드 먼저"가 아니라 "공식 문서 먼저"

전자매체개발 작성 관련 공식문서 3개 파일을 읽고 만들 수 있을까?"였다. 코드를 바로 요청하지 않고, 국세청 공식 수록형식 문서와 매뉴얼을 AI에게 먼저 읽혔다. 그 후 시중 erp의 종합소득세 파일을 ai agent에게 분석 시킨후 구조파악

이유는 분명하다 — 변환파일은 자리 하나까지 공식 스펙이 정답이다. AI가 상상으로 채우면 안 되고, 문서가 근거여야 한다. 그래서 "스펙의 출처"부터 깔고 시작했다.

2단계 — 마법사(Wizard) 골격을 먼저 세우기

전체를 한 번에 만들지 않고, 단계별로 입력받는 마법사 화면 골격부터 세웠다. Step 1, Step 2… 순서대로 진행하는 틀. 내용물(실제 스펙)은 비워두고 흐름부터 잡은 것이다.

이게 중요한 이유 — 골격이 있어야 "어느 단계에서 뭐가 필요한지"가 보이고, 거기에 스펙을 하나씩 끼워 넣을 수 있다. 빈 그릇을 먼저 만들고 채우는 순서.

3단계 — 신고 방식별로 분기시키기

세무의 핵심을 반영했다. Step 1을 "신고 방식 선택"으로 두고 — 복식부기 / 간편장부 / 기준경비율 / 금융소득 — 고른 방식에 따라 그 다음 입력 단계가 달라지게 했다.

이건 매뉴얼이 4개로 나뉜 이유 그대로다. 신고 방식이 다르면 필요한 데이터가 다르니, 프로그램도 그 분기를 따라가야 정확하다. "하나의 만능 폼"이 아니라 "방식별 맞춤 흐름".

4단계 — 가장 중요한 함정: 더미를 실제 스펙으로 교체

여기가 진짜였다. 중간 점검에서 발견한 것 — AI가 변환파일 생성 부분을 TODO 더미로 채워놨었다. 겉으로는 파일이 만들어지고 앱이 도니까 "되는 것처럼" 보였는데, 실제 내용은 홈택스 규격이 아니라 임시 가짜 레코드 한 줄이었다.

이게 AI 코딩의 가장 위험한 함정이다 — "실행은 되는데 결과가 틀린" 상태. 그래서:

• 공식 문서에서 실제 고정길이 레코드 포맷을 다시 추출하고

• 더미 생성 로직을 실제 스펙대로 다시 짜고

• 자리수·항목·순서를 문서와 대조했다.

겉보기 동작에 속지 않고 결과물의 실제 내용을 공식 스펙과 대조하는 것 — 이게 핵심 검증이었다.

5단계 — 실측으로 검증 (인코딩·확장자·저장)

마지막은 실제로 돌려보며 자잘한 것들을 잡았다:

• 저장 파일 확장자/형식 — "홈택스에 올릴 파일이 txt로 읽을수 있냐?"를 의심하고 규격을 재확인.

• 한글 인코딩(CP949) — 윈도우 경로·파일에 한글이 들어가면 깨지는 문제.

• UI 동작 — 탐색기 창이 안 뜨거나, 완료 버튼·주소 검색이 안 눌리는 것들을 스크린샷을 주고받으며 하나씩 수정.

"되겠지"가 아니라 실제 화면을 캡처해 보여주며 고쳤다. 비개발자라도 "여기 안 눌려요"를 스크린샷으로 전달하면, AI가 그 지점을 짚어 고치는 식으로 협업했다.

6단계 완성리뷰

ALT

한국사이트 스크린샷

ALT

한국어가 포함된 한국 웹사이트 스크린샷

ALT

구글애널리틱스 대시보드 스크린샷

ALT

한국사이트 스크린샷

✅ 결과 (After)

Before vs After

결과물

• 종합소득세 전자신고 변환파일 생성 데스크탑 앱 (종합소득세_신고도우미.exe)

• 신고 방식 선택 → 단계별 입력 마법사 → 홈택스 업로드용 변환파일 출력

• 공식 수록형식 문서 기반 고정길이 레코드 생성 로직

💬 이 과정에서 배운 AI 활용 팁

효과적이었던 것

1. 공식 문서를 먼저 먹인다: "짜줘"가 아니라 "이 스펙 문서 읽고 만들 수 있나?"로 시작하면, AI가 상상이 아니라 근거로 만든다. 정형 양식일수록 필수.

2. 골격 먼저, 내용 나중: 마법사 흐름을 먼저 세우고 스펙을 끼워 넣으니 구조가 안 무너졌다.

3. 스크린샷으로 협업: 비개발자도 "여기 안 돼요"를 화면으로 보여주면 AI가 정확히 짚는다. 말로 설명하기 어려운 UI 버그에 특히 강력.

이렇게 하면 안 돼요

1. "실행되면 된 거"라고 믿기: 가장 위험한 함정. AI가 핵심 로직을 TODO 더미로 채워도 앱은 돈다. 결과물 내용을 공식 스펙과 반드시 대조해야 한다.

2. 인코딩 무시: 한글 환경(CP949)은 경로·파일명에서 깨진다. 처음부터 고려.

3. 한 번에 다 만들기: 신고 방식이 여러 개면 분기부터. 만능 폼은 결국 다 틀린다.

🌍 다른 업무에 적용한다면?

• 전자세금계산서·4대보험·각종 신고 변환파일: 공식 수록형식이 있는 모든 정형 양식에 같은 방법론이 그대로 맞는다.

• 사내 양식 자동화: 정해진 포맷으로 데이터를 뱉어야 하는 모든 반복 업무.

• 공공 API/제출 규격: "스펙 문서 먼저 먹이기"는 규격이 엄격한 모든 연동에 통한다.