property — 부동산 세금 AI 상담 프로그램

부동산 세금(증여세·양도세·취득세·재산세·종합부동산세)을 계산하고, AI가 그 계산을 검증한 뒤, 고객용 요약 문서까지 만들어 주는 프로그램입니다.

프로그램 목적 (전체 그림)

이 프로그램은 3단계 파이프라인으로 동작하는 것을 목표로 합니다.

[1단계]                [2단계]                    [3단계]
계산기 로직     →      AI 검증                →   요약 문서 생성
(코드로 세금 계산)     (계산 과정·결과를           (검증된 결과를 바탕으로
                       최신 세법 기준으로 검증)     고객용 요약 보고서 작성)

1단계 — 계산기 로직 (구현 완료)

코드로 작성된 세금 계산 엔진이 먼저 계산을 수행합니다. AI가 아닌 결정적(deterministic) 로직이므로 같은 입력에는 항상 같은 결과가 나옵니다.

2단계 — AI 검증 (구현 완료)

계산기가 어떻게 계산했는지(적용 세율, 공제, 중과 여부, 근거 법령)를 Claude AI가 받아서:

• 계산 과정이 올바른지 검증
• 최신 개정 세법이 제대로 반영되었는지 웹검색으로 확인 (현재 엔진은 2026.5.10 시행분 기준)
• 오류나 누락이 있으면 지적하고 pass / warning / fail 판정을 반환

3단계 — 요약 문서 생성 (구현 완료)

검증까지 끝난 결과를 바탕으로 AI가 고객 전달용 요약 보고서(마크다운)를 자동 생성합니다. 케이스별 세부담 비교표, 세목별 계산 내역, 보유세 변화, 유리한 선택지, 유의사항, 근거 세법을 담습니다. API 키가 없을 때를 위한 템플릿 기반 폴백 보고서(buildBasicReport)도 제공합니다.

심화 검토 보조 장치 (구현 완료)

계산·검증·보고서(3단계)가 "정해진 케이스를 정확히" 다룬다면, 그 바깥의 다양한 상황·문제점·추가 아이디어를 다루기 위한 4가지 보조 장치를 얹었습니다.

1. 절세 대안 생성기 (src/advisor/alternatives.js) — AI가 고정 케이스 밖의 절세 대안을 제안하고, 입력값 조정으로 표현 가능한 대안은 실제 계산 엔진에 통과시켜 검증된 세액을 붙입니다(AI가 지어낸 숫자가 아님). 현재 시나리오로 표현할 수 없는 대안(예: 증여vs양도 케이스의 부담부증여)은 altScenarioId로 다른 시나리오에 매핑해 그 엔진으로 재계산합니다.
2. 리스크·함정 스캐너 (src/advisor/risk-scan.js) — 과세관청 시각에서 이월과세·부당행위계산부인·저가양도·자금출처·취득세 중과 함정 등 거래 구조의 세무 리스크를 위험도·근거법령·확인사항 체크리스트로 뽑습니다.
3. 민감도·손익분기 분석 (src/analysis/sensitivity.js) — 핵심 변수(대출 승계액·취득가액·보유기간 등)를 범위로 스윕해 유불리가 뒤바뀌는 손익분기점을 찾습니다. 순수 엔진 계산이라 AI·네트워크가 필요 없습니다.
4. 세법 개정 감시 (src/monitor/law-watch.js) — 엔진이 박아둔 세법 가정(공정시장가액비율·공제금액·중과 부활일·일시적 2주택 처분기한 등 상수 9종)과 동향 4종(대법원 판결·조세심판원 결정 / 국세청 예규·질의응답 / 기획재정부 유권해석 / 정부안·규제지역)을 웹검색으로 대조해 바뀐 항목과 고쳐야 할 상수 위치를 경고하고, 직전 한 달에 나온 예규·판결·회신을 **세법 동향 일지 등록 후보(JS 블록)**로 리포트에 붙입니다. 케이스와 무관하므로 scripts/law-watch.js로 단독 실행하며, law-watch GitHub Actions 워크플로가 매월 1일 09:00 KST에 자동 실행되어 개정·신규 예규가 발견되면 잡이 실패(빨간불)하고 law-watch 라벨 이슈가 자동 생성됩니다.

네 장치는 adviseCase()로 한 번에 실행해 하나의 심화 리포트로 합칠 수 있습니다(src/advisor/index.js).

참고자료 데이터

• data/nts-housing-tax-2026/ — 국세청 「2026 주택과 세금」 전체 텍스트(OCR)·목차 색인·조정대상지역 정리본. 페이지 이미지는 data/ebook-nts-housing-tax-2026 브랜치

