modern-python

modern-python 技能概覽

modern-python 做什麼

modern-python 技能可幫你以 uv、ruff 和 ty 為核心，啟動或現代化 Python 專案，而不是沿用 pip、Poetry、mypy、black 這類舊組合。當你需要一份實用的 modern-python 指南，用於專案初始化、腳本封裝，或必須可重複、快速、低維護成本的遷移工作時，它特別有用。

誰適合使用

如果你正在建立新套件、製作 CLI、撰寫帶依賴的單檔腳本，或把既有 repo 轉成現代工具鏈，就適合用 modern-python 技能。對於 Python 3.11+ 團隊來說，它很適合拿來統一安裝、lint、格式化、測試與依賴管理的工具路徑。

它和一般提示詞有什麼不同

這個技能不只是單純叫你「用 uv」。它內建了判斷規則：什麼時候該用 pyproject.toml、什麼時候該用 PEP 723 的腳本中繼資料、什麼時候該提交 uv.lock、以及什麼時候不該硬改既有流程。也正因如此，modern-python 技能比一般提示詞更有用，因為它提供的是具體約束，而不是模糊偏好。

如何使用 modern-python 技能

安裝並載入正確脈絡

先用目錄中既有的技能指令安裝 modern-python 技能，然後先讀 SKILL.md，接著依序看 references/pyproject.md、references/ruff-config.md、references/uv-commands.md。如果你是在做遷移，則在動手前也要先看 references/migration-checklist.md 和 references/testing.md。

先把專案型態講清楚

modern-python 的使用情境，最有效的是你先說明你要建立的是：

• library、app，還是 CLI
• 單檔腳本還是多檔專案
• 全新 repo 還是遷移案
• 目前是否必須先保留舊工具

一個好的需求會像這樣：「請把這個 repo 設定成 Python 3.12 套件，使用 uv、ruff、ty 和 uv_build；保留適合 library 的結構，加入 dev dependency groups，並避免使用 Poetry。」這會比只說「請給我現代 Python 最佳實踐」更好，因為技能才能據此選對檔案與指令。

先讀高訊號檔案

如果是偏安裝導向的工作，建議依序先預覽這些路徑：

1. SKILL.md
2. references/pyproject.md
3. references/uv-commands.md
4. references/ruff-config.md
5. 如果是腳本任務，再看 references/pep723-scripts.md
6. 如果是轉換任務，再看 references/migration-checklist.md

如果你需要 repo scaffolding 或 CI hooks，請再查看 templates/dependabot.yml 和 templates/pre-commit-config.yaml，把它們當成實作錨點。

用能減少猜測的輸入

modern-python 技能最吃重的是明確限制：Python 版本、目標套件名稱、是否要忽略 .venv/、是否要提交 uv.lock、以及哪些工具是必備的。若你希望協助遷移，也請一併提供目前的技術棧，以及哪些部分必須維持不變，這樣技能才不會不必要地重寫你的工作流程。

modern-python 技能 FAQ

modern-python 只適合新專案嗎？

不是。modern-python 技能也適合遷移案，但前提是你真的希望 repo 朝 uv、ruff、ty 方向前進。如果專案必須保留現有工具，這個技能就應該限縮使用，甚至不使用。

什麼時候該用 PEP 723，而不是 pyproject.toml？

如果你處理的是帶依賴的單檔工具，就用 modern-python 技能的腳本路徑。如果專案有多個檔案、可重用程式碼，或已經有 package 邊界，就用 pyproject.toml。這個邊界也是安裝 modern-python 技能的主要理由之一。

這能取代一般提示詞嗎？

可以，當你需要可重複的設定決策時尤其如此。一般提示詞能描述工具，但 modern-python 技能會提供依賴管理、lint、格式化與遷移取捨的指引，讓模型比較不會把互相衝突的模式混在一起。

初學 Python 的人也適合嗎？

可以，只要目標是乾淨的現代化技術棧就行。若你還在學舊工具慣例，或需要 Python 3.11 以下版本，這個技能就沒那麼合適，因為它的核心假設就是 modern-python。

如何改進 modern-python 技能

先講清楚你最在意的成果

要讓 modern-python 的結果更準，請先說明你最重視的是 library 封裝、腳本可攜性、CI 就緒，還是遷移安全。這會直接影響輸出：library 需要更嚴謹的依賴管理與 lockfile 指引；腳本則可能只需要 PEP 723 中繼資料，而不必建立完整專案結構。

一開始就補齊缺少的專案資訊

最大的失敗原因是設定條件不夠明確。請一併提供：

• 目標 Python 版本
• 套件名稱與 import 名稱
• flat layout 還是 src/ layout
• 是否要提交 uv.lock
• 必備工具：ruff、ty、測試、pre-commit、Dependabot

這些細節能讓 modern-python 技能產出可直接使用的安裝方案，而不是泛泛的建議。

先對照 repo 慣例再看第一版

拿到第一版結果後，請檢查它是否符合你 repo 對 dependency groups、formatter 設定與測試指令的慣例。如果有落差，就用更精準的修正方式迭代，例如：「保留舊的 CI，但只把 linting 和依賴管理改成 modern-python 的做法。」

注意常見的不適用情境

當專案必須保留 pip/Poetry 語意、支援較舊的解譯器，或長期維持半現代、半傳統的狀態時，modern-python 的效果會比較差。在這些情況下，應請技能保守調整，而不是完全重建整個技術棧；或者乾脆不要在該 repo 上使用它。