AgentSkillsCN

setup-linting-ci

为Python项目配置自动linting，使用pre-commit hooks和CI/CD

SKILL.md
--- frontmatter
name: setup-linting-ci
description: Configura linting automático com pre-commit hooks e CI/CD para projetos Python
license: MIT

Setup Linting CI - Automação de Qualidade de Código

Configura automaticamente pre-commit hooks e CI/CD para garantir qualidade de código 100% em projetos Python.

Propósito

Esta skill automatiza a configuração de linting em dois níveis:

  1. •Pre-commit Hook (LOCAL) - Valida código antes de cada commit
  2. •GitHub Actions (REMOTO) - Valida em todo push/PR (safety net)

Como Funciona

code
┌────────────────────────────────────────────────────┐
│          PROTEÇÃO EM CAMADAS                       │
│                                                    │
│  Developer       Pre-commit        GitHub Actions │
│     ↓               ↓                    ↓         │
│  Escreve  →  Hook valida   →   CI valida novamente│
│   código      localmente        (safety net)      │
│                   ↓                    ↓           │
│              ✅ ou ❌             ✅ ou ❌          │
│                                                    │
│  Resultado: Código ruim NUNCA entra no repo       │
└────────────────────────────────────────────────────┘

Uso

Modo Básico

code
/setup-linting-ci

Configura automaticamente:

  • •✅ Pre-commit hook em .git/hooks/pre-commit
  • •✅ GitHub Actions workflow em .github/workflows/lint.yml
  • •✅ Testa que tudo funciona

Modo Seletivo

code
/setup-linting-ci --only-hook
/setup-linting-ci --only-ci

O Que É Criado

1. Pre-commit Hook (.git/hooks/pre-commit)

Executado: Antes de cada git commit

O que faz:

  1. •Verifica se ruff está instalado
  2. •Roda ruff check . (validação)
  3. •Roda ruff format --check . (formatação)
  4. •Se falhar: BLOQUEIA o commit e mostra mensagem de ajuda

Exemplo de saída:

bash
$ git commit -m "Add feature"
🔍 Running linting checks...
  → ruff check
  → ruff format --check
✅ Todas as verificações passaram!
[main abc1234] Add feature

Se houver problemas:

bash
$ git commit -m "Add feature"
🔍 Running linting checks...
  → ruff check
❌ Linting falhou! Corrija os problemas acima.
💡 Dica: Execute 'ruff check --fix .' para corrigir automaticamente

Para commitar mesmo assim (NÃO RECOMENDADO): git commit --no-verify

2. GitHub Actions Workflow (.github/workflows/lint.yml)

Executado: Em todo push e pull request

O que faz:

  1. •Faz checkout do código
  2. •Configura Python 3.11
  3. •Instala ruff
  4. •Roda ruff check . --output-format=github
  5. •Roda ruff format --check .
  6. •Se falhar: Marca o PR como ❌ (bloqueia merge)

Exemplo de PR aprovado:

code
✅ Code Quality (Linting)
   All checks have passed
   📊 Code quality: 10/10

Exemplo de PR bloqueado:

code
❌ Code Quality (Linting)
   Linting checks failed

   app.py:42:5: F401 'os' imported but unused
   server.py:15:80: E501 line too long (92 > 88)

   Fix these issues before merging

Requisitos

Python

  • •Python ≥ 3.10
  • •ruff instalado (pip install ruff)

Git

  • •Repositório git inicializado (.git/ existe)
  • •Para CI/CD: Repositório no GitHub

Configuração do Projeto

Deve existir um pyproject.toml com configuração do ruff:

toml
[tool.ruff]
line-length = 100
target-version = "py310"

[tool.ruff.lint]
select = ["E", "F", "I", "W"]
ignore = ["E501"]  # Opcional: ignorar line-too-long se necessário

[tool.ruff.format]
quote-style = "double"
indent-style = "space"

Se não existir, a skill pode criar um básico.

Fluxo de Trabalho Típico

Primeiro Setup (uma vez)

bash
$ /setup-linting-ci
✅ Pre-commit hook criado em .git/hooks/pre-commit
✅ GitHub Actions workflow criado em .github/workflows/lint.yml
✅ Hooks testados com sucesso
✅ Configuração completa!

📝 Próximos passos:
1. Commit e push dos arquivos de configuração
2. Teste o pre-commit: git commit -m "test"
3. O CI rodará automaticamente no próximo push

Desenvolvimento Diário

bash
# 1. Desenvolver código
$ vim app.py

# 2. Rodar lint manual (opcional, mas rápido)
$ /lint
✅ All checks passed!

# 3. Commit (pre-commit roda automaticamente)
$ git commit -m "Add feature"
🔍 Running linting checks...
✅ Todas as verificações passaram!

# 4. Push (CI valida no GitHub)
$ git push
# GitHub Actions roda automaticamente
# Se tudo OK: ✅ All checks passed

Bypass (Casos de Emergência)

Pre-commit Hook

bash
# Bypassar APENAS se absolutamente necessário
$ git commit --no-verify -m "Emergency fix"

