시트를 플레이북으로
Repo: ingest/ingest.py가 있는 폴더(Claude Code가 클론에서 열렸다면 현재 프로젝트). 아래 모든 경로는 이 폴더 기준입니다. 3단계 전에 ingest/RAW_FORMAT.md를 읽으세요: 여기에 전사 형식과 플레이북 작성 규칙이 있습니다.
목표는 아무것도 지어내지 않고 당일에 속도를 내는 것입니다. 웹사이트의 모든 줄은 사진이나 음성 노트로 추적 가능해야 합니다. ingest.py verify가 이를 강제합니다.
각 단계에서 무엇을 하는지 한두 줄로 사용자에게 알려주세요. 아래 단계별 시간은 대략 12개 테이블 기준입니다.
행사 전, playbook.config.json에 주최자 이름과 플레이북 웹 주소(약속 카드의 QR 코드가 가리키는 곳)가 있어야 합니다. 아직 기본값이 그대로라면 알려주되 계속 진행하세요: 설정은 이름과 색상만 바꿀 뿐 내용은 바꾸지 않습니다. verify, draft, publish에 --config <file>을 사용하면 다른 설정 파일을 선택합니다.
1. 준비 (1~2분)
python3 ingest/ingest.py prepare "<폴더>"
python3 ingest/ingest.py transcribe # 폴더에 음성 노트가 있을 때만; 백그라운드에서 실행
prepare는 runs/ 아래에 새 실행을 만들고(그리고 runs/latest가 이를 가리키도록 함): 사진을 똑바로 회전하고, HEIC를 변환하며, 사진별 선명도 점수, 자세히 보기 위한 2x2 타일, contact/에 연락처 시트를 만듭니다. 음성 노트는 16kHz WAV로 변환합니다. transcribe는 로컬 Whisper(small.en, 한 번 다운로드하면 오프라인 사용 가능)를 사용하며, 각 노트의 테이블을 시작 부분의 "Table seven…"에서 추측합니다.
두 번째 배치(첫 번째 절반이 진행 중일 때 추가 사진이나 카드): python3 ingest/ingest.py prepare "<폴더>" --into <run>으로 같은 실행에 추가합니다. 새 ID는 마지막 ID(P022…)에서 이어지며, 레이블과 원본 파일은 유지되고, 이미 실행에 있는 파일은 건너뜁니다. 그런 다음 새 ID만 레이블링합니다.
2. 레이블링 및 적용 범위 확인 (약 5분; 시간이 중요하므로 먼저 수행)
모든 연락처 시트(contact/sheet-*.jpg)를 보고, 썸네일이 불명확한 경우 view/의 사진을 확인합니다. 실행 폴더에 labels.json을 작성합니다:
{"photos": {"P001": {"table": 7, "sheet": "S2"}, "P014": {"kind": "stubs"}, "P020": {"kind": "other", "note": "방 사진"}},
"audio": {"A01": {"table": 7, "by": "speech"}}}
- 각 시트는 하단 모서리에 인쇄된 코드(S1, S2, S3, SS)와 인쇄된 제목이 있으며, 테이블 번호는 테이블 리더가 오른쪽 상단 원과 코드 옆(
S2 · Table 7)에 손으로 씁니다. 키트의 기본 제목: S1 "어디서 지원이 막히나요?", S2 "무엇이 도움이 되었거나 되지 않았나요?", S3 "사람들이 지금 시도할 수 있는 것은 무엇이며, 어떻게 지속되나요?", SS 사이드 시트 "좋은 것을 들었나요? 여기에 적어주세요." (인용문 · 질문 · 자료). 주최자가 질문을 변경했다면 인쇄된 코드를 따르세요. 원과 모서리가 일치하지 않으면 펜 색상과 내용으로 판단합니다: 해당 테이블의 다른 시트를 확인하세요. transcribe가 이미 채운 오디오 레이블은 전사본의 첫 줄과 대조한 후 유지하세요.- 동일한 코드와 테이블 번호를 가진 두 개의 다른 시트(
status는 사진이 여러 장인 시트를 나열합니다: 확인 필요): 국가와 내용이 겹치면 한 테이블이 두 부를 사용한 것입니다. 두 사진 모두 해당 번호로 레이블링하고 판독자는 둘 다 전사합니다. 명확히 두 테이블이면 두 번째 테이블에 91부터 시작하는 여분 번호를 부여하고,"note": "wrote 22; second table"을 추가한 후 사용자에게 알립니다. 어느 테이블이 "두 번째"여도 됩니다. 하나를 선택하고, 검토자가 구분할 수 있도록 메모(분야, 펜 색상)에 둘 다 설명합니다. - 테이블 번호가 보이지 않는 클로즈업(예: 집계 박스만): 일치하는 시트로 레이블링하고
"note": "table inferred from <일치한 항목>"을 추가합니다. - 한 사진에 두 시트(나란히 고정):
"sheet": ["S2", "S3"]으로 레이블링하여status가 두 시트 모두에 대해 집계하도록 하고, 판독자가 어느 쪽이 어느 것인지 알 수 있도록 메모에 추가합니다. prepare는 프레임에서 거꾸로 된 사진을 회전할 수 없습니다(읽을 회전 플래그가 없음). 판독자는 처리 가능하지만 메모에 알립니다. 카드 사진은 시트보다 선명도 점수가 낮습니다(평범한 카드, 얇은 펜). 따라서 BLURRY? 카드는 재촬영을 요청하기 전에view/에서 확인하세요.
그런 다음 python3 ingest/ingest.py status를 실행하고(테이블이 12개가 아닌 경우 --tables <n> 추가) MISSING 또는 BLURRY 시트가 있으면 즉시 사용자에게 알리세요. 연락처 시트는 LOW-RES(메시징 앱을 통해 전달: 글씨가 크면 괜찮음)와 DARK(보통 읽을 수 있음)도 태그합니다. 언급하지만 재촬영 대상은 아닙니다. 이상적으로 이 확인은 시트가 아직 벽에 붙어 있고 다시 촬영할 수 있을 때 이루어져야 합니다.
3. 각 테이블 전사 (병렬, 약 5~10분)
테이블당 하나의 하위 에이전트(Agent 도구, general-purpose, 백그라운드, 한 메시지에 모두)를 생성하고, 카드 스텁이 있으면 그를 위한 에이전트도 하나 생성합니다. 모델을 다운그레이드하지 마세요: 손글씨 정확도가 중요한 부분입니다. 각 프롬프트는 독립적이어야 하며 다음을 포함해야 합니다:
- 절대 repo 경로, 실행 폴더, 테이블 번호, 사진 ID(
view/<id>.jpg및manifest.json에 나열된 타일), 음성 전사본 경로(있는 경우). - "
ingest/RAW_FORMAT.md1단계를 읽고 정확히 따르세요. 실행 폴더에raw/T<nn>.json을 작성한 다음python3 ingest/ingest.py verify --run <run>을 실행하고 파일에 대한 오류가 있으면 수정하세요. 짧은 요약(시트별 항목 수, 모든unclear항목, 생략한 모든 취소선 단어)으로 답변하세요." - 스텁의 경우: 1단계 끝에 설명된 대로
raw/commitments.json을 작성하되, 카드의 선택적 이름 및 조직 줄을 정확히 쓰고, 그곳의 카드 규칙(찢어지지 않은 카드, 서명, 두 사진에 걸친 한 카드)을 따르세요.
실행되는 동안 음성 전사본(있는 경우)을 직접 읽어 작성 전에 방 분위기를 파악하세요.
4. 플레이북 작성 (약 10~15분)
RAW_FORMAT.md 2단계를 따르세요. <run>/session.json을 meta.status: "draft"로 작성하세요. meta는 examples/session-template.json에서 시작하고, 사용자가 알려주는 이벤트 세부 정보(이벤트 이름, 날짜, 장소)를 채우세요. people은 실제 참석자 수를 알면 설정하세요. 절대 추측하지 마세요: 필드는 템플릿 그대로 두고 사용자에게 나열하세요.
5. 검증, 수정, 검토 패키지 생성
python3 ingest/ingest.py verify --links
python3 ingest/ingest.py draft # <run>/playbook-draft.html: 점선 상자 = 빈칸, 태그 = 출처
python3 ingest/ingest.py review # <run>/review.html: 모든 항목을 사진 옆에 표시
모든 오류(추적 불가능한 줄, 변형된 인용문, 남아 있는 이름)를 수정하고 verify가 통과할 때까지 다시 실행하세요. 경고는 사람이 검토할 사항입니다: 보고하되 무시하지 마세요.
그런 다음 사용자에게 검토 요약을 제공하세요: 문제점과 병합된 테이블, 사진 ID가 포함된 모든 unclear 판독, 판독자가 생략한 모든 취소선 단어, 사용되지 않은 원시 항목, 링크 문제, 그룹화에 확신이 없는 모든 것. review.html은 각 판독자의 메모와 "이 테이블에는 누가 있나요?" 집계를 각 테이블 아래에 표시합니다. 사용자를 위해 review.html과 playbook-draft.html을 여세요.
불확실한 단어가 많습니까? 검토 앱이 review.html을 처음부터 끝까지 읽는 것보다 빠릅니다: python3 tools/review/make_review.py --run <run>은 <run>/review/index.html을 생성하며, 불확실한 판독마다 하나의 카드와 손글씨 클로즈업을 제공합니다. 사용자가 각각을 확인하거나 수정하고, 결정 파일을 저장한 후 python3 tools/review/apply_review.py --run <run> <decisions.json>이 판독 내용을 원시 파일과 session.json에 다시 씁니다. 이후 verify와 draft를 다시 실행하세요. 불확실한 단어가 아닌 질문(취소선일 수 있는 체크 표시, 두 테이블 병합 여부, 자료 이름 지정 여부)은 앱을 만들기 전에 <run>/review/extra.json에 검사 및 호출로 저장됩니다. apply_review.py는 답변을 <run>/review/to-action.md에 나열하여 조치할 수 있게 합니다. tools/review/README.md를 참조하세요.
6. 배포 (사람이 초안을 확인한 후)
검토자의 수정 사항을 session.json에 적용하고 meta.status를 "final"로 설정한 후:
python3 ingest/ingest.py publish --links # 추적 불가능한 항목이나 빈 섹션이 있으면 거부
이 명령은 data/session.json과 playbook/index.html을 작성합니다. playbook/ 폴더는 정적 사이트입니다: 어디든 배포하는 것은 별도 단계이므로 먼저 물어보세요. 페이지의 모든 링크는 스크립트로 처리되므로 디스크에서 직접 열어도 작동합니다.
절대 금지
- 일반적인 지식에서 내용을 추가하지 마세요. "도움이 되는" 맥락이라도 마찬가지입니다. 빈 내용이 지어낸 내용보다 낫습니다.
- 단어를 조용히 추측하지 마세요:
[?word]또는[illegible]을 사용하고 나열하세요. - 사람의 이름이나 고용주 이름을 게시된 페이지에 넣지 마세요. 단, 약속 카드에 해당 사람이 직접 쓴 약속 자체의 이름과 조직은 예외입니다(
verify가 카드와 대조 확인). verify통과 및 사람이 초안을 읽지 않고 배포하지 마세요.
이후
사진과 음성 노트에는 이름과 얼굴이 포함될 수 있습니다. 플레이북이 최종 확정되면 사용자에게 runs/*/audio, 원본 사진 및 음성 노트, 그리고 주최자가 보관하지 않기로 합의한 기타 모든 항목을 삭제하라고 알리세요.