Kage プロジェクトタスクランナーガイド¶

このプロジェクトでは poethepoet を使用してタスクランナーを実装しています。これにより、開発・テスト・ビルドなどの作業を効率化できます。

インストール・セットアップ¶

poethepoet のグローバルインストール（推奨）¶

poethepoet をグローバルにインストールすることで、uv runを付けずに直接poeコマンドを使用できます：

# poethepoetをグローバルにインストール
uv tool install poethepoet

# 依存関係の同期とデータベースの初期化
poe setup

ローカルプロジェクトでの使用（代替方法）¶

もしグローバルインストールができない場合は、プロジェクト内でも使用可能です：

# プロジェクト内にpoethepoetを追加
uv add poethepoet --dev

# タスク実行（この場合はuv runが必要）
uv run poe setup

基本的な使用方法¶

# 利用可能なタスクの一覧表示
poe --help

# 特定のタスクの実行
poe <task-name>

📋 利用可能なタスク一覧¶

🚀 アプリケーション実行¶

コマンド	説明
`poe app-run`	通常のデスクトップアプリとして起動
`poe app-dev`	開発モード（ホットリロード + 再帰監視）
`poe app-web`	Web ブラウザでアプリを起動
`poe app-web-dev`	Web ブラウザで開発モード起動
`poe app-debug`	詳細ログ出力モードで起動

⚙️ 開発環境セットアップ¶

コマンド	説明
`poe setup`	初回セットアップ（依存関係同期 + DB 更新）
`poe sync`	依存関係の同期

🗄️ データベース操作¶

コマンド	説明
`poe db-upgrade`	データベースマイグレーションの実行
`poe db-downgrade`	1 つ前のマイグレーションにダウングレード
`poe db-history`	マイグレーション履歴の表示
`poe db-current`	現在のマイグレーション状態確認

🔍 コード品質・フォーマット¶

コマンド	説明
`poe lint`	ruff による静的解析
`poe lint-fix`	自動修正可能な問題を修正
`poe format`	コードフォーマット
`poe format-check`	フォーマットチェック（修正なし）
`poe type-check`	型チェック（Pyright）

🎯 複合コマンド¶

コマンド	説明
`poe check`	品質チェック一括実行（lint + format-check + type-check）
`poe fix`	自動修正一括実行（lint-fix + format）

🧪 テスト実行¶

コマンド	説明
`poe test`	全テストの実行
`poe test-unit`	ユニットテストのみ実行
`poe test-integration`	統合テストのみ実行
`poe test-cov`	カバレッジ付きテスト実行

📦 依存関係管理¶

コマンド	説明
`poe deps-list`	インストール済みパッケージの一覧
`poe deps-tree`	依存関係ツリーの表示
`poe deps-outdated`	古いパッケージの確認

🏗️ ビルド・パッケージング¶

コマンド	説明
`poe build-web`	静的 Web サイトとしてビルド
`poe build-desktop`	Windows デスクトップアプリとしてビルド
`poe pack-desktop`	スタンドアロンのデスクトップバンドル作成

🧹 クリーンアップ¶

コマンド	説明
`poe clean`	uv キャッシュのクリア
`poe clean-pyc`	.pyc ファイルの削除
`poe clean-all`	全クリーンアップの実行

📄 ログ管理¶

コマンド	説明
`poe logs-app`	アプリケーションログの最新 50 行表示
`poe logs-agents`	エージェントログの最新 50 行表示
`poe logs-clear`	全ログファイルの削除

💡 開発ワークフローの例¶

初回セットアップ¶

# プロジェクトをクローン後
poe setup

日常の開発作業¶

# 開発モードでアプリ起動
poe app-dev

# コード品質チェック
poe check

# 問題の自動修正
poe fix

# テスト実行
poe test

データベース操作¶

# マイグレーション実行
poe db-upgrade

# 現在の状態確認
poe db-current

デプロイ前のチェック¶

# 全体的な品質チェック
poe check

# テスト実行
poe test

# Webアプリとしてビルド
poe build-web

❓ トラブルシューティング¶

タスクが見つからない場合¶

# 利用可能なタスクを確認
poe --help

依存関係の問題¶

# 依存関係を再同期
poe sync

ログの確認¶

# アプリケーションログを確認
poe logs-app

# エージェントログを確認
poe logs-agents

⚙️ カスタムタスクの追加¶

新しいタスクを追加する場合は、pyproject.tomlの[tool.poe.tasks]セクションに追加してください：

[tool.poe.tasks]
my-custom-task = "echo 'Hello, World!'"

詳細な設定方法については poethepoet 公式ドキュメントを参照してください。

Kage プロジェクト タスクランナーガイド¶