Skip to content

機械可読な仕様

設定用の JSON Schema と API 用の OpenAPI ドキュメント。どちらもコードから生成され CI で検査されるため、コーディングエージェントは選択肢をでっち上げることなく Potato を設定できます。

Potato は散文のドキュメントと並べて、生成された機械検査可能な契約を二つ公開しています。 どちらも手作業で保守するのではなく実行中のコードから生成されるため、誰かがページを最後に編集したときに覚えていたことではなく、Potato が実際に行うことを記述しています。

コーディングエージェントに Potato を扱わせるなら、この二つと llms.txt が渡すべきもっとも価値の高い材料です。

成果物記述する内容
設定 JSON Schemaタスクの config.yaml における有効なキー、アノテーション形式、表示形式のすべて
OpenAPI 3.1 仕様サーバーが登録するすべての HTTP エンドポイント

設定スキーマ

バージョン 2.8.0 はトップレベルの設定キー 159 個、アノテーション形式 61 種類、表示形式 24 種類を、形式ごとの条件分岐も含めてカバーします。そのため constant_sum スキーマには、サーバーが拒否する前に labels が必要だと伝えられます。

任意の設定ファイルの一行目にモードラインを追加すれば、VS Code、JetBrains、Zed、Helix で入力しながら検証されます。

yaml
# yaml-language-server: $schema=https://potatoannotator.readthedocs.io/en/latest/schemas/potato-config.schema.json

Potato リポジトリに同梱されるすべての設定がこれを持っており、プレイグラウンドもダウンロードのたびに出力します。

CI では次のように使います。

bash
check-jsonschema --schemafile \
  https://potatoannotator.readthedocs.io/en/latest/schemas/potato-config.schema.json \
  path/to/config.yaml

未知のキーも併せて報告するローカルのバリデーターを使う場合は次のとおりです。

bash
python -m potato.validate_cli --strict config.yaml

API 仕様

419 パス、456 オペレーション。手書きではなく、稼働中の Flask ルートマップを走査して得ています。設定で有効化されるブループリントは使い捨てのアプリに登録して黙って抜け落ちないようにし、エンドポイントごとの認証は AST 走査で復元しています。

規模の比較として、以前の手書きリファレンスは 400 を超える登録ルートに対して 84 エンドポイントしかカバーしていませんでした。

ずれれば CI が失敗する

両方の成果物は CI で再生成され比較されます。コードからずれうるスキーマは、スキーマがないより悪いものです。信頼されてしまうからです。

なぜ今これが重要なのか

LLM が Potato の設定を書くときにもっともよくある失敗は、存在しない annotation_type をでっち上げることです。エディターやエージェントがオフラインで解決できる JSON Schema を配布することで、これを根本から解消します。

このサイト自身の設定ビルダーも同じ考えの上に成り立っています。プレイグラウンドは Potato のレジストリを読み、そこに含まれるキーしか出力できません。さらに、生成されたすべての設定を validate_cli --strict に通すハーネスを備えています。

関連ページ