2. AGENTS.md — AI に「失敗しない」使い方を伝える

データ出版者が AI エージェントに向けて書く AGENTS.md の書き方と、その効果を学びます。

AGENTS.md とは

AGENTS.md は、AI エージェントがデータを正しく使うための「取扱説明書」です。GIS 専門家の知見を、エージェントが参照できる形で書き残します。

エージェントは「説明書がなければ試行錯誤を繰り返す」。加えて API ドキュメントや独自仕様を毎回解釈するのは非効率です。先行して AGENTS.md を読ませることで、最初から正しいパスでクエリを発行できます。

何を書くのか

Portolan の AGENTS.md は、次の 5 項目を必ず含めると破綻が少ないです。

  1. データの概要 — このコレクションに何が含まれるか
  2. クエリの推奨パターン — 速い・確実なアクセス方法
  3. 座標系（EPSG） — 変換が必要か、どの EPSG を使うか
  4. 既知の制限 — 欠損・更新頻度・使えないフィールド
  5. ライセンス条件 — 出典表示の要否・商業利用の可否

書く内容の例

# このコレクションの使い方

## 概要
全国の公園のポイントデータ（ID・名称・緯度経度・面積）。

## 推奨クエリパターン
- 空間フィルタは lead_status カラムに index を使うと高速
- 緯度経度は経度(lng)、緯度(lat) の順で格納されている

## 座標系
- 座標系は EPSG:3857 なので、利用時は EPSG:4326 に変換
- 変換例: ST_Transform(geom, 4326)

## 既知の制限
- データの一部に欠損がある（update 頻度は 月次）
- 一部のレコードは名称なし（約 2%）

## ライセンス
- CC BY 4.0 — 出典明記が必要

なぜ効果的なのか

エージェントは失敗した後に試行錯誤するよりも、あらかじめ正しい手順を読んでから実行するほうが速く・安定します。さらに、AGENTS.md があれば、エージェントが勝手に推測して重大な誤り（例: 座標系を無視して測量）を犯す確率を下げられます。

書き方のコツ

1. 短く、具体的に

「EPSG:4326 に変換してから使うこと」のように命令形で書くとエージェントが従いやすいです。抽象的な説明より、具体例を 1 つ入れるほうが効果的です。

2. テスト済みのクエリを載せる

自分で一度実行して成功したクエリパターンを載せます。エージェントはそれをそのまま使いやすくなります。

パターン 効果
空間フィルタを使う GeoParquet では INDEX 必須
必要な列だけ指定 転送量を削減
座標系を明示 変換ミスを防止

3. 「使ってはいけない」も書く

可能なこと・不可能なことを明示すると、エージェントが無駄な試行をしません。

- item 検索（個別フィーチャ単位）は未対応
- フィールド: shape_area は geodetic でなく平面投影の値

チェックリスト

  • データの概要を冒頭に 1 文
  • 推奨クエリパターン（テスト済み）を記載
  • EPSG と変換先を明記
  • 制限事項・更新頻度を記載
  • ライセンス条件を明記
  • 日本語／英語どちらでも可（エージェントは両方理解）

次のステップ