davidjurgens/potato-skill

Potato 어노테이션 태스크

Potato 태스크는 하나의 YAML 설정 파일과 데이터 파일로 구성됩니다. 이를 구축하는 작업은 세 가지로 나뉩니다: 무엇을 어떻게 질문할지 결정하고, 이를 올바르게 작성한 후, 로그인 화면에서 연구 종료까지 사용자가 실제로 진행하는 과정을 지켜볼 때까지 실행하는 것입니다. 두 번째 작업에는 검증 도구가 있어 여기서 시작하고 끝내고 싶은 유혹이 생깁니다. 하지만 태스크가 실제로 중단될 가능성이 가장 낮은 곳이기도 합니다.

프로젝트 루트에 AGENTS.md 파일이 있다면 이를 읽으십시오. 이 파일에는 이 문서 위에 추가된 프로젝트 규칙이 포함되어 있습니다.

설명 없이 호출된 경우

누군가 /potato-tasks를 입력했지만 대화에 어떤 설명도 없는 경우입니다. 바로 구축을 시작하지 말고, "무엇을 만들고 싶으신가요?"라고 묻지도 마십시오. Potato를 사용해본 적 없는 연구자는 이 질문에 유용하게 답할 수 없습니다.

한 문장으로 요청을 받고, 그로부터 디자인을 제안한 후, 추측해야 했던 부분만 확인하십시오. references/interviewing.md 파일이 질문 뱅크입니다: 시작 질문, 네 줄로 된 제안, 그 다음 모달리티, 단위, 응답 형식, 항목당 어노테이터 수, 품질 관리, 내보내기 대상 및 로그인 권한에 관한 두 라운드의 객관식 질문, 그리고 마지막으로 일곱 가지 기능 클러스터를 메뉴로 제공하고 선택된 것만 자세히 파고드는 세 번째 라운드로 구성됩니다.

특히 강조하는 두 가지 사항이 있습니다. 데이터의 모달리티가 무엇인지 항상 물어보십시오. 이는 디스플레이, 스키마 계열 및 미디어 위치를 결정하며, 이를 잘못 설정하면 오류 없이 조용히 실패합니다. 또한 단계(consent, training, prestudy)를 강요하지 마십시오. 이들은 프로토콜 결정 사항이며, 대부분의 태스크는 이들을 필요로 하지 않습니다. 이를 필요로 하는 연구자는 이미 알고 있습니다.

명시된 가정을 바탕으로 기다리지 않고 구축하는 기본 원칙은 여전히 유효합니다. 인터뷰에서 가정할 수 있는 내용이 생긴 이후에 적용됩니다. 아무런 맥락이 없는 상태에서는 당신이 어떤 추측을 하는 것보다 구조화된 네 가지 질문을 하는 것이 연구자에게 더 빠릅니다.

Potato 설치

이 스킬의 대부분은 potato 명령어를 실행하고 Potato의 레지스트리를 가져오는 데 사용됩니다. 패키지가 명령어를 실행하는 환경에 설치되어 있지 않으면 작동하지 않습니다.

potato --version || pip install potato-annotation

scripts/walk_task.py의 브라우저 워크에는 추가로 Playwright가 필요합니다: pip install 'potato-annotation[preview]' && playwright install chromium.

이 스킬의 스크립트

아래 절차 중 일곱 가지는 명령어가 아닌 스크립트로 제공됩니다. 수동으로 실행하기에는 너무 길고 반복적으로 실행하게 될 작업이기 때문입니다. 이 파일과 같은 디렉토리의 scripts/ 폴더에 있습니다.

