agentleFS
goul4rtgoul4rt/quick-guardrails-ia/.claude/skills/applying-guardrails/SKILL.md

applying-guardrails

Skill12 starsChanged 4 months agoMITView on GitHub

Use when asked to apply, audit, or bootstrap guardrails in a repo (CI gate, git hooks, supply chain, secrets scan, CLAUDE.md), e.g. "aplique os guardrails", "rode o checklist", "deixe este repo seguro para agentes", "audite o projeto contra o guideline", or when starting agent work in a repo that has none of them.

  • Reads credentials

The file

Files
SKILL.md

Aplicando guardrails em um repo

Referência: o repo quick-guardrails-ia. Se esta skill veio via plugin, o guideline completo já está no disco: CHECKLIST.md, docs/ e templates/ ficam três níveis acima deste arquivo. Senão, use um clone local (ex.: ~/workspace/quick-guardrails-ia) ou um clone raso de github.com/goul4rt/quick-guardrails-ia. Esta skill não resume o guideline; ela impõe o fluxo sobre ele: auditar → decidir → implementar, nessa ordem, cada fase com seu artefato. Implementar sem auditar é o modo de falha nº 1, e competência técnica não substitui o fluxo.

Fase 1: auditoria (sempre primeiro)

Rode o CHECKLIST.md da referência contra o repo-alvo, item a item, executando a verificação objetiva indicada em cada item (rode o comando, não presuma).

Rodar o comando não basta: o comando também erra.

  • Verificação negativa exige caso de controle. Grep vazio e contador zero passam igual com repo limpo e com comando quebrado. Antes de marcar ✅, rode o mesmo comando contra uma linha fabricada que deveria casar; se não casar, o gap é o comando. Foi assim que uma auditoria real marcou "deps pinadas" com 30 de 36 deps em ^.
  • Item que depende de execução se verifica pelo run (gh run list --workflow <arquivo> --limit 5), não pela leitura do YAML. Gate suspenso por billing lê como protegido.

Artefato obrigatório: o checklist preenchido, com ✅ / ❌ / n/a (condição não vale) e evidência por item (comando rodado + resultado). Sem esse artefato entregue, a fase não terminou e nenhum arquivo é criado.

Fase 2: decisão humana (gate)

Apresente os gaps em ordem de impacto, com a proposta de implementação de cada um (template de origem + adaptações).

Impacto é dano × probabilidade no histórico daquele repo, não a ordem do checklist. Antes de ordenar, leia o histórico (issues, STATUS.md, incidentes, o que já vazou ou já se perdeu) e olhe o que está a um commit de distância do desastre: um .env com credencial de produção na raiz, separado do push só pelo .gitignore, coloca scan de secrets acima dos hooks de git, por mais que hook seja o item mais visível. Se o humano aprovar só o primeiro bloco, ele precisa ser o que mais dói perder.

Depois conduza as decisões como entrevista, não formulário:

  • Fato se descobre, decisão se pergunta. O que um comando ou arquivo responde (stack, remoto, público × privado), descubra você mesmo; só trade-off, custo e preferência vão para o humano.
  • Uma decisão por vez, na ordem das dependências entre elas (ex.: público × privado antes de branch protection, que depende do custo). Várias perguntas de uma vez confundem.
  • Toda pergunta chega com a sua recomendação e o porquê ("Recomendo bloquear só push forçado porque…"). Espere a resposta antes da próxima.

São sempre decisões humanas: todo item ⚠️ ou com custo (doc 09 da referência); a variante do hook de push (todo push × só forçado); o modo do Dependabot (agrupado × só-segurança, registrado na 1ª linha do dependabot.yml); e conteúdo que exige conhecimento do projeto, porque CLAUDE.md se escreve com o humano (propor esqueleto é ok, inventar conteúdo não é). Aprovado o bloco 1, a implementação dele é a skill writing-agents-md.

Nada de implementar até o humano confirmar que o entendimento é comum. Usuário indisponível ou sessão autônoma? Entregue auditoria + propostas com a recomendação registrada por decisão pendente e pare aí. Implementar tudo sozinho é o erro, não o zelo.

Fase 3: implementação (só o aprovado)

  • Branch + PR por bloco do checklist; nunca commit ou merge direto na mainline, nem "porque não há remoto". Agrupe blocos conforme o time: com um mantenedor só, três PRs temáticos são tão revisáveis quanto oito e muito mais baratos de mergear em cascata. Cerimônia escala com o tamanho do time, não com o tamanho do checklist.
  • Adapte, não copie: resolva todo placeholder ⟨...⟩, siga o ADAPTING.md/doc do template; os checks do gate refletem o stack real do alvo (não infle com ferramentas que o projeto não tem).
  • Dívida zerada no mesmo PR que liga o gate; canário entra junto do hook que ele testa.
  • Refaça a verificação objetiva do CHECKLIST após implementar cada item: evidência fresca, não "deve funcionar".
  • O que ficou de fora vira gap consciente registrado (no PR ou em issue), nunca omissão silenciosa.

Erros comuns (observados em baseline real)

ErroCorreção
Ir direto à implementação, auditoria vira relatório ad-hoc no finalFase 1 entrega o CHECKLIST preenchido antes de qualquer arquivo ser tocado
Inventar CLAUDE.md completo (branches, STOPs) para projeto desconhecidoEsqueleto + perguntas ao humano; conteúdo real vem do projeto
Merge direto na mainline "porque não há remoto/PR"Deixe a branch pronta e reporte; o merge é decisão do dono
Decidir sozinho item ⚠️/custo e só documentar depoisDocumentar a decisão não substitui pedir a decisão
Marcar ✅ porque o grep voltou vazioVerificação negativa precisa do caso de controle que prova que ela detecta
Marcar ✅ de gate lendo o YAMLConfira os últimos runs; workflow que não executa lê como proteção
Encher o CLAUDE.md seguindo os subitens do bloco 1Cada seção nova aponta o que saiu; o arquivo tem teto

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.