현재 구현 상태

단계	상태	위치
1단계 계산기 로직	✅ 구현 완료	tax-ai-consulting/src/core, src/scenario
2단계 AI 검증	✅ 구현 완료 (Claude API + 웹검색)	tax-ai-consulting/src/verify
3단계 요약 문서 생성	✅ 구현 완료 (AI 생성 + 템플릿 폴백)	tax-ai-consulting/src/report
전체 파이프라인 / CLI	✅ 구현 완료	tax-ai-consulting/src/pipeline.js, src/cli.js
심화 검토 장치 (대안·리스크·민감도·개정감시)	✅ 구현 완료	tax-ai-consulting/src/advisor, src/analysis, src/monitor
웹 입력폼 + 보고서 (Word·PDF 내보내기)	✅ 구현 완료	tax-ai-consulting/src/web
상속세 계산기 (간주·추정재산, 일괄·배우자·금융·동거주택 공제, 공제한도, 세대생략 할증, 증여세액공제, 상속인별 안분)	✅ 구현 완료	tax-ai-consulting/src/core/inheritance-tax.js, src/web/static/inherit-tax.html
세무 판정기 (양도세·취득세 중과, 1세대1주택·재건축·혼인 비과세, 지방주택 1세대1주택)	✅ 구현 완료	tax-ai-consulting/src/core/heavy-tax-judge.js, single-house-exempt.js, redev-exempt.js, marriage-exempt.js, local-house-judge.js

테스트 381개 (모든 AI 단계는 mock으로 네트워크 없이 검증).

저장소 구조

property/
└── tax-ai-consulting/
    ├── src/
    │   ├── core/               # 1단계: 세금 계산 엔진 (2026.5.10 시행 기준)
    │   │   ├── gift-tax.js           # 증여세 (calcGiveTax)
    │   │   ├── inheritance-tax.js    # 상속세 (calcInheritanceTax — 공제·할증·세액공제·상속인별 안분)
    │   │   ├── acquisition-tax.js    # 취득세 (calcTakingTax, calcGiveTakingEtcTax)
    │   │   ├── transfer-tax.js       # 양도세 (calcSaleIncomeTax)
    │   │   ├── property-tax.js       # 재산세 (calcPropertyTax)
    │   │   ├── comprehensive-tax.js  # 종합부동산세 (calcAggrTax)
    │   │   └── constants.js          # 세율·공제 상수
    │   ├── scenario/           # 1단계: 상담 시나리오 10종 (runScenario1 ~ runScenario10)
    │   ├── ai/client.js        # Claude API 클라이언트 래퍼 (pause_turn 재개, refusal 처리)
    │   ├── verify/             # 2단계: AI 검증 (verifyCalculation — 웹검색으로 최신 세법 확인)
    │   ├── report/             # 3단계: 요약 보고서 (generateReport / buildBasicReport)
    │   ├── analysis/           # 장치3: 민감도·손익분기 분석 (sweep — 순수 엔진)
    │   ├── advisor/            # 장치1·2 + 통합: 절세 대안 생성 / 리스크 스캐너 / adviseCase
    │   ├── monitor/            # 장치4: 세법 개정 감시 (checkLawChanges — 웹검색)
    │   ├── web/                # 웹 입력폼 + 보고서 서버 (Word·PDF·인쇄 내보내기)
    │   ├── pipeline.js         # 계산 → 검증 → 보고서 전체 파이프라인 (runPipeline)
    │   └── cli.js              # 커맨드라인 실행기
    ├── scripts/                # run-cases.js (튜닝), advise.js (심화 검토)
    └── tests/                  # vitest 테스트 (core / scenario / verify / report / analysis / advisor / monitor)

시나리오 목록

#	대상	비교 내용
1	2주택자	자녀에게 증여 vs 타인에게 양도
2	2주택자	자녀에게 일반증여 vs 부담부증여
3	2주택자	자녀 1명에게 증여 vs 여러 명에게 분산증여
4	2주택자	자녀 1명 부담부증여 vs 여러 명 부담부증여
5	2주택자	배우자에게 일반증여 vs 부담부증여
6	1주택자	일부 지분 배우자 일반증여 vs 부담부증여
7	공동명의 1주택자	배우자 단독명의로 전환
8	2주택자	배우자에게 증여 vs 타인에게 양도
9	2주택자	배우자에게만 증여 vs 배우자+자녀 분산증여
10	2주택자	배우자에게만 부담부증여 vs 여러 명에게 부담부증여

실행 방법

cd tax-ai-consulting
npm install
npm test          # vitest 테스트 실행 (네트워크·API 키 불필요)

