Imported from shiguredo/webcodecs-py (
AGENTS.md). Install upstream withnpx skills add shiguredo/webcodecs-py. Copyright stays with the author.
AGENTS
- Premature Optimization is the Root of All Evil
- 一切妥協をしないこと
- 一切忖度しないこと
- 常に日本語を利用すること
- 全角と半角の間には半角スペースを入れること
- 絵文字を使わないこと
- コメントは全て日本語にすること
- ログメッセージは全て英語にすること
- エラーメッセージは全て英語にすること
- テストメッセージは全て日本語にすること
レビューについて
- 常に日本語を利用すること
- レビューはかなり厳しくすること
- レビューの表現は、シンプルにすること
- レビューの表現は、日本語で行うこと
- レビューの表現は、指摘内容を明確にすること
- レビューの表現は、指摘内容を具体的にすること
- レビューの表現は、指摘内容を優先順位をつけること
- レビューの表現は、指摘内容を優先順位をつけて、重要なものから順に記載すること
- ドキュメントは別に書いているので、ドキュメントについては考慮しないこと
- 変更点とリリースノートの整合性を確認すること
コミットについて
- 勝手にコミットしないこと
- 全てのテストが通らない限りコミットしないこと
- コミットメッセージは確認すること
- コミットメッセージは日本語で書くこと
- コミットメッセージは命令形で書くこと
- コミットメッセージは〜するという形で書くこと
- フックをスキップしないこと
issues について
0000-template.mdを参考にすること- 番号が小さい issues から順番に対応すること
{seqnum}-{category}-{short-description}.mdという命名規則を守ること- seqnum は
issues/SEQUENCEファイルの値を使うこと（9999 を超えたら 5 桁にする） - issue を新規作成したら
issues/SEQUENCEの値を +1 して更新すること - 例:
0001-bug-fix-parse-error.md - 例:
0002-fmt-enhance-support-for-joins.md
- seqnum は
- 仕様的に対応が難しい場合は issues/pending/ へ移動すること
- issue を作成したらコミットすること
- issue をコミットするときはコミットメッセージに issue の番号とタイトルを記載すること
- 1 issue 完了ごとに 1 コミットすること
- Issue の作成日はファイルのタイトルの後に
Created: YYYY-MM-DDとして記載すること - Issue の完了日はファイルのタイトルの後に
Completed: YYYY-MM-DDとして記載すること - Issue の優先度はファイルのタイトルの後に
Priority: <優先度>という形で記載すること- 優先度は High / Medium / Low のいずれかをつけること
- High は最優先で対応する issue、Medium は優先的に対応する issue、Low は時間があれば対応する issue という意味合いで使うこと
- Issue を作成した LLM の Model と Version をファイルのタイトルの後に
Model: <model-name> <version>として記載すること- Opus 4.7 や GPT-5.4 など
- Issue はなぜこの対応が必要なのかの根拠を明確にすること
git ブランチの命名規則
- Git Flow を使うこと
- バグ修正は prefix を
feature/fix-でブランチを切って対応すること - 機能追加は prefix を
feature/add-でブランチを切って対応すること - 後方互換のない変更は prefix を
feature/change-でブランチを切って対応すること - リファクタリングは prefix を
feature/refactor-でブランチを切って対応すること - ブランチ名に issue の番号を含めないこと
issue が実は解決してなかった場合
- reopen の理由を issue に書いて issues/closed から issues/ に移動すること (git mv を使うこと)
- reopen の理由は、何がどう解決していなかったのかを明確にすること
バグが見つかった場合
- issues/ 以下にバグを markdown 形式で登録すること
- バグは再現手順を明確にすること
- できる限りの情報を
バグを修正した場合
- issues/ 以下のバグを修正した場合は、修正内容を markdown 形式で記載すること
- issues/closed に移動すること (git mv を使うこと)
- issues/closed に移動するときは issue ファイルに「## 解決方法」セクションを追記し、何をどう修正したかを明記すること
設計判断が必要な issue の場合
- 外部依存の追加や設計判断が必要で保留中の issue は
issues/pending/に置くこと - issues/pending に移動するときは issue ファイルに pending にした理由を明記すること
- pending の issue は修正せずそのまま残す（close しない）
テストについて
- モックやスタブは絶対に利用しないこと
変更履歴について
- 変更履歴は
CHANGES.mdに記載すること - 変更の種別は以下の 4 つを使うこと
[CHANGE]: 後方互換のない変更[ADD]: 後方互換がある追加[UPDATE]: 後方互換がある変更[FIX]: バグ修正
- エントリは種別の順番を守って記載すること（CHANGE → ADD → UPDATE → FIX の順）
- 機能に直接影響しない変更（ドキュメント追加、リファクタリング等）は
### miscサブセクションに記載すること - 未リリースの変更は
## developセクションに追記すること - 各エントリは
- [種別] 変更内容を〜するという形で書くというフォーマットにすること - 各エントリの担当者はエントリの次の行に記載し、変更内容より 2 文字分インデントを下げて
- @ユーザー名の形式にすること - 担当者の行はそのエントリの最後に書くこと
- 変更内容の説明は日本語で書くこと
- リリース時は
## developを## バージョンに変更し、**リリース日**: YYYY-MM-DDを記載すること - 変更履歴は派生元ブランチとの最終的な差分のみを記載すること
- 開発ブランチ内の中間状態の修正は記載しないこと
webcodecs-py
- 後方互換性は考慮しないこと
- 一時的な修正はしないこと
- 変数名を省略しないこと
- 何か変更をする場合はテストを先に修正すること
keyframeではなくkey_frameとすること
カットオフについて
- CMake の最新版は 4.2.1
- Python の最新版は 3.14
Git について
- 勝手にプッシュしないこと
デバッグについて
- かならず timeout を指定する事
- timeout は最大でも 10 秒以内に収めること
- pytest 時は pytest の --timeout オプションを利用すること
コメントについて
- 末尾コメントを利用しないこと
仕様について
- WebCodecs API にできるだけ準拠すること
- WebCodecs API 自体が正式リリースされていないため、後方互換性を考慮しないこと
- WebCodecs API に準拠していない API を追加する場合は確認すること
- 確認する際はなぜ追加が必要なのかを丁寧にわかりやすく解説すること
C/C++
make formatでフォーマットすること
pyi スタブファイル
- pyi ファイルは nanobind の stubgen で自動生成されるため、直接編集しないこと
- 型情報を変更したい場合は C++ バインディングで nanobind の
nb::sigを使用すること make developでビルドすると pyi ファイルが再生成される
ビルド
- ビルドは timeout は 300 秒以内に収めること
- 開発中は
make developでビルドすること - リリース時は
uv build --wheelでビルドすること
ソース
_deps/以下に依存ライブラリのソースコードがあるのでそれを利用すること
Python
- pip を使わず uv を使うこと
- 直接 python を使わず uv 経由で使うこと
matchを利用することnumpy.ndarrayを利用することmake formatでフォーマットすることuv run ty checkで型チェックを行うことuv run pytestでテストを実行すること- Python の命名規則に従うこと
- 動作を確認やデバッグを行うときはかならず pytest を利用すること
- tests/ 以下にテストケースを追加してテストすること
- test_debug_ という prefix から始めること
- test_debug_ は不要になったら削除すること
- 勝手にフォールバックしないこと
- Python ではなく C++ で機能を実装すること
- 最小の Python は 3.12 をサポートすること
- 最大の Python は 3.14 をサポートすること
型アノテーション
Optionalではなく| Noneを使うこと
GIL
- GIL の取得と解放は nanobind の仕組みを利用すること
pytest
- テストは pytest のみを利用すること
- タスクを完了する前に全てのテストを実行して、全てのテストが通ることを確認すること
- pytest 実行時長くても 60 秒以内にすること
- pytest のタイムアウトは pytest-timeout を利用すること
pytest --timeout=10のように指定すること
- テスト実行時は
NO_UV_SYNC=1を指定することNO_UV_SYNC=1 uv run pytestのように指定すること
- テストを削除してテストを通したりしないこと
- テストを無効にしてテストを通したりしないこと
- テストがタイムアウトしたら重大な問題が発生していると考えること
- デッドロックが発生している可能性がある
- 明確な理由がない限りは try/expect をテストでは利用しないこと
- class を使わないこと
- lambda は使わないで def を使うこと
ベンチマーク
- ベンチマークは
tests/benchmarks/以下に配置すること - ベンチマークファイルは
bench_prefix を持つファイルのみが実行される - 通常の pytest 実行時はベンチマークは無効化されている (
--benchmark-disable) - ベンチマークを実行するには
--benchmark-enableオプションで有効化するNO_UV_SYNC=1 APPLE_VIDEO_TOOLBOX=1 uv run pytest tests/benchmarks/ --benchmark-enable
ドキュメント
- WebCodecs API に準拠していない独自拡張は必ず docs/PYTHON_INTERFACE.md に記載すること
- API 変更時は docs/PYTHON_INTERFACE.md を必ず更新すること
- 独自拡張を追加する際は、なぜ必要なのかを明確に記載すること
- ドキュメントは Audio 、 Video の順番で記載すること
Issues 管理
- issues は develop ブランチに作成すること
- ブランチ削除時に消えないようにするため
GitHub Actions の URL
- まずは gh コマンドで確認すること