skills/tochi-satei-kun/README.md

# 土地価格査定クン

**透明性・再現性・検証可能性を重視する OSS AVM、「AVM 界の Linux」を目指す土地査定エンジン。**

媒介査定担当者向けの一次土地査定スキル。取引事例比較法（比準法）に基づき、ヘドニック係数を **都度回帰** で算定して個別格差補正を全開示する **白箱 AVM**。係数・アルゴリズム・補正率を完全公開する設計で、係数全開示型の OSS AVM として Apache 2.0 ライセンスで配布。

- **最新バージョン**: v1.4.3（2026-07-19）
- **ライセンス**: Apache 2.0
- **作者**: 松田幸一（不動産鑑定士）
- **配布**: https://github.com/signal-yield/tochi-satei-kun

## インストール

このスキルは `~/.claude/skills/tochi-satei-kun/` に配置することで Claude Code から利用可能になります。

```bash
# Python 依存関係のインストール
cd ~/.claude/skills/tochi-satei-kun
pip install -r requirements.txt
```

## 必要なデータ

スキル実行前に以下のファイルを取得してください。スキル本体には実データを同梱していません（再配布リスク回避＋常に最新版を使うため）。

### 1. MLIT 取引価格情報CSV（必須）

国土交通省「不動産情報ライブラリ」から取得します。

1. https://www.reinfolib.mlit.go.jp/ にアクセス（旧 www.land.mlit.go.jp/webland/）
2. 「取引価格情報を検索」を選択
3. 期間：**MLITに含まれる全期間を採用**（期間フィルタは解除済み、時点修正で査定時点に揃える）。なるべく多くの年分を取得することで件数増・回帰精度向上
4. 種類：「宅地(土地)」または「宅地(土地と建物)」を選択
5. 地域：対象市区町村（市区町村単位で取得。本スキルは隣接拡張を行わないため、必要件数は対象市区町村1つで確保）
6. CSV形式でダウンロード（cp932/Shift-JIS エンコーディング）

**ファイル例**：`Tokyo_Setagaya Ward_20251_20254.csv`（2025年 第1〜第4四半期、世田谷区）

**更新頻度**：四半期ごとに新規取引が追加。査定時点を変えるたびに最新版を取得することを推奨。

### 2. 地価公示GeoJSON（必須）

国土交通省「**国土数値情報** ダウンロードサービス」から取得します。

1. https://nlftp.mlit.go.jp/ksj/gml/datalist/KsjTmplt-L01.html にアクセス
2. 最新年度（例：令和8年=2026年度）の **都道府県別** から対象を選択
   - 東京都 = `13`、神奈川県 = `14`、千葉県 = `12`、埼玉県 = `11` 等
3. 「**GML（JPGIS2.1）形式**」のZIPをダウンロード
4. ZIPを解凍し、`L01-XX_YY.geojson` ファイル（XX=年度、YY=都道府県コード）を任意フォルダに置く
   - 例：`L01-26_13.geojson`（2026年版・東京都）

**スキルが使うフィールド**：
- `L01_024`：市区町村名（短縮形：「世田谷」「練馬」など）
- `L01_025`：住所（標準地の所在）
- `L01_007`：価格時点年
- `L01_074`〜`L01_105`：**過去32年分の年次価格時系列**（時点修正のCAGR算出に使用）

**更新頻度**：**毎年3月下旬に新年度版が公開**。年1回ダウンロードし直してください。古い年度版でも動きますが、時点修正の年率算出が古い水準になります。

**注意**：基準地価（都道府県地価調査 L02）は **アルゴリズム未対応のため使用不可** です。地価公示（L01）のみで動作します。

### 3. 基準地価について（使用不可）

基準地価（都道府県地価調査 L02）は、現状アルゴリズムが対応していないため使用できません。時点修正・標準価格チェックともに地価公示（L01）のみで完結します。

## データの利用規約と再配布

