ポモドーロタイマープロジェクトの README.md - Amplifier（AI駆動開発ツール）で生成

pomodoro-timer-README.md

Pomodoro Timer

シンプルで効果的なポモドーロテクニック実装。集中力を維持し、生産性を向上させるための時間管理ツールです。

特徴

• 25分作業 + 5分休憩 - クラシックなポモドーロサイクル
• セッション記録 - すべての作業セッションを自動保存
• 統計表示 - 今日の集中時間、完了ポモドーロ数、連続日数を追跡
• OS通知 - セッション完了時にデスクトップ通知
• キーボードショートカット - 効率的な操作
• ローカルデータ保存 - プライバシー重視、クラウド不要

インストール

前提条件

• Python 3.11以上
• uv（パッケージマネージャー）

セットアップ

# リポジトリをクローン
git clone <repository-url>
cd pomodoro-timer

# 依存関係をインストール
uv sync

使い方

アプリケーションの起動

uv run streamlit run ui/app.py

ブラウザが自動的に開き、タイマーインターフェースが表示されます。

基本操作

1. 開始: 「Start」ボタンをクリックまたはSpaceキーを押す
2. 一時停止: タイマー実行中に「Pause」ボタンまたはSpaceキー
3. 停止: 「Stop」ボタンまたはEscキー
4. 休憩開始: Bキーで手動で休憩を開始
5. 統計表示: Sキーで統計ビューに切り替え

キーボードショートカット

キー	操作
Space	タイマーの開始/一時停止
Esc	タイマーの停止とリセット
B	休憩の手動開始
S	統計表示の切り替え

タイマーサイクル

1. 作業セッション - 25分間の集中作業
2. 短い休憩 - 5分間の休憩
3. 長い休憩 - 4ポモドーロごとに15分間の休憩

設定

デフォルト設定は以下の通りです:

work_duration: 1500秒（25分）
short_break: 300秒（5分）
long_break: 900秒（15分）
pomodoros_until_long_break: 4
sound_enabled: True
notification_enabled: True

設定を変更するには、UIの設定パネルを使用します。

データ保存

セッションデータはdata/sessions.jsonにローカル保存されます。各セッションには以下の情報が含まれます:

• セッションID
• タイプ（作業/休憩）
• 開始時刻と終了時刻
• 完了状態
• 継続時間

統計

以下の統計が表示されます:

• 今日の集中時間 - 本日完了した作業セッションの合計時間
• 完了ポモドーロ数 - 本日完了した25分セッションの数
• 連続日数 - 少なくとも1ポモドーロを完了した連続日数
• 週間概要 - 過去7日間の日別ポモドーロ数

トラブルシューティング

通知が表示されない

Windows:

• システム設定で通知が有効になっているか確認
• Pythonアプリに通知権限があるか確認

macOS:

• システム環境設定 > 通知でPythonの通知を許可

Linux:

• libnotifyがインストールされているか確認
• 通知デーモンが実行中か確認

タイマーが不正確

タイマーはシステムクロックに基づいており、ドリフトを防ぐように設計されています。それでも問題がある場合:

1. システムの時刻設定を確認
2. 他のCPU負荷の高いプロセスを終了
3. アプリケーションを再起動

データファイルが見つからない

初回起動時にdata/ディレクトリとsessions.jsonが自動作成されます。手動で作成する必要はありません。

開発

テストの実行

# すべてのテストを実行
uv run pytest

# カバレッジ付き
uv run pytest --cov=pomodoro --cov-report=html

# 特定のテストファイル
uv run pytest tests/test_timer.py -v

コード品質チェック

# リント、フォーマット、型チェック
make check

# 個別実行
uv run ruff check .
uv run pyright

プロジェクト構造

pomodoro-timer/
├── pomodoro/              # コアモジュール
│   ├── models.py          # データモデル
│   ├── timer.py           # タイマーロジック
│   ├── storage.py         # データ永続化
│   ├── stats.py           # 統計計算
│   └── notifications.py   # 通知システム
├── ui/                    # ユーザーインターフェース
│   ├── app.py            # メインアプリケーション
│   └── components/        # UIコンポーネント
├── tests/                 # テストスイート
├── data/                  # セッションデータ（gitignored）
└── docs/                  # 追加ドキュメント

詳細なアーキテクチャ情報はDESIGN.mdを参照してください。

アクセシビリティ

このアプリケーションは以下のアクセシビリティ機能を提供します:

• 高コントラスト - タイマー表示は7:1のコントラスト比
• キーボードナビゲーション - マウスなしで完全操作可能
• スクリーンリーダー対応 - 意味のあるHTML構造
• 大きなタッチターゲット - 最小44×44pxのボタンサイズ

ライセンス

このプロジェクトは学習目的のAmplifierチュートリアルプロジェクトです。

貢献

問題や提案がある場合は、Issueを作成してください。

関連ドキュメント

• DESIGN.md - アーキテクチャと設計決定
• AGENTS.md - AI開発ガイドライン
• 親プロジェクトAGENTS.md - 全体的な開発原則