framework-spec-writing

スター6

フォーク2

更新日2026年7月26日 12:05

フレームワーク本体 (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 ページを確認してインストールできます。

ソース

niart120

niart120/Project_NyX

GitHub リポジトリを開く Creator のリポジトリを見る

ダウンロード

フレームワーク仕様書執筆スキル

Project NyX のフレームワーク本体 (src/nyxpy/framework/) に対する仕様書を、リポジトリ規約に従って執筆・レビュー・修正するためのスキル。

いつ使うか

フレームワークの新機能・リファクタリングの仕様書を作成するとき
既存フレームワーク仕様書のレビュー・修正を行うとき
spec/agent/ 配下でフレームワーク関連の Markdown を編集するとき
src/nyxpy/framework/ のモジュール設計を文書化するとき

対象外（macro-spec-writing を使うべきケース）

macros/ 配下のマクロパッケージの仕様書
macros/shared/ 共通部品の仕様書（ただし共通部品がフレームワーク層に昇格する場合は本スキル）

ディレクトリ規約

新規執筆（spec/agent/ 経由）

spec/agent/wip/local_{連番}/FEATURE_NAME.md    # 着手中
spec/agent/complete/local_{連番}/FEATURE_NAME.md  # 完了済み

ファイル名は 大文字スネークケース（例: CAPTURE_PIPELINE.md, LOG_MANAGER_V2.md）
完了後は wip → complete にディレクトリ移動

永続化（spec/ 配下）

機能が安定したら以下にも配置を検討する:

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. 概要

1.1 目的

1〜3 文で機能の目的を明記。フレームワーク層の責務を明確にする。

1.2 用語定義

表形式で統一。 フレームワーク仕様で頻出する用語例:

用語	定義
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 等）や、新機能固有の用語があれば追加する。

1.3 背景・問題

現状の課題やリファクタリング動機を簡潔に記述する。

1.4 期待効果

表形式で定量的に記載。

指標	現状	目標
API 呼び出し回数	──	──
テストカバレッジ	──	──

定量化が困難な場合は定性的な記述でも可とするが、測定可能な基準を優先する。

1.5 着手条件

前提となる他の仕様や機能を列挙する
既存テストが通ること、など

2. 対象ファイル

ファイル	変更種別	変更内容
`src/nyxpy/framework/core/xxx/yyy.py`	新規	──
`tests/unit/test_xxx.py`	新規	──

変更種別は 新規 / 変更 / 削除 のいずれか。

3. 設計方針

以下を必要に応じて含める:

アーキテクチャ上の位置づけ: 変更対象が全体アーキテクチャのどこに位置するか
公開 API 方針: 新規 API の合理性、既存 API との整合性
後方互換性: 破壊的変更の有無と移行計画
レイヤー構成: モジュール分割方針、依存方向
性能要件: 表形式で定量的に記載
並行性・スレッド安全性: 必要に応じてロック戦略やスレッドモデルを記述

4. 実装仕様

公開インターフェース: クラス図またはシグネチャ一覧を Python コードブロックで記載
内部設計: 必要に応じてシーケンス図や状態遷移を記述
設定パラメータ: 4 列の表形式

パラメータ	型	デフォルト	説明
`xxx`	`str`	`""`	──

エラーハンドリング: カスタム例外の定義と発生条件
シングルトン管理: 新規グローバル singleton は原則追加しない。既存 singleton を残す場合は互換目的ではなく現行責務として必要な理由を明記

5. テスト方針

テストケースを表形式で列挙:

テスト種別	テスト名	検証内容
ユニット	`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/ — パフォーマンステスト

6. 実装チェックリスト

- [ ] 公開 API のシグネチャ確定
- [ ] 内部実装
- [ ] 既存テストが破壊されないことの確認
- [ ] ユニットテスト作成・パス
- [ ] 統合テスト作成・パス
- [ ] 型ヒントの整合性チェック（pyright / ruff）
- [ ] ドキュメントコメント（公開 API のみ）

完了時は [x] でマーク。

フレームワーク設計原則

仕様書を書く際は、以下の原則を設計方針セクションに反映すること。

インターフェース駆動設計

ハードウェア依存を ABC（抽象基底クラス） で隔離する
- SerialCommInterface, CaptureDeviceInterface, SerialProtocolInterface
テスト用 Dummy 実装（DummySerialComm, 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・マクロ）には依存しない。

シングルトンの管理

新規グローバル singleton は原則追加しない
Runtime、Port、settings store、secrets store、device manager は composition root またはテスト fixture が lifetime を所有する
既存 singletons.py への依存は cleanup 対象として扱い、互換目的で延命しない

後方互換性

Project NyX のフレームワーク本体はアルファ版として扱い、再設計や cleanup では破壊的変更を許容する
レガシー API、互換 shim、旧 import path、旧設定経路は、ユーザから明示的に求められない限り移行期間を設けず削除する
warnings.warn()、旧名 alias、import 互換 module を追加して旧実装を延命しない
旧実装を残す場合は、後方互換性ではなく現行アーキテクチャ上の責務として必要な理由を仕様書に明記する

スレッド安全性

CancellationToken はスレッドセーフに設計されている（threading.Event ベース）
AsyncCaptureDevice はフレームキャッシュに threading.Lock を使用
シングルトンへのアクセスが複数スレッドから行われる場合はロック戦略を明記する

記述スタイルガイド

言語: 日本語で記述。技術用語（Command, MacroBase, ABC, OCR 等）は英語のまま使用
文体: 事実ベース・簡潔に。「である」調
コードブロック: 言語指定付き（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`	定数定義

執筆手順

新規作成 (new)

スコープ確認: 変更対象のフレームワークモジュールを特定する
現状調査: 対象モジュールのソースコードを読み、公開 API・内部構造を把握する
関連ドキュメント確認: spec/framework/archive/ 配下の旧設計ドキュメントを参考情報として参照する
- spec/framework/archive/architecture.md — 全体アーキテクチャ
- spec/framework/archive/logging_design.md — ロガー設計
- spec/framework/archive/protocol_design.md — プロトコル設計
- spec/framework/archive/macro_design.md — マクロ基盤設計
- spec/framework/archive/notification_system.md — 通知システム設計
- 現行仕様は src/nyxpy/framework/ のソースコードを正とする
影響範囲分析: GUI・CLI・既存マクロへの影響を洗い出す
テンプレート展開: テンプレートファイルをコピーし各セクションを埋める
後方互換チェック: 既存の公開 API を変更する場合は移行ガイドを記述
テスト方針策定: Dummy 実装で単体テスト可能かを確認

レビュー (review)

対象ファイルを読み込む
以下の観点でチェック:
- 6 セクションすべてが存在するか
- 用語定義が表形式か
- 公開 API のシグネチャが Python コードブロックで記載されているか
- 依存方向の制約が守られているか
- 後方互換性への言及があるか（破壊的変更の場合）
- テスト方針にテスト種別（unit / integration / hardware / perf）が明記されているか
- 設計原則（インターフェース駆動・シングルトン管理・スレッド安全性）が反映されているか
問題点を箇条書きで報告し修正案を提示

修正 (fix)

レビュー結果に基づき対象ファイルを編集
チェックリストの該当項目を [x] に更新

framework-spec-writing

このリポジトリの他の Skills

このリポジトリの他の Skills

フレームワーク仕様書執筆スキル

いつ使うか

対象外（macro-spec-writing を使うべきケース）

ディレクトリ規約

新規執筆（spec/agent/ 経由）

永続化（spec/ 配下）

必須セクション構成

各セクションの記述規約

1. 概要

1.1 目的

1.2 用語定義

1.3 背景・問題

1.4 期待効果

1.5 着手条件

2. 対象ファイル

3. 設計方針

4. 実装仕様

5. テスト方針

6. 実装チェックリスト

フレームワーク設計原則

インターフェース駆動設計

依存方向の制約

シングルトンの管理

後方互換性

スレッド安全性

記述スタイルガイド

フレームワークモジュール一覧

執筆手順

新規作成 (new)

レビュー (review)

修正 (fix)

フレームワーク仕様書執筆スキル

いつ使うか

対象外（macro-spec-writing を使うべきケース）

ディレクトリ規約

新規執筆（spec/agent/ 経由）

永続化（spec/ 配下）

必須セクション構成

各セクションの記述規約

1. 概要

1.1 目的

1.2 用語定義

1.3 背景・問題

1.4 期待効果

1.5 着手条件

2. 対象ファイル

3. 設計方針

4. 実装仕様

5. テスト方針

6. 実装チェックリスト

フレームワーク設計原則

インターフェース駆動設計

依存方向の制約

シングルトンの管理

後方互換性

スレッド安全性

記述スタイルガイド

フレームワークモジュール一覧

執筆手順

新規作成 (new)

レビュー (review)

修正 (fix)