Instrução em prompt é probabilística; hook e gate são determinísticos. Este repositório reúne práticas, guardrails e artefatos prontos para copiar para desenvolver software com agentes de IA (Claude Code) de forma segura, reprodutível e auditável, usando só regras locais, ferramentas OSS e recursos gratuitos. A única base paga assumida é a assinatura do Claude Code que você já tem; o que exige serviço pago ou cobrança por token não entra nos templates (doc 09).

Tudo aqui nasceu de trabalho real em três codebases em produção: um app mobile (React Native), um painel web (Next.js) e um bot (Node), onde agentes de IA passaram a operar com gate de CI bloqueante, supply chain travada, guardrails de git e fluxo de task com evidência obrigatória. Os números e as lições são reais; as referências internas foram generalizadas para servir a qualquer projeto (doc 07). E o repo come o próprio dogfood: o CI daqui roda o canário dos guardrails dos templates e checa que nenhum doc cita caminho fantasma.

Comece em 60 segundos

Auditar um repo existente (com um agente): instale a skill como plugin do Claude Code. Ela impõe o fluxo certo em qualquer repo:

/plugin marketplace add goul4rt/quick-guardrails-ia
/plugin install guardrails@metodologias
# em qualquer repo: "aplique os guardrails" / "rode o checklist"

Sem plugin, o mesmo efeito via clone + symlink (ln -s <este-repo>/.claude/skills/applying-guardrails ~/.claude/skills/), ou só o prompt da seção Usando com um agente de IA.

Adotar do zero: siga os 6 passos de Como adotar em um repositório novo.

Só quer um artefato: tudo em templates/ é copiável, e cada arquivo aponta o doc que explica o porquê de cada decisão.

O que muda na prática

Teste real (baseline documentado na criação da skill): mesmo modelo, mesmo pedido ("aplique os guardrails neste repo"), num projeto Node recém-criado.

A diferença não é o modelo, é o processo imposto por guardrail: auditar → decidir → implementar, cada fase com artefato obrigatório.

Princípios

1. Gate bloqueante ou gate nenhum. Check que não trava merge é decoração. Zere a dívida que impede o bloqueio no mesmo PR que cria o gate.
2. Guardrail no harness, não no prompt. Instrução em prompt é probabilística; hook PreToolUse é determinístico. O que não pode acontecer, bloqueie por código.
3. Reprodutibilidade por hash. Dependências pinadas na versão exata; skills de IA fixadas por hash em lockfile. Upgrade é PR explícito, nunca efeito colateral.
4. Evidência, não afirmação. Task só fecha com prova visual (screenshot + log) por critério de aceite. Falhou? Reporta como falhou, sem maquiar.
5. Não presuma, não invente. Sem critérios de aceite, pergunta. Sem PR aberto, pede. MCP desconectado, avisa e para. O agente expõe trade-offs em vez de decidir em silêncio.
6. Exceções são documentadas, não escondidas. Fugiu da convenção de propósito? A decisão e o porquê ficam registrados no PR.
7. Guardrail também é código. Sem teste, quebra em silêncio e continua verde. Cada gate tem um canário (caso mau que deve reprovar, caso bom que deve passar) rodando no CI.

Mapa do repositório

Guias (docs/)

Artefatos prontos (templates/)