전체 파이프라인 실행 (CLI)

# AI 검증·보고서까지 실행 — ANTHROPIC_API_KEY 환경변수 필요
export ANTHROPIC_API_KEY=sk-ant-...
node src/cli.js 1                          # 시나리오 1을 샘플 입력으로 실행
node src/cli.js 1 inputs.json --out 보고서.md   # 입력 파일 지정, 보고서 파일로 저장

# AI 없이 계산 + 템플릿 보고서만 (API 키 불필요)
node src/cli.js 1 --no-ai

코드에서 사용

import { runPipeline } from './src/pipeline.js';

const { calculation, verification, report } = await runPipeline(1, inputs);
// calculation : 1단계 계산 결과 (세액, lawRef 등)
// verification: 2단계 AI 검증 { verdict, summary, issues, lawChanges, reportText }
// report      : 3단계 고객용 요약 보고서 (마크다운)

AI 단계는 claude-opus-4-8 모델과 웹검색 도구(web_search)를 사용해 계산 엔진 기준일(2026.5.10) 이후의 세법 개정 여부까지 확인합니다.

웹 입력폼 + 보고서 (Word·PDF)

cd tax-ai-consulting
npm run web            # http://localhost:3000 (PORT 환경변수로 변경)

브라우저에서 시나리오를 고르고 입력값을 넣으면 보고서가 즉시 생성됩니다 (AI·API 키 불필요 — 계산 엔진만 사용, 동일 입력 = 동일 결과).

• 금액 입력 시 콤마와 억/만 단위 힌트가 자동 표시됩니다.
• Word 저장: 실제 .docx 파일 다운로드 (MS 워드에서 편집 가능)
• PDF 저장: 서버의 Chromium/Chrome으로 A4 PDF 생성. Chrome이 없는 환경이면 안내 메시지가 뜨며, 그 경우 인쇄 버튼 → 브라우저 인쇄에서 "PDF로 저장"을 쓰면 됩니다. (CHROMIUM_PATH 환경변수로 Chrome 실행 파일 경로 지정 가능)
• 보고서 구성: 입력값 요약 → 케이스별 세부담 비교표 → 세금 계산 내역(엔진 산출 단계별) → 보유세 변화·계산 내역 → 결론 → 근거 법령

AI 버튼 (정밀 보고서 · 심화 검토)

서버 실행 전 API 키를 설정하면 웹 화면의 AI 버튼이 활성화됩니다:

ANTHROPIC_API_KEY=sk-ant-... npm run web

• AI 정밀 보고서: 계산 → AI가 최신 세법을 웹검색하며 검증 → 검증 판정 배지(✅/⚠️/❌)가 붙은 고객용 정밀 보고서 생성 (약 3~6분)
• 심화 검토 (리스크·대안): 민감도·손익분기 분석 + AI 세무 리스크 체크리스트 + 절세 대안(엔진 재계산 검증 포함) 리포트 생성 (약 2~4분)
• 작업은 백그라운드로 실행되며 화면에 진행 단계와 경과 시간이 표시됩니다. 완료된 AI 문서도 동일하게 Word/PDF 저장·인쇄가 가능합니다 (파일명: AI정밀보고서-…, 심화검토-…).
• 키가 없으면 버튼을 눌렀을 때 설정 방법을 안내합니다. 일반 [보고서 생성]은 키 없이 항상 동작합니다.

심화 검토 실행 (대안·리스크·민감도·개정감시)

cd tax-ai-consulting

# 민감도·손익분기 분석만 — API 키 불필요
npm run advise:dry -- --case 01

# 4가지 장치 전부 (대안·리스크는 AI) — ANTHROPIC_API_KEY 필요
export ANTHROPIC_API_KEY=sk-ant-...
node scripts/advise.js --case 01                 # 케이스 01 심화 리포트
node scripts/advise.js --case 01 --law-watch     # 세법 개정 감시까지 포함(느림)
node scripts/advise.js --scenario 2 inputs.json --out advisory.md

결과는 advisory-results/<사례명>.md로 저장됩니다. 코드에서는 adviseCase(scenarioId, inputs, { ai, lawWatch }) → renderAdvisory(result)로 사용합니다. GitHub Actions에서는 advisory-deep-dive 워크플로(수동 실행)로 돌릴 수 있습니다.

# 세법 개정 감시 단독 실행 (권장 — 케이스 검토와 분리, 웹검색 10회 확보)
npm run law-watch                     # law-watch-results/law-watch-<날짜>.md 저장
node scripts/law-watch.js --strict    # 조치 필요 항목 발견 시 종료코드 1 (CI 알림용)
node scripts/law-watch.js --days 62   # 동향 감시 기간 변경 (기본 31일 = 직전 한 달)

