ipzitalk-recent-market-trend

name	ipzitalk-recent-market-trend
description	시군구 여러 곳의 매매 거래량·중위 평당가·중위 거래가를 전월 대비로 비교해 지역 시장동향을 만든다. "최근 시장동향", "요즘 시장 어때", "거래 늘었어?", "어느 구가 오르나", "지역별 비교" 등의 표현이 있으면 이 스킬을 사용한다. 시군구 집계는 전용타입을 통일할 수 없어 구성 편향이 있으므로 "참고 신호"로만 제시한다.
version	1.2.7
license	proprietary

최근 시장동향

tier: L2

시군구 N곳의 확정월 vs 전월 매매 지표를 비교한다. ※ 구성 미보정 참고 신호다. 전용타입·단지 구성 변화가 중위값에 그대로 반영된다. 시세 감정이 아니다.

입력

파라미터	필수	기본	설명
regions	✅	-	지역명 또는 region_code 배열. 최대 5곳
year_month	✕	최신 확정월	기준월. 최근 2개월은 신고 지연으로 자동 제외

⚠️ 시군구 × 2개월 = 2크레딧. 5곳이면 10크레딧. 데모·기본값은 3곳 권장.

필수 도구

도구	용도
get_region_code	지역명 → sigungu_code 5자리
get_complex_trades	region_code + year_month + trade_type='sale' + limit=1

💡 limit=1로 부른다. summary는 전체 필터 결과 기준으로 계산되므로 items를 안 받아도 거래량·중위값이 정확하다. 응답 크기를 100배 줄인다.

워크플로우

1. 기준월 결정 — 오늘 기준 최근 1~2개월은 신고 등록 지연으로 제외하고 최신 확정월을 기준월로 쓴다. 2026-07이면 기준월 2026.05, 비교월 2026.04.
2. 지역 해소 — 지역명이면 get_region_code로 sigungu_code 확보.
3. 월별 조회 — 각 시군구 × (기준월, 비교월) get_complex_trades(..., limit=1).
4. 커버리지 확인 — 각 응답의 metadata.coverage.complete, missing_months, provisional_months, reason_code를 먼저 확인한다. 미확인·잠정 월을 거래 0건으로 바꾸지 않는다.
5. 변동률 계산 — 기준월과 비교월이 모두 완전 확인된 지역만 거래량·중위 평당가·중위 거래가의 전월 대비 %를 계산한다.
6. 모순 검출 — 중위 평당가와 중위 거래가가 반대 방향이면 구성 변화 경고를 강제 표기(아래 gotcha).
7. 렌더 — 시군구 카드 + 거래량 막대 + 상세 표 + 최근월 제외 설명.

등급·색 규칙

• 상승 --up(빨강) / 하락 --down(파랑) — 국내 관행. ±1% 미만은 flat(회색)로 중립 표기.
• 등급(★)을 매기지 않는다. 지역 우열 단정 금지. 변동률과 표본만 제시한다.

🚨 Gotcha (데모로 실증)

• 중위 평당가와 중위 거래가가 반대로 움직일 수 있다. 평당가가 내리는데 거래가가 오르면 시장이 아니라 거래 구성(소형·저가 단지 비중 증가)이 바뀐 것이다. 이때는 반드시 경고를 붙인다.
• 시군구 단위는 전용타입을 통일할 수 없다. 목록 상한(100건)보다 한 달 매매가 훨씬 많은 시군구가 있어 단지·타입 분해는 원리적으로 불가능하다. 타입 고정 흐름이 필요하면 실거래 추이 분석(단지 단위) 스킬로 넘긴다.
• 최근 1~2개월은 신고 등록 지연으로 과소 집계된다. 신고는 계약 후 30일 이내이고 적재에도 시차가 있다. 최근월을 쓰면 "거래 절벽"이라는 허위 신호가 만들어진다.
• 응답 metadata.truncated는 items 상한 때문에 항상 true다. summary는 영향받지 않는다 — 이 구분을 리포트에 명시한다(화면에는 "중위값·거래량은 전체 거래 기준"으로만).

출력 포맷

