jasonericsiegel/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を通じてページを開き、show.pyはAppleScriptを使ってChromeを制御するため、承認が必要になる場合があります。承認を求め、ステップ3をスキップしないでください。
• 各ステップ（カーソル、各ラウンドの開始、ReceivedとDone）でのページの動作は、references/what-the-user-sees.mdに記載されています。ユーザーがページの動作について質問したら、それを読んでください。

使用するタイミング

• あなたが作成した作業（レポート、計画、ドラフト、モックアップ、選択肢、提案ルール）のレビュー、承認、または選択をユーザーに求めている場合、またはユーザーがレビューを依頼した場合→求められなくても、ここにページを作成します。
• 作業がまだページになっていない場合→プレーンなHTMLを構築し、元のファイルをソースとして保持します。
• レビューページを必要としない独立した質問は、チャットに残します。
• メモ内のユーザーの質問に回答します。 質問をしているメモには--replyを使用します。変更、詳細な説明、およびあなた自身のレビュー質問は、ページの該当部分に配置します。ユーザーが明示的に要求した場合のみ、--askまたは--againを使用して自分の質問をバブル表示します。
• ページがユーザーのメモを受け付ける準備ができたら、その後の各ラウンドでも：inbox-for-humanが利用可能なスキルリストにある場合（その名前か、プラグインプレフィックス付きの名前）、Skillツールでそれを読み込み（Codexの場合は、そのスキルリストが指すSKILL.mdを開く）、ページをキューに入れます。ない場合、一度だけ言います：「inbox-for-humanスキルなしで実行しました。これにより、このページがレビューリストに保持されません。」

初回使用

セットアップで最初のページを開く前に、python3 "$SKILL_DIR/scripts/self_check.py"を実行し、そのメッセージを平易な言葉で伝えてください。チェックに合格した後は再実行しないでください。スクリプトは合格したチェックを記憶します。--forceは、必要な場合に再実行します。

ここでコマンドをまったく実行できない場合は、試みないでください。「このモードではhuman-feedbackは機能しません。ここではコンピュータ上のファイルを操作できないからです。Claudeデスクトップアプリでは、Codeタブを開いてLocalセッションを選択してください。ChatGPTデスクトップアプリでは、Codexに切り替えてLocalを維持してください。」と正確に伝えてください。

終了コード2、またはそのメッセージが表示された場合は停止します：ページを構築しようとしないでください。終了コード1は、ユーザーが自分で開いて確認できるファイルを生成します。

1. 部分をマークする

ユーザーがコメントする可能性のある各ユニット（カード、セクション、オプション、テーブル行）にdata-noteを配置します。ラベルはその部分の最初の見出しから取得されるため、通常は裸のdata-noteで十分です。見出しがない部分、または見出しが他の部分と重複する部分には、独自のラベルを付けます：data-note="オプションB · 穏やか"。ラベルはページ内で一意である必要があります。

独自のスクリプトから部分を描画するページも、スクリプトがそれらをすぐに描画する限り（DOMContentLoadedやクリックのような後続のイベントではない）、それらの部分にメモを付けます。HTMLにコピーしないでください。ステップ2のカウントは、そこに記述された部分のみを対象とします。

<iframe>に表示されるローカルページの周囲の部分をマークします。ステップ2はフレーム化されたページにタグを付け、そのテキストにコメント、編集、ハイライトを提供します。レビューページはフィードバックを保存し、コピーされた編集でフレーム化されたソースを指定します。

ユーザーが入力または書き換えるテキストを決してマークせず、ユーザーにページを編集するように依頼しないでください：ユーザーは、クリックまたは選択によって表示されるポップアップの編集機能を使用して、任意の行を自分で書き換えます（⌘Zで編集を元に戻せます）。代わりに質問をしてください（ステップ6）。

独自のコメントボックス、入力フィールド、コピーボタンを作成しないでください。レイヤーがそれらすべてを処理します。

左側のアウトラインはすでにページのナビゲーションです：すべての部分をリストし、部分外のセクション見出しをキャプションとして表示し、表示中の部分をマークし、ページのトップバーに邪魔されずに部分にジャンプします。ページに独自のナビゲーション（セクションタブ、目次、ジャンプリンク、前/次ステップボタン）を追加する前に、ユーザーにとって最も簡単な方法を判断し、ユーザーが1つのことを行うために2つの方法に遭遇しないようにします。