정기 감시는 law-watch 워크플로가 매월 1일 09:00 KST에 자동 실행합니다(월 1회로 API 비용 절감). 개정·시행예정 항목이나 신규 예규·판결이 발견되면 잡이 실패해 GitHub 알림이 가고, law-watch 라벨 이슈가 자동 생성되며, 리포트에 고쳐야 할 상수 위치(constants.*)가 표시됩니다. 리포트 끝의 「세법 동향 일지 등록 후보」에는 국세청 예규·질의응답, 기획재정부 유권해석, 판결·심판 결정이 law-updates-data.js에 바로 붙여 넣을 수 있는 JS 블록으로 정리되므로, 검토 후 engineStatus·engineNote만 채워 세법 동향 일지(src/web/static/law-updates-data.js)에 추가합니다.

매일 자동 점검 (daily-check)

daily-check 워크플로가 매일 06:00 KST에 API 키 없이 3단계를 점검합니다: ① 계산 엔진 회귀 테스트(vitest 381개) → ② 정적 사이트 빌드 → ③ 화면 스모크 테스트(scripts/smoke-test.js — 15개 페이지 로드·JS 에러 0건, 계산기/판정기 버튼 클릭 후 결과 표시 확인, 메인 화면 세목 클릭 시 하위 메뉴 화면 전환 확인). 실패 시 daily-check 라벨 이슈가 자동 생성됩니다. 로컬 실행: npm run smoke.

프롬프트 튜닝 (사례 일괄 실행)

tax-ai-consulting/cases/에 실제 상담 사례 10건(시나리오 1~10 전부)이 준비되어 있습니다. API 키를 설정한 뒤 일괄 실행하면 사례별 검증 판정과 보고서가 tuning-results/에 저장됩니다.

cd tax-ai-consulting
export ANTHROPIC_API_KEY=sk-ant-...
npm run cases          # 사례 10건 전체를 계산→검증→보고서로 실행
npm run cases:dry      # AI 없이 계산만 (키 불필요, 입력값 점검용)
node scripts/run-cases.js --case 01   # 특정 사례만 실행

