geo-software-tdd · git:20261114.05b9cc4 · 2026-11-14 · sha256 2a41752c10c89d9b

geo-software-tdd git:20261114.05b9cc4A

Immutable. This exact content never changes and is served at /api/v1/blob/2a41752c10c89d9b.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_nqv7nct52cmknljx/2a41752c10c89d9b886489ca6a17de703c48563155077728eb6dc1912c96318c.json

Then /plugin install geo-software-tdd@markdownregistry-nqv7nct52cmknljx in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: geo-software-tdd
description: 地図プロダクトを作る実装者が、人間の確認の前に成果物の品質をできるだけ上げるために、テストを先に書き、CI で落とす仕組みを自分で組む。純粋な処理、地図に載せるデータ、サーバー、画面の配線、本物のブラウザでの地図、描画の比較、操作、性質や差分の試験、壊れた入力までを、地図のライブラリ (MapLibre、Leaflet、OpenLayers、CesiumJS、deck.gl、MapLibre Native、mln-rs、ezu、forge3d、RustGIS、GeoPandas、cartopy、matplotlib、folium) と非 GPL の OSS の地図アプリが実際に行っている作法に沿って書く。試験は手元のデータで閉じ、公開のサーバーを呼ばず、CI は 1 つの合否にまとめ、不安定な試験は期限つきで隔離する。「TDD で」「テストを書いて」「CI を組んで」「品質を上げて」「回帰を防いで」と言われたとき、geo-software-build で作るあいだずっと使う。完成の判定は geo-software-eval の評価で行い、このスキルの試験では行わない。
---

# geo-software-tdd

人間がコードを読まないダークファクトリーでは、人間が見る前に、実装者が自分で品質を上げきる必要がある。その道具がテストと CI である。このスキルは、実装者が書く試験の種類、試験のデータと通信、CI の組み立て、不安定な試験の扱い、エージェントが試験を書くときの決まりを、地図のライブラリと地図アプリが実際に行っている作法から定める。

試験は実装者が見て書くものなので、正しさの最終の判定には使わない。最終の判定は、実装者に本文を見せない geo-software-eval の評価で行う。このスキルの試験が守るのは「作りながら壊さない」と「同じ不具合を二度出さない」であり、評価が見るのは「利用者の目的を果たすか」である。

| reference | 読むとき | 中身 |
|---|---|---|
| [characterization-legacy](references/characterization-legacy.md) | 既存ソフトの改修・機能追加、依存更新、全面作り直しのとき | 旧ソフトを正本として特性テストを追加し、新環境へ厳密に移植してから TDD で進める手順 |
| [kinds](references/kinds.md) | 何の試験を書くか決めるとき | 地図のプロダクトの試験の種類と、それぞれの書き方と合否の決め方 |
| [fixtures](references/fixtures.md) | 試験のデータと通信を用意するとき | 手元で閉じる試験、タイルとフォントの持ち方、通信の差し替え、公開のサーバーを呼ばない仕組み |
| [ci](references/ci.md) | CI を組むとき | 段の分け方、1 つの合否、GPU の無い CI での描画、版の両端、ライセンスと大きさの関門 |
| [discipline](references/discipline.md) | 試験を書くとき、試験が落ちたとき、不安定なとき | エージェントが試験を書くときの決まり、不安定な試験の隔離、許容の扱い、試験の仕組みそのものの確かめ |
| [sources](references/sources.md) | 作法の根拠を確かめたいとき | どのライブラリやアプリが、どのファイルでそうしているか |
| [scripts/tdd_guard.py](scripts/tdd_guard.py) | CI の関門と試験の隔離・通信遮断を動かすとき | 不安定な試験の隔離台帳の検証 (理由・担当・期限切れ・通った試験の検出)、TODO/FIXME の減る方向にだけ動く上限 (ratchet)、外部ホストへのソケット通信遮断 |
| [assets/ci-checklist.md](assets/ci-checklist.md) | CI を組み終えたとき | 組んだ CI の点検表 |

## 原則

