pessimistcamellia/proto-note

プロトタイプ変更追跡レイヤー（proto-note）

単一ファイルHTMLプロトタイプに「開発者視点の変更案内レイヤー」を重ねます：右側固定ダークコメントバー（モジュールチェックボックス＋コメントカード）↔ ページ番号アンカー＋キャンバス線；双方向ホバー/クリック位置特定；コメントカードにSDDディープリンク付き。

インストールとディレクトリ

# 個人用スキル（推奨）
git clone https://github.com/pessimistcamellia/proto-note.git ~/.cursor/skills/proto-note

# またはプロジェクト内
git clone https://github.com/pessimistcamellia/proto-note.git .cursor/skills/proto-note

上記パスにディレクトリ全体をコピーしても構いません。ディレクトリ構造：

proto-note/
├── SKILL.md
├── assets/diff-annotator.js      # 注釈エンジン（プロトタイプにインライン化、ロジック変更禁止）
├── references/changeset-schema.md
├── docs/screenshots/             # README 効果画像
└── scripts/deploy_github.sh      # GitHub Pages 代替デプロイ

環境依存関係

能力	ツール	欠如時
技術スタック/ソースコード特定	codewiki MCP（または同等のコード検索）	オンラインURL＋ソースコードリポジトリ＋ブラウザDOMで復元
SDD ディープリンク	lark-cli（Feishu）	手動でドキュメントURLとセクションblockIdを入力；Feishu以外は対応セクションアンカーにリンク
ピクセルレベル調整	ブラウザ DevTools / chrome-devtools MCP	手動でオンラインページを開いて对照
デプロイ	イントラネット静的ホスティング（優先）	個人GitHub Pages（deploy_github.sh、gh認可が必要）

チームに別途フロントエンド規範スキル（例：選定ホワイトリスト、コンポーネントライブラリ使用法）がある場合は、作成前に必要に応じて読み込んでください；ない場合はターゲットリポジトリのソースコードとチームドキュメントを基準とします。

デフォルト方式：コンポーネントライブラリと公開優先順位

優先順位に従って実行；前の項目が利用不可の場合のみ次の項目にフォールバックし、最後の項目がデフォルトのフォールバックです：

1. コンポーネントライブラリ / 規範（優先）：ターゲットのオンラインシステムで実際に使用されているコンポーネントライブラリとコンポーネント規範を使用する（ソースコード/DOM/チーム規範スキルと对照）。根拠なくライブラリを変更してはいけません。
2. 公開アドレス（優先）：イントラネットに既存の静的ホスティング（またはチームが合意したイントラネットアドレス）がある場合は、イントラネットに公開することを優先します。
3. デフォルトフォールバック：実際のコンポーネントライブラリ/規範を取得できない場合、または権限、ネットワーク、イントラネット到達不能などの理由で使用できない場合 → コンポーネントは汎用的な方式で自由に選択できます（ただし単一ファイルのインタラクティブHTMLは維持）；ユーザーの個人GitHubリポジトリ（Pages）に公開します。デプロイ前にgh認可を確認し、未認可の場合はユーザーと事前にコミュニケーションを取り、同意なくプライベートリポジトリにプッシュしてはいけません。

プロダクトの鉄則

