Imported from suisui-swimmy/pokemon-SnapCrop (
AGENTS.md). Install upstream withnpx skills add suisui-swimmy/pokemon-SnapCrop. Copyright stays with the author.
AGENTS.md
作業の進め方
- 実装依頼では、既存コードから判断できる通常の実装判断を行い、依頼の範囲内で修正・関連検証・報告まで進める。すでに許可された作業について、再確認のためだけに止まらない。
- 計画・調査だけの依頼は、その成果物を完成させる。実行モードの制約を守り、計画依頼を実装の許可と解釈しない。
- 質問する前に、コード・設定・既存資料から解決できる点を調べる。調査で解決できず、結果や作業範囲を大きく左右する不明点を質問する。
- 上位の安全ルール・実行モードを守ったうえで、今回のユーザー指示を、このファイルやスキルの既定方針より優先する。
- スキルが確認・停止・未完了の理由になる場合は、該当する
SKILL.mdのリンクと原文を示し、明示された要件と自分の解釈を区別して説明する。影響しない許可済みの作業は進める。 - サブエージェントは、ユーザーから明示的な使用指示がある場合のみ使用する。 並列化や効率化が可能という理由だけで、自発的に生成・委任しない。指示がなければメインエージェントで進め、使用確認のためだけに作業を止めない。
- 報告は結果・検証・残件を中心に、短く具体的な日本語で書く。口調はユーザー共通指示を引き継ぐ。
進捗記録
- 個人用の汎用スキル
/progress-update（~/.agents/skills/progress-update/SKILL.md）を使用する。 - 進捗記録の標準は
Format: 2とし、PROGRESS.mdのCurrent Snapshot・Recent Updatesと、PROGRESS.archive/のアーカイブで管理する。 - 完了記録は直近5件を残し、それ以前の完了記録を月別アーカイブへ移す。未解決の
in_progress/blockedは件数枠外でPROGRESS.mdに保持する。 - 意味のある完了・検証・引き継ぎを、原則として1依頼につき1回記録する。細かな途中経過、通常の質問への回答、未採用の提案だけでは更新しない。
- 現在の実装はコード・テスト・
README.mdを根拠とする。進捗ログは引き継ぎ履歴として扱い、過去の記録だけで現在の実装や検証結果を断定しない。 - 通常は
Current Snapshotと直近の更新を読み、未解決の履歴やアーカイブは必要な箇所だけ検索・参照する。長いログやアーカイブを一括で読み込まない。
このリポジトリについて
このリポジトリは pokemon-SnapCrop の本体です。
対戦画面のライブ映像をブラウザで表示しながら、左右に参照画像を保持表示し、terminal 風 CLI パネルを中心に操作する静的 Web アプリを管理します。
このアプリの主目的は以下です。
- 左右の参照画像を対戦中ずっと表示し続けること
- キーボード中心で素早く操作できること
- 対応条件下で待機中画面を自動検出し、
snap bothできること
主目的snap は「現在フレームから参照画像を更新すること」です。
画像のダウンロードは snap とは別の機能で、今後実装する可能性はありますが、主目的ではありません。
主な利用環境
- Windows 11
- Google Chrome 推奨
- Microsoft Edge でも動作するが、auto snap は Chrome の方が安定しやすい場合がある
- GitHub Pages または localhost 経由で利用する
- 16:9 入力を主経路とする
主なファイル
index.html
アプリ全体の DOM 構造style.css
レイアウトと UIapp.js
メディア入力、クロップ、terminal、auto snap などの主要ロジックpokemon-icon-matcher.js,pokemon-icon-worker.js: ポケモンアイコンの照合処理と、画像読み込み・認識を実行する Workerassets/auto/*
auto snap 用テンプレート画像battle-api.js: Pokémon Champions Battle Dataへの読み込み、取得内容の検証、通信数の制御battle-statistics.js: 統計設定コマンド、候補、選出・手入力の統計表示data/pokemon-display-catalog.json,data/showdown-LICENSE.txt: Showdown識別子・分類・表示名・翻訳を生成した同梱データと出典ライセンスtools/: 表示辞書の生成・検証、公開ファイルの組み立て、ブラウザ用ベンチマーク。旧CSV・同梱アイコンの生成処理は過去検証用で、本番の生成経路ではないtests/,package.json: Node テスト、検証用 fixture、実行コマンドmanifest.webmanifest,sw.js
PWA 関連.github/workflows/deploy.yml
GitHub Pages 自動 deployREADME.md
ユーザー向け取扱説明書docs/technical-guide.md: 内部処理・使用技術・判定条件・診断・開発時の確認方法
実行と確認
このアプリは静的サイトです。
file:// 直開きではなく、HTTP 経由で確認してください。
- VS Code Live Server などの静的ファイルサーバーを使う
- または GitHub Pages で確認する
file:// を前提に直さないこと。
getUserMedia()、表示辞書の読み込み、Service Worker の都合で、localhost または HTTPS 前提です。
このリポジトリで守ること
1. 最小差分を優先する
- 大きなリファクタは避ける
- まず既存の流れを読み、既存関数を再利用する
- 1つのタスクで広げすぎない
- 最小差分とは、依頼を満たすために必要な修正を揃えること。必要な修正や関連検証を省略する理由にしない
2. 主目的を見失わない
- 主線は「左右参照画像の保持表示」
- terminal 中心の操作性を壊さない
- click 依存を増やしすぎない
3. 既存の本線を壊さない
特に以下は壊しやすいので慎重に触ること。
- 映像デバイス選択と stream 切り替え
- 音声入力の分離構成
- crop overlay の drag / resize
- terminal focus return
- auto snap の検出フロー
- fullscreen / PWA / Service Worker
workspace-top/video-stage/terminal-panelを含むレイアウト
4. UI 文言は日本語で短く自然にする
- terminal の文言は簡潔にする
- debug 用の内部情報は通常表示に混ぜすぎない
- 実装していない機能を README に書かない
5. 相対パスを維持する
- ルート相対パスに寄せない
- GitHub Pages の repo 名付き URL 配下でも壊れにくい構成を維持する
現在の重要仕様
- 映像入力選択時に、自動で映像開始または切り替えを試みる
- 音声入力は映像と分離して扱う
- OBS Virtual Camera は映像のみを前提とする
- 16:9 入力では固定クロッププリセットを主経路とする
- 4:3 入力ではクロップ補正はするが、自動認識は行わない
auto onはreadyへの切り替えまでまとめて行う- auto snap は
ready中だけ監視する debug onのときだけ認識範囲表示を出す- terminal は本番導線であり、入力フォーカスの維持を重視する
変更時の基本方針
ドキュメントの書き分け
README.mdはユーザー向けの取扱説明書 / 使い方ガイドとする。初期設定、操作手順、コマンド、表示される結果、対応条件・制限、保存される内容、困ったときの対処を、内部知識がなくても分かる言葉で記述する。- 内部処理、使用技術、判定の秒数・閾値・連続一致条件、候補探索・照合方式、生成データの構造、診断ログの形式や詳細、開発・検証手順は
docs/technical-guide.mdに記述する。技術資料を分割する場合も、同文書を入口にして相互に参照できるようにする。 - READMEには技術資料への相対リンクを置く。診断が必要な利用者への案内は残してよいが、
debugコマンドの詳細や内部仕様をREADMEへ重複掲載しない。 - 技術説明を移す際も、ユーザーの操作・判断に必要な対応条件、失敗時の挙動、保存の制限はREADMEに平易な説明で残す。例えば「名前を推定できない場合は未確定」は残し、採用スコアや再探索手順は技術資料へ分ける。
- 挙動変更時はREADMEの利用説明と技術資料の該当箇所をそれぞれ確認し、必要な側を更新する。両方とも変更後の現行仕様として書き、作業履歴・検証結果は進捗記録へ分離する。未実装の機能や未確認の挙動を断定しない。
README.md/docs/technical-guide.mdを作業ログにしない。各記述は「ユーザーの操作・判断、または開発者の実装理解・保守・検証に必要か」「変更の経緯を知らなくても現行仕様として意味が通るか」で判断し、該当しない情報は載せない。- 追加・削除・移動・集約したという作業報告、変更前との比較、維持した挙動の列挙、検証結果は進捗記録へ書く。必要な制約・互換性・失敗時の挙動・設計理由は、現在の操作や保守に役立つ形で該当文書へ残す。例えばクレジットの参照先は案内してよいが、表示をどこから削除・集約したかは説明書へ書かない。
- 文書変更時は記述と実装の整合性、相対リンクと参照先、
git diff --checkを確認する。
terminal / CLI
- terminal を主導線として扱う
- コマンド追加は本当に必要なものだけにする
- 1文字 alias を増やしすぎない
- 状態確認系は
status/auto status/debug statusに寄せる
media / stream
- video と audio を不用意に巻き込んで再初期化しない
audio-selectの変更で video を再初期化しない- 権限拒否、未接続、使用中の分岐を壊さない
auto snap
- 誤発火より見逃し寄りを優先する
- 16:9 専用の前提を崩さない
- テンプレ画像と ROI 前提の保守的な構成を維持する
layout
- 見た目の微調整でも、fullscreen / PWA / mobile fallback への影響を見る
- UI 改修は広げすぎない
- 便利そうでも、レイアウト事故の温床になる変更は慎重に扱う
参考資料
others/はGit追跡外の参考資料置き場。本体はothers/なしで動く状態を維持し、runtime import（実行時の読み込み・参照）を行わない。- 通常の利用・テスト・公開ビルドの必須構成に参考資料を含めない。データ再生成などで外部ソースが必要な場合は、別途準備する開発用入力として扱い、本体の実行要件と分けて説明する。
生成データ
- 生成済みデータやアイコン画像を変更するときは、対応する生成元・生成処理から更新する。生成結果への手修正だけで済ませない。
npm run generate:catalogは表示辞書を書き換えるコマンド。単なる検証には使わず、検証はnpm run validate:catalogで行う。再生成・再現性検証には所定のコミットに揃えた Pokémon Showdown と damage-calc-ja-layer のソース、Node.js 24以上が必要。外部ソースの準備と生成ツールの読み込み先は技術資料で確認する。- 外部提供の比較画像・生の統計・API一覧を配布物に同梱しない。取得は利用者のブラウザから行い、HTTPのキャッシュ指定に従う。Cache API、IndexedDB、localStorageへ独自に永続保存しない。
- 公開物は
npm run build:pagesの許可リストから作成する。旧assets/pokemon-icons/、旧CSV・アイコンJSON、others/、診断ログを公開対象へ戻さない。
完了前に確認すること
以下の22項目は、変更内容に応じて関係する項目を選ぶ確認表。毎回すべてを実行する要件ではない。
- 文書のみの変更:
git diff --checkと記述の整合性・参照先の確認を行う。アプリのテスト追加や実機検証は不要。 - JavaScript のロジック変更: 変更したファイルの
node --checkと関連する Node テストを行う。全体の回帰確認が必要ならnpm testを使う。 - 表示辞書・生成処理・認識処理の変更: 関連テストと
npm run validate:catalogを行う。認識結果に影響する場合は、対象サンプルと既存サンプルをベンチマークで比較し、誤採用が増えていないか確認する。配布内容の変更時はnpm run build:pagesと公開対象の検査も行う。 - 表示・操作の変更: localhost のブラウザで関連する表示・操作・terminal のフォーカスを確認する。レイアウト変更では狭い幅、fullscreen、PWA への影響も確認する。
- 意味のある検証を選び、軽微な変更に対して実装をなぞるだけのテストを増やさない。必要な確認が合格したら、新たな変更・失敗・具体的な懸念がある場合に限り、検証を拡大・再実行する。
- 実機や必要なサンプルが使えない場合は、実行できる検証を進め、未確認の挙動・影響・次の確認方法を報告する。代替検証を実機確認済みと扱わない。
基本
- localhost でページが開く
- GitHub Pages 配下でも壊れにくい
- README の説明が実装とズレていない
映像・音声
- 映像入力一覧が表示される
- 映像入力選択で開始または切り替えできる
- 音声入力が壊れていない
- OBS Virtual Camera の映像のみ運用が壊れていない
クロップ
edit/readyが動く- crop overlay の drag / resize が動く
- 4:3 の補正や保存復元が壊れていない
terminal
snap bothが動く- 空 Enter /
Ctrl + Enterが動く - terminal focus return が壊れていない
- 検索結果表示が壊れていない
auto snap
auto on/auto off/auto statusが動くauto onでreadyまで入る- 16:9 入力で待機中検出が動く
- 4:3 入力で監視しないことが維持されている
debug onで必要な認識範囲が出る
表示まわり
- fullscreen が壊れていない
- PWA / Service Worker まわりに明確な退行がない
- gh-pages でキャッシュずれによる不整合が起きていないか確認する
確認していないことを、確認済みと書かないこと。
Done の定義
タスクは、依頼の種別と変更範囲に応じて、以下の該当項目を満たしたら完了です。
- 依頼された成果物（実装・調査結果・計画など）が揃っている
- 主線である対戦中の利用フローが壊れていない
- terminal 中心の操作感が保たれている
- 映像 / 音声 / クロップ / auto snap の既存本線に不要な退行がない
- ユーザー向け挙動が変わった場合は
README.mdを必要に応じて更新している - 不要な複雑化を増やしていない
- 変更に必要な検証結果と、残件・未確認事項が報告されている
やってはいけないこと
- バックエンドを追加しない
- 新たな外部API依存を無断で追加しない。ユーザー承認済みの例外として、名前推定の比較画像・候補一覧・バトル統計は Pokémon Champions Battle Data から実行時に取得する。通信失敗で映像・撮影・画像保持・選出番号判定を止めない。開発時の公式資料参照は妨げない
- OCR を勝手に追加しない
- 4:3 自動認識対応を勝手に広げない
- terminal 導線を click-heavy UI に置き換えない
- 実装していない仕様を README に書かない
- README はユーザー向けの取扱説明書であり、開発 / デバッグ関連の詳細を記述しない
- 軽い見た目調整のつもりで広範囲レイアウト改修に広げない
詰まったとき
詰まった場合は、以下の順で整理すること。
- 何が blocker か
- それがブラウザ制約 / デバイス制約 / 実装不備のどれか
- 最善の代替策は何か
- 今のスコープのままで前進できる最小の次手は何か
整理した後、許可済みの範囲で進められる代替策や影響しない作業を実行する。ユーザーの判断や外部状態の変化が必要な部分は、具体的な blocker と必要な次手を報告する。