templates/
├── .github/
│   ├── workflows/ci.yml            # gate de PR bloqueante (adapte os checks à sua stack)
│   ├── workflows/ci-docs-noop.yml  # companheiro do paths-ignore (required check nunca trava)
│   ├── workflows/audit.yml         # npm audit mensal → abre/atualiza issue
│   ├── workflows/security.yml      # gitleaks CLI (free, bloqueante): secrets no histórico
│   ├── workflows/preview-smoke.yml # valida que o preview de deploy responde (via check_run)
│   ├── workflows/close-sub-issues.yml # cascata: pai fechada → fecha sub-issues (cross-repo)
│   ├── dependabot.yml              # mensal, agrupado, majors excluídos; modo registrado no arquivo
│   └── CODEOWNERS                  # config que o agente executa só muda com revisor humano
├── .claude/
│   ├── settings.json               # hooks + plugins versionados (guardrails de time)
│   ├── hooks/
│   │   ├── block-dangerous-git.sh  # PreToolUse: bloqueia git destrutivo
│   │   └── eslint-fix-edited.sh    # PostToolUse: auto-fix só no arquivo editado
│   └── skills/routing-work/        # skill de roteamento por tiers (copiável; ver ADAPTING.md)
├── .husky/
│   └── pre-commit                  # disciplina de branch no git, vale p/ humano e agente
├── .mcp.json                       # MCPs pinados (versão exata / digest); Jira em Docker, creds via .env
├── scripts/
│   ├── skills-install.mjs          # restaura skills do lock (postinstall seguro)
│   ├── jira-attach.sh              # anexa evidência a issue do Jira via REST
│   ├── diff-coverage.mjs           # cobertura nas linhas novas do PR (doc 14)
│   └── test-guardrails.sh          # canário do hook: must-block/must-pass (doc 11)
└── .npmrc                          # save-exact=true

Checklist de guardrails

CHECKLIST.md é uma lista checável de guardrails sugeridos, com verificação objetiva e ponteiro pro doc/template de cada item. Serve para os dois sentidos: auditar um projeto existente (o que falta?) e implementar do zero (em que ordem?). Copie para o projeto-alvo ou cole numa issue de tracking.

Usando com um agente de IA

Esse fluxo está empacotado como skill em .claude/skills/applying-guardrails/: auditar (CHECKLIST preenchido com evidência) → decisão humana (itens ⚠️/custo, variante de push, conteúdo do CLAUDE.md) → implementar só o aprovado, por PR. Instalação no quickstart.

Sem a skill, o mesmo contrato vale como prompt. Aponte o agente para cá neste formato:

Use goul4rt/quick-guardrails-ia como referência. Rode o CHECKLIST.md contra o projeto <alvo>: para cada item, verifique com o comando/observação indicado e marque ✅/❌. Para cada ❌, proponha a implementação a partir do template referenciado, adaptando ao stack do projeto (os docs explicam o porquê de cada decisão: siga-os, não só copie o arquivo). Itens marcados ⚠️ ou que envolvem custo (doc 09) exigem minha decisão antes de implementar. Entregue: o checklist preenchido com evidência por item + os PRs/diffs propostos, em ordem de impacto.

Regras para o agente que vier por aqui: verifique, não presuma (cada item tem verificação objetiva; rode-a); adapte, não copie cego (os placeholders ⟨...⟩ e os ADAPTING.md dizem o que muda por projeto); custo é decisão humana (nada de serviço pago sem aprovação explícita, doc 09); gap consciente se registra, não se esconde.

Como adotar em um repositório novo

1. Máquina (uma vez): instale o rtk (brew install rtk no macOS/Linux com Homebrew, winget install rtk-ai.rtk no Windows, ou o install.sh do repo) e rode rtk init -g; depois claude plugins install mattpocock-skills e claude plugins install ponytail@ponytail (o marketplace já vem declarado no settings.json). O que é por repo (plugins habilitados, hook do rtk) já vem no templates/.claude/settings.json (doc 05).
2. Contexto: escreva um CLAUDE.md enxuto com regras objetivas (doc 01).
3. Guardrails: copie templates/.claude/ e versione no repo (doc 04), junto do canário que prova que eles funcionam (doc 11).
4. Gate: adapte templates/.github/workflows/ci.yml à sua stack e zere a dívida antes de ligar o bloqueio (doc 02).
5. Supply chain: .npmrc com save-exact, pins exatos, dependabot.yml e audit.yml (doc 03).
6. Branch protection: exija o check ci e bloqueie push direto na branch principal. Sem isso o gate não trava nada (passo manual, precisa de admin).
7. Fluxo: crie um comando /task adaptado ao seu tracker (doc 06).

Licença

MIT: copie, adapte e use; atribuição é bem-vinda.