jasonericsiegel/human-feedback

Human Feedback

모든 HTML 페이지를 사용자가 코멘트할 수 있는 페이지로 변환합니다: 왼쪽에 개요, 오른쪽에 사용자가 검토 중인 내용 옆에 메모, 그리고 복사 버튼: 비어 있을 때는 내 피드백 복사, 첫 복사 전에는 N개 메모 복사, 이후에는 N개의 새 메모 복사 또는 다시 복사. 사용자는 복사된 텍스트를 채팅에 붙여넣고, 당신이 이를 적용합니다. 모든 키 입력은 사용자의 브라우저에 저장됩니다.

이 버전은 사용량을 수집하지 않습니다.

• Claude Code와 Codex 모두 이 파일을 로드할 수 있습니다. allowed-tools는 Claude Code 전용 필드이며, Codex는 이를 무시합니다.
• $SKILL_DIR은 이 SKILL.md가 로드된 폴더(예: ~/.claude/skills/human-feedback 또는 ~/.codex/skills/human-feedback)를 의미합니다. 해당 리터럴 경로를 명령어에 작성하세요. 모든 셸 호출은 새로운 셸에서 실행됩니다.
• Codex 샌드박스에서 add_notes.py는 show.py를 통해 페이지를 열며, 이는 AppleScript를 사용해 Chrome을 제어하므로 승인이 필요할 수 있습니다. 이 경우 3단계를 건너뛰지 말고 승인을 요청하세요.
• 각 단계(커서, 각 라운드 시작, Received 및 Done)에서 사용자 페이지가 어떻게 보이는지는 references/what-the-user-sees.md에 설명되어 있습니다. 사용자가 페이지 동작 방식을 물을 때 참조하세요.

사용 시기

• 사용자가 당신이 만든 작업(보고서, 계획, 초안, 목업, 옵션, 제안된 규칙)을 검토, 승인 또는 선택하도록 요청하거나, 사용자가 검토를 요청하는 경우 → 요청 없이 여기에 페이지를 올리세요.
• 작업이 아직 페이지가 아닌 경우 → 일반 HTML로 빌드하고 원본 파일을 소스로 유지하세요.
• 검토 페이지가 필요 없는 독립적인 질문은 채팅에 남겨두세요.
• 메모에서 사용자의 질문에 답변하세요. 질문하는 메모에 --reply를 사용하세요. 변경 사항도 요구하는 경우에도 마찬가지입니다. 변경 사항, 더 긴 설명, 그리고 당신의 검토 질문은 페이지의 관련 부분에 넣으세요. 사용자가 요청한 경우에만 --ask 또는 --again을 사용하여 당신의 질문이 담긴 버블을 만드세요.
• 페이지가 사용자의 메노를 받을 준비가 되면, 그리고 이후 각 라운드에서: inbox-for-human이 당신의 사용 가능한 스킬 목록에 있다면(플러그인 접두사 유무와 관계없이 이름으로), 스킬 도구를 사용하여 로드하고(Codex의 경우 스킬 목록이 가리키는 SKILL.md 열기) 페이지를 대기열에 추가하세요. 그렇지 않으면 한 번만 말하세요: "inbox-for-human 스킬 없이 실행되었습니다. 이 스킬이 있었다면 이 페이지를 검토 목록에 유지했을 것입니다."

첫 사용

설정에서 첫 페이지를 만들기 전에 python3 "$SKILL_DIR/scripts/self_check.py"를 실행하고 그 메시지를 일반 언어로 전달하세요. 한 번 통과한 후에는 다시 실행하지 마세요. 스크립트는 통과 여부를 기억합니다. --force는 필요할 때 다시 실행합니다.

여기서 명령을 전혀 실행할 수 없다면 시도하지 마세요. 정확히 다음과 같이 말하세요: "human-feedback은 이 모드에서 작동할 수 없습니다. 여기서는 컴퓨터의 파일을 처리할 수 없기 때문입니다. Claude 데스크톱 앱에서 코드 탭을 열고 로컬 세션을 선택하세요. ChatGPT 데스크톱 앱에서 Codex로 전환하고 로컬을 유지하세요."