• 채팅(먼저): 시군구별 거래량·평당가 변동률 한 줄 요약 + 모순 지역 경고.
• HTML 리포트: 시군구 카드 3~5개 → 거래량 전월 대비 막대 → 상세 표 → 최근월 제외 설명 → 출처·hedge 푸터.
• 상세 표는 첫 열 지역만 왼쪽 정렬하고, 거래량·변동률·중위값 열은 헤더와 값을 모두 오른쪽 정렬한다. 첫 열 이후 행 셀은 {n:"표시값"} 형식을 사용한다.

구성 변화 신호를 화면에 세 번 반복하지 않는다

평당가와 거래가가 반대 방향이면 거래 구성(면적·단지 비중) 변화일 수 있다. 이 사실은 두 곳에만 낸다.

위치	내용
KPI 카드 칩	구성 변화 가능성 (템플릿이 자동 부착)
푸터 hedges	실제 수치와 함께 한 줄. 예: "중위 평당가(−9.5%)와 중위 거래가(+2.6%)가 서로 반대로 움직였다 — 시장 방향이 아니라 거래 구성 변화일 수 있다."

• 예전엔 같은 문장을 경고 콜아웃으로 한 번 더 띄웠다. 화면에서 세 번 반복돼 걷어냈다.
• 🚨 칩은 템플릿이 자동으로 붙이지만 hedge 한 줄은 스킬이 넣어야 한다. 반대 방향인 지역이 하나라도 있으면 반드시 넣는다.
• 차트 막대 폭은 지역 수에 따라 자동 조정된다(1개 140px ~ 6개 27px). 지역 1개여도 화면이 비지 않는다.
  • 레이아웃 기준: templates/result.html. 마크업·CSS·렌더 JS는 고정이고 실행마다 바뀌는 것은 비실행 ipzi-data JSON 블록 하나뿐이다.

HTML·감사 산출물 계약 🚨

• out/ipzitalk-recent-market-trend/result.json과 out/ipzitalk-recent-market-trend/audit.json은 내부 계약용 고정 이름으로 먼저 만든다.
• 입력 순서대로 정규화한 지역명을 _로 잇고 기준월을 YYYY-MM으로 바꿔 <지역묶음>_시장동향_<기준월>을 만든다. 예: 강남구_송파구_서초구_시장동향_2026-05.html. 지역명을 확보하지 못하면 이름을 지어내지 말고 ipzitalk-recent-market-trend.html로 폴백한다.
• 최종 HTML 경로는 out/ipzitalk-recent-market-trend/<지역묶음>_시장동향_<기준월>.html이다.
• 셸 허용 환경에서는 스킬 기준 ../../scripts/html_artifact_contract.mjs를 --file-name "<지역묶음>_시장동향_<기준월>"과 함께 사용해 렌더·검증한다. shell-free 또는 셸 금지 환경에서는 같은 파일명으로 ipzi-data 블록만 교체하고 fixed template region을 비교한다.
• validator가 통과하지 않거나 고정 영역을 비교할 수 없으면 완료 처리하지 않는다.
• audit.json 최상위에는 skillBaseDirectory, 입력 요약, calls, auditIncomplete, shellUsed, webUsed, generatedFiles를 둔다.
• 각 MCP 호출의 최초 반환 직후 calls에 한 행을 추가한다. 행 필드는 sequence, baseToolName, region, regionCode, yearMonth, tradeType, limit, resultCount, sampleCount, truncated, reasonCode, coverageComplete, missingMonths, provisionalMonths, provenance다. 해당하지 않는 값은 null로 두고 필드를 생략하지 않는다.
• get_complex_trades는 지역 N곳마다 기준월·비교월을 조회하므로 정확히 2N회다. 지역명이어서 코드 해소가 필요한 곳의 수를 R이라 하면 get_region_code는 R회이고 정상 총 호출 수는 2N + R회다. 입력이 이미 region_code면 해당 지역의 해소 호출은 0회다.
• 최종 도구별 호출 수와 총합은 calls에서 자동 계산한다. 수기 집계나 별도 실행 기록을 감사 원장보다 우선하지 않는다.
• 감사 누락 복구·보완을 위한 MCP 재호출은 금지한다. 기존 최초 반환으로 행을 복구할 수 없으면 auditIncomplete:true로 남기고 재조회하지 않는다.
• 최종 응답은 audit.json의 calls에서 도구별 호출 횟수·Remote provenance·Skill base directory·shell/web 사용 여부·생성 파일을 계산한다.
• audit.json.generatedFiles에는 예시 이름이 아니라 실제 최종 파일명과 경로를 기록한다.

