📑

CLIでルーレットを作るためのSPEC.md

2025/11/10に公開

 Roulette CLI - Project Specification
 プロジェクト概要プロジェクト名: Roulette CLI

バージョン: 0.1.0

リポジトリ: https://github.com/※※※※/roulette-cli

ライセンス: MIT

開発状況: Alpha
インタラクティブなアニメーション付きルーレット機能を持つPython製CLIアプリケーション。メンバー管理、統計追跡、柔軟な入力オプションを備えた、uvプロジェクト管理ツールを使用した現代的なCLIツール。

 技術スタック
 パッケージ管理
uv: Python プロジェクト管理ツール

hatchling: ビルドバックエンド

 Python要件
Python: 3.8以上

対応バージョン: 3.8, 3.9, 3.10, 3.11, 3.12

 依存関係

パッケージ
バージョン
用途


click
>=8.1.0
CLIフレームワーク

rich
>=13.0.0
リッチな出力・アニメーション

pydantic
>=2.0.0
データバリデーション・設定管理


 アーキテクチャ
 ディレクトリ構造roulette-cli/
├── src/
│   └── roulette_cli/
│       ├── __init__.py      # パッケージ初期化
│       ├── main.py          # CLIエントリーポイント
│       ├── roulette.py      # コアルーレット機能
│       └── config.py        # 設定管理
├── pyproject.toml           # プロジェクト設定
├── README.md                # プロジェクトドキュメント
└── SPEC.md                  # 本ファイル

 モジュール設計
 1. main.py責務: CLIコマンドの定義とルーティング
主要コンポーネント:

cli(): メインコマンドグループ

hello(): 挨拶コマンド

spin(): ルーレット実行コマンド

members(): デフォルトメンバー表示

config(): 設定管理コマンドグループ

config_add(): メンバー追加

config_remove(): メンバー削除

config_list(): メンバー一覧

config_clear(): メンバー全削除

config_stats(): 統計表示

CLIオプション:

--version: バージョン表示

--help: ヘルプ表示

 2. roulette.py責務: ルーレットのコアロジック
クラス:

Roulette: ルーレット実行クラス

__init__(members: List[str]): 初期化

spin(show_animation: bool = True) -> str: ルーレット実行

_show_spinning_animation(): アニメーション表示（private）

_show_result(selected: str): 結果表示（private）

関数:

get_default_members() -> List[str]: デフォルトメンバー取得
デフォルトメンバー: Alice, Bob, Charlie, Diana, Eve, Frank

 3. config.py責務: 設定ファイルの読み書きと管理
データモデル:

RouletteConfig (Pydantic BaseModel)

members: List[str]: メンバーリスト

last_winner: Optional[str]: 最後の当選者

spin_count: int: 実行回数

クラス:

ConfigManager: 設定管理クラス
__init__(config_dir: Optional[Path] = None)
load_config() -> RouletteConfig
save_config(config: RouletteConfig) -> bool
add_member(member: str) -> bool
remove_member(member: str) -> bool
list_members() -> List[str]
clear_members() -> bool
update_stats(winner: str)
get_stats() -> dict

設定ファイル: ~/.roulette-cli/config.json

 機能仕様
 1. ルーレット実行（spin）コマンド: roulette-cli spin [OPTIONS]
オプション:


オプション
短縮形
型
説明


--members
-m
multiple
ルーレットに含めるメンバー（複数指定可）

--no-animation
-
flag
アニメーションをスキップ

--use-default
-
flag
デフォルトメンバーを使用

メンバー選択の優先順位:

--members オプション（コマンドライン引数）

--use-default フラグ（デフォルトリスト）
保存された設定ファイルのメンバー
動作フロー:
メンバーリストの決定
メンバー数とソースの表示
アニメーション実行（オプション）
ランダム選択
結果表示
統計更新（設定ファイル使用時のみ）
アニメーション仕様:
10回のサイクル
各サイクル0.3秒
メンバーリストを順番に表示
カーソル位置を上書き更新

 2. メンバー管理（config）
 追加コマンド: roulette-cli config add <NAME>