- **MLIT取引価格情報**：[政府標準利用規約2.0](https://www.land.mlit.go.jp/webland/agreement.html) 準拠（CC-BY互換）
- **国土数値情報（地価公示・基準地価）**：[政府標準利用規約2.0](https://nlftp.mlit.go.jp/ksj/other/agreement.html) 準拠（CC-BY互換）

本スキルは **これらのデータを再配布せず、ユーザー自身がダウンロードする運用** とすることで利用規約解釈の責任をユーザー側に置く設計です。スキル本体（`samples/_generate_dummy.py` で生成される合成データ含む）は Apache 2.0 ライセンスで配布します。

## 使い方

### 会話で起動

Claude Code で以下のように発話：

> 土地価格査定クンを使って、港区麻布十番の120㎡の土地を査定して

スキルが起動し、2つのファイル（MLIT CSV / 地価公示GeoJSON）のパスと物件詳細を確認しながら査定を進めます。

### CLIで実行

**実データを使う場合（推奨）**：
```bash
python scripts/main.py path/to/property.json \
                       path/to/Tokyo_Setagaya_Ward_20251_20254.csv \
                       path/to/L01-26_13.geojson \
                       --out output/
```

2つの入力（MLIT CSV / 地価公示GeoJSON）＋物件JSONが必須。基準地価GeoJSONは **使用不可**。

**ダミーデータでテストする場合**：
```bash
# 同梱の合成データ（港区の30件）
python samples/_generate_dummy.py  # 初回のみ
python scripts/main.py samples/sample_property.json \
                       samples/sample_mlit.csv \
                       samples/sample_koji.csv \
                       --out output/
```

出力：`output/土地査定_{物件略号}_{YYYYMMDD}.xlsx`

## 物件JSONフォーマット

```json
{
  "物件略号": "MIN001",
  "都道府県名": "東京都",
  "市区町村名": "港区",
  "地区名": "麻布十番",
  "丁目": "1丁目",
  "面積(㎡)": 120,
  "最寄駅:名称": "麻布十番",
  "最寄駅:距離(分)": 7,
  "土地の形状": "整形",
  "間口": 8.0,
  "前面道路:方位": "南",
  "前面道路:種類": "公道",
  "前面道路:幅員(m)": 6.0,
  "都市計画": "第一種中高層住居専用地域",
  "建ぺい率(%)": 60,
  "容積率(%)": 200,
  "角地補正率(%)": 5,
  "査定時点": "2025-12-01"
}
```

**注記**:
- `角地補正率(%)` は **業者の判断値**（MLIT データに角地情報が無いためヘドニック推定不能。白箱ポリシー上、自動値は与えず業者入力に委ねる。デフォルト 0）
- `前面道路:方位` は北/北東/北西/東/西/南東/南西/南 のいずれか。方位スコア（北=0, 南=4 の ordinal）で標準化補正に反映

## 出力xlsx

**3シート構成**：業者用 → 附属資料 → 顧客用

### 業者用シート（係数全開示、A3 横印刷）
- 物件概要・スコープ情報
- **査定価格**（モデル適合度ラベル付き：良好/中程度/要注意/参考情報）
- **2価格サマリ**（採用査定価格 vs ヘドニック母集団予測の乖離マトリクス）
- 価格レンジ（類似上位3事例の最大/中央/最小）
- **比準表**（鑑定書様式の2行式、事情補正/時点修正/標準化補正/地域格差を分子・分母で表示）
- **比準表の内訳**（取引事例の補修正率と地域格差率、規模・形状・方位・街路・交通接近・環境・行政の細目）
- **個別格差 + 査定価格の算定**（角地・方位・不整形を縦並びで表示。価格反映済みの説明表示であり、方位・不整形を査定価格へ再適用しない）
- **取引事例の概要**（13列：事例番号・取引㎡単価・取引時点・地区・最寄駅・駅距離・道路・幅員・方位・形状・地積・用途地域・容積率）
- **公示価格の概要**（13列、選定された1地点の詳細：公示番号「世田谷-50」形式、価格・所在・地区・最寄駅・道路・形状・用途地域・容積率など）
- **ヘドニック回帰サマリ**（n, R², 全β、p値色分け、β符号チェック、期待符号 vs 実際の整合性）

### 附属資料シート（グラフ専用、A4 横印刷）
- **公示地価推移**（折れ線グラフ、選定地点の直近5年分）
- **ヘドニック回帰係数 β**（横向き棒グラフ、全12特徴量の影響度を可視化）
- **散布図**（駅距離 vs 単価、全事例・top3 比較事例・査定対象の3系列を色分けプロット）

### 顧客用シート（流推方式準拠、A4 縦印刷）
- ですます調、係数・統計用語は完全非表示
- 査定結果サマリ／価格レンジ／標準価格／時点修正
- **公示価格の詳細**（縦並びの9項目：公示番号・公示価格・所在・最寄駅・前面道路・形状・地積・用途地域・容積率）
- 机上査定価格
- **比準表**（取引事例比較表、Excel 関数式で標準画地の試算値を計算）
- **個別格差**（角地・方位・不整形を青字でハイライト。ヘドニック補正に反映済みの説明表示であり、再適用しない）
- 査定の考え方／重要事項（机上査定の前提と免責）
- **件数不足時は「参考情報」モードに自動切替**（赤色バナー＋「査定書ではない」明記）

### 印刷設定（自動付与）

| シート | 用紙 | 向き | フィット |
|---|---|---|---|
| 業者用 | A3 | 横 | fitToWidth=1 |
| 附属資料 | A4 | 横 | fit-to-page |
| 顧客用 | A4 | 縦 + ヘッダ「机上査定書」 | fitToWidth=1 |

### OEM 対応

ツール提供元のブランド名は文書に出ません。顧客用シートは仲介業者が自社ブランドで配布できる中立的な表現で構成。データ出典（国土交通省）と「鑑定評価書ではない」旨は法的義務として残存。

## ヘドニック特徴量（v1.2.0、12 特徴量 + 定数項）

| 特徴量 | 種別 | 説明 |
|---|---|---|
| `ln_area` | 連続 | 面積の自然対数（規模効果） |
| `ln_area_sq` | 連続 | 面積²（規模逓減項） |
| `walk_min` | 連続 | 駅徒歩分 |
| `ln_shape` | 連続 | 形状指数 ln(間口²/面積)（帯地・旗竿地検出） |
| `ln_road_w` | 連続 | 道路幅員の自然対数 |
| `ln_far` | 連続 | 容積率の自然対数（行政条件） |
| `dir_score` | **Ordinal** | **方位スコア（北=0, 北東/北西=1, 東/西=2, 南東/南西=3, 南=4）** |
| `D_shidou` | ダミー | 私道フラグ |
| `D_fukuro` | ダミー | 袋地フラグ |
| `D_fuseikei` | ダミー | 不整形フラグ |
| `ln_district_mean` | 連続 | 地区平均単価の自然対数（ターゲット符号化） |
| `ln_station_mean` | 連続 | 駅勢圏平均単価の自然対数（ターゲット符号化） |

**期待符号**: `ln_area` `walk_min` `D_shidou` `D_fukuro` `D_fuseikei` は負、`dir_score` `ln_road_w` `ln_far` `ln_district_mean` `ln_station_mean` は正。実データで符号反転（有意な p < 0.10）した場合は業者用シートに警告色で表示。

## トラブルシューティング

| 症状 | 対処 |
|---|---|
| 「件数 N 件 < 15 件」警告 | 件数不足のためヘドニック回帰スキップ→類似度ベース集約に降格、顧客用シートは『参考情報』モード（赤色バナー）。隣接拡張は行わない方針のため、件数が極端に少なければ無理に査定価格を出さず、取れた事例を類似性順に並べて参考情報として提示 |
| MLIT CSV 必須列欠損エラー | MLITのダウンロード形式が変わった可能性。`load_mlit.py` の `MLIT_COLUMN_MAP` と `COLUMN_NORMALIZE` を確認 |
| MLIT CSV 文字化け | エンコーディング自動判定（utf-8-sig→cp932→shift_jis）に対応済み。新しい形式が出たら `_read_csv_auto_encoding` を確認 |
| 公示GeoJSON 市区町村名マッチング失敗 | `load_mlit.py` の `KOJI_CITY_NORMALIZE` に対象市区町村の短縮名→完全名マッピングを追加 |
| 時点修正年率が極端な値 | 標準地件数が少ない可能性。`time_adjust.py` の `_cagr_per_standard_point` のサンプル数を確認 |
| ヘドニック係数の符号反転警告 | データの分散・地域特性が原因。業者用シートの「β符号チェック」セクションで該当係数を確認、必要なら事例を絞り込み再実行 |
| 採用査定とヘドニック母集団予測の乖離率が30%超 | 規範性の高い事例が母集団から外れている可能性。事例選定のスコープ規則（市区町村単位・期間枠なし）を確認 |
| 角地補正が反映されない | JSON の `角地補正率(%)` 入力を確認（白箱ポリシー上、自動値は与えない） |
| 公示価格 1 地点の選定がイメージと違う | `main.py` の `_score_koji_point` のスコアリング（用途地域カテゴリ一致 0.4 + 容積率近さ 0.3 + 丁目一致 0.3）を確認 |

## バージョン履歴

- **v1.4.3 (2026-07-19)**: v1.2.3からv1.4.2まで、ヘドニック係数から算定した標準化補正・地域格差の適用方向に不整合があり、一部条件で比準表の試算値および最終査定価格へ影響する可能性がありました。補正計算を「事例から査定対象への変換倍率」に統一し、方位・不整形の二重適用を解消しました。比準表、最終査定価格、価格レンジ、散布図および顧客用シートが同じ補正後価格を参照するよう修正しました。あわせて、時点修正の根拠表示、未来データへのフォールバック、建物込み取引の混入、欠損列処理を修正し、期待値固定の回帰テストを追加しました。
- **v1.4.2 (2026-05-18)**: SKILL.md 冒頭に「実行時の絶対命令 6 箇条」を追加、業者用シート A2 セルに認証マーカー追加、Workbook プロパティに `creator` / `description` 設定、INSTALL.md に「出力検証チェックリスト」新設（ハルシネーション出力との判別容易化）
- **v1.4.1 (2026-05-18)**: `main_helpers.py` を `main_helpers_geo.py` + `main_helpers_koji.py` の 2 ファイルに分割（Cowork 配布層 truncate ライン 17 KB 対策）、`xlsx_gyosha_sheet.py` 関数冒頭に `print_area = "A1:N200"` を暫定設定（truncate されても印刷範囲が反映されるよう）
- **v1.4.0 (2026-05-17)**: ライセンスを **MIT → Apache License 2.0** に変更、全 .py に Apache ヘッダー追加、NOTICE 新設、GitHub Issues に 13 本起票（コミュニティで育てる OSS への移行）
- **v1.3.2 (2026-05-16)**: 業者用シート末尾に `ws.print_area` を明示指定（散布図用隠しデータ R-W 列を印刷範囲から除外、29 ページ → 4 ページ）
- **v1.3.1 (2026-05-16)**: 列幅消失バグ修正（`_adjust_col_widths` 呼び出しを関数冒頭に移動、Cowork 配布層 truncate 対策）
- **v1.3.0 (2026-05-16)**: Watcher を `tools/watch_cowork_outputs.py` として正式追加、`INSTALL.md` 新設（エンドユーザー向け導入手順）、README 全面リライト（「6 つの特徴」テーブル、競合言及全削除）、動的改ページ実装（業者用 4 ページ / 顧客用 3 ページ構成）、`pageBreakPreview` view モード設定
- **v1.2.9 (2026-05-16)**: `main.py`（28KB → 9.9KB）と `correction.py`（22.7KB → 17.1KB）を物理的に分割、`main_helpers.py`（16.6KB）と `hijun_breakdown.py`（5.8KB）を新設し全実行系ファイルを 20KB 未満に圧縮
- **v1.2.0 (2026-05-13)**: 鑑定書様式リファイン、OEM 化、公示価格1地点絞込、附属資料シート分離、方位スコア化（北=0, 南=4）、印刷設定自動付与
- **v1.1.0 (2026-05-11)**: OSS リブランディング、LightGBM 撤去、ハイブリッド設計（ヘドニック全期間 + 比準直近1.5年）
- **v1.0.0 (2026-05-10)**: MVP リリース

## ライセンス

Apache License 2.0

## 作者

松田幸一（不動産鑑定士）
運営：Signal Yield Advisory
配布：https://github.com/signal-yield/tochi-satei-kun