스크립트	기능
boot_and_check.py config.yaml -p 8000	서버를 시작하고 200 응답을 기다린 후, 설정되었지만 아무것도 로드하지 못한 모든 기능을 나열합니다
walk_task.py --url … --config … --task-dir .	어노테이터를 등록하고 전체 연구를 진행하며 답변이 user_state.json에 도달했는지 확인합니다
estimate_effort.py config.yaml --rate 15	항목 수, 필요한 어노테이터 수, 각 항목당 소요 시간, 총 시간 및 비용을 추정합니다
find_design.py --type span --with-instructions	Potato Showcase에서 440개의 게시된 태스크 디자인을 검색합니다
handover.py config.yaml --confirm	테스트 중 만든 계정을 삭제하고 RUNNING.md 파일을 작성합니다
check_ui.py --url … --config config.yaml	모든 페이지를 렌더링하고 화면 아래에 숨겨진 스키마, 빈 미디어, 빈 선택 타일, 답변할 컨트롤이 없는 스키마, 수집되지 않는 답변, 위젯이 보고한 오류, 키바인딩 충돌 및 한 번도 나타나지 않은 스키마를 보고합니다. --phase poststudy는 워크가 접근할 수 없는 페이지를 측정합니다
study_status.py --url … --task-dir .	실행 중인 연구의 진행 상황, 어노테이터별 속도, 일치도 및 문제점을 보고합니다

각 스크립트는 --help 플래그를 지원하며, boot_and_check, walk_task, check_ui 및 study_status는 결과를 읽기보다는 활용하려는 경우 --json 플래그를 지원합니다.

루프

potato validate config.yaml --strict               # 구조 및 알 수 없는 키 검증
potato preview config.yaml                         # 폼이 선언하는 내용 미리보기
potato preview config.yaml --screenshot out.png    # 한 페이지 렌더링, 브라우저 오류 보고
nohup potato start config.yaml -p 8000 > server.log 2>&1 &    # 서버 시작 및 로그 읽기

처음 세 명령어는 즉시 반환됩니다. 네 번째 명령어는 반환되지 않습니다. 백그라운드로 실행하고, curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8000/로 200 응답을 폴링한 후 server.log를 읽으십시오.

potato --help는 이들을 other commands 아래, start 플래그 아래에 나열합니다. 각 명령어는 고유한 문법을 가지므로 potato validate --help와 potato preview --help에서 해당 옵션을 확인하십시오.

각 단계는 서로 다른 유형의 실패를 잡아냅니다

단계	잡아내는 것	놓치는 것
validate --strict	필수 키 누락, 잘못된 유형, 1~2단계 깊이의 알 수 없는 키	사이드 파일, 단계 유형, 스키마 항목 내부
preview	설정이 선언하는 스키마 및 키바인딩	실제로 렌더링되는지 여부
preview --screenshot	한 페이지에서 잡히지 않은 예외, console.error, 실패한 요청	900px 이하의 모든 것, 모든 조건부 위젯, 다른 모든 단계
서버 시작 + 로그 읽기	사이드 파일 형식, 단계 조립, 하위 시스템 초기화	실제로 어떻게 보이는지
브라우저에서 직접 실행	실제 연구	—

마지막 두 단계를 건너뛰면 검증과 스크린샷은 깨끗하지만 훈련 단계, 주의 집중 확인 및 항목의 1/3을 잃어버리는 태스크가 배포될 수 있습니다.

일찍 시작하세요

시작 로그는 실제 검증 도구입니다. validate가 열어보지 않는 설정 부분이 실제로 작동하는지 여부를 보고하는 유일한 도구입니다:

grep -E "ERROR|Traceback|Loaded [0-9]+|phase|missing required" server.log

훈련 및 주의 집중 확인이 있는 태스크의 정상적인 시작은 Loaded 3 training instances 및 Loaded 2 attention check items를 표시하며 단계에 관한 내용은 표시하지 않습니다. 다른 모든 것은 설정되었지만 꺼져 있는 기능을 의미합니다.

설정이 구문 분석되는 즉시 시작하십시오. 인터페이스가 완성되기 전, 지침이 작성되기 전에 말입니다. running-a-task.md에는 백그라운드 실행 방법, 준비 상태 확인 방법, 로그 라인 테이블 및 편집 후 삭제해야 할 생성 파일에 대한 설명이 있습니다.