重複チェック実施
成功時に確認メッセージ表示

 削除コマンド: roulette-cli config remove <NAME>
存在チェック実施
成功時に確認メッセージ表示

 一覧表示コマンド: roulette-cli config list
メンバー数と一覧を表示
メンバーが0件の場合、追加方法を案内

 全削除コマンド: roulette-cli config clear
確認プロンプトを表示
確認後に全メンバーを削除

 統計表示コマンド: roulette-cli config stats
総実行回数
最後の当選者
総メンバー数

 3. その他のコマンド
 Helloコマンド: roulette-cli hello
挨拶メッセージを表示
プロジェクトの紹介

 Membersコマンド: roulette-cli members
デフォルトメンバーリストを表示
カスタムメンバー使用方法を案内

 UI/UX設計
 カラースキーム
成功: green

エラー: red/bold red

警告: yellow

情報: cyan/blue

強調: bold

 アイコン使用🎰: ルーレット
👥: メンバー
✨: 当選
🎯: 選択
🎉: 祝福
✅: 成功
❌: エラー
⚠️: 警告
💡: ヒント
📊: 統計
📝: リスト

 メッセージング成功時: 明確なフィードバック
エラー時: 問題と解決方法を提示
ヒント: 次のアクションを提案

 インストール方法
 エンドユーザー向け
 PyPIから（パブリック公開時）uvx roulette-cli

 プライベートリポジトリから（現在）uvx --from git+https://github.com/※※※※/roulette-cli.git roulette-cli

 開発者向けgit clone https://github.com/※※※※/roulette-cli.git
cd roulette-cli
uv sync
uv run roulette-cli

 使用例
 基本的な使い方# 設定にメンバーを追加
roulette-cli config add "Alice"
roulette-cli config add "Bob"
roulette-cli config add "Charlie"

# ルーレットを実行
roulette-cli spin

# 統計を確認
roulette-cli config stats

 ワンショット実行# 設定を使わず、その場でメンバーを指定
roulette-cli spin --members Alice --members Bob --members Charlie

 デフォルトメンバーで実行# 設定を無視してデフォルトメンバーを使用
roulette-cli spin --use-default

 アニメーションなしで実行# 高速実行（アニメーションスキップ）
roulette-cli spin --no-animation

 データ永続化
 設定ファイル
パス: ~/.roulette-cli/config.json

フォーマット: JSON

エンコーディング: UTF-8

インデント: 2スペース

 データ構造{
  "members": ["Alice", "Bob", "Charlie"],
  "last_winner": "Bob",
  "spin_count": 42
}

 エラーハンドリング
 設定ファイルファイル不存在: デフォルト設定を使用
JSON解析エラー: 警告表示＋デフォルト設定
バリデーションエラー: 警告表示＋デフォルト設定

 メンバー管理重複追加: 警告表示＋操作キャンセル
存在しないメンバーの削除: 警告表示＋操作キャンセル
空のメンバーリストでspin: エラー表示＋ヒント表示

 ルーレット実行メンバー未設定: エラー表示＋追加方法の案内
予期しないエラー: エラーメッセージ表示

 テスト戦略
 現在の状態手動テスト実施済み
自動テスト未実装

 今後のテスト計画ユニットテスト

Rouletteクラス

ConfigManagerクラス
ヘルパー関数
統合テスト
CLIコマンドの動作
ファイルI/O
エラーハンドリング
E2Eテスト
実際のCLI実行シナリオ

 デプロイメント
 現在のステータスプライベートリポジトリ: GitHub
GitHub認証: gh CLI経由でHTTPS認証済み
パッケージレジストリ: 未公開

 実行方法# リモート実行（プライベートリポジトリ）
uvx --from git+https://github.com/※※※※/roulette-cli.git roulette-cli

