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:

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

Como Funciona

┌────────────────────────────────────────────────────┐
│          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

/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

/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:

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

Exemplo de saída:

$ 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:

$ 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:

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

Exemplo de PR aprovado:

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

Exemplo de PR bloqueado:

❌ 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:

[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)

$ /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

# 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

# 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"

$ 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

# 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

# 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

# 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:

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

Adicionar Outros Checks

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

echo "  → mypy"
mypy . || exit 1

Mudar Branch Protegido

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

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

Aspecto	Pre-commit Hook	GitHub Actions CI
Quando roda	Antes 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
Feedback	Terminal local	GitHub PR interface
Propósito	Dev experience	Safety net

Conclusão: Use ambos para melhor resultado!

Integração com /lint Skill

Esta skill complementa a /lint skill:

Skill	Quando Usar	Propósito
`/lint`	Durante desenvolvimento	Feedback rápido, correções iterativas
`/setup-linting-ci`	Uma vez no início do projeto	Automatizar validação

Workflow ideal:

# 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)

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

Projeto Monorepo

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

Ruff Documentation
GitHub Actions Documentation
Git Hooks Documentation
Pre-commit Framework (alternativa mais robusta)

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

Install Skill

SKILL.md