종료 코드 2 또는 해당 메시지는 중지를 의미합니다: 페이지를 만들려고 시도하지 마세요. 종료 코드 1은 사용자가 직접 열어 확인할 수 있는 파일을 제공합니다.

1. 부분 표시

사용자가 주석을 달 수 있는 각 부분(카드, 섹션, 옵션, 테이블 행)에 data-note를 넣으세요. 레이블은 해당 부분의 첫 번째 제목에서 가져오므로, 일반적으로 data-note만으로 충분합니다. 제목이 없거나 제목이 다른 부분의 제목과 중복되는 부분은 자체 레이블을 갖습니다: data-note="옵션 B · 차분함". 레이블은 페이지 내에서 고유해야 합니다.

자체 스크립트에서 부분을 가져오는 페이지도 그 부분에 메모를 받습니다. 단, 스크립트가 즉시 가져오는 경우에 한하며, DOMContentLoaded나 클릭과 같은 이후 이벤트에서 가져오는 경우는 제외됩니다. 이를 HTML에 복사하지 마세요. 2단계의 개수는 작성된 부분만 포함합니다.

<iframe>에 표시된 로컬 페이지 주변의 부분을 표시하세요. 2단계는 프레임 내 페이지에 태그를 추가하여 해당 단어에 Comment, Edit 및 Highlight를 제공합니다. 검토 페이지는 피드백을 저장하고 복사된 편집에서 프레임 소스를 명명합니다.

사용자가 입력하거나 다시 작성할 텍스트는 절대 표시하지 마세요. 사용자가 선택하거나 클릭할 때 나타나는 팝업의 Edit을 통해 직접 줄을 다시 작성합니다(⌘Z로 편집을 취소할 수 있음). 대신 질문하세요(6단계).

자체 주석 상자, 입력 필드 또는 복사 버튼을 만들지 마세요. 레이어가 모두 처리합니다.

왼쪽의 개요는 이미 페이지의 탐색입니다: 각 부분을 나열하고, 부분 외부의 섹션 제목을 캡션으로 표시하며, 현재 보이는 부분을 표시하고, 페이지의 자체 상단 표시줄과 겹치지 않게 부분으로 이동합니다. 페이지에 자체 탐색(섹션 탭, 콘텐츠 목록, 점프 링크, 이전/다음 단계 버튼)을 제공하기 전에, 사용자에게 가장 쉬운 방법을 판단하여 사용자가 하나의 작업에 두 가지 방법을 접하지 않도록 하세요:

• 개요를 반복할 뿐인 경우 → 생략하세요. 부분과 섹션 제목을 해당 버튼이 말했을 내용으로 명명하세요.
• 개요가 할 수 없는 작업(어두움/밝음 전환, 필터, 페이지를 부분별로 스크롤하는 이전/다음 버튼)을 수행하는 경우 → 해당 부분만 유지하세요.
• 부분이 탭이나 기타 숨겨진 패널에 표시되는 경우 → 하나의 스크롤 페이지로 만드세요. 사용자가 탭을 요청한 경우 → 탭을 표시하고 다른 것은 작성하지 마세요: role="tablist"인 <button role="tab" aria-controls="…"> 목록, 각각 role="tabpanel"을 명명하고, 패널 내부에 data-note 부분을 평소처럼 넣으세요. 레이어는 패널을 전환하고, 일반 고정 막대를 그리고, 각 탭을 개요에 계층 구조의 수준으로, 페이지에서의 위치와 함께 나열하고, 열린 탭을 새로고침 및 버전 간에 유지하며, 개요 행, 스텝퍼 또는 해당 탭으로의 # 링크에 대한 탭을 열고, 해당 탭이 열릴 때까지 스레드를 보류합니다. 자체 탭 스크립트가 있는 페이지는 이를 유지하며, class가 있는 탭 목록은 페이지의 자체 스타일링을 유지합니다.
• 모든 페이지는 두 번째 라운드(5단계)부터 버전을 갖습니다. ← 및 → 키를 바인딩하지 마세요. 버전 스텝퍼가 이를 사용합니다.

