python3-development

独自方針の Python 開発スキル

最新の Python 3.11～3.14 のパターンに対応した Python 開発ガイドです。

ドメイン別スキルの選択

テスト

テストの品質をレビューする場合、またはテスト監査を実施する場合は、/python3-development:comprehensive-test-review を読み込んでください（完全なチェックリスト）。

失敗しているテストを分析する場合、またはテストの失敗をデバッグする場合は、/python3-development:analyze-test-failures を読み込んでください（バランスの取れた調査）。

テストの失敗に対するアプローチを見直す場合は、/python3-development:test-failure-mindset を読み込んでください（テストを仕様として捉える考え方）。

CLI および UI ライブラリ

Typer と Rich を組み合わせて CLI を構築する場合は、/python3-development:typer-and-rich を読み込んでください（統合、幅の処理、例）。

Typer のみを使った CLI パターンに取り組む場合は、/python3-development:typer を読み込んでください（コマンド、引数、Typer の機能）。

Rich の出力に取り組む場合は、/python3-development:rich を読み込んでください（テーブル、パネル、進捗表示、ツリー）。

Textual を使ってターミナル UI を構築する場合は、/python3-development:textual を読み込んでください。

開発ワークフロー

追跡とフェーズを含む、構造化された機能タスクを作成する場合は、/python3-development:create-feature-task を読み込んでください。

テンプレートのワークフローから新しい Claude Code スキルを作成する場合は、/python3-development:use-command-template を読み込んでください。

コード品質

最新の Python 3.11 以降のパターンを適用する場合、またはレガシーコードを最新化する場合は、/python3-development:modernpython を読み込んでください（PEP に基づいています）。

shebang または PEP 723 のインラインスクリプトメタデータを検証する場合は、/python3-development:shebangpython を読み込んでください。

段階的な品質改善（静的解析、型付け、最新化計画、TDD ループ）を実施する場合は、/python3-development:stinkysnake を読み込んでください。

拡張ツールマトリックス

タスクに uv、Hatchling、ty、pre-commit、パッケージング、または上記に記載されていないその他の専門ツールが関わる場合は、/python3-development:specialist-skill-routing を読み込んでください（そのスキル内に完全なトリガーマップがあります）。

スキルの構成

バンドルされたリソース（このスキルに含まれます）

リファレンスドキュメント：

• references/python3-standards.md — Python 3.11 以降の統一標準、ナレッジグラフ、プロセスグラフ、およびその改訂方法（プラグイン全体のルールを適用する際に参照）
• references/user-project-conventions.md — 実運用プロジェクトの規約。既存プロジェクトを開始または既存のスタイルに合わせる際に参照
• references/modern-modules.md - 使用パターンとベストプラクティスをまとめた 50 以上のライブラリガイド
• references/tool-library-registry.md - リント、テスト、ビルド自動化のための開発ツールカタログ
• references/python-development-orchestration.md - TDD、機能追加、リファクタリング、コードレビューの詳細なワークフローパターン

専門スキル（ルーティングコマンド — ドメイン別スキルの選択を参照）：

• テスト：comprehensive-test-review、analyze-test-failures、test-failure-mindset
• CLI/UI：typer-and-rich、typer、rich、textual
• ワークフロー：create-feature-task、use-command-template
• 品質：modernpython、shebangpython、stinkysnake
• その他：specialist-skill-routing（uv、Hatchling、ty、パッケージング、…）

スクリプトとアセット：

• パターンを示すサンプルスクリプト
• 設定テンプレートとボイラープレート

システムツール（パッケージマネージャーまたは uv でインストール）：

• uv - Python のパッケージおよびプロジェクトマネージャー（必須）
• ruff - リンターおよびフォーマッター
• ty - 主な静的型チェッカー（Astral）。新しい作業ではデフォルトとして使用 — /astral:ty を参照
• mypy - 静的型チェッカー。プロジェクトですでに設定されている場合に使用 — mypy からの移行を無理に進めないでください
• pyright / basedpyright - プロジェクトですでに標準として採用されている場合に使用
• pytest - テストフレームワーク
• pre-commit - Git フックフレームワーク
• mutmut - ミューテーションテスト（重要なコード向け）
• bandit - セキュリティスキャナー（重要なコード向け）

インストールに関する注意：

• uv の詳細なドキュメントとパッケージ管理のガイダンスについては、uv スキルを使用してください

基本概念

Python 開発標準

このスキルは、Python 開発向けに最新の Python 3.11 以降の標準、品質ゲート、リファレンスドキュメントを提供します。

共通ルールを適用する際は、references/python3-standards.md を参照してください。