세 가지 조용한 실패 모드

활성화가 실행을 의미하지는 않습니다. attention_checks.enabled: true와 잘못된 형식의 항목 파일은 경고 하나를 기록한 후 Loaded 0 attention check items를 표시한 다음 품질 관리가 꺼진 상태로 전체 연구를 실행합니다. 설정이 아닌 개수를 확인하십시오.

--strict는 모든 것을 검사하지 않습니다. 최상위 레벨과 대부분 블록의 한 단계 내부를 확인합니다. phases, surveyflow, quality_control, crowdsourcing, publish, automatic_assignment, ui, ui_config 내부 또는 annotation_schemes나 instance_display.fields의 항목 내부는 확인하지 않습니다. key_binding을 key_value 대신 사용하면 검증은 통과하지만 아무런 효과도 없습니다. 존재하지 않는 type:을 가진 단계도 마찬가지입니다.

스크린샷은 페이지가 아닌 뷰포트입니다. --screenshot은 1280×900 크기로 저장됩니다. 지침 배너가 있는 태스크의 경우 배너와 항목의 절반만 보여주며 질문은 전혀 보여주지 않습니다. "PNG를 보고 다음 버튼이 화면 위쪽에 있는지 확인하세요"라는 조언은 이 도구만으로는 따를 수 없습니다. 브라우저를 직접 실행하고 full_page=True로 스크린샷을 찍으십시오.

이미 가지고 있는 것 파악하기

설명과 데이터 파일이 일반적인 경우이지만 유일한 경우는 아닙니다. 아무것도 디자인하기 전에 네 가지를 물어보십시오. 각각에는 명령어가 있고, 설정을 작성한 후에 발견하면 비용이 많이 들기 때문입니다:

질문	이유
데이터 형식은 무엇이며 미디어는 어디에 있습니까?	대본 및 대화 코퍼스에는 자체 변환기가 있습니다
이미 어노테이션이 있습니까?	potato import는 14가지 형식을 읽고 실행 가능한 프로젝트를 작성합니다
최종적으로 무엇이 출력되어야 합니까?	29가지 내보내기 형식이 있습니다. 어노테이션을 시작하기 전에 대상을 확인하십시오
인계 후 누가 얼마나 오랫동안 실행합니까?	호스팅, 로그인 및 허용 목록을 결정합니다

potato import --list-formats                      # coco, cvat, labelme, labelbox, via, …
potato transcripts interviews/ -r --dry-run       # whisper, srt, vtt, textgrid, eaf, …
potato convokit reddit-corpus-small --unit conversation --emit-config

references/importing-existing-work.md는 세 가지 모두를 다루며, 가장 중요한 한 가지 결정도 포함합니다: 가져온 어노테이션이 사람이 수정하는 사전 어노테이션인지, 아니면 항목을 완료로 표시하는 --seed-user 작업인지입니다.

불완전한 설명

설정을 작성하기 전에 references/asking-the-experimenter.md를 읽으십시오. 잘못 판단해도 비용이 적게 드는 경우 직접 결정하고, 비용이 많이 들거나 되돌릴 수 없거나 자신의 것이 아닌 경우(어노테이션 단위, 어노테이터 예산, 동의 문구, 식별 가능한 사람과 관련된 모든 것)는 질문하십시오.

답변을 기다리지 마십시오. 명시된 가정을 바탕으로 구축하고, 실행 가능한 결과물과 함께 질문을 QUESTIONS.md에 기록한 후, 가장 먼저 재검토해야 할 가정을 명시하십시오.

기능을 직접 구축하기 전에 먼저 찾아보십시오

Potato는 설정 참조 문서에서 명확하게 드러나는 것보다 더 많은 내장 기능을 가지고 있습니다. 비용이 많이 드는 실수는 존재하지 않는 유형 이름을 발명하는 것이 아닙니다. 검증이 이를 잡아냅니다. 실제 비용이 많이 드는 실수는 Potato가 이미 수행하는 작업을 수동으로 조립하는 것입니다.

