modern-python

modern-python skill の概要

modern-python ができること

modern-python skill は、pip、Poetry、mypy、black のような従来の組み合わせではなく、uv、ruff、ty を中心に Python プロジェクトを立ち上げたり、現代的な構成へ移行したりするのに役立ちます。プロジェクトの初期設定、スクリプトのパッケージ化、あるいは再現性が高く、速く、保守しやすい移行作業について、実用的な modern-python ガイドがほしいときに特に有効です。

どんな人に向いているか

新しいパッケージを作る場合、CLI を作る場合、依存関係のある単体スクリプトを書く場合、既存リポジトリを modern なツールチェーンに変える場合に modern-python skill を使ってください。Python 3.11+ を前提に、インストール、lint、フォーマット、テスト、依存関係管理までをひとつのツールチェーンで揃えたいチームには特に相性がよいです。

一般的なプロンプトと何が違うのか

この skill は単に「uv を使う」だけではありません。pyproject.toml を使うべきケース、PEP 723 のスクリプトメタデータを使うべきケース、uv.lock をコミットすべきケース、既存のワークフローを置き換えないほうがよいケースまで、判断ルールを組み込んでいます。曖昧な好みではなく具体的な制約をモデルに渡せるので、普通のプロンプトよりも modern-python skill のほうが実用的です。

modern-python skill の使い方

インストールして、適切なコンテキストを読み込む

ディレクトリ標準の skill コマンドで modern-python skill をインストールしたら、まず SKILL.md を読み、その後で references/pyproject.md、references/ruff-config.md、references/uv-commands.md を確認してください。移行作業であれば、変更を入れる前に references/migration-checklist.md と references/testing.md も読んでおくべきです。

skill に実際のプロジェクト形態を伝える

modern-python の使い方は、次のどれを作るのかを明示すると最も効果的です。

• library、app、CLI のどれか
• 単一ファイルの script か、複数ファイルの project か
• 新規 repo か migration か
• いまは legacy tools を残す必要がある repo か

たとえば、uv、ruff、ty、uv_build を使ってこの repo を Python 3.12 package として整備し、library にも使いやすい構成にしたうえで、dev dependency groups を追加し、Poetry は避けてください——という依頼は、単に「modern Python best practices を教えて」よりずっと良いです。skill が適切な files と commands を選べるからです。

重要度の高いファイルから先に読む

インストール前提の作業では、次の paths をこの順で確認するとよいです。

1. SKILL.md
2. references/pyproject.md
3. references/uv-commands.md
4. references/ruff-config.md
5. task が script なら references/pep723-scripts.md
6. task が conversion なら references/migration-checklist.md

repo scaffolding や CI hook が必要なら、実装の足場として templates/dependabot.yml と templates/pre-commit-config.yaml も確認してください。

迷いを減らす入力を与える

modern-python skill は、明確な制約があるほど力を発揮します。たとえば、Python version、対象の package 名、.venv/ を ignore すべきかどうか、uv.lock を commit すべきかどうか、必須の tools は何か、といった情報です。migration の支援がほしいなら、現在の stack と、何を変えてはいけないのかも一緒に書いてください。そうすれば、skill が不要に既存ワークフローを作り替えるのを避けられます。

modern-python skill FAQ

modern-python は新規プロジェクト専用ですか？

いいえ。modern-python skill は migration にも使えます。ただし、それは repo を uv、ruff、ty の方向へ寄せたい場合に限ります。現行の tools を維持しなければならないなら、skill は部分的に使うか、あるいは使わないほうがよいです。

PEP 723 と pyproject.toml はどちらを使うべきですか？

依存関係付きの単一ファイル utility なら、modern-python skill の script 用の分岐を使ってください。複数ファイル、再利用される code、package 境界があるなら pyproject.toml を使います。この境界設定は、modern-python skill を導入する主な理由のひとつです。

これは通常のプロンプトの置き換えになりますか？

はい、再現性のある setup 判断が必要な場合には置き換えになります。通常のプロンプトでも tools の説明はできますが、modern-python skill なら dependency management、linting、formatting、migration の tradeoff まで含めたガイドになるため、互換性のない pattern を混ぜにくくなります。

初心者の Python ユーザーにも向いていますか？

はい、目的が clean な modern stack なら向いています。いっぽうで、古い tool の慣習を学習中の場合や、Python 3.11 未満を使う必要がある場合は適性が下がります。skill 自体が modern-python の前提に寄っているためです。

modern-python skill をより良く使うには

最も重視する成果を伝える

modern-python の結果を良くしたいなら、library packaging、script portability、CI readiness、migration safety のどれを最優先したいのかを伝えてください。それによって出力が変わります。たとえば library なら dependency の厳密さと lockfile の扱いが重要ですが、script ならフルな project layout ではなく PEP 723 メタデータのほうが適している場合があります。

足りないプロジェクト情報を先に埋める

最大の失敗要因は、setup の前提が足りないことです。次の情報を入れてください。

• 対象の Python version
• package name と import name
• flat layout か src/ layout か
• uv.lock を commit するかどうか
• 必須の tools: ruff、ty、tests、pre-commit、Dependabot

こうした details があれば、modern-python skill は generic な助言ではなく、すぐ使える install plan を出せます。

最初の案を repo の convention と照らし合わせて確認する

最初の出力が返ってきたら、dependency groups、formatter 設定、test command があなたの repo の期待値に合っているか確認してください。ずれているなら、「CI は legacy のまま残しつつ、linting と dependency management だけ modern-python 方式に置き換える」のように、範囲を絞って修正を依頼するとよいです。

よくあるミスマッチを見分ける

modern-python は、プロジェクトが pip/Poetry の semantics を維持しなければならない場合、古い interpreter をサポートする必要がある場合、あるいは半分 modern、半分 legacy の状態を長く続ける必要がある場合には弱くなります。そういうときは、stack 全体を作り替えるのではなく保守的に適応するよう skill に依頼するか、その repo では使わないほうがよいです。