1. 変更3段階＋タイプ：ページ / モジュール / フィールド；タイプは「新規」「文案」「列挙口径」「ロジック」「フロー」「削除」に区別し、「新規」とだけラベルを付けることは禁止。
2. デフォルト非表示、モジュールチェック：開くときに注釈を表示しない；page::moduleでチェック；localStorageに状態を保存。新規モジュールの欠落キーはデフォルトでtrue（可視）、「かつてスイッチをオフにした」状態を継承して非表示にすることは禁止；古い状態はLS_KEYバージョンをアップグレードしてクリア。
3. SDDのみ連携、PRDは表示しない：コメントカードはSDDドキュメントURL#blockIdを使用。
4. 情報は簡潔に：コメントバーにバージョン番号/ベースライン/操作説明を含めない；descは結論のみ記述。
5. クリック可能なものは必ず有効：モジュールをチェックするとビューを切り替え＋スクロール＋パルス位置特定。
6. レビュー状態はコメントバー内のみ：通常/空/エラー状態などはdemoControlsに配置；実際のビジネスタブは業務ページに残す。
7. 入力分岐には再現可能な例を：examplesはfixtureと一致させ、プレースホルダーや偽の値を使用禁止。
8. コメントバーはコンテンツを妨げない：業務レイアウトを圧縮しない；spacerでscrollWidthを拡張し、水平スクロールで右側全体を表示可能にする。body padding-rightのみ追加したり、業務ルートの幅を変更したりするのは禁止。
9. コンポーネントライブラリと規範は実際のオンライン版を優先：復元可能な場合は必ず復元する（「デフォルト方式」第1段を参照）。同じコンポーネントライブラリを使用することは復元を意味しない——スケルトン、列セット/列幅、固定列、セル構造、操作列レイアウト、カスタムクラス名と主要スタイルは、オンラインのDOM/ソースコードと对照する必要あり；納品前にスクリーンショットを画面ごとに比較。実際のコンポーネントライブラリ/規範を取得できない場合にのみ、汎用コンポーネントによるフォールバックを許可。
10. 公開はイントラネットを優先、次に個人GitHub：イントラネットアドレスがあれば優先使用；利用不可の場合は個人GitHub Pagesに公開（「デフォルト方式」第2～3段を参照）。
11. 「以前(after)」＝オンラインの現状：新規追加は「該当ページ/モジュール/機能/フィールドなし」と記述；前回のデモ版との差分として記述することは禁止；オンライン上の新規追加点を見逃してはいけない。
12. UIの設置場所がない場合は線を引かない：純粋なフロー/パスはtarget: nullとし、アンカーなし；カードは「フローとパス · ページ不可視」に分類し、changesの末尾に配置。
13. モーダル内の変更：コメントカードをクリックする際はDIFF_HOOKS.locateを経由してモーダルを開いてから線を接続；アンカー/線のz-indexはモーダルより高くする（エンジンは9000台を使用）。
14. モーダルはページの水平垂直スクロールに追従：コメントバーが開いているとき、モーダルコンテナは(-scrollX,-scrollY)で平行移動（エンジンで処理済み）；スクロールをロックして回避するのは禁止。
15. ダウンロード可能なファイルは正しい形式で：テンプレート/領収書は実際の業務と同じ形式と同じ構造（例：2シートの場合は実際の.xlsx）、CSVで代用するのは禁止。
16. 複数エンドポイントはそれぞれ作成し連携：運営管理画面、C端などはシステム境界ごとにHTMLを分割；統一メニューで「エンド · ページ」を表示；ページ間のデータがある場合は、書き込み/読み取り/起動/停止/異常を模擬して実装。
17. コメントカードはSDDにジャンプ可能であること：SDDがある場合、各変更（または該当機能ポイント）にsdd.section＋blockIdを設定し、カードにディープリンクをレンダリング；クリック時に対応セクションを開く必要があり、セクション名のみを表示するのは禁止。

表示レイヤー仕様（エンジンに組み込み済み、後退させないこと）

• 右側コメントバー：ダークネイビー、幅360px、折りたたんでフローティングエントリに変更可能。
• 水平スクロール：document.body.scrollWidthで業務幅を測定（spacerはabsoluteで、この値には含まれない）；spacerを非表示にしてから測定しないこと。スクロール復元はbehavior:"instant"を使用し、scroll-behavior:smoothとの競合を避ける。
• アンカー：ドキュメント座標position:absoluteで、ターゲットの左上隅に固定；fixed＋スクロール追跡フレームは禁止；elementFromPointで隠れている場合は非表示。
• 線：通常時は線なし；ホバー/固定時は1本のみ描画；固定状態がホバー状態より優先；起点はリアルタイムのrectを取得。
• コメントカード：番号＋タイトル＋タイプ・レベル＋結論＋before/after＋SDD；examplesを含めることができる。
• デモ領域：コメントバー上部のsegmented control → DIFF_HOOKS.setDemoState。

技術スタック復元（ステップ0）

「デフォルト方式」に従って実行：復元可能な場合は必ず復元；復元できない場合は理由を記録して自由選択フォールバックに進む。

1. ユーザーがオンラインURLを提供していない → 最初にリマインダー；それでもない場合は、システム/ルート/ソースコードを自分で検索。
2. codewiki（またはソースコード検索）を使用して確認：フレームワーク、コンポーネントライブラリ、ルート→ページファイル、主要テンプレートフラグメント；必要に応じてインデックスの鮮度を確認し、オンラインDOMで校正。
3. 優先的にターゲットリポジトリの実際のコンポーネントライブラリと規範を使用；新規コントロールは該当ページの既存のタイプ/サイズ/配置に従う。同じコンポーネントライブラリを使用することは復元を意味しない——スケルトン、列セット/列幅、固定列、セル構造、操作列レイアウト、カスタムクラス名はオンラインのDOM/ソースコードと对照する必要あり。
4. チーム規範スキルがあればそれに従う；なければターゲットリポジトリとドキュメントに従う。
5. ピクセルレベルまたは検索が不十分な場合：オンラインページを開いて、マウント方法、コンポーネントクラス名、テーブル列幅/固定列、操作列構造、カスタムcomputed styleを取得。
6. 成果物は依然として単一ファイルHTML；CDNで同じフレームワーク/コンポーネントライブラリを導入できる場合は導入する。ページ全体を復元できない場合、一般的なコンポーネントライブラリを自由に選択してインタラクティブなプロトタイプを完成させ、納品説明に「復元できない理由」を記載。
7. 公開：イントラネットの静的アドレスがある場合は優先的にアップロード；ない場合は、ユーザーのGitHub認可を得た後にdeploy_github.shを使用して個人リポジトリに公開。

