---
inclusion: always
---

# Qt-Theme-Manager ライブラリ単独化ステアリング

このステアリングドキュメントは、Qt-Theme-Managerプロジェクトのライブラリ単独化に関する開発ガイドラインと制約を定義します。

## 🎯 プロジェクト目標

Qt-Theme-Managerを**純粋なライブラリ**として整理し、GUIツール部分を別リポジトリ（qt-theme-studio）に分離する。

### 主要原則
- **ライブラリの純粋性**: `qt_theme_manager/` パッケージは一切変更しない（`theme_manager/`から名称変更）
- **後方互換性**: 既存APIの破壊的変更は禁止
- **依存関係最小化**: PySide6→PyQt6→PyQt5の自動判別機能を維持
- **コード品質**: 行長制限79文字、PEP 8準拠

## 📁 ライブラリ構造（保持するファイル）

```
qt-theme-manager/
├── qt_theme_manager/       # 🔒 コアライブラリ（フォルダ名を変更し類推しやすく）
│   ├── __init__.py
│   ├── main.py
│   ├── cli/                # CLI機能
│   ├── qt/                 # Qt統合モジュール
│   └── config/             # 設定ファイル
├── pyproject.toml          # ライブラリ設定
├── setup.py               # パッケージング設定
├── MANIFEST.in            # 配布ファイル設定
├── README.md              # ライブラリドキュメント
├── API_REFERENCE.md       # API仕様書
├── INSTALL.md             # インストールガイド
├── CHANGELOG.md           # 変更履歴
└── LICENSE                # ライセンス
```

## 🚫 移行対象ファイル（削除予定）

以下のファイルは`qt-theme-studio`リポジトリに移行後、このリポジトリから削除：

```
❌ launch_theme_editor.py
❌ launch_zebra_theme_editor.py
❌ launch_gui_preview.py
❌ theme_editor_zebra_extension.py
❌ zebra_pattern_editor.py
❌ analyze_zebra_colors.py
❌ improve_zebra_colors.py
❌ examples/                # ディレクトリ全体
❌ scripts/                 # ディレクトリ全体
❌ utils/                   # ディレクトリ全体
```

## 🔧 開発制約とルール

### コード標準
- **行長制限**: 79文字厳守
- **コードスタイル**: PEP 8準拠、black/isort/autoflake使用
- **ログ出力**: print文禁止、必ずloggerを使用
- **タイプヒント**: 全関数・メソッドに必須
- **docstring**: 全パブリックAPI要素に必須

### ファイル配置ルール
- **ルートディレクトリ**: メインエントリーポイント以外のスクリプト配置禁止
- **パッケージ構造**: `qt_theme_manager/` 以下の既存構造は変更禁止（`theme_manager/`から名称変更）
- **設定ファイル**: プロジェクトルートに配置（pyproject.toml等）

### 依存関係管理
- **Qt自動判別**: PySide6→PyQt6→PyQt5の順で自動選択機能を維持
- **最小依存**: 必要最小限の依存関係のみ
- **オプション依存**: 開発用依存関係は`[dev]`セクションに分離

## 📋 実装フェーズガイドライン

### フェーズ1: 移行準備（1週間）
1. **移行ファイル移動**
   - 移行対象ファイルを元の場所から`migrate/`フォルダに移動
   - **重要**: qt-theme-studioリポジトリへの実際の移行作業は手動で実行
   - AIは`migrate/`フォルダへの移動のみ実行、`migrate/`フォルダ削除は人間が手動で行う

2. **ライブラリ最適化**
   - コード品質向上（black/isort/autoflake）
   - 未使用インポート削除
   - テストカバレッジ向上（95%目標）

3. **ドキュメント更新**
   - ライブラリ専用README作成（ライブラリ単独化の背景・思想・意義セクション含む）
   - API仕様書更新
   - インストールガイド更新
   - README思想セクション追加例:
     ```markdown
     ## ライブラリ単独化の背景
     本プロジェクトは、GUIとライブラリの関心分離を通じて、保守性・拡張性・構造美を追求しています。
     純粋なライブラリとして独立することで、外部開発者の貢献を促進し、長期的な持続可能性を実現します。
     ```