필수 단서 · 금지 표현

• 필수: 구성 미보정 명시 · 표본(거래량) 표기 · 최근월 제외 사유 · 전용면적 기준 평당가 · 목록 개수 제한과 무관하게 중위값·거래량은 전체 거래 기준이라는 설명 · 출처·조회일.
• 금지: 최근월(신고 지연)을 전월과 비교 · 지역 우열/등급 단정 · 평당가 변동률을 "집값 변동"으로 단언 · 결측 보간.

엣지 · 실패 처리

상황	처리
성공 + NO_TRADES_FOR_REQUESTED_SCOPE + coverage.complete=true	정상적으로 확인된 거래 0건. 해당 행만 "거래 없음" 표기
PARTIAL_COVERAGE 또는 coverage.complete=false	"조회 불완전"과 미확인 월 표기. 거래 0건·전월 대비 변동률로 렌더하지 않음
coverage.provisional_months에 대상월 포함	잠정 집계로 표시. 확정 거래량·변동률로 단정하지 않음
도구 오류 NOT_FOUND	조회 실패로 표시. 거래 0건과 구분하고 나머지 지역만 정상 렌더
거래량 < 30건인 시군구	변동률 신뢰 낮음 → "참고" 꼬리표
평당가·거래가 방향 불일치	구성 변화 경고 강제 표기
지역 해소 실패	후보 나열 후 선택

검증된 사항 (회귀 참고 전용 · 서울 서초·강남·송파 · 조회 2026-07-09)

검증된 사항은 런타임 fallback 또는 실행값 대체에 사용하지 않는다. 운영 MCP 실호출. trade_type='sale', limit=1, 기준월 2026.05 / 비교월 2026.04.

시군구	거래량 04→05	Δ	중위 평당가 04→05	Δ	중위 거래가 04→05	Δ
서초 11650	301 → 350	+16.3%	9,382 → 9,664	+3.0%	255,000 → 265,000	+3.9%
강남 11680	397 → 433	+9.1%	11,920 → 11,966	+0.4%	267,000 → 270,000	+1.1%
송파 11710	600 → 582	−3.0%	9,269 → 8,393	−9.5%	199,500 → 204,750	+2.6%

• 송파 모순 실증: 평당가 −9.5% / 거래가 +2.6% → 구성 변화 경고 대상.
• 최근월 지연 실증: 서초 2026.06 total_count 49 vs 2026.05 350건.
• limit=1로도 summary.sample_count가 전체(301/350/…)로 나오는 것을 확인 → items 없이 요약만 받는 전략 유효.
• 모든 응답 truncated:true(items 상한). summary는 정확.

섹션마다 출처를 작게 단다

데이터 블록 하단에 .src 한 줄. 도구·API 이름은 쓰지 않는다. 사용자가 아는 기관명만.

블록	출처 표기
단지 개요·세대수·준공·주차·연차	공동주택관리정보시스템(K-apt)
매매·전세·평당가·거래량	국토교통부 실거래가
학교·교통·생활·상권 등 장소	카카오맵
분양공고·분양가·주택형·입주월	청약홈
지도 (장소 마커)	네이버 지도 · 카카오맵
지도 (분양공고 마커)	네이버 지도 · 청약홈

• 🚨 출처 문자열은 ipzi-data로 받지 않고 템플릿 마크업에 직접 박는다. 어느 블록이 어디서 왔는지는 실행마다 달라지지 않는다. 데이터로 받으면 채우는 걸 잊거나 틀리게 쓸 여지만 생긴다.
• 🚨 한 블록에 두 출처가 섞이면 병기한다. 예: 세대수·주차 — 공동주택관리정보시스템(K-apt) · 위치 — 카카오맵. 하나로 뭉뚱그리면 어느 숫자가 어디서 왔는지 사용자가 알 수 없다.
• 🚨 쓰지 않은 기관을 출처로 적지 않는다. 우리가 부르는 곳은 위 다섯 곳뿐이다.
• 히어로·유의사항·푸터에는 달지 않는다. 데이터 블록에만.

