Do vibe coding ao desenvolvimento com intenção, segurança e estrutura. Usando apenas ferramentas open source.
Cansei de ver apps nascendo sem segurança, arquitetura torta e zero versionamento.
O vibe coding virou padrão — você descreve vagamente o que quer, aceita o que o agente gera e vai embora. O resultado: SQL injection em produção, API keys no histórico do git, dependências com CVEs críticos e código que ninguém consegue manter.
O gargalo não é a IA. É a ausência de estrutura antes e durante a geração do código.
SpecShield é uma pipeline de desenvolvimento que combina Spec-Driven Development com segurança desde o primeiro commit, execução via agentes especializados e versionamento automático.
Princípio central: nenhuma linha de código antes de uma spec. Nenhum commit sem passar pelos guardrails de segurança.
Sua ideia
↓
📋 GitHub Spec Kit → spec.md + plan.md + tasks.md
↓
🤖 CrewAI + Gemma 4 31B → arquiteto → segurança → implementador → revisor
↓
🔐 Semgrep + Trivy + Gitleaks → bloqueia antes do commit
↓
📦 Conventional Commits + Semantic Release → versão automática
↓
⚙️ GitHub Actions → CI/CD roda tudo a cada PR
| Ferramenta | Camada | O que faz |
|---|---|---|
| GitHub Spec Kit | Intenção | Transforma sua ideia em spec, plano e tasks |
| Ollama Cloud | Execução | Roda Gemma 4 31B na nuvem Ollama (plano pago) |
| Claude Code CLI | Execução | Agente de terminal que implementa as tasks |
| CrewAI v1.13.0 | Orquestração | Time de agentes: arquiteto, segurança, dev, revisor |
| Semgrep OSS | Segurança | SAST — detecta vulnerabilidades no código |
| Trivy | Segurança | CVEs em dependências, containers e IaC |
| Gitleaks | Segurança | Bloqueia secrets antes do push |
| Conventional Commits | Versionamento | Padroniza mensagens de commit |
| Semantic Release | Versionamento | Versão e CHANGELOG automáticos |
| Husky | Qualidade | Git hooks que bloqueiam commits inválidos |
| pre-commit | Qualidade | Centraliza todos os checks num único arquivo |
| GitHub Actions | CI/CD | Roda toda a pipeline a cada Pull Request |
Antes de começar, certifique-se de ter instalado:
- Git
- Node.js 20+
- Python 3.11+
- Ollama CLI com plano pago ativo
- Claude Code CLI
Clique em "Use this template" no GitHub e crie seu repositório.
git clone https://github.com/seu-usuario/seu-projeto
cd seu-projetoCopie o arquivo SPECSHIELD.md deste repositório para a raiz do seu projeto e abra o Claude Code:
ollama launch claude --model gemma4:31b:cloudNo prompt do agente, digite:
Leia o SPECSHIELD.md e configure nosso ambiente SpecShield para este projeto.
O agente vai executar todos os 11 passos de setup automaticamente.
Após o setup, edite o arquivo agents/.env:
OLLAMA_API_KEY=sua-chave-ollama-aqui
OLLAMA_BASE_URL=https://api.ollama.com
MODEL=ollama/gemma4:31b# Inicie o agente com Gemma 4 31B via Ollama Cloud
ollama launch claude --model gemma4:31b:cloudNo agente:
/specify Quero construir [descreva sua ideia aqui]
O Spec Kit vai gerar spec/spec.md, spec/plan.md e spec/tasks.md. Só depois disso o código começa.
.
├── SPECSHIELD.md ← instrução para o agente de IA fazer o setup
├── spec/
│ ├── constitution.md ← princípios e constraints do projeto
│ ├── spec.md ← especificação funcional (fonte da verdade)
│ ├── plan.md ← plano técnico e arquitetura
│ └── tasks.md ← tasks atômicas para implementação
├── agents/
│ └── src/agents/
│ ├── crew.py ← orquestração dos agentes CrewAI
│ └── config/
│ ├── agents.yaml ← definição dos 4 agentes
│ └── tasks.yaml ← tasks dos agentes
├── scripts/
│ └── spec-drift-check.sh ← detecta divergência código vs spec
├── docs/
│ └── adr/ ← Architecture Decision Records
├── .github/
│ └── workflows/
│ └── specshield.yml ← pipeline CI/CD completa
├── .husky/
│ ├── pre-commit ← roda Gitleaks + Semgrep antes do commit
│ └── commit-msg ← valida padrão Conventional Commits
├── .pre-commit-config.yaml
├── .gitleaks.toml
├── .semgrepignore
├── commitlint.config.js
└── .releaserc.json
O SpecShield usa um time de 4 agentes especializados rodando com Gemma 4 31B via Ollama Cloud:
Arquiteto — lê a spec e valida coerência arquitetural antes de qualquer implementação. Sinaliza inconsistências e ambiguidades.
Especialista em Segurança — analisa a spec e o plano técnico identificando vetores de ataque, dados sensíveis expostos e configurações inseguras antes do primeiro commit.
Desenvolvedor — implementa as tasks seguindo estritamente a spec. Escreve testes para cada funcionalidade.
Revisor — compara o código implementado com a spec e sinaliza qualquer divergência. Nada chega ao PR sem passar por ele.
Para rodar os agentes:
cd agents && crewai run# 1. Iniciar o agente
ollama launch claude --model gemma4:31b:cloud
# 2. Criar a spec da nova feature
/specify [descreva a feature]
# 3. Gerar o plano técnico
/plan
# 4. Gerar as tasks
/task
# 5. Rodar os agentes (validação + implementação)
cd agents && crewai run
# 6. Commitar (Husky roda Gitleaks + Semgrep automaticamente)
git add . && git commit -m "feat: descrição da feature"
# 7. Abrir PR → GitHub Actions roda toda a pipeline
# 8. Merge na main → Semantic Release publica versão + CHANGELOGTodas as mensagens de commit seguem este padrão. Commits que não seguirem são bloqueados automaticamente pelo Husky:
git commit -m "feat: adiciona autenticação OAuth2"
git commit -m "fix: corrige race condition no worker pool"
git commit -m "docs: atualiza guia de instalação"
git commit -m "refactor: extrai lógica de validação"
git commit -m "test: adiciona testes para o módulo de pagamento"
git commit -m "chore: atualiza dependências"
git commit -m "ci: adiciona step de scan no pipeline"Três camadas de proteção antes que qualquer código chegue ao repositório:
Gitleaks — roda antes de cada git push. Detecta API keys, tokens JWT, senhas e qualquer secret que tente entrar no histórico.
Semgrep — análise estática que detecta SQL injection, uso inseguro de criptografia, secrets hardcoded e padrões vulneráveis específicos de cada linguagem.
Trivy — escaneia todas as dependências do projeto em busca de CVEs com severidade HIGH e CRITICAL. Um PR com CVE crítico não passa.
Para rodar manualmente:
# Checar secrets
gitleaks detect --source .
# Checar código
semgrep scan --config auto .
# Checar dependências
trivy fs .A cada Pull Request, a pipeline executa automaticamente:
- Gitleaks — secrets scan
- Trivy — CVEs em dependências
- Semgrep — análise estática
- Spec Drift Check — código ainda bate com a spec?
- Testes
- Semantic Release (dry-run no PR, real no merge)
O agente usa este guia durante o planejamento técnico:
API REST simples → Python (FastAPI) ou TypeScript (Hono)
Alta performance → Go
Segurança crítica → Rust
Frontend web → TypeScript (nunca JS puro)
Mobile → Flutter ou React Native (TypeScript)
CLI tools → Go ou Rust
Scripts de automação → Python ou Shell + shellcheck
Infraestrutura como código → Terraform ou Pulumi (TypeScript)
Preciso de conta paga no Ollama? Sim, o SpecShield usa o Gemma 4 31B via Ollama Cloud para os agentes CrewAI. É o modelo mais capaz da família Gemma 4 e requer o plano pago do Ollama.
Posso usar outro modelo?
Sim. Edite o agents/.env e o agents/src/agents/config/agents.yaml com o modelo que preferir. O SpecShield é agnóstico — qualquer modelo compatível com a API do Ollama funciona.
O GitHub Spec Kit é pago? Não. É 100% open source (MIT) e gratuito.
E o resto das ferramentas? Semgrep OSS, Trivy, Gitleaks, Husky, Conventional Commits, Semantic Release e CrewAI são todos gratuitos e open source. O único custo é o plano Ollama.
Como atualizo a spec depois de começar?
Edite spec/spec.md, rode /plan para atualizar o plano técnico e depois crewai run para que os agentes se adaptem.
PRs são bem-vindos. Antes de abrir um PR:
- Leia a
spec/constitution.md - Siga os Conventional Commits
- Certifique-se que
trivy fs .esemgrep scan --config auto .passam sem erros críticos
MIT — use, modifique e distribua à vontade.
🧰🩹 Spec primeiro. Código depois. Segurança sempre.
Feito com intenção por playandogamer150