| 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~2개월은 신고 등록 지연으로 제외하고 최신 확정월을 기준월로 쓴다. 2026-07이면 기준월 2026.05, 비교월 2026.04.
- 지역 해소 — 지역명이면
get_region_code로 sigungu_code 확보.
- 월별 조회 — 각 시군구 × (기준월, 비교월)
get_complex_trades(..., limit=1).
- 커버리지 확인 — 각 응답의
metadata.coverage.complete, missing_months, provisional_months, reason_code를 먼저 확인한다. 미확인·잠정 월을 거래 0건으로 바꾸지 않는다.
- 변동률 계산 — 기준월과 비교월이 모두 완전 확인된 지역만 거래량·중위 평당가·중위 거래가의 전월 대비 %를 계산한다.
- 모순 검출 — 중위 평당가와 중위 거래가가 반대 방향이면 구성 변화 경고를 강제 표기(아래 gotcha).
- 렌더 — 시군구 카드 + 거래량 막대 + 상세 표 + 최근월 제외 설명.
등급·색 규칙
- 상승
--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) 이다.
- 먼저 연결된 도구 목록에서 같은 기본 도구명을 찾는다.
- 그중
ipzitalk-remote 플러그인의 ipzitalk 서버 provenance가 확인되는 도구만 우선 사용한다. Codex에서는 실제 도구 호출 이벤트의 server: ipzitalk과 기본 도구명을 기준으로 확인한다.
presale-mcp 또는 다른 로컬 MCP provenance의 동명 도구는 Remote Skill의 대체 수단으로 사용하지 않는다.- provenance를 확인할 수 없거나 같은 기본 도구명이 여러 서버에 있어 모호하면 임의 선택하지 말고 중단하여 필요한 Remote 도구명을 안내한다.
클라이언트가 연결 도구 목록에 plugin/server provenance를 구조적으로 제공하지 않을 때만 다음 명시적 fallback을 사용한다.
mcp__plugin_ipzitalk-remote_ipzitalk__<도구명>mcp__ipzitalk_mcp__<도구명>mcp__ipzitalk__<도구명>mcp__claude_ai_ipzitalk__<도구명>
fallback으로도 Remote 출처를 유일하게 확인할 수 없으면 값을 추정하지 말고, 사용자에게 ipzitalk Remote MCP 연결 상태를 확인하도록 안내한 뒤 중단한다.