디자인 정본

스킬 폴더 밖 문서에 의존하지 않도록 규칙을 여기 인라인으로 둔다.

• CDN·외부 폰트·이모지 금지. 아이콘은 <symbol> 인라인 + <use> 참조로 self-contained.
• 라이트/다크 양쪽. prefers-color-scheme + :root[data-theme] 모두 대응.
• 토큰만 사용: --g/--y/--o/--r/--x/--brand/--up/--down/--zebra (+ -s 배경 변형).
• 예외 상태: null은 "정보없음"(0 아님) · 표본 부족은 판정 유보 · 목록 상한 도달은 "목록 불완전" 표기.
• ★·☆는 활자 기호이며 이모지가 아니다. 등급 표기에 사용 가능.

분석 목적 맞춤 요약

목적을 확보하는 방법

• 사용자가 처음부터 목적을 밝혔으면 다시 묻지 않고 사용자 문장을 goal.purpose에 그대로 보존한다.
• 목적이 없고 현재 클라이언트가 4개 선택지와 직접 입력(Other/기타)을 함께 지원하는 네이티브 사용자 입력 UI를 제공하면 그 UI를 정확히 한 번 사용한다.
  • 4인가족 실거주 검토
  • 투자 심의 회의 자료
  • 분양 제안서용 자료
  • 건너뛰기
  • UI가 자동 제공하는 기타(직접 입력)으로 자유 입력도 허용한다.
• 네이티브 UI가 직접 입력을 지원하고 지원 가능한 수가 2~3개이면, 그 수만큼 위 목적 프리셋을 앞에서부터 선택지로 제시한다. 질문에는 건너뛰기를 기타(직접 입력)에 입력해도 된다고 알린다.
• 네이티브 사용자 입력 UI가 없거나 직접 입력을 지원하지 않으면 다음 질문만 출력하고 그 턴을 종료해 답을 기다린다:

  원하는 분석 목적을 한 문장으로 알려주세요. (예: "4인가족 실거주 검토", "투자 심의 회의 자료", "분양 제안서용 자료") 건너뛰셔도 됩니다.

• 질문 단계에서는 목적 입력 UI 또는 위 텍스트 질문 외의 도구를 사용하지 않는다.
• 사용자가 목적 또는 명시적인 건너뛰기로 답변하기 전에는 MCP·웹·파일·셸 도구를 호출하지 않는다.
• 프리셋을 고르면 해당 문구를 goal.purpose에 그대로 저장하고, 직접 입력을 고르면 사용자가 입력한 원문을 그대로 저장한다.
• 건너뛰기를 고르거나 사용자가 건너뛰겠다고 답한 경우에만 goal:null로 두고 목적 섹션 없이 진행한다. 목적을 지어내지 않는다.

데이터 수집 후 맞춤 요약

• purpose에는 사용자 문장을 그대로 보존한다.
• 데이터 조회·수집이 완료된 후에만 conclusions(결론)·evidence(근거)·cautions(주의사항)·nextActions(다음 행동 제안)를 작성한다. 조회 전에 문구나 결론을 미리 만들지 않는다.
• goal은 사용자 표현을 그대로 보존한 purpose, conclusions(35), evidence(13), cautions(02), nextActions(13)로 구성한다.
• conclusions는 실제 조회·판정 결과만 목적에 맞춰 요약하고, 각 결론에 실제 evidence를 최소 1개 연결한다.
• evidence에는 이번 실행에서 확보한 필드·수치·비교 결과만 쓴다. 예시·검증값·모델 지식으로 빈 값을 채우지 않는다.
• 새 데이터나 없는 수치를 창작하지 않는다.
• cautions는 실제로 확인된 데이터 누락·표본 한계·시점 차이·방법상 제약만 쓴다. 본문 경고를 약화하거나 새 위험을 지어내지 않는다.
• nextActions는 실제 발견사항·누락·사용자 목적에서 이어지는 검토 행동만 제안한다. URL이나 원시 Skill ID 대신 한글 Skill 이름과 자연어 질의 예시를 쓴다.
• 템플릿은 배열 상한을 잘라내고 빈 단계는 숨긴다. goal:null이면 goal-box 전체를 숨긴다.
• 최초 반환 구조화가 실패하면 해당 호출의 resultCount·sampleCount·truncated와 지표 값을 null로 기록한다. 예시·검증값으로 대체하지 않는다.
• auditIncomplete:true이면 정상 완료를 주장하지 않는다. 해당 셀을 "확인되지 않음"으로 표시하고 부분 완료 또는 실패로 보고한다.