• アーキテクチャ標準（レイヤードアーキテクチャ、関心の分離）
• Python 標準（ネイティブ型ヒント、Google スタイルの docstring、フェイルファストなエラー処理）
• CLI 標準（Typer／Rich）
• サービス統合標準（Protocol クラス）
• テスト標準（pytest-mock、カバレッジ 80%）
• 識別子の命名標準（公開名では頭字語を展開してください。§1.5 を参照）

Python 開発プロセスグラフ

標準的な開発ライフサイクルについては、references/python3-standards.md（セクション 3）を参照してください。

docstring 標準は Google スタイルです（Args／Returns／Raises セクション）。ruff の pydocstyle 設定（convention = "google"）については、references/user-project-conventions.md を参照してください。

Pyproject.toml テンプレート変数

すべての pyproject.toml の例では、汎用的なプレースホルダーではなく、明示的なテンプレート変数（例：{{project_name_from_directory_or_git_remote}}）を使用しています。ファイルを書き込む前に、すべてのテンプレート変数を実際の値に置き換えてください。変数の参照方法、値の取得方法、検証手順については、references/tool-library-registry.md#18-pyprojecttoml-template-variable-reference を参照してください。

コマンドの使用方法

/python3-development:modernpython

目的：公式 PEP の引用を含む、Python 3.11 以降のパターンに関する包括的なリファレンスガイドです。

使用する場面：

• 新しいコードを書く際のリファレンスガイドとして
• 最新の Python 3.11～3.14 の機能やパターンを学ぶとき
• 公式 PEP（585、604、695 など）を理解するとき
• 避けるべきレガシーパターンを特定するとき
• 古いコード向けの最新の代替手段を探すとき

注意：これは読むためのリファレンスドキュメントであり、自動検証ツールではありません。実装方法の判断に役立ててください。

使用方法：

/python3-development:modernpython
→ Loads comprehensive reference guide
→ Provides Python 3.11+ pattern examples
→ Includes PEP citations with research tool guidance (prefer MCP tools: Ref/exa over WebFetch)
→ Shows legacy patterns to avoid
→ Shows modern alternatives to use
→ Framework-specific guides (Typer, Rich, pytest)

Research tool preference for PEP documentation:
1. mcp__Ref__ref_search_documentation(query="PEP {number} Python enhancement proposal")
2. mcp__exa__get_code_context_exa(query="PEP {number} implementation examples")
3. WebFetch as fallback

> [Web resource access, definitive guide for getting accurate data for high quality results](./references/accessing_online_resources.md)

ファイルパス引数を指定する場合：

/python3-development:modernpython src/mymodule.py
→ Loads guide for reference while working on specified file
→ Use guide to manually identify and refactor legacy patterns

/python3-development:shebangpython

目的：依存関係と実行コンテキストに基づいて、すべての Python スクリプトで shebang が正しいか検証します。

使用する場面：

• 単独で実行可能な Python スクリプトを作成するとき
• スクリプトの shebang が正しいか検証するとき
• スクリプトに適切な実行設定があることを確認するとき

必須対象：すべての実行可能な Python スクリプト（スクリプトの種類に shebang が適合しているか検証します）

検証内容：

• 標準ライブラリのみを使用するスクリプト：#!/usr/bin/env python3（宣言するものがないため、PEP 723 は不要です）
• 依存関係のあるスクリプト：#!/usr/bin/env -S uv run --quiet --script ＋依存関係を宣言する PEP 723 メタデータ
• パッケージの実行ファイル：#!/usr/bin/env python3（依存関係はパッケージマネージャー経由）
• ライブラリモジュール：shebang なし（直接実行できません）

参照先：インラインスクリプトメタデータの詳細については、references/PEP723.md を参照してください。

パターン：

/python3-development:shebangpython scripts/deploy.py
→ Analyzes imports to determine dependency type
→ **Corrects shebang** to match script type (edits file if wrong)
→ **Adds PEP 723 metadata** if external dependencies detected (edits file)
→ **Removes PEP 723 metadata** if stdlib-only (edits file)
→ Sets execute bit if needed
→ Provides detailed verification report

品質ゲート

必須の品質ゲート手順（リンティング、型チェック、テスト、ファイル全体のレビュー、shebang の検証）については、/python3-development:python-cli-architect スキルを有効にしてください。

診断ルール

error[unresolved-import]: Cannot resolve imported module 'X' — モジュール X を含むディレクトリを pyproject.toml の [tool.ty.environment] extra-paths に追加してください。uv run ty check <path> を実行して検証します。エラーが続く場合は、ty が読み込んでいる設定ファイルが pyproject.toml であることを確認してください（プロジェクトルートの ty.toml が優先され、pyproject.toml は無視されます）。

標準的なプロジェクト構造