よくある落とし穴：外側にmin-widthを設定しすぎてテーブルを引き伸ばさない（内部の水平スクロールとfixed列が失われる）；統一メニューのトップバーにはposition:fixedを使用し、ページ幅が広い場合にトップバーが途切れるのを防ぐ。

複数ページ / 複数エンドポイントとデータ連携

1. まずマトリックスを作成：エンドポイント/システム → ページ → 主要状態 → 上流/下流データ；異なる技術スタックはファイルを分け、強制的にマージしない。
2. 統一メニュー：「エンド · ページ」の命名、現在のページをハイライト；メニューには変更注釈を付けない。
3. 同一オリジン同一ディレクトリにデプロイし、localStorageの共有を保証。
4. 共有状態のキー：proto-note:<requirement-slug>:state:v1；読み書き後に同一ページでイベントを発行し、タブ間でstorageをリッスン。
5. URLには業務IDのみを含める；本文は共有状態に含める。同一オリジンでない場合は、同一オリジンに変更することを優先し、それが不可能な場合はpostMessageを使用してoriginを検証。
6. 組み込みfixture＋「デモデータリセット」；上流/下流の状態と異常を再現可能にする。

ワークフロー

0. ステップ0 技術スタック復元。
1. PRDから変更リスト、エンドポイント/ページマトリックス、入力分岐とページ間データ関係を抽出 → references/changeset-schema.mdを参照。
2. SDD blockIdを取得し、各変更のsddに書き込む。
3. エンドポイントごとにプロトタイプを作成；複数エンドポイントにはメニューと共有状態を設定し、連携を検証。
4. 注釈レイヤーを組み込む：
   • コンテナにdata-diff-pageを追加；配置場所にidを補完；DIFF_HOOKS.locate / setDemoStateを実装。
   • レビューTabをmeta.demoControlsに移行。
   • 分岐をexamplesに書き込む（fixtureと一致させる）。
   • </body>の前にDIFF_CHANGESETをインライン化し、次に最新版全体をコピー assets/diff-annotator.js（古いコピーを使用しない）。
5. デプロイとセルフチェック：

   • イントラネット優先：既存のイントラネット静的ホスティングがある場合はアップロード；オブジェクトキーが上書きされない場合は新しいパス（-v2など）を使用し、返されるURL＋md5を基準とする。

   • フォールバックGitHub Pages：イントラネットが利用できない場合は個人リポジトリに公開。まずgh auth statusを実行；権限がない場合はコミュニケーションを取り、gh auth loginを完了させる。未認可でプライベートリポジトリにプッシュしてはいけない：

     bash ~/.cursor/skills/proto-note/scripts/deploy_github.sh <slug> ./index.html
     

セルフチェックリスト

• 復元可能な場合はオンラインの実際のコンポーネントライブラリ/規範を使用；復元できない場合は理由を記載し、自由選択フォールバックに進んだ
• 公開はイントラネット優先；イントラネットが利用できない場合は認可後に個人GitHubに公開
• オンラインと画面ごとに比較（オンラインページがある場合：列幅、固定列、操作列、ページネーション、トップバー）
• 初期状態でアンカー/線なし；モジュール未チェック；新しいモジュールは過去の訪問者に対してデフォルトで可視
• モジュールをチェックすると対応するカード/アンカー/線のみ表示され、自動的に位置特定される；モーダル内の変更は自動的にモーダルを開き、線はモーダルの上に表示される
• スクロール時にアンカーがずれない；通常時は線なし、固定/ホバー時は1本のみ；固定状態がhoverに奪われない
• コメントバーを開いた状態で水平スクロールし、右側全体を表示可能；DOM更新によって水平スクロール位置が戻されない；モーダルはベースページの水平垂直スクロールに追従
• target:nullはアンカーなし、カードは「フローとパス」に分類され末尾に配置；「以前(after)」はすべてオンラインの現状、漏れなし
• コメントカードのSDDディープリンクが開き、対応セクションに位置特定される
• デモ状態はコメントバー内のみ；examplesは再現可能；ダウンロードファイルの形式が正しい
• 複数エンドポイントのメニューにアクセス可能；プロトタイプ間での読み書き/リフレッシュ/タブ間/リセットが一貫している
• コメントバーを折りたたむとクリーン；業務インタラクションに影響を与えない

参考

• 本リポジトリ README.md（効果スクリーンショット、Live demo、デフォルト方式の説明）
• Live demo：https://pessimistcamellia.github.io/non-ecommerce-thirdparty-order-prototype/admin-upload.html