튜닝 절차: ① npm run cases 실행 → ② tuning-results/*/verdict.json과 verification.md에서 이상한 판정(과잉 warning, 놓친 오류 등) 확인 → ③ src/verify/index.js의 VERIFY_SYSTEM / src/report/index.js의 REPORT_SYSTEM 지시문 수정 → ④ 다시 실행해 비교. 사례 추가는 cases/에 JSON 파일(scenarioId, title, description, inputs)을 넣으면 됩니다.

프롬프트 튜닝 이력

사례 10건(시나리오 110 전부) 기반 튜닝 3라운드 완료 (2026.7). 최종 상태: 10건 전부 pass, 사례당 실행 25분.

• 1라운드: 검증 AI가 부담부증여 취득세 유상·무상 미분리 버그 발견 → calcBurdenedGiveTakingTax 추가로 수정. AI 호출 스트리밍 전환(타임아웃 해소), effort medium·웹검색 3회로 속도 개선, 판정 기준 프롬프트 명문화.
• 2라운드: 조정지역 다주택 중과 시 장기보유특별공제 미배제 버그(양도세 1.2억 과소), 공동명의 재산세 지분별 누진 계산 오류 발견 → 수정 후 재검증 pass 확인.
• 3라운드: 미검증 시나리오(3·4·6·8·10)에 사례 5건 추가해 전 시나리오 검증. 실제 버그 3건 발견·수정 → ① 부담부증여 다주택 양도세 중과 누락(시나리오 2·4·5·10, 조정지역 양도세 약 1억 과소) — calcSaleIncomeTax에 ownCount·isAdj 전달로 수정. ② 부담부증여 무상분 증여취득세 12% 중과 판정 오류(분산 부담부증여에서 무상분<3억이면 잘못 3.5% 적용) — 중과 판정을 취득 주택가액(heavyBase) 기준으로 수정. ③ 중과 적용 시 양도세 breakdown 누진공제(finalDc) 표시 오류(최종세액은 정확) 정정. 각 버그마다 회귀 테스트 추가 후 재검증 pass 확인.

앞으로 할 일 (로드맵)

1. 사례 추가 확충(조정지역·고가·상속 연계 등)으로 검증 커버리지 확대
2. 다주택 중과 경과규정(5/9까지 계약 체결 시 잔금 유예) 로직 반영 검토

온라인 세무 도구 (GitHub Pages)

정적 멀티페이지 사이트가 GitHub Pages에 자동 배포됩니다: https://daehantax.github.io/property/

세목·기능별 페이지로 구성된 도구 허브이며, 상단 내비게이션으로 이동합니다. 앞으로 판정기 등을 페이지로 계속 추가합니다.

모든 페이지의 상단 메뉴는 nav.js 하나가 그린다(세목별 2단 구성: 양도 · 상속 · 증여 · 취득 · 보유 · 상담 시나리오 · 세법 동향 → 그룹 안의 도구). 도구를 추가하면 nav.js의 GROUPS에 한 줄만 넣으면 메뉴와 index.html 하단 「세목별 도구 모음」이 함께 갱신된다. 메인 계산기 탭은 index.html#gift 처럼 해시로 바로 열 수 있다.

페이지	파일	내용
세금 계산기 (메인)	index.html + calculators.js	증여세·양도소득세·재산세·종합부동산세 세목별 단독 계산기 (탭 전환, 계산 내역·근거 법령 표시). 양도소득세 탭은 1세대1주택 선택 시 보유 2년 + 취득 당시 조정대상지역이면 거주 2년 요건을 체크리스트로 확인하고, 미충족이면 비과세를 배제한 세액과 충족 시 세액을 함께 표시 (judgeExemptRequirementByYears)
상담 시나리오	scenarios.html + scenarios.js	2주택 증여 vs 양도 등 시나리오 10종 비교 보고서
양도세 중과 판정기	transfer-heavy.html + transfer-heavy.js	1세대 주택수 산정 → 2주택(+20%p)·3주택 이상(+30%p) 중과·장특공 배제 판정 (heavy-tax-judge.js)
취득세 중과 판정기	acq-heavy.html + acq-heavy.js	취득 후 주택수 × 조정지역 → 8%·12% 중과 판정 (세율 매트릭스 강조)
1세대1주택 비과세 판정기	single-exempt.html + single-exempt.js	보유·거주요건(2017.8.3 조정지역), 상생임대 면제, 고가주택 12억, 일시적 2주택 판정 (single-house-exempt.js, 재건축 제외)
재건축·재개발 비과세 판정기	redev-exempt.html + redev-exempt.js	조합원입주권 양도 비과세(§89①4 가/나목)·대체주택 특례(§156의2⑤) 판정, 고가주택 12억 반영 (redev-exempt.js)
혼인 비과세 판정기	marriage-exempt.html + marriage-exempt.js	혼인 시 주택·입주권·분양권 특례(§156의2⑨ 제14호, 10년 기한 2024.11.12/종전 5년)·혼인 2주택(§155⑤) 판정, §154① 보유·거주요건·고가 12억 반영 (marriage-exempt.js)
세법 동향	law-updates.html + law-updates.js + law-updates-data.js	계산 로직에 영향 주는 개정·시행령·정부 발표·판결·예규를 일자별 타임라인으로 기록 — 영향 계산기 태그·엔진 반영 상태 표시, 국세청 예규·질의응답·기획재정부 유권해석·조세심판원 공식 출처 바로가기, 자동 점검(daily-check·law-watch) 상태 배지
지방주택 1세대1주택 판정기	local-house.html + local-house.js	수도권 주택 1채 + 지방주택 1채 보유 세대의 소득세법·종부세법 1세대1주택 판정 (local-house-judge.js). 양도세: 일시적 2주택·상속·농어촌(§155①②⑦⑧), 조특법 농어촌·고향주택(§99의4, ~2028.12.31)·세컨드홈(§71의2, 인구감소지역 9억·관심지역 4억)·준공 후 미분양(§98의9) 7경로 + §154① + 중과 주택수 제외(3억) 표시. 종부세: §8④ 일시적 2주택·상속·지방 저가주택(4억·인구감소지역 9억) + 조특법 특례 → 12억 공제·1주택분 세액공제 적용 전후 세액 비교. 시·군·구 검색으로 인구감소지역 89곳·관심지역 18곳·접경지역 15곳·광역시 군 여부 자동 판별 ()

• 계산 엔진이 브라우저 안에서 직접 실행되므로 입력값이 서버로 전송되지 않습니다.
• 페이지 추가 방법: src/web/static/에 이름.html + 이름.js를 만들고 scripts/build-static.js의 PAGES 배열에 등록하면 됩니다.
• 로컬 서버(npm run web)는 같은 사이트를 서빙하며, 상담 시나리오 페이지는 AI 정밀 보고서·심화 검토 버튼이 포함된 강화판으로 제공됩니다(정적 사이트는 클라이언트 계산 전용).
• main 브랜치에 push 될 때마다 deploy-pages 워크플로가 자동으로 재배포합니다.