プロジェクトディレクトリの構成、Hatchling の設定、パッケージの命名規則については、/python3-development:python-cli-architect スキルを有効にしてください。

統合

参考例（同梱）

完全な動作例（同梱）：Skill(skill="python3-development:typer-and-rich") を読み込むと、推奨されるすべてのパターンを実演する完全な CLI デモ python-cli-demo.py を利用できます。

このリファレンス実装では、推奨されるすべてのパターンを実演します。

• 正しいシバンを含む PEP 723 メタデータ
• Typer + Rich の連携
• モダンな Python 3.11+（StrEnum、Protocol、TypeVar、Generics）
• CLI パラメーターに対する Annotated 構文
• 非同期処理
• 包括的な docstring

このファイルは、ワークフローを自己完結させるため、このプラグインに同梱されています。CLI ツールを作成するときの参考として使用してください。

アセットテンプレートの使用

新しい Python プロジェクトを作成するときは、確立された規約との一貫性を保つため、スキルのアセットディレクトリから標準の設定ファイルをコピーしてください。

理由：テンプレートは実証済みのパターンを実装しており、セットアップの時間を節約できます。

アセットディレクトリの場所（プラグイン内）：./assets/

利用可能なテンプレート：

1. version.py - デュアルモードのバージョン管理（hatch-vcs + importlib.metadata のフォールバック）

   cp "${CLAUDE_PLUGIN_ROOT}/skills/python3-development/assets/version.py" "packages/{package_name}/version.py"
   

2. hatch_build.py - バイナリ／アセット処理用のビルドフック（必要な場合のみ）

   mkdir -p scripts/
   cp "${CLAUDE_PLUGIN_ROOT}/skills/python3-development/assets/hatch_build.py" "scripts/hatch_build.py"
   

3. .markdownlint.json - Markdown の lint 設定

   cp "${CLAUDE_PLUGIN_ROOT}/skills/python3-development/assets/.markdownlint.json" "."
   

4. .pre-commit-config.yaml - 標準的な git フックの設定

   cp "${CLAUDE_PLUGIN_ROOT}/skills/python3-development/assets/example.pre-commit-config.yaml" ".pre-commit-config.yaml"
   
   # Install hooks using pre-commit or prek (whichever is available)
   # Both tools use the same configuration file and have identical interfaces
   uv run pre-commit install  # or: uv run prek install
   

5. .editorconfig - エディターのフォーマット設定

   cp "${CLAUDE_PLUGIN_ROOT}/skills/python3-development/assets/.editorconfig" "."
   

これらのテンプレートは、references/user-project-conventions.md に記載されているパターンを実装しており、すべてのプロジェクトがバージョン管理、lint、フォーマット、ビルド設定について同じ標準に従うようにします。

詳細なドキュメント

リファレンスドキュメント

PEP 723 仕様：references/PEP723.md - 例や移行パターンを含む、PEP 723 のインラインスクリプトメタデータについてのユーザーフレンドリーなガイド

例外処理と Typer／Rich の例：Skill(skill="python3-development:typer-and-rich") を読み込みます — 例外チェーンの防止、Typer の終了パターン、Rich の非 TTY 表示ソリューション、typer_examples/ スクリプトや python-cli-demo.py などの動作する実行可能な例を網羅しています。

モジュールリファレンス：references/modern-modules.md - 50 以上のモダンな Python ライブラリに関する包括的なガイド。各モジュールについて、使用パターンやベストプラクティスを含む詳細なドキュメントを掲載しています。

ツールレジストリ：references/tool-library-registry.md - 開発ツール、その用途、および lint、テスト、ビルド自動化のための使用パターンをまとめた一覧

大きなリファレンスのナビゲーション

modern-modules.md で特定のモジュールを見つけるには：

grep -i "^### " references/modern-modules.md

tool-library-registry.md でカテゴリ別にツールを検索するには：

grep -A 5 "^## " references/tool-library-registry.md

python-development-orchestration.md でワークフローパターンを見つけるには：

grep -i "^## " references/python-development-orchestration.md

外部コマンド

これらのスキルはこのプラグインに同梱されており、スラッシュコマンドとして利用できます。

• ../modernpython/SKILL.md - Python 3.11+ のパターンと PEP リファレンス
• ../shebangpython/SKILL.md - PEP 723 の検証とシバンの標準

まとめ

• モダンな Python 3.11+ の標準とパターン
• 品質ゲート：ruff、ty（デフォルトの型チェック）、プロジェクトで使用する場合は mypy／pyright、pytest（カバレッジ 80% 超）
• コマンドの標準：/python3-development:modernpython、/python3-development:shebangpython
• 50 以上のモダンな Python モジュールに関するリファレンスドキュメント
• ツールとライブラリのレジストリ