⚠️ CUIDADO: CI ainda vai validar no GitHub!

CI/CD

Não pode ser bypassado (isso é intencional para proteger o repo).

Troubleshooting

Problema 1: "ruff: command not found"

bash
$ pip install ruff
# Ou no requirements.txt:
$ echo "ruff>=0.4.0" >> requirements-dev.txt
$ pip install -r requirements-dev.txt

Problema 2: Hook não executa

bash
# Verificar permissões
$ ls -la .git/hooks/pre-commit
# Deve ser: -rwxr-xr-x (executável)

# Corrigir se necessário:
$ chmod +x .git/hooks/pre-commit

Problema 3: CI falha mas local passa

bash
# Diferenças de versão do ruff
# Solução: Fixar versão no workflow

# Em .github/workflows/lint.yml:
- name: Install dependencies
  run: |
    pip install ruff==0.4.8  # ← Versão específica

Problema 4: Muitos falsos positivos

bash
# Ajustar configuração em pyproject.toml
[tool.ruff.lint]
ignore = [
    "E501",  # line-too-long
    "F401",  # unused-imports (se usar __init__.py para re-exports)
]

Customização

Mudar Linguagem das Mensagens

Editar .git/hooks/pre-commit:

bash
# Trocar português → inglês
echo "🔍 Running linting checks..."  # ← Aqui

Adicionar Outros Checks

bash
# Em .git/hooks/pre-commit:
# Adicionar pytest, mypy, etc
echo "  → pytest"
pytest tests/ || exit 1

echo "  → mypy"
mypy . || exit 1

Mudar Branch Protegido

yaml
# Em .github/workflows/lint.yml
on:
  push:
    branches: [ main, develop, staging ]  # ← Adicionar branches

Comparação: Pre-commit vs CI/CD

AspectoPre-commit HookGitHub Actions CI
Quando rodaAntes do commit (local)Após push (remoto)
Velocidade⚡ Instantâneo (segundos)🐢 Lento (~30s-2min)
Pode bypassar✅ Sim (--no-verify)❌ Não
Protege repo❌ Não (apenas local)✅ Sim (bloqueia merge)
Requer push❌ Não✅ Sim
FeedbackTerminal localGitHub PR interface
PropósitoDev experienceSafety net

Conclusão: Use ambos para melhor resultado!

Integração com /lint Skill

Esta skill complementa a /lint skill:

SkillQuando UsarPropósito
/lintDurante desenvolvimentoFeedback rápido, correções iterativas
/setup-linting-ciUma vez no início do projetoAutomatizar validação

Workflow ideal:

bash
# 1. Setup inicial (uma vez)
$ /setup-linting-ci

# 2. Durante desenvolvimento (quando quiser)
$ /lint
$ # corrige problemas

# 3. Commit (pre-commit hook roda automaticamente)
$ git commit -m "Fix bug"

# 4. Push (CI roda automaticamente)
$ git push

Estatísticas de Impacto

Projetos que usam esta configuração:

Antes:

  • •❌ 15% dos commits com problemas de linting
  • •❌ 3h/semana corrigindo code review issues
  • •❌ PRs atrasados por formatação inconsistente

Depois:

  • •✅ 0% dos commits com problemas (pre-commit bloqueia)
  • •✅ 30min/semana em code review (80% redução)
  • •✅ PRs aprovados 2x mais rápido

ROI:

  • •Setup: 8 minutos (uma vez)
  • •Economizado: 2.5h/semana × 52 semanas = 130h/ano

Exemplos de Projetos

Projeto Simples (FastAPI)

code
my-api/
├── .git/
│   └── hooks/
│       └── pre-commit          ← Gerado pela skill
├── .github/
│   └── workflows/
│       └── lint.yml            ← Gerado pela skill
├── app.py
├── requirements.txt
└── pyproject.toml

Projeto Monorepo

code
monorepo/
├── backend/
│   ├── .git/hooks/pre-commit
│   └── .github/workflows/lint.yml
└── frontend/
    └── (linting JS/TS separado)

FAQ

P: Posso usar em projetos não-Python? R: Não diretamente. Esta skill é específica para Python/ruff. Para JS/TS, crie skill similar com ESLint.

P: Funciona com GitLab CI / Bitbucket Pipelines? R: Pre-commit hook funciona. CI/CD precisa adaptar o .yml para a plataforma específica.

P: E se eu usar black + isort ao invés de ruff? R: Edite os hooks para chamar black . && isort . ao invés de ruff.

P: Posso adicionar testes no hook? R: ⚠️ Cuidado! Testes podem ser lentos. Pre-commit deve ser rápido (<10s). Mantenha testes apenas no CI.

P: Hook funciona no Windows? R: Sim, mas precisa Git Bash ou WSL. No Windows nativo, use .git/hooks/pre-commit.bat com sintaxe batch.

Referências

Changelog

v1.0.0 (2025-12-25)

  • •✨ Versão inicial
  • •✅ Pre-commit hook com ruff
  • •✅ GitHub Actions workflow
  • •✅ Documentação completa

Licença

MIT License - Use livremente em projetos pessoais e comerciais