references/modes-and-subsystems.md는 연구자의 말을 해당 작업을 수행하는 블록에 연결하는 라우팅 테이블입니다: QDA 및 코드북, 단독 모드, 방, 조정, 검토 워크플로, 세션, 포켓, 능동 학습, 심사자, 크라우드소싱, 게시, 텔레메트리. 해결 방법처럼 보이는 스키마를 작성하기 전에 이를 확인하십시오.

이 문서는 일곱 가지 클러스터(자료, 답변, 단위, 사람, 신뢰, 모델 지원, 출력)로 시작하며, 이는 인터뷰가 메뉴로 제공하는 것과 동일한 맵입니다. 설명에 대해 체크리스트로 실행하십시오: 설명에서 언급되지 않은 클러스터는 연구자가 원하는 것을 놓칠 가능성이 가장 높은 곳입니다. 그 중 최대 두 가지만, 그리고 그것들이 중요한 경우에만 제기하십시오. 나머지는 QUESTIONS.md에 기록하십시오.

연구자들이 가장 일관되게 놓치는 클러스터는 답변입니다. 그들은 radio와 likert를 요구하고 멈추며, soft_label, range_slider, semantic_differential, constant_sum 및 confidence는 결코 도달하지 못합니다.

디자인하기

references/designing-a-task.md는 모든 태스크 뒤에 있는 일곱 가지 결정(단위, 질문, 응답 형식, 항목당 어노테이터 수, 항목 순서, 품질 관리 및 양쪽 단계)을 다룹니다.

라우팅 테이블은 일반적인 요청과 중단점을 다룹니다. 11가지 유형은 생성된 참조 문서 외에는 어디에도 이름이 지정되지 않아 결코 도달하지 못합니다: multirate(10개의 등급을 하나의 척도에, 10개의 likert 스키마가 아님), hierarchical_multiselect(축소된 분류 체계, 검색 포함), select, soft_label(강제 선택이 아닌 분포), range_slider, semantic_differential, conjoint, card_sort, extractive_qa, multi_document_event, code_review. 각각은 작동하는 예제와 designing-a-task.md의 행을 가지고 있습니다.

잘못하기 쉽고 늦게 발견하면 비용이 많이 드는 두 가지:

• 응답 형식이 일치도 지표를 결정합니다. Potato는 스키마 종류에서 이를 선택합니다. radio로 저장된 1-5 등급은 순서가 없는 것으로 채점되므로 "1 대 2"와 "1 대 5"가 동일하게 계산됩니다. 이는 측정 오류이며 외관상의 문제가 아닙니다. 표는 references/assignment-and-agreement.md에 있습니다.
• num_annotators_per_item은 목표를 설정하고, max_annotations_per_user는 한 사람이 실제로 보는 것을 설정합니다. 설정하지 않으면 상한은 항목 수이므로 모든 사람이 전체 코퍼스를 제공받습니다. 그 이하로 설정하면 어노테이터는 이유 없이 일찍 중단합니다. automatic_assignment.instance_per_annotator는 이에 대한 키처럼 보이지만 전혀 읽히지 않습니다.

디자인 기록 및 비용

설정 옆에 있는 두 파일로, 설정이 보유할 수 없는 내용입니다:

• DESIGN.md — 어노테이션 단위와 그 이유, 각 응답 형식을 선택한 이유, 항목당 어노테이터 수, 품질 관리의 목적, 그리고 설명에 명시되지 않아 가정한 선택 사항을 별도로 명시한 목록입니다. 마지막 문단이 이 문서를 열어볼 가치가 있게 만듭니다.
• QUESTIONS.md — 전혀 결정할 수 없었던 사항입니다. 답변을 기다리지 마십시오. 질문과 함께 실행 가능한 결과물을 제공하십시오.

python .claude/skills/potato-tasks/scripts/estimate_effort.py config.yaml --rate 15

