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에 통과시키는 하니스를 갖추고 있습니다.

관련 문서