• アウトラインを繰り返すだけの場合→省略します。ボタンが表示するはずだった名前を部分とセクション見出しに付けます。
• アウトラインができないこと（ダーク/ライト切り替え、フィルター、ページをパーツごとにスクロールする前/次ボタン）を行う場合→その部分だけを保持します。
• タブやその他の非表示パネルに部分を表示する場合→1つのスクロールページにします。ユーザーがタブを要求した場合→タブをマークし、それ以外は何も記述しません：各role="tabpanel"を指定する<button role="tab" aria-controls="…">のrole="tablist"を作成し、パネル内に通常通りdata-note部分を配置します。レイヤーはパネルを切り替え、プレーンなスティッキーバーを描画し、各タブをその階層のレベル、ページ上の位置としてアウトラインにリストし、リロードとバージョン間で開いているタブを保持し、アウトライン行、ステッパー、またはそこへの#リンクのためにタブを開き、タブが開くまでスレッドを保持します。独自のタブスクリプトを持つページはそれを保持し、classを持つタブリストはページ独自のスタイリングを保持します。
• すべてのページは2回目のラウンド（ステップ5）からバージョンを取得します→←と→キーをバインドしないでください。バージョンステッパーがそれらを使用します。

プラグインポイント（別のスキルや手作業で作成された、レイヤーをホストするページ用）：

• data-note部分は、上記のようにアウトラインとメモ列にフィードされます。
• レイヤーが描画されると、<html>にdata-notes-layerが設定され、レイヤーがないページには存在しません。ホストページはこれを使用して、独自のアウトラインやレイヤーなしでのみ意味をなす行を非表示にし、ユーザーが2つを見ることがないようにします：html[data-notes-layer] .its-outline { display: none; }。レイヤーをオフにするものはないため、マーカーは残ります。レイヤーが追加する他のものに依存しないでください。

2. メモを有効にする

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

</body>の直前に1つのタグを追加し、ラウンド数と部分数を表示し、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>:[パートラベル]"：別のエージェント（送信したサブエージェント、Codex、あなた以外の誰か）がページの一部を作成しました。各ヘルパーを人が知る名前で一度指定し、各パートを--ownsで指定します。ラベルはアウトラインに表示される通りです。両方とも繰り返し、最大3つのヘルパーまで。あなたがリード（--agent）を続けます。ページ上では、各エージェントのカーソルは自分が所有する部分のみを実行します。以降の実行はそれらを保持します。どちらかのフラグのある実行は置き換えます。新しいバージョンは何も持たずに開始するため、そのパートがまだヘルパーのものである場合は、フォローアップ実行で再度渡します。あなたがすべてを作成した場合→両方を省略します。

  python3 "$SKILL_DIR/scripts/add_notes.py" <page.html> --agent "Claude" --helper "Codex" --owns "Codex:[オプションB · 穏やか]"
  

• --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を実行して終了します。専用フォルダ内にアセットがある新しいレビューは、すべてのラウンドで1つのローカルWebアドレスを使用するため、ブラウザはページのズームとメモを保持します。ラウンドとそのアセットをそのフォルダまたはサブフォルダに保持し、相対アセットパスを使用します。オープナーが出力するレビューアドレスをリンクします。
• HTTP経由ですでに提供されているページの場合、--hold --copyで準備し、show.py <local page.html> --preview-url <新しいラウンドの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コマンドを使用してページを開きます。ユーザーに、メモの準備ができていること、場所（オープナーが出力する行）、およびコピーボタンが提供するものを貼り付けるように伝えます。質問をしたり、返信を残したりした場合は、ページで待機している数も伝えます。

ページが表示されたら、チャットは準備完了の行、リンク、およびページの開封を妨げたものや別のスキルが必要とする行のみに保ちます。変更、調査結果、ソース、注意事項、チェック、質問は、それらが関係する部分に配置します。ページに「詳細情報」がある場合は、ソースと詳細にそれを使用します。