레이어를 호스팅하는 모든 페이지(다른 스킬이나 수동으로 만든 페이지)에 대한 플러그인 포인트:

• data-note 부분은 위와 같이 개요와 메모 열을 제공합니다.
• data-notes-layer는 레이어가 그려진 후 <html>에 설정되며, 레이어가 없는 페이지에는 없습니다. 호스트 페이지는 이를 사용하여 자체 개요 또는 레이어 없이만 의미가 있는 행을 숨겨 사용자가 두 개를 보지 않도록 합니다: html[data-notes-layer] .its-outline { display: none; }. 레이어를 끄는 것은 없으므로 마커가 유지됩니다. 레이어가 추가하는 다른 것에 의존하지 마세요.

2. 메모 켜기

python3 "$SKILL_DIR/scripts/add_notes.py" <page.html> --agent "Claude"

</body> 바로 앞에 하나의 태그를 추가하고, 라운드와 부분 개수를 출력하며, show.py를 통해 페이지를 엽니다. 재실행, --next-round 및 새 버전의 후속 실행도 페이지를 엽니다. --new-version 단독, --received 및 --converged는 열지 않습니다. 열기에 실패하면 페이지는 준비 상태로 유지되고 실행은 이유와 수동으로 여는 명령을 출력합니다. 첫 번째 라운드에서는 페이지의 head에 작은 스타일을 추가하여 레이어가 그려질 때까지 페이지를 숨깁니다. 재실행은 태그를 교체하므로 페이지를 다시 작성한 후 다시 실행하세요. 부분이 없거나 중복 레이블에 대한 경고가 있으면 표시를 수정하고 재실행하세요.

• --hold: 페이지를 열지 않고 준비 상태로 유지합니다. 페이지를 빌드하거나 확인하는 동안, 또는 사용자가 링크만 요청한 경우(3단계)에 사용합니다.

• --pictures off: 다른 사람과 공유하거나 공개 빌드하는 페이지에 대해 그림 첨부를 비활성화합니다. 이후 실행은 설정을 유지합니다.

• --agent: 사람들이 알고 있는 당신의 이름입니다. Claude Code는 Claude, Codex는 Codex, 다른 에이전트는 자체 제품 이름을 전달합니다. 해당 이름과 로고를 가진 커서가 사용자 페이지에서 당신의 역할을 수행합니다: 메시지를 입력하고 메모 표시줄 상태(4단계의 Received 및 Updating, 8단계의 Done)에서 클릭합니다. 이후 실행은 이름을 유지하므로 처음에 전달하세요.

• --helper "<name>" 및 --owns "<name>:[Part label]": 다른 에이전트(당신이 보낸 서브에이전트, Codex 등 당신이 아닌 모든 사람)가 페이지의 일부를 만들었습니다. 각 도우미를 사람들이 아는 이름으로 한 번 명명하고, --owns로 각 부분을 개요에 표시된 레이블로 명명하세요. 둘 다 반복되며, 최대 세 명의 도우미까지 가능합니다. 당신이 리드로 남습니다(--agent). 페이지에서 각 에이전트의 커서는 자신이 소유한 부분만 수행합니다. 이후 실행은 이를 유지합니다. 두 플래그 중 하나가 있는 실행은 이를 대체합니다. 새 버전은 없이 시작되므로, 해당 부분이 여전히 그들의 것인 경우 후속 실행에서 다시 전달하세요. 당신이 모두 만들었다면 둘 다 생략하세요.

  python3 "$SKILL_DIR/scripts/add_notes.py" <page.html> --agent "Claude" --helper "Codex" --owns "Codex:[Option B · Calm]"
  

