Menu
マクロ仕様書の新規作成・レビュー・修正を行うスキル。Use when: ユーザが「仕様書を書いて」「specを作成」「仕様書レビュー」「仕様のテンプレート」と言ったとき、または spec/agent/ 配下のMarkdownを扱うとき。Nintendo Switch自動化マクロの設計仕様・実装仕様・テスト方針を所定フォーマットで執筆する。
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
| name | macro-spec-writing |
| description | マクロ仕様書の新規作成・レビュー・修正を行うスキル。Use when: ユーザが「仕様書を書いて」「specを作成」「仕様書レビュー」「仕様のテンプレート」と言ったとき、または spec/agent/ 配下のMarkdownを扱うとき。Nintendo Switch自動化マクロの設計仕様・実装仕様・テスト方針を所定フォーマットで執筆する。 |
Project NyX のマクロ仕様書を、リポジトリ規約に従って執筆・レビュー・修正するためのスキル。
spec/agent/ 配下の Markdown を編集するときspec/macro/{macro_name}/spec.md # メイン仕様書
spec/macro/{macro_name}/補助ドキュメント.md # 補足（任意）
{macro_name} は macros/ 配下のパッケージ名と一致させる（小文字スネークケース）spec.md で統一以下の 6 セクションを 必ず 含めること。
# {機能名} 仕様書
## 1. 概要
### 1.1 目的
### 1.2 用語定義
## 2. 対象ファイル
| ファイル | 変更種別 | 変更内容 |
## 3. 設計方針
## 4. 実装仕様
## 5. テスト方針
## 6. 実装チェックリスト
1〜3 文で機能の目的を明記。
表形式で統一。 本リポジトリで頻出する用語例:
| 用語 | 定義 |
|---|---|
| frame | 1/60 秒を 1 単位とする時間の最小単位 |
| advance | LCG32 の消費回数（乱数を 1 回引く = 1 advance） |
| frame1_offset | ユーザ補正用のオフセット（frame 単位） |
| advance_offset | プラットフォーム固有の補正値（advance 単位） |
| rng_multiplier | 1 frame あたりの乱数消費倍率（Switch=2, GC=1） |
マクロ固有の用語があれば追加する。
| ファイル | 変更種別 | 変更内容 |
|---|---|---|
macros/xxx/macro.py | 新規 | メインマクロ |
resources/xxx/settings.toml | 新規 | 設定ファイル |
変更種別は 新規 / 変更 / 削除 のいずれか。
以下を必要に応じて含める:
seed_{n+1} = (0x41C64E6D × seed_n + 0x6073) mod 2^32seconds = frames / 59.7275| パラメータ | 型 | デフォルト | 説明 |
|---|---|---|---|
min_frame | int | 500 | 最小フレーム |
仕様書冒頭に以下のメタデータブロックを置いてもよい。 移植の場合は「元ファイル」「移植スコープ」を記載し、新規作成の場合は省略してよい。
> **対象タイトル**: ポケットモンスター ファイアレッド・リーフグリーン
> **目的**: ──
> **元ファイル**: references/XXX.csx ← 移植時のみ
> **移植スコープ**: Switch 720p のみ ← 移植時のみ
> **関連仕様**: [別仕様書名](../別仕様書.md)
テストケースを表形式で列挙:
| テスト種別 | テスト名 | 検証内容 |
|---|---|---|
| ユニット | test_xxx | ── |
| 結合 | test_xxx_integration | ── |
- [ ] settings.toml 作成
- [ ] macro.py 実装
- [ ] 共通部品の抽出・既存部品の再利用確認
- [ ] ユニットテスト作成・パス
- [ ] 統合テスト作成・パス
- [ ] 実機動作確認
完了時は [x] でマーク。
マクロ仕様書を書く際は、以下の原則を設計方針セクションに反映すること。
Command 経由に集約し、ロジック関数には渡さないCommand なしで単体テスト可能になる# Good: 純粋関数 — テスト容易
def calc_target_frame(base_frame: int, offset: int, fps: float) -> float:
return (base_frame + offset) / fps
# Bad: Command に依存 — テスト困難
def calc_and_wait(cmd: Command, base_frame: int, offset: int) -> None:
cmd.wait((base_frame + offset) / 59.7275)
MacroBase サブクラス) のインスタンス変数は 設定値 と 最小限の実行状態 に限定するself に蓄積しないconfig.py の dataclass / frozen dataclass に分離し、マクロクラスから独立させるmacros/shared/ に抽出済みの共通部品:
| モジュール | 提供関数 | 用途 |
|---|---|---|
macros.shared.timer | start_timer() / consume_timer() | フレーム精度タイマー |
macros.shared.image_utils | crop_and_pad() | ROI 切り出し + 白パディング |
macros.shared.ocr_utils | warmup_ocr() | OCR エンジンの初回レイテンシ解消 |
仕様書作成時に設計方針セクションで以下を検討すること:
macros/shared/ への追加方針を仕様書に記載macros/xxx/ → nyxpy.framework.* OK (フレームワーク依存)
macros/xxx/ → macros/shared/* OK (共通部品依存)
macros/xxx/ → macros/yyy/* NG (マクロ間の直接依存)
Command に依存せず、引数と戻り値のみでやり取りするresources/<macro_id> を標準配置にし、旧 static/<macro_name> を前提にしないspec/macro/{macro_name}/references/ や既存の macros/ を読み、アルゴリズム・タイミング情報を抽出spec/macro/ の既存仕様書からパターンや用語を参照[x] に更新python, toml など）code span で、ブロックは独立行で記載|---| を必ず入れるフレームワーク本体 (src/nyxpy/framework/) の仕様書を新規作成・レビュー・修正するスキル。Use when: ユーザが「フレームワークの仕様書」「framework spec」「コア機能の設計書」「Command / MacroBase / imgproc / logger 等の仕様」と言ったとき、または spec/agent/ 配下でフレームワーク関連の Markdown を扱うとき。フレームワーク層の公開 API・内部設計・テスト方針を所定フォーマットで執筆する。マクロ (macros/) の仕様書には macro-spec-writing スキルを使うこと。
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 を使う。