| name | ipzitalk-living-environment |
| description | 주소 또는 단지명을 입력받아 생활 환경(상권=백화점·대형마트/대형슈퍼, 공원·녹지, 공공기관=도서관·주민센터·법원, 관광·문화·먹거리)을 종합해 종합 등급 + 한줄평 + 인터랙티브 HTML 리포트와 지도를 생성한다. "생활 환경", "생활 편의", "생활 인프라", "상권 좋아?", "마트 가까워", "공원 있어?", "도서관 근처", "생활 편의시설" 등의 표현이 있으면 이 스킬을 사용한다. (단일 "쇼세권만/공원만" 질문은 해당 근접 진단 배지 스킬로 분리 — 트리거 겹치지 않게 할 것.)
|
| version | 1.0.0 |
| license | proprietary |
생활 환경 분석
주소/단지명 하나로 상권·공원·공공기관·관광문화를 종합해 대표 보고용 생활 리포트를 만든다.
※ 모든 거리는 직선거리 기준, 개수는 근사치. 영업 여부·매장 규모·운영시간 미반영. 45건 cap 도달 시 "개수 근사" 표기.
※ 특정 단일 시설만 물으면(예: "쇼세권만") 해당 배지 스킬로. 이 스킬은 생활 인프라 종합.
입력
| 파라미터 | 필수 | 기본 | 설명 |
|---|
address 또는 complex_query | ✅(택1) | - | 주소 또는 단지명 |
radius_m | ✕ | 2500 | 표시 반경. 최대 5,000m. 생활 축은 전부 근린이라 모든 축에 적용 |
단지명이 브랜드면 후보가 여러 개면 자동 확정하지 말고 후보(지역 포함)를 사용자에게 제시해 선택받는다.
⚠️ 4개 카테고리 = 검색 5~7회 → 크레딧·시간 소요. 비용 절감 필요 시 카테고리 축소 가능(관광 먼저 생략).
반경 처리 (R1~R3) — radius_m은 판정 파라미터가 아니라 관측 파라미터다
| 층위 | 값 | 사용자 radius_m |
|---|
| 밴드(등급 판정) | 축별 절대 거리, 불변 | 영향 없음 |
| 표시 반경(지도 원·목록) | 기본 2,500 · 사용자가 주면 그 값 | 그대로 반영 |
| 수집 반경(API 호출) | max(radius_m, 축 밴드최대 × 1.25) | 하한만 보장 |
- R1. 밴드는 절대 기준. 반경을 5km로 넓혀도 2.5km 마트는 여전히 "미흡"이고, 300m로 좁혀도 137m 공원은 여전히 "우수"다.
- R2. 수집 반경은 항상 밴드 최대 이상으로 자동 확장. 안 그러면 "반경 내 없음"과 "원거리(미흡)"를 구분할 수 없다.
- R3. 요청 반경 밖이라도 축별 최근접 1건은 항상 표시. 회색 + "요청 반경 밖 · 2.6km" 꼬리표.
- cap 5,000m. 2,000m 초과 시 45건 캡 경고를 강제 표기.
- 광역 축 없음. 생활 4축(상권·공원·공공기관·관광)은 전부 근린이라
radius_m을 모두에 적용한다.
- 수집 반경 내 0건이면 "N m 내 없음(미확인)"으로 명시하고 멈춘다. 추정 금지. 구청 0건은 검색 한계이지 부재가 아니다(아래 gotcha).
🚨 45건 캡 (카카오)
search_by_nearby_category(대형마트)는 쿼리당 45건 상한이고 grid 옵션이 없다. 키워드 검색만 grid=true로 우회 가능.- 다만
sort=distance라 최근접 값은 정확 → 등급 판정은 안전, 개수·목록은 근사.
- 응답
metadata.truncated가 true면 "개수 근사" 표기(관광 r2500은 밀집지에서 거의 항상 캡 도달).
필수 도구
| 도구 | 용도 |
|---|
get_geocode / get_address | 좌표 확보(주거시설 후보 우선) |
search_by_nearby_category | 대형마트 categories=['mart_large'] |
search_by_nearby_keyword | 백화점·공원·도서관·주민센터·법원·관광명소 (키워드+필터) |
get_static_map / get_map_embed_url | 지도(주요 생활시설 마커 + 크게 열기 링크) |
워크플로우 (반경 근린)
- 좌표 확보 — address→geocode / 단지명→get_address(주거시설 우선). 후보 다수 → 사용자 선택.
- 상권 (검증됨) — 백화점
keyword "백화점" + category_filter{include_contains:["백화점"]} (r2500) + 대형마트/대형슈퍼 category ['mart_large'] (r2500). → 백화점·대형마트·SSM 최근접·개수.
- 공원·녹지 (검증됨) —
keyword "공원" + category_filter{include_contains:["공원"], exclude_contains:["공원시설물"]} (r1500). → 공원 최근접·개수. (공원시설물=벤치·운동기구 노이즈 제거)
- 공공기관 (검증됨) — 도서관
keyword "도서관" · 주민센터 keyword "주민센터" · 법원 keyword "법원" (r2500). 구청은 검색 불가(아래 gotcha) → 도서관·주민센터·법원으로 공공 인프라 평가. 화장실·무인민원발급기·주차장 노이즈는 표에서 제외(실제 시설만).
- 관광·문화 (검증됨, 참고 섹션) —
keyword "관광명소" (r2500). 먹자골목·카페거리·명소·저수지 등. 가중 낮음(종합 반영 참고). 45건 cap 흔함 → 대표 시설만.
- 판정·등급 — 카테고리별 최근접·개수 → 카테고리 등급 → 종합(균등 가중).
- 지도 + 출력 — 대표 생활시설 마커, md 요약 먼저 → HTML 리포트(
templates/result.html).
검색식 요약 (복붙용)
수집 radius = max(사용자 radius_m, 밴드최대 × 1.25) — 아래는 사용자 미지정 시 기본값.
| 카테고리 | 도구/검색식 | 밴드 최대 | 수집 radius | 필터·주의 |
|---|
| 백화점 | keyword "백화점" | 2000 | 2500 | include_contains:["백화점"] |
| 대형마트/SSM | category ['mart_large'] | 2000 | 2500 | 카테고리 조회(clean) · grid 미지원 |
| 공원 | keyword "공원" | 1000 | 1500 | include_contains:["공원"], exclude_contains:["공원시설물"] |
| 도서관 | keyword "도서관" | 2000 | 2500 | 국공립/작은도서관 모두 포함 |
| 주민센터 | keyword "주민센터" | 2000 | 2500 | 동주민센터(=동사무소) |
| 법원 | keyword "법원" | 2000 | 2500 | 법조타운 인접 여부 |
| 관광명소 | keyword "관광명소" | – | 2500 | 45건 cap 흔함, 참고 가중 |
구청 | keyword "구청"/"○○구청" | – | – | ❌ 검색 0건(gotcha) — 넣지 말 것 |
관광 | category ['attraction'] | – | – | ❌ Unknown 카테고리(작동 안 함) — "관광명소" 키워드로 대체 |
⚠️ 상권 수집 반경은 밴드 최대(2000)와 같으면 경계 판정이 불가능하다(2,000m 밖 마트를 "없음"과 구분 못 함). R2에 따라 2500으로 올린다.
지도 호출 규칙 (서버 렌더 버그 회피)
/map?d= 페이지의 fitBounds는 마커만 감싸고 반경 원을 무시한다. center에서 마커 bounds의 북·남·동·서 여유가 각각 radius_m 이상이어야 원이 온전히 보인다.
- 🚨 반경 눈금 마커를 넣지 않는다. 예전엔
fitBounds가 반경 원을 무시해 원이 잘리는 걸 막으려고
정북·남·동·서에 회색 더미 마커 4개를 심었다. 사용자에게는 정체를 알 수 없는 점으로 보여 혼란만 준다.
원이 잘리더라도 마커는 실제 장소만 찍는다. (근본 해결은 render.ts가 원을 bounds에 포함하도록 고치는 것 — 발견사항 6번)
center + radius_m 항상 함께, 마커 2개 이상(1개면 서버가 zoom:15 고정).- 카드 CSS에서 iframe에
min-width:720px, .map{overflow-x:auto} — 사이드바 280px 고정 탓에 좁은 화면에서 최소 줌(한반도)으로 떨어지는 것을 막는다.
0건이 나오면 재확인한다 (🚨 부재 단정 금지)
카테고리 검색의 45건 캡은 서버가 아니라 후처리 필터라, 밀집지역에서는 실제로 있는 시설이 0건으로 보일 수 있다.
0건이 나온 축은 ① metadata.truncated 확인 → ② 같은 축을 search_by_nearby_keyword 로 한 번 더 조회(반경 동일, center 재해소 금지) → ③ 둘 다 0건 + truncated:false 면 "반경 내 없음" 확정, 한쪽이라도 캡에 걸리거나 엇갈리면 "확인 불가(검색 한계)" 로 적는다. 없음과 확인 불가를 섞어 쓰지 않는다.
등급 (카테고리별, 직선거리)
| 카테고리 | 우수 | 양호 | 보통 | 미흡 |
|---|
| 상권(대형마트·SSM 최근접) | ≤500m + 백화점 有 | ≤500m SSM(백화점 無) 또는 대형마트 ≤1.5km | 1.5–2km | >2km/없음 |
| 공원(최근접) | ≤300m | 300–600 | 600–1000 | >1000 |
| 공공기관(도서관·주민센터 최근접) | ≤500m 도보권 | 500–1000 | 1000–2000 | >2000 |
| 관광·문화 | 참고만(등급 산정 낮은 가중) | | | |
색 밴드(리포트 표): ≤500 우수(초록) / 500–1200 근접(노랑) / 1200–2000 이격(주황) / >2000 원거리(회색).
종합 등급 (★ 3단계)
- 균등 가중: 상권 · 공원 · 공공기관을 동등하게 반영. 관광·문화는 참고(낮은 가중, 종합 등급을 좌우하지 않음).
- 세 카테고리 모두 우수 → ★★★ / 두 개 이상 양호
우수면 ★★☆ / 대부분 보통미흡 ★☆☆.
- 약점 명시: 특정 카테고리(예: 백화점 부재)가 약점이면 종합을 낮추지 않더라도 한줄평에 정직히 명시.
- 한줄평: 강점/약점 카테고리를 1~2문장으로 정직하게(근거 없는 우열 단정 금지).
출력 포맷
- 채팅(먼저): 종합 등급 + 한줄평 + 카테고리별(상권/공원/공공기관/관광) 최근접·개수·등급 요약(md 표).
- HTML 리포트(선택): 상단 제목+종합 등급 pill → 지도 히어로 → 종합 평가 박스 → 상권/공원/공공기관/관광 4섹션 표(시설명·직선거리·비고) → 출처·hedge 푸터.
- 레이아웃 기준:
templates/result.html
필수 단서 · 금지 표현
- 필수: 직선거리·개수 근사 · 45건 cap 근사 · 영업/규모/운영시간 미확인 · 관광은 참고 가중 · 출처(카카오맵)·조회일 표기.
- 필수: 폐점·예정 표기 시설은 등급에서 제외하고 목록에만 꼬리표로 남겼음을 밝힌다.
- 금지: "생활 인프라 최고" 등 근거 없는 우열 단정, 없는 시설 지어내기, 구청 부재 단정(검색 한계이지 실제 부재 아님), 재개장·개청 시점 추정.
Gotcha (검증에서 확인)
- 🚨 구청 검색 불가:
"구청"·"○○구청" 키워드가 카카오 로컬에서 반경 내 0건으로 잡히는 경우가 있음. 구청을 필수 카테고리로 넣지 말 것. 공공기관은 도서관·주민센터·법원으로 평가하고, 리포트에는 "구청은 검색상 결과 없음 → 대체 평가"로 명시(부재 단정 금지).
- ⚠️ 공공기관 노이즈: 도서관/법원/구청 키워드는 화장실·무인민원발급기·주차장·민원실 등 부속시설이 다수 섞임 → 실제 시설명만 표에 표기.
- ⚠️ 공원 노이즈:
"공원"만 검색하면 벤치·운동기구 등 "공원시설물"이 섞임 → exclude_contains:["공원시설물"] 필수. 결과가 어린이공원 위주면 한줄평에 명시.
- ⚠️ 관광 45건 cap:
"관광명소" r2500은 밀집지에서 45건 cap이 흔함 → 개수는 근사, 대표 시설만.
엣지 · 실패 처리
| 상황 | 처리 |
|---|
지오코딩 실패 / NOT_FOUND | 재입력 요청 |
후보 다수 / AMBIGUOUS | 후보(지역) 나열 후 선택 |
| 특정 카테고리 0건(백화점 등) | 해당 섹션 "반경 내 없음" 명시, 거리 지어내지 않음 |
| 구청 0건 | 정상(gotcha) — 도서관·주민센터·법원으로 대체 평가 |
| 법원 0건 | 반경 밖일 수 있음(잠실 2.5km 실측 0건). "반경 내 없음"이지 부재 아님 |
최근접이 폐점·예정 표기 시설 | 다음 순위의 운영 중 시설로 최근접을 다시 잡고, 등급도 그 값으로 산출 |
| 키워드 45건 cap | 최근접·대표 시설만 사용, "개수 근사" 표기 |
검증된 사항 (서울 서초구 방배동 사례 · 조회 2026-07-08)
실데이터로 도심 근린 · 양호(★★☆) 케이스 검증.
- 상권: 대형슈퍼(SSM) 320m(도보권) · 대형마트 1.3km · 백화점 0건. → 근린 생활편의 양호, 백화점 부재(약점 명시).
- 공원 (keyword "공원", r1500, 공원시설물 제외): 최근접 137m(우수) · 324m · 466m 등 반경 500m 내 다수. → 우수(단 어린이공원 위주).
- 공공기관 (도서관·주민센터·법원 keyword, r2500): 작은도서관 425m · 주민센터 428m(도보권) · 국공립 도서관 1.4~1.5km · 법조타운 2.1km. 구청 검색 0건 → 대체 평가.
- 관광·문화 (keyword "관광명소", r2500, 45건 cap): 꼬치거리 460m · 먹자골목 609m · 카페골목 1.3km · 명소 2.0km. → 먹거리·문화 풍부(참고 가중).
- 종합: ★★☆ 양호 — 공원(137m)·도서관·주민센터 도보권 + 법조타운(2.1km) + 먹자/카페골목 다수가 강점, 백화점 부재가 유일한 약점. → 균등 가중 규칙이 실제 케이스로 확인됨.
- 확인된 필터·gotcha: 공원시설물 제외 정상 동작 · 공공기관 부속시설 노이즈 다수 → 실제 시설만 표기 · 구청 키워드 0건(gotcha) 실측 확인 · 관광 45건 cap 확인.
섹션마다 출처를 작게 단다
데이터 블록 하단에 .src 한 줄. 도구·API 이름은 쓰지 않는다. 사용자가 아는 기관명만.
| 블록 | 출처 표기 |
|---|
| 단지 개요·세대수·준공·주차·연차 | 공동주택관리정보시스템(K-apt) |
| 매매·전세·평당가·거래량 | 국토교통부 실거래가 |
| 학교·교통·생활·상권 등 장소 | 카카오맵 |
| 분양공고·분양가·주택형·입주월 | 청약홈 |
| 지도 (장소 마커) | 네이버 지도 · 카카오맵 |
| 지도 (분양공고 마커) | 네이버 지도 · 청약홈 |
- 🚨 출처 문자열은
ipzi-data JSON으로 받지 않고 템플릿 마크업에 직접 박는다.
어느 블록이 어디서 왔는지는 실행마다 달라지지 않는다. 데이터로 받으면 채우는 걸 잊거나 틀리게 쓸 여지만 생긴다.
- 🚨 한 블록에 두 출처가 섞이면 병기한다. 예:
세대수·주차 — 공동주택관리정보시스템(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 아님) · 표본 부족은 판정 유보 · 45건 캡 도달은 "목록 불완전" 표기.
★·☆는 활자 기호이며 이모지가 아니다. 등급 표기에 사용 가능.- 지도 카드 CSS:
.map{overflow-x:auto; overflow-y:hidden} + .map iframe{display:block; min-width:720px}.
overflow:hidden만 주면 iframe이 카드 폭에 짓눌려 지도가 최소 줌(한반도)으로 떨어진다.
- 🚨 지도 링크는 발급 후 7일 만료. 산출물 지도 캡션에 유효기간·재발급 필요를 반드시 적는다.
🚨 categories:['park'] 는 0건을 반환한다 (실측 2026-07-09)
반경 1000m · categories:['park'] → 0건 ← 죽은 검색식
카카오 카테고리 그룹에 공원이 없다. attraction·구청 과 같은 부류다. 공원은 키워드 검색으로만 찾는다.
그리고 키워드 "공원" 은 상호명이 상위를 도배한다. 실측 상위 5건:
뻥튀기공작소 위례호수공원점 187m · 컴포즈커피 위례호수공원점 194m · 오마뎅 위례호수공원점 194m
파리바게뜨 위례호수공원점 194m · 뉴메이킹코딩학원 위례 호수공원센터 213m
도구도 경고를 낸다 — "Short keyword 공원 can return noisy or incomplete Kakao results."
→ category_filter 로 반드시 거른다. include_contains:["공원"] + exclude_contains:["공원시설물"].
category_name 이 음식점·카페·학원이면 공원이 아니다.
🚨 운영 상태는 장소명 문자열에만 있다 — 폐점·예정 (실측 2026-07-10)
카카오는 운영 상태 필드를 주지 않는다. 상태를 장소명에 괄호로 붙이고, category_name 과 거리는
정상 시설과 똑같이 준다. 카테고리 검색도 걸러주지 않는다.
잠실래미안아이파크 실측 — 상업시설과 공공기관 양쪽에서 관측됐다.
홈플러스 잠실점 (폐점) 774m 가정,생활 > 대형마트 > 홈플러스
롯데마트 월드타워점 799m 가정,생활 > 대형마트 > 롯데마트 ← 운영 중 최근접 대형마트
풍납2동주민센터 (2027년 예정) 1,244m 사회,공공기관 > … > 동행정복지센터
풍납2동주민센터 1,263m 사회,공공기관 > … > 동행정복지센터 ← 운영 중 본체
거르지 않으면 문 닫은 마트가 최근접 대형마트가 되고, 아직 짓지도 않은 주민센터가 최근접이 된다.
운영 중 본체가 25m 뒤에 따라오기 때문에 조용히 등급만 어긋난다.
- 장소명에
폐점·폐업·휴업·임시휴업·오픈예정·개점예정·예정·(20NN년 이 있으면
등급·최근접·개수에서 제외하고, 목록에만 사유 꼬리표를 단다.
- 재개장·개청 시점을 지어내지 말 것. 장소명에 있는 문자열만 화면에 쓴다.
- 생활 4축 전부에 적용한다. 상권만의 문제가 아니다(주민센터에서 관측됨).
- 학교의
휴교·폐교, 역의 예정과 같은 함정이다 → ipzitalk-education-environment · ipzitalk-transit-environment 동일 규칙.
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 연결 상태를 확인하도록 안내한 뒤 중단한다.