• --workspace <dir>: 당신의 작업 공간(당신이 작업하는 프로젝트 폴더)입니다. 모든 실행은 <dir>/human-feedback/attachments/를 누락된 경우 생성하고, human-feedback/에 마커 파일을 만듭니다. 페이지는 사용자가 첨부한 그림을 그곳에 저장하며, 사용자가 Chrome에서 해당 human-feedback 폴더를 선택한 후에 저장됩니다. 페이지의 프롬프트는 당신을 명명합니다("Claude의 작업 공간 폴더에서 human-feedback 하위 폴더 선택…"). 없으면: 페이지의 리포지토리, 그렇지 않으면 현재 디렉토리의 리포지토리, 그렇지 않으면 현재 디렉토리입니다. 이후 실행은 태그가 명명한 폴더를 유지합니다.

• 페이지가 http를 통해 제공되는 경우(fetch, 모듈 또는 ../ 자산을 사용) --copy를 추가하여 페이지 옆에 human-feedback.js를 배치합니다. 이후 실행, 재작성 및 새 버전은 이를 유지하고 그렇게 말합니다.

• human-feedback.js를 페이지에 붙여넣거나 인라인하지 말고, 읽지도 마세요. 태그만으로 페이지에 충분합니다.

• 페이지에 대한 질문은 해당 부분에 넣으세요(6단계).

모양새

• 기본적으로 시스템 모양을 따릅니다. 검토 중인 자료가 공유 읽기 스타일의 산문인 경우, 또는 사용자가 제어를 요청한 경우 Auto, Light 및 Dark를 제공하세요. 다른 검토에서는 제공하지 마세요.
• 제어를 제공할 때, 읽기 열에 이미 두 팔레트가 있고 둘 다 확인할 수 있는 경우 --appearance page를 사용하세요. 동일한 페이지에서 이를 재사용하세요. 독립적인 테마가 있거나 테스트된 팔레트가 없거나 모양이 검토의 일부인 페이지의 경우 --appearance sidebars를 사용하여 개요와 메모만 전환하세요. 스크린샷과 임베드는 그대로 유지하세요.
• 읽기 열의 CSS에서 html[data-notes-layer="light"] 및 html[data-notes-layer="dark"]는 명시적 선택입니다. Auto 및 페이지가 레이어 없이 열릴 때 시스템 미디어 쿼리를 유지하세요. 사용자의 선택은 라운드 간에 이 검토와 함께 유지됩니다. 다른 검토는 Auto에서 시작합니다.
• 재실행 또는 --new-version으로 복사된 버전은 설정을 유지합니다. 제어를 제거하려면 --appearance off를 전달하거나, 처음부터 파일을 다시 빌드하는 경우 의도한 설정을 다시 전달하세요.

3. 표시

모든 종류의 검토에 대해, 모든 라운드에서:

• 검토가 준비되면 매 라운드마다 사용자의 브라우저에서 엽니다. 오프너는 이전 라운드를 찾으면 Chrome에서 기존 탭을 재사용합니다. 페이지를 빌드하거나 확인하는 동안, 또는 사용자가 명시적으로 링크만 요청한 경우 --hold를 사용하세요.
• 로컬 검토의 경우, --hold 없이 add_notes.py로 마무리하세요. 전용 폴더에 자산이 있는 새 검토는 모든 라운드에 하나의 로컬 웹 주소를 사용하므로 브라우저가 페이지 확대/축소와 메모를 유지합니다. 라운드와 해당 자산을 해당 폴더 또는 하위 폴더에 유지하고 상대 자산 경로를 사용하세요. 오프너가 출력하는 검토 주소를 링크하세요.
• 이미 HTTP를 통해 제공되는 페이지의 경우 --hold --copy로 준비하고 show.py <local page.html> --preview-url <new round's HTTP URL>을 실행하세요. 오프너가 기존 탭을 찾고 브라우저가 사용자의 메모를 유지할 수 있도록 라운드 간에 동일한 프리뷰 서버를 유지하세요.
• 매 라운드마다 당신의 답변에 페이지 링크를 포함하세요. 프로젝트의 링크 형식을 사용하고, 오프너의 결과를 사용하여 페이지 위치를 알리세요. 오프너가 실패하거나 페이지를 닫은 상태로 두었다고 말하면 그렇게 말하고 링크를 제공하세요.
• 이전 라운드나 버전을 사용자가 file://에서 연 페이지 → file://에서 계속 표시하고(경로에서 show.py) localhost 링크를 제공하지 마세요. 프로젝트에서 요청하더라도 마찬가지입니다. 브라우저는 주소별로 사용자의 답변을 유지하므로 localhost 복사본은 이를 표시하지 않으며 사용자가 닫은 스레드를 다시 엽니다. 답변에 링크가 없는 이유를 말하세요.