# ローカル開発
uv run roulette-cli

 将来の展開
 PyPIへの公開

 GitHub Releasesでのバイナリ配布

 Homebrewフォーミュラ作成（macOS）

 制約・制限事項
 技術的制約Python 3.8以上が必要
ターミナル環境でのみ動作
Unicode/絵文字対応ターミナル推奨

 機能的制約メンバー数に上限なし（理論上）
アニメーション速度は固定（0.3秒/サイクル）
統計データはローカルのみ（クラウド同期なし）

 セキュリティローカル設定ファイルのみ使用
ネットワーク通信なし（パッケージインストール時を除く）
機密情報の保存なし

 パフォーマンス
 想定ユースケースメンバー数: 2〜100名程度
実行頻度: 日次〜週次
設定ファイルサイズ: 数KB程度

 パフォーマンス特性起動時間: 即座（<1秒）
アニメーション時間: 約3秒（10サイクル × 0.3秒）
ファイルI/O: 最小限（必要時のみ）

 今後の拡張案
 短期的改善
 テストスイートの実装

 CI/CDパイプラインの構築

 PyPIへの公開

 中期的機能追加
 重み付けルーレット（各メンバーに確率設定）

 履歴機能（過去の当選履歴を表示）

 エクスポート/インポート機能（設定の共有）

 テーマ/カラースキームのカスタマイズ

 変更履歴
 v0.1.0 (2025-11-07)✅ 初期リリース
✅ 基本的なルーレット機能
✅ メンバー管理機能
✅ 統計追跡機能
✅ アニメーション表示
✅ 設定ファイル管理
✅ プライベートリポジトリからのuvx実行確認
✅ ディレクトリ名の修正（roulet-cli → roulette-cli）

 メンテナンス
 開発環境
OS: macOS

Shell: zsh

エディター: VS Code

パッケージ管理: uv

 コード品質
リンター: ruff

ターゲットPython: 3.8

行長: 88文字

フォーマット: ruff互換

 ドキュメントREADME.md: ユーザー向けドキュメント
SPEC.md: 技術仕様書（本ファイル）
コード内docstring: 全関数・クラスに記載

 連絡先・サポート
Repository: https://github.com/※※※※/roulette-cli

Issues: GitHub Issues

Owner: ※※※※
Last Updated: 2025-11-10

Document Version: 1.0.0

パッケージ	バージョン	用途
click	>=8.1.0	CLIフレームワーク
rich	>=13.0.0	リッチな出力・アニメーション
pydantic	>=2.0.0	データバリデーション・設定管理

オプション	短縮形	型	説明
--members	-m	multiple	ルーレットに含めるメンバー（複数指定可）
--no-animation	-	flag	アニメーションをスキップ
--use-default	-	flag	デフォルトメンバーを使用

Roulette CLI - Project Specification

プロジェクト概要

技術スタック

パッケージ管理

Python要件

依存関係

アーキテクチャ

ディレクトリ構造

モジュール設計

1. main.py

2. roulette.py

3. config.py

機能仕様

1. ルーレット実行（spin）

2. メンバー管理（config）

追加

削除

一覧表示

全削除

統計表示

3. その他のコマンド

Hello

Members

UI/UX設計

カラースキーム

アイコン使用

メッセージング

インストール方法

エンドユーザー向け

PyPIから（パブリック公開時）

プライベートリポジトリから（現在）

開発者向け

使用例

基本的な使い方

ワンショット実行

デフォルトメンバーで実行

アニメーションなしで実行

データ永続化

設定ファイル

データ構造

エラーハンドリング

設定ファイル

メンバー管理

ルーレット実行

テスト戦略

現在の状態

今後のテスト計画

デプロイメント

現在のステータス

実行方法

将来の展開

制約・制限事項

技術的制約

機能的制約

セキュリティ

パフォーマンス

想定ユースケース

パフォーマンス特性

今後の拡張案

短期的改善

中期的機能追加

変更履歴

v0.1.0 (2025-11-07)

メンテナンス

開発環境

コード品質

ドキュメント

連絡先・サポート

Discussion