菜单
フレームワーク本体 (src/nyxpy/framework/) の仕様書を新規作成・レビュー・修正するスキル。Use when: ユーザが「フレームワークの仕様書」「framework spec」「コア機能の設計書」「Command / MacroBase / imgproc / logger 等の仕様」と言ったとき、または spec/agent/ 配下でフレームワーク関連の Markdown を扱うとき。フレームワーク層の公開 API・内部設計・テスト方針を所定フォーマットで執筆する。マクロ (macros/) の仕様書には macro-spec-writing スキルを使うこと。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
マクロ仕様書の新規作成・レビュー・修正を行うスキル。Use when: ユーザが「仕様書を書いて」「specを作成」「仕様書レビュー」「仕様のテンプレート」と言ったとき、または spec/agent/ 配下のMarkdownを扱うとき。Nintendo Switch自動化マクロの設計仕様・実装仕様・テスト方針を所定フォーマットで執筆する。
Project NyX の PyPI release を計画・実行する workflow skill。USE WHEN: ユーザが PyPI / TestPyPI への公開、バージョン更新、release PR、v* tag、GitHub Actions publish、公開後 smoke check、release 手順の確認を依頼したとき。
作業ブランチを GitHub PR 経由で main にマージし、ローカル同期・ブランチ削除まで一括実行するワークフロースキル。USE WHEN: ユーザが「PRを出して」「マージして」「ブランチをまとめて」「mainに入れて」「PRクリーンアップ」など、作業ブランチの変更をリモートに反映したい意図を示したとき。push → PR作成 → squashマージ → ローカル同期 → ブランチ削除の全ステップを自動化する。
実装中の設計上の気づき・疑問・バックログ送りにしたタスクを spec/dev-journal.md に記録するスキル。USE WHEN: ユーザが「ジャーナルに書いて」「メモしておいて」「dev-journal に追記して」「これ記録して」「あとで見返せるようにして」「バックログに入れて」「後回しにしたい」など、実装中の気づきや先送りタスクの記録を依頼したとき。spec/dev-journal.md を読み書きするときは必ず参照すること。
Project NyX のマクロ実装・修正・レビューを行うスキル。USE WHEN: ユーザが「マクロを作って」「マクロを直して」「macros/ 配下を実装」「resources/ の設定を追加」「NyX の MacroBase / Command を使う」「examples/macros を参考にしたい」など、Nintendo Switch 自動化マクロのコード・設定・テストを扱う意図を示したとき。仕様書だけを書く場合は macro-spec-writing を使う。
| name | framework-spec-writing |
| description | フレームワーク本体 (src/nyxpy/framework/) の仕様書を新規作成・レビュー・修正するスキル。Use when: ユーザが「フレームワークの仕様書」「framework spec」「コア機能の設計書」「Command / MacroBase / imgproc / logger 等の仕様」と言ったとき、または spec/agent/ 配下でフレームワーク関連の Markdown を扱うとき。フレームワーク層の公開 API・内部設計・テスト方針を所定フォーマットで執筆する。マクロ (macros/) の仕様書には macro-spec-writing スキルを使うこと。 |
Project NyX のフレームワーク本体 (src/nyxpy/framework/) に対する仕様書を、リポジトリ規約に従って執筆・レビュー・修正するためのスキル。
spec/agent/ 配下でフレームワーク関連の Markdown を編集するときsrc/nyxpy/framework/ のモジュール設計を文書化するときmacros/ 配下のマクロパッケージの仕様書macros/shared/ 共通部品の仕様書（ただし共通部品がフレームワーク層に昇格する場合は本スキル）spec/agent/wip/local_{連番}/FEATURE_NAME.md # 着手中
spec/agent/complete/local_{連番}/FEATURE_NAME.md # 完了済み
CAPTURE_PIPELINE.md, LOG_MANAGER_V2.md）wip → complete にディレクトリ移動機能が安定したら以下にも配置を検討する:
spec/framework/{module_name}/spec.md # メイン仕様書
spec/framework/{module_name}/補助ドキュメント.md # 補足（任意）
{module_name} は src/nyxpy/framework/core/ 配下のパッケージ名と対応させる
macro, hardware, imgproc, logger, settings, api, utils以下の 6 セクションを 必ず 含める。
# {機能名} 仕様書
## 1. 概要
### 1.1 目的
### 1.2 用語定義
### 1.3 背景・問題
### 1.4 期待効果
### 1.5 着手条件
## 2. 対象ファイル
| ファイル | 変更種別 | 変更内容 |
## 3. 設計方針
## 4. 実装仕様
## 5. テスト方針
## 6. 実装チェックリスト
1〜3 文で機能の目的を明記。フレームワーク層の責務を明確にする。
表形式で統一。 フレームワーク仕様で頻出する用語例:
| 用語 | 定義 |
|---|---|
| Command | マクロがハードウェア操作（ボタン入力・キャプチャ・ログ）を行うための高レベル API |
| MacroBase | ユーザ定義マクロの抽象基底クラス。initialize / run / finalize ライフサイクルを持つ |
| CancellationToken | スレッドセーフなマクロ中断メカニズム |
| ImageProcessor | テンプレートマッチング・OCR を統合した画像処理ファサード |
| LoggerPort | Runtime から注入されるログ出力 port。ユーザ向け event と technical log を分離する |
| MacroRuntimeBuilder | Registry と各種 port factory から実行 context を組み立てる composition root |
| SerialProtocolInterface | シリアル通信プロトコルの抽象インターフェース |
| FrameSourcePort | Runtime が最新 frame を取得するための入力 port |
マクロ固有の用語（frame, advance 等）や、新機能固有の用語があれば追加する。
現状の課題やリファクタリング動機を簡潔に記述する。
表形式で定量的に記載。
| 指標 | 現状 | 目標 |
|---|---|---|
| API 呼び出し回数 | ── | ── |
| テストカバレッジ | ── | ── |
定量化が困難な場合は定性的な記述でも可とするが、測定可能な基準を優先する。
| ファイル | 変更種別 | 変更内容 |
|---|---|---|
src/nyxpy/framework/core/xxx/yyy.py | 新規 | ── |
tests/unit/test_xxx.py | 新規 | ── |
変更種別は 新規 / 変更 / 削除 のいずれか。
以下を必要に応じて含める:
| パラメータ | 型 | デフォルト | 説明 |
|---|---|---|---|
xxx | str | "" | ── |
テストケースを表形式で列挙:
| テスト種別 | テスト名 | 検証内容 |
|---|---|---|
| ユニット | test_xxx | ── |
| 結合 | test_xxx_integration | ── |
| ハードウェア | test_xxx_device | @pytest.mark.realdevice |
| パフォーマンス | test_xxx_perf | ── |
テスト配置ルール:
tests/unit/ — 純粋ロジックの単体テストtests/integration/ — 複数モジュールの結合テストtests/hardware/ — 実機必要テスト（@pytest.mark.realdevice）tests/perf/ — パフォーマンステスト- [ ] 公開 API のシグネチャ確定
- [ ] 内部実装
- [ ] 既存テストが破壊されないことの確認
- [ ] ユニットテスト作成・パス
- [ ] 統合テスト作成・パス
- [ ] 型ヒントの整合性チェック（pyright / ruff）
- [ ] ドキュメントコメント（公開 API のみ）
完了時は [x] でマーク。
仕様書を書く際は、以下の原則を設計方針セクションに反映すること。
SerialCommInterface, CaptureDeviceInterface, SerialProtocolInterfaceDummySerialComm, DummyCaptureDevice）を用意し、実機なしでテスト可能にする# Good: インターフェースで抽象化
class NewDeviceInterface(ABC):
@abstractmethod
def connect(self) -> None: ...
# Bad: 具象クラスに直接依存
class MacroBase:
def __init__(self):
self.device = ConcreteDevice() # テスト困難
macros/xxx/ → nyxpy.framework.* OK （フレームワーク依存）
nyxpy.framework.* → macros/xxx/ NG （逆依存禁止）
nyxpy.gui → nyxpy.framework.* OK （GUI がフレームワークを使う）
nyxpy.framework.* → nyxpy.gui NG （フレームワークが GUI に依存しない）
フレームワーク層は 下位レイヤー（ハードウェア抽象・ユーティリティ）にのみ依存し、上位レイヤー（GUI・CLI・マクロ）には依存しない。
singletons.py への依存は cleanup 対象として扱い、互換目的で延命しないwarnings.warn()、旧名 alias、import 互換 module を追加して旧実装を延命しないCancellationToken はスレッドセーフに設計されている（threading.Event ベース）AsyncCaptureDevice はフレームキャッシュに threading.Lock を使用python, toml など）code span で記載|---| を必ず入れる仕様書のスコープ設定に使える。対象モジュールを選ぶ際の参考にすること。
| パッケージ | 主要クラス / 関数 | 責務 |
|---|---|---|
core/macro/ | MacroBase, Command, DefaultCommand, MacroRegistry | マクロ公開 API と登録 |
core/runtime/ | MacroRuntime, MacroRuntimeBuilder, MacroRunner, RunResult | 実行 context と lifecycle 制御 |
core/io/ | ControllerOutputPort, FrameSourcePort, ResourceStorePort, RunArtifactStore | Runtime の入出力 port と resource I/O |
core/hardware/ | SerialComm, DeviceDiscoveryService, CH552SerialProtocol, ThreeDSSerialProtocol | ハードウェア抽象化 |
core/imgproc/ | ImageProcessor, TemplateMatcher, OCRProcessor | 画像処理・OCR |
core/logger/ | LoggerPort, DefaultLogger, LogSinkDispatcher, JsonlLogBackend | 構造化ログと sink dispatch |
core/settings/ | GlobalSettings, SecretsSettings | 設定永続化 |
core/notifications/ | NotificationHandler, DiscordNotification, BlueskyNotification | 外部通知 |
core/utils/ | CancellationToken | キャンセル制御 utility |
core/constants/ | Button, Hat, LStick, RStick, KeyType | 定数定義 |
spec/framework/archive/ 配下の旧設計ドキュメントを参考情報として参照する
src/nyxpy/framework/ のソースコードを正とする[x] に更新