사용자의 메모를 받을 준비가 된 경우에만 이 작업을 수행하세요.

페이지가 사용자의 메모를 받을 준비가 되면 --hold 없이 add_notes.py를 실행하세요. 먼저 페이지 콘텐츠를 완료하고 모든 부분을 표시하세요. 해당 실행에서 사용자가 요청한 완료 표시와 버블(새 버전에 대한 5단계의 후속 실행)을 전달하세요.

수정 사항이 진행 중이라고 사용자에게 알린 경우 다음 버전도 보류합니다. 해당 수정 사항이 적용된 후에만 표시하세요.

확인의 경우 --hold로 준비한 다음, 메모 레이어가 켜진 상태에서 직접 확인하거나(서브에이전트에게 스크린샷을 찍도록 하여) 확인하세요. 레이어가 페이지를 좁히기 때문입니다. 발견한 문제를 수정하세요. 당신의 메시지(질문, 답변)는 탭에 포커스가 있을 때만 들어오며, 헤드리스 브라우저는 포커스 에뮬레이션이 켜져 있지 않으면(tests/harness.mjs가 켬) 포커스를 절대 지정하지 않습니다. 이것이 없으면 대신 태그의 데이터에서 메시지를 확인하세요. 페이지 자체는 열기 뒤에 빈 상태로 유지됩니다. reading-page-formats의 shoot_page.py로 촬영하세요. 이 스크립트는 태그와 보류 스타일 없이 베어 카피를 스크린샷한 다음 삭제합니다. 해당 베어 카피는 전체 창을 채우지만, 사용자 화면에서는 메모 열이 각 측면에서 약 375px를 차지합니다(2560 너비에서 측정, 2026-11-01). 따라서 더 좁은 너비에서도 촬영하고, 표시하기 전에 줄바꿈이나 오버플로를 수정하세요. 베어 카피는 페이지를 덮는 열을 표시할 수 없으므로, 레이어가 켜진 상태에서 보류된 페이지를 로드하고 document.querySelector('h1').getBoundingClientRect().left가 개요의 가장자리 오른쪽에 있는지 확인하세요. h1이 없는 페이지에서는 첫 번째 텍스트 요소로 충분합니다. 그런 다음에만 위의 로컬 또는 HTTP 명령을 사용하여 페이지를 여세요. 사용자에게 메모를 위한 준비가 되었음을 알리고, 위치(오프너가 출력하는 줄)를 알려주고, 사용자에게 복사가 제공하는 것을 붙여넣도록 요청하세요. 질문을 했거나 답변을 남긴 경우 페이지에 몇 개가 대기 중인지 말하세요.

페이지가 표시되면 채팅은 준비 줄, 링크, 페이지 열기를 방해한 모든 것 또는 다른 스킬의 필수 줄로 유지하세요. 변경 사항, 발견 사항, 소스, 주의 사항, 확인 및 질문은 해당 부분에 넣으세요. 페이지에 자체 더 많은 정보가 있는 경우 소스와 세부 사항에 사용하세요.

프레임으로 만든 페이지는 프레임 태그도 함께 가지므로, 자체적으로 열리면 메모 열이 표시되고 좁아지며, 확인 시 가짜 결함을 보고합니다. 대신 스크래치패드의 베어 카피에서 확인하세요. 보류 스타일을 삭제하고 태그를 제거한 다음 shoot_page.py를 사용하세요.