あなたがフレーム化したページはフレームタグも運ぶため、単独で開くとメモ列が表示され、圧迫され、チェックすると誤った欠陥が報告されます。代わりに、スクラッチパッドからベアコピーをチェックします：ホールドスタイルを削除し、add_notes.pyの代わりにhuman-feedback.jsのベアコピーを読み込み、コンテンツの内側の端を確認します。human-feedback.jsはfile://プロトコルを必要とし、sourceURLコメントを持つ場合があります。

4. フィードバックを受け取る

ユーザーがコピーボタンからテキストを貼り付けます。そのテキストは、各メモの作成者、メモ内のユーザーのテキスト、およびトップレベルの絵文字のセットを含みます。--reply、--ask、または--againでマークされたメモは、チャットで送信されたかのように動作するため、それらに返信すると、あなたの返信がページ内のそのメモの横に表示されます。他のメモは、次のバージョンで個別に対処するために使用します（ステップ5）。

--receivedは、ユーザーが貼り付けたことを確認したときに送信されます。これは、ユーザーがフィードバックを送信したことを確認し、あなたがそれを受け取ったことを示します。--receivedはページを更新せず、単に状態をマークします。

--updatingは、次のバージョンの作業を開始したことを示します。--updatingは、ページのメモバーを「更新中…」に変更します。

5. 次のバージョン

ユーザーのフィードバックを適用したら、新しいバージョンを作成します。新しいバージョンは、以前のバージョンのすべてのメモとコメントを保持する必要があります。新しいバージョンを作成するには、--new-versionフラグを付けてadd_notes.pyを実行します。

python3 "$SKILL_DIR/scripts/add_notes.py" <page.html> --new-version

新しいバージョンは、ページの新しいコピーを作成し、以前のバージョンからすべてのメモとコメントを保持します。その後、--holdなしでadd_notes.pyを実行して、ユーザーに表示します。

新しいバージョンのフォローアップ実行では、--next-roundを使用して、前のラウンドから続行します。

6. 質問と返信

ページ内のメモに返信するには、メモの横にある返信ボタンを使用します。返信はチャットに表示されず、ページ内にのみ表示されます。

質問をするには、--askフラグを付けてメモを作成します。質問はページ内のそのメモの横にバブルとして表示されます。

--againフラグは、前のラウンドからの質問を再度表示します。

7. 完了

すべてのメモに対処し、ユーザーが満足したら、--doneフラグを付けてadd_notes.pyを実行します。

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

これは、ページを完了としてマークし、メモバーを「完了」に変更します。

8. その他のコマンド

• --help：ヘルプメッセージを表示します。
• --version：バージョン情報を表示します。
• --list：現在のページのすべてのメモをリストします。
• --show：現在のページを表示します。
• --save：現在のページを保存します。
• --load：以前に保存したページを読み込みます。

設定

設定は、~/.human-feedback/config.jsonに保存されます。設定ファイルは、以下のオプションをサポートします：

• workspace：デフォルトのワークスペースディレクトリ。
• agent：デフォルトのエージェント名。
• appearance：デフォルトの外観設定。

例

計画のレビュー

1. 計画をHTMLページとして作成します。
2. data-note属性を各部分に追加します。
3. add_notes.pyを実行してページを準備します。
4. ユーザーがフィードバックを追加します。
5. ユーザーがフィードバックをコピーし、チャットに貼り付けます。
6. フィードバックを適用し、新しいバージョンを作成します。
7. ユーザーが満足するまで繰り返します。

選択肢のレビュー

1. 選択肢をHTMLページとして作成します。
2. 各選択肢にdata-note属性を追加します。
3. add_notes.pyを実行してページを準備します。
4. ユーザーが選択肢を比較し、コメントを追加します。
5. ユーザーが選択をコピーします。
6. 選択を適用します。

トラブルシューティング

• ページが開かない場合：show.pyが正しく設定されていることを確認します。--holdフラグがあるかどうかを確認します。
• メモが表示されない場合：data-note属性が正しく設定されていることを確認します。
• 重複ラベル：すべてのラベルが一意であることを確認します。
• ページが空白の場合：add_notes.pyが正しく実行されていることを確認します。