변경 이력

버전	날짜	내용
1.2.7	2026-07-20	지역·월별 커버리지와 잠정월을 확인해 부분 조회를 거래 0건으로 오인하지 않도록 하고 감사 필드 확장
1.2.6	2026-07-15	정규화 지역 묶음과 기준월 기반 시장동향 HTML 파일명을 동적화하고 내부 JSON·감사 파일 고정 이름 유지
1.2.5	2026-07-15	단지·전용타입 후속 분석의 사용자 노출 명칭을 시세 추이 분석에서 실거래 추이 분석으로 통일
1.2.4	2026-07-15	팝업 지원 환경의 4개 목적 프리셋+직접 입력과 텍스트 대체 질문을 함께 지원하는 하이브리드 목적 입력 계약 추가
1.2.3	2026-07-15	상세 표의 첫 열 이후 헤더와 숫자 값을 같은 오른쪽 정렬로 맞춰 열 밀림 개선
1.2.2	2026-07-15	목적 질문 대기·실데이터 후속 추론 계약과 검증값 런타임 대체 금지, 불완전 감사의 정상 완료 금지 규칙 추가
1.2.1	2026-07-14	지역·월·호출 인자를 보존하는 호출별 calls 감사 원장과 2N + R 호출식 추가
1.2.0	2026-07-14	main 승격. 비실행 JSON·고유 출력·공통 audit 계약과 목적 맞춤 요약 내러티브 레일 추가
1.1.0	2026-07-14	목적 맞춤 요약 goal 스키마 추가
1.0.0	2026-07-09	패키지 확정. 데모를 templates/result.html 템플릿(고정 마크업 + ipzi-data JSON 렌더)으로 이식. 차트를 regions 데이터에서 그리도록 전환
0.1	2026-07-09	서초·강남·송파 실데이터로 신규 작성. limit=1 요약 전략 확립 · 송파 평당가/거래가 모순 실증 · 최근월 지연(49건) 직접 확인 · 구성 미보정 경고 규칙 · 등급 미부여 원칙 · 정본 토큰/아이콘 적용

MCP 도구 네임스페이스와 출처

ipzitalk MCP 도구의 네임스페이스는 실행 환경(Codex, Claude Code, Hermes, claude.ai 커넥터 등)에 따라 다르다. 이 문서에 적힌 도구 이름(search_announcement_info, get_geocode, get_map_embed_url 등)은 접두사 없는 기본 도구명(base tool name) 이다.

1. 먼저 연결된 도구 목록에서 같은 기본 도구명을 찾는다.
2. 그중 ipzitalk-remote 플러그인의 ipzitalk 서버 provenance가 확인되는 도구만 우선 사용한다. Codex에서는 실제 도구 호출 이벤트의 server: ipzitalk과 기본 도구명을 기준으로 확인한다.
3. presale-mcp 또는 다른 로컬 MCP provenance의 동명 도구는 Remote Skill의 대체 수단으로 사용하지 않는다.
4. provenance를 확인할 수 없거나 같은 기본 도구명이 여러 서버에 있어 모호하면 임의 선택하지 말고 중단하여 필요한 Remote 도구명을 안내한다.

클라이언트가 연결 도구 목록에 plugin/server provenance를 구조적으로 제공하지 않을 때만 다음 명시적 fallback을 사용한다.

1. mcp__plugin_ipzitalk-remote_ipzitalk__<도구명>
2. mcp__ipzitalk_mcp__<도구명>
3. mcp__ipzitalk__<도구명>
4. mcp__claude_ai_ipzitalk__<도구명>

fallback으로도 Remote 출처를 유일하게 확인할 수 없으면 값을 추정하지 말고, 사용자에게 ipzitalk Remote MCP 연결 상태를 확인하도록 안내한 뒤 중단한다.