1. 試験を先に書く。直すときは、直す前に落ちる試験を書き、直したら通ることを確かめる。直す前に落ちない試験は、その不具合の試験ではない。
2. 地図に触れる試験は、本物のブラウザで動かす。地図のライブラリは WebGL と DOM の配置に依存するので、jsdom のような偽の DOM では大事なところが見えない。純粋な処理 (スタイルの組み立て、データの変換、URL の作成) は Node や Python や Rust の単体の試験にする。
3. 試験は手元で閉じる。タイル、フォント、スプライト、スタイル、外部の API は、手元のデータと手元のサーバーで用意し、公開のサーバーを呼ばない。呼んだら試験を落とす。
4. 数で言えるものは数で判定する。地図の絵は、描けたか (真っ白でないか)、何個描けたか、どの色が何画素あるかで先に判定し、絵でしか言えないものだけを基準の画像と比べる。比べるときは許容を明示し、差分の画像を残す。
5. 許容は黙って緩めない。環境ごとの違いは、環境ごとの基準の画像や期待値で受け止め、1 つの許容を広げて隠さない。
6. 不安定な試験は、理由、担当、期限を書いて隔離する。再試行は 1 回までにし、再試行のときは記録を増やす。隔離した試験が通るようになったら、隔離の一覧を落として気づく。
7. CI は 1 つの合否にまとめる。合否の段が通らなければ、マージも公開もしない。毎晩の重い段は、落ちたら issue を立てる。
8. 試験の仕組みそのものを疑う。基準の画像を「実際の出力」として流して通ること、わざと壊した版で落ちること (geo-software-eval の eval-of-eval と同じ考え方) を確かめる。

## 進め方

1. 作り始める前に、[kinds](references/kinds.md) から、このプロダクトで要る試験の種類を選び、プロダクト概要の「技術選定の結果」の実装の節に書く。地図に載せるデータ、サーバー、画面の配線、地図の描画、操作のそれぞれに、少なくとも 1 種類を当てる。
2. 試験の道具と CI を最初に通す ([ci](references/ci.md))。空の試験が CI で回り、公開のサーバーへの通信で落ちる仕組み ([fixtures](references/fixtures.md)) が効くことを、わざと外へ通信する試験で確かめてから、本物の試験を書き始める。
3. geo-software-build の [order](../geo-software-build/references/order.md) の段ごとに、試験を先に書き、落ちるのを見てから作る。1 段ごとに試験、型検査、ビルドを通してコミットする。
4. 不具合を見つけたら (自分の確かめ、評価者から返った症状、監査の指摘)、まず症状を再現する試験を書き、落ちることを確かめてから直す ([discipline](references/discipline.md))。評価者から返った症状は、シナリオの本文ではなく症状だけから試験にする。
5. 描画の試験は、基準の画像を作ったら、自分の目で見てから採用する。初めの基準の画像が誤っていると、以後の試験は誤りを守り続ける。
6. 公開の前に [assets/ci-checklist.md](assets/ci-checklist.md) で CI を点検する。点検の結果と、隔離した試験の一覧を、朝の報告に入れる。
7. 公開のあと、本番に向けた読み出しだけの確かめ (geo-software-deploy の smoke) と、毎晩の重い試験の結果を、geo-software-swarm の見つける役割に渡す。

## 出力

- 試験の一式と CI の設定 (リポジトリの中)。README に、試験の動かし方、試験のデータの出どころ、公開のサーバーを呼ばない仕組みを書く。
- プロダクト概要の更新: 選んだ試験の種類、CI の合否の段、隔離した試験の一覧 (理由、担当、期限)。

## 注意

- 試験が全部通ることは、完成ではない。完成は geo-software-eval の評価で決まる。実装者は評価のシナリオの本文を見ず、評価に合わせた分岐を入れない。
- 試験のために本番の外部サービスや公開の OSM のサーバーを呼ばない。試験のデータは、出どころとライセンスを書いて置く。
- GPL のライブラリやアプリの試験のコードは読まず、写さない。ここに挙げた作法は、ライセンスを確かめた非 GPL のものから取り、自分の言葉で書いた。
- 長く動く試験 (ブラウザ、描画、ファジング) は、メモリと CPU に上限を掛けて流す。