Claude Code向けPythonテンプレート
このリポジトリは、Claude Code との協働に最適化された、本番環境に対応可能なPythonプロジェクトテンプレートです。適度な型チェック、Claude Codeのパフォーマンスを引き出すための包括的なドキュメントやテンプレート、便利なカスタムスラッシュコマンドなどを備えています。
🚀 クイックスタート
テンプレートの使用方法
- GitHubで「Use this template」ボタンをクリックして、新しいリポジトリを作成
- 新しいリポジトリをクローン
- セットアップスクリプトを実行
- Claude CodeとGemini CLIを初回起動して認証
- Claude Codeの対話モードで
/initialize-projectコマンドを実行して、プロジェクトを初期化
# 新しいリポジトリをクローン
git clone https://github.com/yourusername/project-name.git
cd project-name
# セットアップ
make setup
claude
gemini
# プロジェクトの初期化
claude # /initialize-projectを実行
セットアップスクリプトは、以下の処理を自動的に実行します。
- プロジェクト内のすべての
project_nameを、指定したプロジェクト名に置換 uvを使用してPythonの仮想環境を構築- Claude Codeをインストール
- Gemini CLIをインストール
- GitHub CLI (
gh) をインストール（途中でログインを求められることがあります） - すべての依存関係をインストール
- pre-commitフックを設定
- 初期テストを実行
🔗 主要ドキュメント
📋 Claude Code チートシート
基本的なCLIコマンド
# 対話モードを開始
claude
# プロンプトを指定して対話モードを開始
claude "質問内容"
# SDKモードで質問を実行
claude -p "質問内容"
# 最新の会話を続ける
claude -c
# 対話的にセッションを選択して再開
claude -r
# アップデートとシステム管理
claude update # Claude Codeを最新版に更新します
claude --version # バージョン情報を確認します
claude --help # ヘルプを表示します
claude mcp # Model Context Protocol (MCP) を設定します
CLIフラグとオプション
# モデル設定
claude --model sonnet # Sonnetモデルを使用します
claude --model opus # Opusモデルを使用します
# セッション管理
claude --list-sessions # セッションの一覧を表示します
claude --delete-session "<id>" # 指定したセッションを削除します
# ディレクトリと作業環境
claude --add-dir /path/to/dir # 作業ディレクトリを追加します
claude --add-dir dir1 --add-dir dir2 # 複数のディレクトリを追加します
# 出力とフォーマット制御
claude --output-format text # テキスト形式で出力します
claude --output-format json # JSON形式で出力します
claude --output-format stream-json # ストリーミングJSON形式で出力します
claude --verbose # 詳細なログを表示します
claude --quiet # 最小限の出力に抑制します
# 実行制御と権限管理
claude --max-turns 5 # 最大ターン数を制限します
claude --timeout 30 # タイムアウトを秒単位で設定します
claude --tool-permissions restricted # ツールの権限を制限します
claude --allowedTools "Read,Write,Bash" # 許可するツールを指定します
claude --disallowedTools "WebFetch" # 禁止するツールを指定します
# セッションと履歴の管理
claude --list-sessions # セッションの一覧を表示します
claude --delete-session "<id>" # 指定したセッションを削除します
claude --session-id "<id>" # 特定のセッションで開始します
claude --no-history # 履歴を保存しません
パイプとストリーム操作
# パイプからの入力
echo "コードをレビューしてください" | claude
cat file.py | claude "このコードを説明してください"
# ファイルの内容を直接入力
claude < input.txt
# 環境変数による設定
export ANTHROPIC_API_KEY=your_api_key
REPLモードのスラッシュコマンド
Claude Codeの対話モード（REPL）中に使用できるコマンドです。
# 基本コマンド
/help # ヘルプと利用可能なコマンド一覧を表示します
/clear # 画面をクリアし、履歴をリセットします
/resume # 対話的にセッションを選択して再開します
/continue # 直前のセッションに戻ります
/exit # Claude Codeを終了します
/quit # Claude Codeを終了します（/exitのエイリアス）
# モデルと設定の管理
/model # 現在のモデルを表示・変更します
/model sonnet # Claude 4 Sonnetに変更します
/model opus # Claude 4 Opusに変更します
/settings # 現在の設定を表示・変更します
/permissions # 現在のツール権限を表示します
# メモリと記憶の管理
/memory # メモリ管理とプロジェクトの記憶（ナレッジ）を表示・編集します
/memory clear # メモリをクリアします
/memory show # 現在のメモリ内容を表示します
/memory edit # メモリを編集します
# # CLAUDE.mdへのクイックアクセス（行頭で#）
# セッション管理
/save # 現在のセッションを保存します
/save <name> # セッションに名前を付けて保存します
/load <session-id> # 指定したセッションを読み込みます
/sessions # セッションの一覧を表示します
/list-sessions # セッションの一覧を表示します（/sessionsのエイリアス）
/delete-session <id> # 指定したセッションを削除します
# ファイルとプロジェクトの操作
/add-dir <path> # 作業ディレクトリを追加します
/remove-dir <path> # 作業ディレクトリを削除します
/list-dirs # 現在の作業ディレクトリ一覧を表示します
/cwd # 現在の作業ディレクトリを表示します
/pwd # 現在の作業ディレクトリを表示します（/cwdのエイリアス）
# モードと表示の切り替え
/terminal-setup # 複数行入力モードを設定します
/vim-mode # Vimキーバインドを有効化します
/emacs-mode # Emacsキーバインドを有効化します
# デバッグ、診断、ユーティリティ
/debug # デバッグ情報を表示します
/status # システムの状態と接続状況を表示します
/version # Claude Codeのバージョン情報を表示します
/whoami # 現在のユーザー情報を表示します
/tokens # トークン使用量の統計を表示します
/feedback # フィードバックを送信します
/reset # 設定をデフォルトにリセットします
カスタムスラッシュコマンド
このプロジェクトには、開発効率を向上させるための独自のスラッシュコマンドが含まれています。これらは.claude/commands/ディレクトリに定義されています。
/ensure-quality
make check-allが成功するまで自動的にコードを修正し、コード品質を保証します。フォーマット、リント、型チェック、テストを順番に実行し、エラーを自動修正します。
使用例：
- /ensure-quality
このコマンドは、プロジェクトのコード品質を一貫して高いレベルに保つために使用します。
/write-tests
CLAUDE.mdで定義されているt-wada流のTDD（テスト駆動開発）に従って、高品質なテストを作成します。template/tests/ディレクトリのサンプルコードを参考にします。
使用例：
- /write-tests
Red-Green-Refactorサイクルに従い、単体テスト、プロパティベーステスト、統合テストを作成します。
/commit-and-pr
現在の変更をコミットし、適切なブランチを作成してプルリクエストを作成します。CLAUDE.mdのGitHub操作規約に従い、適切なブランチ名とコミットメッセージ形式を使用します。
使用例：
- /commit-and-pr
変更の種類に応じて自動的にfeature/、fix/、refactor/などのブランチを作成し、PRを生成します。
/safe-refactor
テストカバレッジを維持しながら、コードを安全にリファクタリングします。template/ディレクトリの実装パターンを参考に、型安全性、エラーハンドリング、パフォーマンスを改善します。
使用例：
- /safe-refactor
小さなステップで進め、各変更後にテストを実行して動作を確認します。
/analyze - 多次元コード分析
コード、アーキテクチャ、セキュリティ、パフォーマンスの包括的な分析を行います。
オプション：
--code: コード品質の分析（命名規則、複雑性、DRY原則、型カバレッジ）--arch: アーキテクチャの分析（結合度、依存関係、設計パターン）--security: OWASP Top 10準拠のセキュリティ監査--perf: パフォーマンス分析（時間計算量、メモリ効率、I/O最適化）--think,--think-hard,--ultrathink: 分析の深度を指定
使用例：
/analyze --code --security --think-hard
/analyze --perf --ultrathink src/core/
/improve - エビデンスベースの改善
測定可能な証拠に基づいてコードを改善します。改善前後のメトリクスを提供します。
オプション：
--quality: コード品質の改善（可読性、保守性、エラーハンドリング）--perf: パフォーマンスの最適化（アルゴリズム、メモリ、I/O）--arch: アーキテクチャの改善（設計パターン、依存性注入）--iterate: 指定された閾値まで繰り返し改善--metrics: 改善前後のメトリクスを表示--threshold: 品質閾値（low, medium, high, perfect）
使用例：
/improve --quality --metrics
/improve --perf --iterate --threshold high
/task - 複雑タスク管理
複雑なタスクを自動的に分解し、階層的に管理します（Epic→Story→Task→Subtask）。
操作：
:create "<タスク名>": タスクの作成と自動分解:status: 全タスクの状態確認:resume: 中断したタスクの再開:update <task-id>: タスクの更新:complete <task-id>: タスクの完了
使用例：
/task :create "認証システムの実装"
/task :status
/task :complete AUTH-001
/troubleshoot - 体系的デバッグ
エラーの根本原因分析と修正を行います。Five Whys手法を活用します。
オプション：
--fix: 修正案の実装--deep: Five Whys分析--prod: 本番環境向け分析--interactive: 対話的トラブルシューティング
使用例：
/troubleshoot "ImportError: No module named 'mypackage'"
/troubleshoot --deep --fix
/scan - セキュリティ・品質検証
OWASP準拠のセキュリティスキャンと品質メトリクスの包括的チェックを実行します。
オプション：
--security: セキュリティ脆弱性スキャン--quality: 品質メトリクスチェック--full: 完全スキャン（セキュリティ＋品質）--fix: 問題の自動修正
使用例：
/scan --security --full
/scan --fix
/gemini-documentation
Gemini AIを使用してドキュメントの作成や校正を行います。Geminiは文章作成に優れているため、技術文書の品質向上に活用できます。
使用例：
- /gemini-documentation README.mdを校正
- /gemini-documentation APIドキュメントを作成
- /gemini-documentation ユーザーガイドを更新
/gemini-search
Gemini AIを使用してWeb検索を実行します。最新の技術情報や解決策を検索する際に便利です。
使用例：
- /gemini-search Python 3.13の新機能
- /gemini-search FastAPIのベストプラクティス
- /gemini-search 型ヒントの高度な使い方
🔄 ワークフロー統合
これらのカスタムコマンドは相互に連携し、効果的な開発フローを実現します：
推奨ワークフロー例：
# 1. 初期分析
/analyze --code --arch
# 2. 品質改善
/improve --quality --metrics
# 3. テスト作成
/write-tests
# 4. 品質保証
/ensure-quality
# 5. セキュリティチェック
/scan --security --full
# 6. コミットとPR
/commit-and-pr
キーボードショートカットと対話操作
# 基本操作
Ctrl+J # 改行
Esc x 2 # 前のメッセージに戻る
Ctrl+C # 現在の入力や生成をキャンセル
Ctrl+D # Claude Codeセッションを終了
Ctrl+L # ターミナル画面をクリア
Ctrl+R # コマンド履歴を逆方向に検索（対応端末のみ）
Up/Down arrows # コマンド履歴を移動
Tab # オートコンプリート（利用可能な場合）
Shift + Tab # Planモードの切り替え
# 複数行入力（環境によって異なります）
\<Enter> # クイックエスケープ（すべての端末で対応）
Option+Enter # macOS標準
Shift+Enter # /terminal-setup後に有効
Alt+Enter # Linux/Windows（一部の端末）
# 特殊入力
Esc Esc # 前のメッセージを編集
#<Enter> # CLAUDE.mdへのクイックアクセス
/<tab> # スラッシュコマンドの補完
高度な使用例と統合
# 複数のオプションを組み合わせる
claude --model opus --verbose --add-dir ./src --add-dir ./tests "プロジェクト全体をレビューしてください"
# 特定の形式で出力を制御する
claude --output-format json -p "このコードの問題点をJSON形式で教えてください" < code.py
# タイムアウト付きで実行する
claude --timeout 60 --max-turns 3 "複雑な最適化を提案してください"
# 制限されたツール権限で実行する
claude --tool-permissions restricted "安全にコードを分析してください"
# セッション管理を活用する
claude --save-session "code-review-2024" --model sonnet
claude --load-session "code-review-2024" --continue
# スクリプトの自動化で活用する
claude --output-format json --quiet -p "テストを実行してエラー数を返してください" | jq '.error_count'
# CI/CDでの活用例
cat test_results.txt | claude --output-format text -p "テスト結果を分析してサマリーを作成してください"
# 設定ファイルと連携する
export CLAUDE_CONFIG_FILE="./claude-config.json"
claude