코딩 에이전트에게 주석 설정을 맡기는 방법

LLM이 주석 설정을 작성할 때 가장 흔한 실패는 존재하지 않는 옵션을 지어내는 것입니다. 모델은 그럴듯한 무언가를 내놓고, 서버는 알 수 없는 키를 무시하거나 파일을 거부하며, 오류는 몇 분 뒤 "아무도 설정하지 않은 동작"으로 나타납니다. 기계 판독 가능한 스키마는 그 실패를 작성하는 그 순간으로 앞당깁니다.

모드라인을 추가한다

설정 파일 맨 위에 한 줄:

# 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에서 검증한다

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

이 JSON Schema는 알 수 없는 키에 대해 의도적으로 관대합니다. 서버 자체가 경고만 내기 때문이며, 더 엄격한 스키마는 잘 동작하는 설정까지 거부하게 됩니다. 그래서 알 수 없는 키를 보고해 주는 프로젝트 자체 검증기와 함께 쓰십시오.

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

--strict는 알 수 없는 키를 치명적 오류로 다룹니다. 이것이 annotaton_type 같은 오타를 잡아내며, 관대한 스키마는 그것을 조용히 받아들입니다.

에이전트에게 명세를 준다

Claude Code, Codex, Cursor를 어떤 도구에 붙일 생각이라면, 생성된 명세가 서술형 문서보다 값집니다. 누군가 기억하던 내용이 아니라 코드가 오늘 무엇을 하는지를 기술하기 때문입니다.

유형별 조건부 규칙이 키 목록보다 더 중요합니다. constant_sum 스키마에 labels가 필요하다는 사실을 서버보다 먼저 에이전트에게 알려주는 것이 바로 그것이기 때문입니다.

명세는 코드에서 생성한다

도구를 쓰는 쪽이 아니라 관리하는 쪽이라면, 이 방식을 성립시키는 성질은 스키마가 서버가 검증에 사용하는 바로 그 레지스트리에서 생성된다는 점과, 어긋났을 때 CI가 실패한다는 점입니다.

손으로 관리하는 스키마는 없는 것보다 나쁩니다. 신뢰를 받게 되고, 누군가 스키마를 고치지 않은 채 유형을 추가하는 첫 순간에 틀린 것이 되기 때문입니다.

이 사이트에서 하는 방식

이 사이트의 설정 빌더도 같은 방식으로 만들어졌습니다. Potato의 레지스트리를 커밋된 명세 파일로 읽어 들이고, 모든 필드를 그에 대조하며, 레지스트리에 없는 것은 버립니다. 그런 다음 하니스가 생성된 모든 설정을 — 주석 유형마다 하나씩, 그리고 모든 스타터 템플릿까지 — validate_cli --strict에 통과시킵니다.

그 하니스는 실제 버그를 잡아냈습니다. 존재하지 않는 주석 유형, 필수 필드가 빠진 스키마 셋, 그리고 인가된 사용자 목록을 조용히 버리던 중복 YAML 키입니다. 어느 것도 출력을 읽는 것만으로는 보이지 않았습니다.

더 읽을거리

• 기계 판독 가능한 명세
• 플레이그라운드
• 설정 기초