Community코딩 & 개발github.com

sheets-to-playbook

워크숍이나 커뮤니티 세션의 종이 워크시트 사진(약속 카드 스텁 사진, 선택적 음성 노트 포함)이 담긴 폴더를 받아 초안 플레이북 웹사이트로 만들고, 모든 줄을 사진과 대조 확인한 후 배포합니다.

sheets-to-playbook란 무엇인가요?

이 스킬은 실제 워크숍에서 종이 워크시트를 촬영한 사진 폴더를 입력받아, 플레이북(실행 보고서) 웹사이트 초안을 자동으로 생성합니다. 사용자가 '이 사진들을 처리해줘', '이 폴더로 플레이북을 만들어줘' 등과 같이 요청하면 활성화됩니다. 지원 플랫폼은 Claude Code와 같은 터미널 기반 AI 에이전트이며, `ingest/ingest.py` 파이썬 스크립트를 통해 동작합니다. 주요 단계는 사진 준비(prepare, 회전 변환 및 화질 평가), 각 사진에 테이블 번호와 시트 종류를 라벨링(label), 각 테이블의 필적을 전사(transcribe, 로컬 Whisper 및 하위 에이전트 활용), RAW_FORMAT.md 규칙에 따라 플레이북 작성(write), 검증(verify, 모든 문장이 사진 또는 음성 노트에 기반하는지 확인), 검토 패키지 생성(review/draft), 마지막으로 배포(publish)입니다. 중요한 원칙은 어떤 내용도 임의로 생성하지 않고(invent) 모든 내용이 사진 또는 음성에서 추적 가능해야 하며, 사람 이름이나 고용주 이름을 동의 없이 공개하지 않습니다. 검증 단계에서 오류가 있으면 배포를 차단하고, 모든 흐릿한 판독과 삭제된 단어를 보고합니다. 이 스킬은 공식 워크숍 데이터만을 신뢰하며 일반적인 지식으로 내용을 추가하지 않습니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Chris-Keene/sheets-to-playbook/tree/HEAD/.claude/skills/sheets-to-playbook

Installed? Explore more 코딩 & 개발 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

시트를 플레이북으로

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.md 1단계를 읽고 정확히 따르세요. 실행 폴더에 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, 원본 사진 및 음성 노트, 그리고 주최자가 보관하지 않기로 합의한 기타 모든 항목을 삭제하라고 알리세요.

관련 스킬