### フェーズ3: クリーンアップ（1日）
1. **移行完了確認**
   - qt-theme-studioでの動作確認完了後
   - ファイル移行の完全性確認

2. **クリーンアップ**
   - **手動作業**: `migrate/`フォルダの削除（移行完了後）
   - **手動作業**: ライブラリ専用構造の最終確認
   - **注意**: `migrate/`フォルダの削除は人間が手動で行う。AIは移動までを担当。

## 🧪 テスト要件

### カバレッジ目標
- **単体テスト**: 95%カバレッジ
- **統合テスト**: API互換性テスト
- **パフォーマンステスト**: メモリ使用量最適化
- **クロスプラットフォームテスト**: Windows/macOS/Linux対応

### テスト対象
- 全パブリックAPI
- Qt自動判別機能
- CLI機能
- 設定ファイル処理
- エラーハンドリング

## 📦 パッケージング仕様

### PyPI配布設定
```toml
[project]
name = "qt-theme-manager"
version = "1.0.0"
description = "A comprehensive theme management library for PyQt5/PyQt6/PySide6 applications"
dependencies = [
    # Qt自動判別: PySide6 → PyQt6 → PyQt5
]

[project.optional-dependencies]
dev = [
    "pytest>=6.0",
    "pytest-qt>=4.0",
    "black",
    "isort",
    "flake8",
]
```

### 配布ファイル管理
- `MANIFEST.in`: 必要ファイルのみ含める
- `setup.py`: パッケージング設定
- `pyproject.toml`: モダンなPython設定

## 🚀 成功指標

### 定量的目標
- **コードサイズ**: 30%削減
- **依存関係**: 最小化
- **テストカバレッジ**: 95%以上
- **パフォーマンス**: 現在の速度維持または改善

### 定性的目標
- **関心の分離**: ライブラリとGUIの明確な分離
- **保守性**: 独立した開発・リリースサイクル
- **後方互換性**: 既存ユーザーへの影響なし
- **開発者体験**: 貢献しやすい構造

## 🔄 移行チェックリスト

### AI実行タスク（自動）
- [ ] 移行対象ファイルの`migrate/`フォルダへの移動完了
- [ ] `theme_manager/`から`qt_theme_manager/`への名称変更対応
- [ ] 既存テストの実行確認
- [ ] 依存関係の整理完了
- [ ] ドキュメント更新（ライブラリ単独化の思想セクション含む）完了
- [ ] コード品質向上（black/isort/autoflake）完了

### 手動実行タスク（人間）
- [ ] `migrate/`フォルダからqt-theme-studioリポジトリへの実際の移行
- [ ] `migrate/`フォルダの削除（移行完了後）
- [ ] ライブラリ単体での動作確認
- [ ] PyPI配布テスト完了
- [ ] API互換性テスト完了
- [ ] パフォーマンステスト完了
- [ ] ドキュメント整合性確認完了

## �  AIの責務と制約

### 実行許可範囲
- **ファイル移動**: `migrate/`フォルダへの移動のみ実行
- **コード品質**: black/isort/autoflake による整形
- **ドキュメント**: README、API仕様書、インストールガイドの更新
- **テスト**: 既存テストの実行確認

### 厳格な制約事項
- **削除禁止**: ファイル・フォルダの削除は一切行わない
- **パッケージ保護**: `qt_theme_manager/`パッケージは変更禁止(パッケージ名変更に伴う変更を除く)
- **print文禁止**: 必ずloggerを使用
- **日本語応答**: すべての応答は日本語で行う
- **ルート配置禁止**: メインエントリーポイント以外のスクリプトをルートに配置しない

### 開発アプローチ
- **段階的実装**: フェーズごとの確実な進行
- **安全第一**: 移動とテストを重視、削除は人間が担当
- **文書化**: 変更内容の詳細な記録
- **検証**: 各段階での動作確認

### 責任分離
- **AI担当**: `migrate/`フォルダへの移動、コード品質向上、ドキュメント更新
- **人間担当**: `migrate/`フォルダからqt-theme-studioへの移行、`migrate/`フォルダ削除、最終確認

---

このステアリングドキュメントに従って、Qt-Theme-Managerライブラリの単独化を安全かつ確実に実行してください。