디자인에 필요한 어노테이터 수, 각자의 작업 시간, 총 시간 및 비용을 보고합니다. 지침을 작성하기 전에 실행하십시오. 아무도 감당할 수 없는 디자인을 발견하기에 가장 저렴한 장소입니다.

references/recording-decisions.md에는 DESIGN.md 템플릿과 추정치를 변경하는 사항이 있습니다.

게시된 디자인에서 시작하기

필드 목록에서 스키마를 작성하기 전에 누군가 이미 실행한 디자인을 찾아보십시오:

python .claude/skills/potato-tasks/scripts/find_design.py --query "stance" --with-instructions
python .claude/skills/potato-tasks/scripts/find_design.py --show text/argumentation-stance/argument-quality

Potato Showcase에는 440개의 어노테이션 태스크 디자인이 있으며, 대부분은 게시된 논문을 기반으로 하고 실제 레이블 세트와 실제 질문 문구를 포함합니다. 그리고 그중 281개는 서면 지침을 포함하고 있습니다. 그중 어느 것도 phases 블록, 동의 페이지 또는 훈련 라운드가 없으므로, 거기서 질문을 가져오고 worked-example.md에서 연구 주변 구조를 가져오십시오. references/finding-a-design.md는 재사용하기 전에 변경해야 할 사항을 다룹니다.

지침 작성

설정 뒤에는 검증 도구가 있습니다. 어노테이터가 읽는 텍스트에는 그런 것이 없으며, 완성된 데이터셋의 불일치 대부분이 여기서 발생합니다.

references/writing-guidelines.md는 어노테이터 대상 텍스트가 있을 수 있는 네 가지 표면(instructions 단계, annotation_instructions 배너, annotation_codebook_url, 스키마별 description), 논쟁을 해결하기 위해 레이블 정의에 포함되어야 하는 내용, 동점 해소 규칙, 경계 사례를 포함한 작업 예제, 파일럿의 불일치를 바탕으로 지침을 반복하는 방법을 다룹니다. examples/advanced/long-guidelines/는 이 모든 것의 작동 모델입니다.

더 읽지 않고도 올바르게 처리해야 할 두 가지 사항:

• 배너는 코드북이 아닙니다. annotation_instructions는 모든 페이지 상단에 위치하며, 코드북은 별도 URL로 연결됩니다. 배너는 방향 제시용이지 참조용이 아닙니다.
• 레이블은 '동의함'이 아니라 '무엇에 동의함'이어야 합니다. 딱 한 문장으로 정의하십시오. 모호한 레이블은 낮은 신뢰도로 이어집니다.

도움말 참조

이 파일은 대부분의 일반적인 질문과 실패 모드를 다룹니다. references/ 디렉토리에는 더 깊은 내용이 있습니다:

파일	대상 독자
asking-the-experimenter.md	연구자 인터뷰
designing-a-task.md	디자인 결정
finding-a-design.md	기존 디자인 검색 및 재사용
importing-existing-work.md	기존 어노테이션 가져오기
interviewing.md	구조화된 질문 스크립트
modes-and-subsystems.md	기능 라우팅 테이블
recording-decisions.md	DESIGN.md 템플릿
running-a-task.md	서버 운영 세부 사항
writing-guidelines.md	어노테이터를 위한 지침 작성
assignment-and-agreement.md	할당 및 일치도 지표

potato --help 및 각 스크립트의 --help도 CLI 옵션에 대한 참조 역할을 합니다.

태스크 완료

설정이 검증되고, 브라우저에서 실행되고, 데이터가 수집되면 태스크를 인계할 준비가 되었습니다:

python .claude/skills/potato-tasks/scripts/handover.py config.yaml --confirm

이 명령어는 테스트 계정을 제거하고, 연구 실행 방법을 설명하는 RUNNING.md를 작성하며, 최종 설정을 정리합니다.

handover는 estimate_effort 및 study_status와 함께 작동하며, 모든 데이터가 수집되었고 비용이 예산 내에 있는지 확인합니다.

Potato 태스크 구축에 행운을 빕니다!