modern-python

Visão geral da skill modern-python

O que a skill modern-python faz

A skill modern-python ajuda você a iniciar ou modernizar projetos Python em torno de uv, ruff e ty, em vez de combinações legadas como pip, Poetry, mypy e black. Ela é mais útil quando você quer um guia prático de modern-python para configuração de projeto, empacotamento de scripts ou trabalho de migração que precise ser repetível, rápido e de baixa manutenção.

Quem deve usar

Use a skill modern-python se você estiver criando um novo pacote, montando um CLI, escrevendo um script independente com dependências ou convertendo um repositório existente para ferramentas modernas. Ela é uma ótima opção para equipes em Python 3.11+ que querem um único caminho de toolchain para instalações, lint, formatação, testes e gerenciamento de dependências.

Por que ela difere de um prompt genérico

Esta skill não é só “use uv”. Ela codifica regras de decisão sobre quando usar pyproject.toml, quando usar metadados de script do PEP 723, quando commitar uv.lock e quando não substituir um fluxo de trabalho já existente. Isso torna a skill modern-python mais útil do que um prompt comum, porque dá ao modelo restrições concretas em vez de preferências vagas.

Como usar a skill modern-python

Instale e carregue o contexto certo

Instale a skill modern-python com o comando normal de skills do diretório e, em seguida, leia SKILL.md primeiro, seguido de references/pyproject.md, references/ruff-config.md e references/uv-commands.md. Se você estiver migrando, leia também references/migration-checklist.md e references/testing.md antes de fazer alterações.

Dê à skill uma forma real de projeto

O uso da modern-python funciona melhor quando você informa se está construindo:

• uma biblioteca, aplicativo ou CLI
• um script de arquivo único ou um projeto com vários arquivos
• um repositório novo ou uma migração
• um repositório que ainda precisa manter ferramentas legadas por enquanto

Um pedido forte seria: “Configure este repositório como um pacote Python 3.12 usando uv, ruff, ty e uv_build; mantenha-o amigável para biblioteca, adicione grupos de dependências de desenvolvimento e evite Poetry.” Isso é melhor do que pedir “boas práticas de Python moderno”, porque a skill consegue escolher os arquivos e comandos certos.

Leia primeiro os arquivos com maior sinal

Para trabalho orientado à instalação, visualize estes caminhos nesta ordem:

1. SKILL.md
2. references/pyproject.md
3. references/uv-commands.md
4. references/ruff-config.md
5. references/pep723-scripts.md se a tarefa for um script
6. references/migration-checklist.md se a tarefa for uma conversão

Se você precisar de scaffold do repositório ou de ganchos de CI, examine templates/dependabot.yml e templates/pre-commit-config.yaml como âncoras de implementação.

Use entradas que reduzam suposições

A skill modern-python se beneficia de restrições explícitas: versão do Python, nome do pacote de destino, se .venv/ deve ser ignorado, se uv.lock deve ser commitado e quais ferramentas são obrigatórias. Se você quiser ajuda de migração, inclua o stack atual e o que precisa permanecer inalterado para que a skill evite reescrever seu fluxo de trabalho sem necessidade.

FAQ da skill modern-python

A modern-python é só para projetos novos?

Não. A skill modern-python também foi pensada para migrações, mas só quando você quer levar o repositório em direção a uv, ruff e ty. Se o projeto precisa manter as ferramentas atuais, a skill deve ser usada de forma seletiva ou talvez nem deva ser usada.

Quando devo usar PEP 723 em vez de pyproject.toml?

Use o caminho de script da skill modern-python quando você tiver um utilitário de arquivo único com dependências. Use pyproject.toml quando o projeto tiver vários arquivos, código reutilizável ou uma fronteira de pacote. Essa fronteira é um dos principais motivos para instalar a skill modern-python.

Isso substitui um prompt normal?

Sim, quando você precisa de uma decisão de configuração repetível. Um prompt normal pode descrever as ferramentas, mas a skill modern-python fornece um guia para gerenciamento de dependências, lint, formatação e trade-offs de migração, reduzindo a chance de o modelo misturar padrões incompatíveis.

Funciona para quem está começando em Python?

Sim, se o objetivo for uma stack moderna e limpa. Ela é menos adequada se você ainda estiver aprendendo convenções de ferramentas antigas ou precisar de versões de Python abaixo de 3.11, já que a skill é centrada em pressupostos de modern-python.

Como melhorar a skill modern-python

Diga qual resultado importa mais

Para obter melhores resultados com modern-python, diga se o que importa mais é empacotamento de biblioteca, portabilidade de script, prontidão para CI ou segurança na migração. Isso muda a saída: uma biblioteca precisa de disciplina de dependências e orientação sobre lockfile, enquanto um script pode precisar de metadados do PEP 723 em vez de uma estrutura completa de projeto.

Forneça os fatos que faltam sobre o projeto logo de início

O principal modo de falha é uma configuração pouco especificada. Inclua:

• versão alvo do Python
• nome do pacote e nome do import
• layout plano ou layout src/
• se uv.lock deve ser commitado
• ferramentas obrigatórias: ruff, ty, testes, pre-commit, Dependabot

Esses detalhes permitem que a skill modern-python produza um plano de instalação útil, em vez de recomendações genéricas.

Revise o primeiro rascunho contra as convenções do repositório

Depois da primeira saída, verifique se o resultado bate com as expectativas do seu repositório para grupos de dependências, configurações do formatador e comandos de teste. Se algo estiver fora do lugar, refine com uma correção específica, como “mantenha o CI legado, mas substitua apenas linting e gerenciamento de dependências pela abordagem modern-python.”

Fique atento aos casos de incompatibilidade comuns

A modern-python é mais fraca quando o projeto precisa preservar a semântica de pip/Poetry, oferecer suporte a interpretadores antigos ou permanecer indefinidamente meio moderno e meio legado. Nesses casos, peça à skill para se adaptar de forma conservadora em vez de remodelar toda a stack, ou simplesmente não a use para aquele repositório.