Skip to content

コーディングエージェントにアノテーション設定を書かせる方法

LLM が設定を書くときによくある失敗は、存在しない選択肢をでっち上げることです。JSON Schema とバリデーターがあれば、それは実行時の驚きからエディター上のエラーに変わります。

LLM がアノテーション設定を書くときにもっともよくある失敗は、存在しない選択肢をでっち上げることです。 モデルはもっともらしいものを出力し、サーバーは未知のキーを無視するかファイルを拒否し、エラーは数分後に「誰も設定していない挙動」として表面化します。機械可読なスキーマは、その失敗を書いているその瞬間へ前倒しします。

モードラインを追加する

設定ファイルの先頭に一行：

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

これで VS Code、JetBrains 系 IDE、Zed、Helix でライブ検証が有効になります。でっち上げられた annotation_type は入力しながら下線が引かれ、補完は実在するものを提示します。

Potato はこの行をすべてのサンプル設定に同梱しており、プレイグラウンドもダウンロードのたびに出力します。

CI で検証する

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

この JSON Schema は未知のキーに対して意図的に寛容です。サーバー自身が警告にとどめるためであり、より厳格なスキーマは動作する設定を拒否してしまうからです。そこで、未知キーを報告するプロジェクト自身のバリデーターと組み合わせてください。

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

--strict は未知のキーを致命的エラーとして扱います。これが annotaton_type のようなタイプミスを捕まえるものであり、寛容なスキーマはそれを黙って受け入れてしまいます。

エージェントに仕様を渡す

Claude Code、Codex、Cursor をあるツールに向けるなら、生成された仕様は散文のドキュメントより価値があります。誰かが覚えていたことではなく、コードが今日どう動くかを記述しているからです。

成果物カバー範囲
設定 JSON Schema設定キー 159 個、アノテーション形式 61 種類、表示形式 24 種類、加えて形式ごとの条件分岐
OpenAPI 3.1419 パス、456 オペレーション
llms.txt精選されたドキュメント索引

形式ごとの条件分岐はキー一覧より重要です。constant_sum スキーマには labels が必要だと、サーバーより先にエージェントへ伝えるのがこれだからです。

仕様はコードから生成する

ツールを使う側ではなく保守する側なら、この仕組みを成立させている性質は、スキーマがサーバーが検証に使うのと同じレジストリから生成されることと、ずれたときに CI が失敗することです。

手作業で保守するスキーマは、ないよりも悪いものです。信頼されてしまい、そして誰かがスキーマを更新せずに型を追加した最初の瞬間に間違ったものになるからです。

このサイトでの実践

このサイト自身の設定ビルダーも同じ作りです。Potato のレジストリをコミット済みの仕様ファイルに読み込み、すべてのフィールドをそれと突き合わせ、レジストリにないものは落とします。さらにハーネスが、生成されたすべての設定——アノテーション形式ごとに一つ、加えてすべてのスターターテンプレート——を validate_cli --strict に通します。

このハーネスは実際のバグを捕まえました。存在しないアノテーション形式、必須フィールドを欠いた三つのスキーマ、そして認可ユーザー一覧を黙って破棄していた重複 YAML キーです。いずれも出力を読むだけでは見えませんでした。

参考文献