Mais de 178.000 utilizadores do GitHub deram estrela a um único ficheiro markdown. O ficheiro limita-se a dizer a uma IA como se comportar.
Quatro regras: Pensar Antes de Programar. Simplicidade Primeiro. Alterações Cirúrgicas. Execução Orientada a Objetivos. É só isto. Sem biblioteca. Sem framework. Sem instalador. O Forrest Chang empacotou as observações de Andrej Karpathy sobre os modos de falha dos LLM a programar num único ficheiro CLAUDE.md, e a comunidade de programadores levou-o para além das 178.000 estrelas no GitHub nos meses que se seguiram.
Se olhar com atenção para o que aconteceu ali, parece-se muito com aquilo que toda a organização de engenharia acabou por perceber que precisava, mais cedo ou mais tarde, depois de sofrimento suficiente: um conjunto partilhado de restrições sobre como o código é escrito. Uma camada de regras. O tipo de coisa que costumava viver numa checklist de revisão de código, ou num guia de estilo, ou na memória institucional de um engenheiro sénior. A comunidade de vibe coding encontrou uma versão muito mais leve dessa mesma disciplina: escrever as regras em markdown e deixar o agente lê-las antes de escrever código.
Isto não é um caso isolado. É um padrão.
Resumo rápido
- O ecossistema de instruções para agentes (CLAUDE.md, AGENTS.md, bibliotecas de skills partilhadas e agentes de acessibilidade) está a tornar-se uma camada distribuída de imposição de qualidade para a programação assistida por IA.
- A lacuna de qualidade a que responde é real: a Snyk analisou 3.984 skills do ClawHub e do skills.sh e descobriu que 1.467, ou 36,82%, tinham pelo menos uma falha de segurança; 534, ou 13,4%, tinham pelo menos um problema de nível crítico.
- A resposta da comunidade foi construir mais regras, não abandonar a abordagem, e há agora instituições envolvidas, da Vercel à OWASP e à Linux Foundation.
A Lacuna de Qualidade É Real, e a Comunidade Sabe-o
13,4% dos ficheiros de skills da comunidade contêm falhas de segurança críticas. Isto vem do relatório ToxicSkills da Snyk, publicado em fevereiro de 2026 após analisar 3.984 skills do ClawHub e do skills.sh. 36,82% tinham pelo menos uma vulnerabilidade de segurança. 76 eram abertamente maliciosos, com 91% destes a usar injeção de prompt como mecanismo de entrega.
A história mais ampla da qualidade do código de IA é semelhante. Segundo a análise de dados de revisão de código da CodeRabbit, o código assistido por IA tem, em média, 10,83 problemas por pull request face a 6,45 do código escrito por humanos, cerca de 1,7x mais problemas. O estudo anual de código da GitClear relatou aquilo a que chama "crescimento de 4x" na clonagem de código: uma subida de 8,3% para 12,3% das linhas alteradas entre 2021 e 2024.
Estes são números de fornecedores, por isso encare a precisão com o ceticismo adequado. Ainda assim, são úteis a nível de direção: a programação assistida por IA está a criar pressão de qualidade suficiente para que os programadores construam novas salvaguardas em torno dela.
O que importa é o que a comunidade fez com esta informação. A resposta não foi "os ficheiros de skills são perigosos, parem de os usar". Foi: a OWASP lançou o Agentic Skills Top 10 (AST10), o equivalente, no ecossistema de skills, ao Web Application Security Top 10. Mais regras. Mais estrutura. Uma framework de segurança formal para um ecossistema informal.
Essa é uma resposta clássica de engenharia, mesmo vinda de uma comunidade que muitas vezes tenta evitar processos pesados.
O Ecossistema Que Surgiu
Ao longo da primeira metade de 2026, isto começou a parecer-se menos com um punhado de ficheiros markdown isolados e mais com um ecossistema em camadas.
Comece pela camada comportamental. O CLAUDE.md inspirado em Karpathy empacota a versão de Forrest Chang das observações de Andrej Karpathy sobre os modos de falha dos LLM a programar num único ficheiro de instruções, e está agora com mais de 178.000 estrelas no GitHub, um dos repositórios com mais estrelas na história do GitHub, para um ficheiro construído em torno de quatro regras simples. O que essas regras são é menos interessante do que aquilo que representam: uma tentativa de codificar o discernimento que um engenheiro sénior aplicaria durante a revisão de código.
Acima disso fica uma camada de agregação da comunidade. O Antigravity Awesome Skills ultrapassou as 1.595+ skills agênticas, reunindo manuais reutilizáveis para Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity e outros assistentes de programação por IA. Funciona como uma biblioteca partilhada de evolução rápida para o espaço: o tipo de coisa que um comité de normalização poderia produzir se trabalhasse através do GitHub em vez de PDFs.
Depois apareceram as frameworks. A Vercel tornou o vercel-labs/agent-skills um repositório oficial da organização, agora com 28.000 estrelas. Só a skill React Best Practices contém mais de 40 regras em oito categorias focadas em desempenho, incluindo waterfalls, tamanho de bundle, desempenho do lado do servidor, obtenção de dados do lado do cliente, otimização de re-render, desempenho de renderização e micro-otimizações de JavaScript. Quando a empresa que detém a sua plataforma de deployment lança regras de qualidade oficiais para agentes de IA, o ecossistema passou de experiência da comunidade a infraestrutura de produção.
E no topo, uma camada de normalização. A OpenAI doou a especificação AGENTS.md à Agentic AI Foundation (AAIF) da Linux Foundation, a par do MCP (Anthropic) e do Goose (Block): multi-ferramenta, multi-agente, em vias de normalização. A direção é rumo à portabilidade: o AGENTS.md dá às equipas um sítio partilhado para orientações de agente específicas do projeto, ainda que ferramentas individuais possam diferir na forma como carregam e aplicam essas instruções.
Estas peças não surgiram como uma stack planeada centralmente. Convergiram porque a procura era real.
A Dimensão de Que Ninguém Fala
Os dados de segurança e qualidade de código recebem cobertura. A dimensão da acessibilidade quase nunca a recebe.
Community-Access/accessibility-agents começou a 21 de fevereiro de 2026 com seis agentes. Em junho de 2026: 79 agentes especializados em oito equipas, 18 skills de acessibilidade reutilizáveis, com WCAG 2.2 AA como alvo, e suporte em cinco plataformas: Claude Code, GitHub Copilot, Gemini CLI, Codex CLI e um MCP Server que pode servir clientes compatíveis com MCP.
O que este projeto é, em termos simples: uma comunidade de programadores decidiu que as ferramentas de programação por IA geram código inacessível por predefinição (saltam as regras ARIA, ignoram a navegação por teclado, produzem modais que prendem os leitores de ecrã) e construiu 79 agentes especializados para impor as regras que a IA continua a esquecer.
É uma coisa notável de acontecer. Os engenheiros de frontend têm, historicamente, ficado aquém na acessibilidade. É a primeira coisa a ser cortada sob pressão de prazos. O projeto accessibility-agents são vibe coders a escrever as regras que, de outra forma, precisariam de um engenheiro sénior para impor, e a fazê-lo em público, gratuitamente, em cinco integrações suportadas.
Na minha leitura, o projeto é invulgarmente minucioso para um esforço voluntário de acessibilidade, sobretudo porque transforma a acessibilidade de uma preocupação tardia de QA em instruções de agente reutilizáveis que correm durante a geração de código.
Porque Isto Era Inevitável
O argumento de que "os ficheiros de skills são apenas READMEs para IA" é justo se olhar para qualquer ficheiro isolado. Deixa de se sustentar quando olha para a OWASP a lançar uma framework de segurança para o ecossistema, a Vercel a lançar uma biblioteca de qualidade oficial, ou um projeto voluntário de acessibilidade a crescer para 79 agentes especializados.
Eis o que está realmente a acontecer: a imposição de qualidade não desaparece quando se remove o processo. Reaparece sob outra forma, porque a ausência de qualidade gera dor depressa, e a pessoa mais próxima dessa dor corrige-a na origem.
A disciplina tradicional de engenharia (revisão de código, guias de estilo, barreiras de QA, governação arquitetural) existe para apanhar o que cada programador salta sob pressão de tempo. Funciona quando se tem uma equipa e um processo. Os vibe coders, por design, muitas vezes não têm nenhum dos dois. Por isso pré-codificaram a revisão nas instruções do agente.
O CLAUDE.md é revisão de código pré-codificada. O Awesome Skills é um guia de estilo distribuído. O AGENTS.md é uma norma de governação. As palavras mudaram. A função não.
O que é interessante não é que as restrições reapareceram, isso era inevitável. O que é interessante é que reapareceram mais depressa do que da primeira vez, e mais publicamente, e a um nível de qualidade que envergonha algumas organizações de engenharia com processos maduros.
A comunidade de vibe coding não reinventou a disciplina de engenharia com relutância, sob pressão da gestão. Construiu-a porque bateu numa parede e as ferramentas para a corrigir estavam à distância de um ficheiro markdown.
Perguntas frequentes
O Que Entra Num Ficheiro CLAUDE.md?
Restrições comportamentais para a IA: o que evitar, o que priorizar, regras arquiteturais, sinais de alerta de segurança e convenções específicas do projeto. A utilização focada em qualidade vai além de atalhos de fluxo de trabalho: regras como "nunca remover o tratamento de erros para fazer os testes passarem" ficam ao lado de "usar sempre TypeScript". Para exemplos reais e testados, comece pela agregação da comunidade Awesome Skills. O agent-skills da Vercel é outra referência sólida.
O Que é o AGENTS.md e Em Que Difere do CLAUDE.md?
O AGENTS.md é uma norma universal para orientações de agente específicas do projeto, lançada pela OpenAI e contribuída para a Agentic AI Foundation da Linux Foundation em dezembro de 2025. O CLAUDE.md é o ficheiro de orientação de projeto do Claude Code. Sobrepõem-se no propósito, mas não são formatos idênticos em todas as ferramentas. A conclusão prática é que as equipas podem, cada vez mais, escrever as instruções de agente uma vez e adaptá-las a ferramentas como Codex, Cursor, Copilot, Gemini CLI e Claude Code.
Os Ficheiros de Skills São Seguros de Usar?
As skills de origem comunitária devem ser lidas antes de importadas. relatório ToxicSkills da Snyk descobriu que 36% das skills da comunidade analisadas tinham pelo menos uma falha de segurança, e 13,4% tinham falhas de nível crítico, com a injeção de prompt como principal mecanismo de ataque. O OWASP Agentic Skills Top 10 é a framework de referência para compreender a superfície de ataque. Os ficheiros de skills de repositórios oficiais ou projetos open-source estabelecidos carregam, em geral, menor risco na cadeia de fornecimento do que contribuições anónimas da comunidade, mas devem ainda assim ser revistos antes da importação.
O Que é o OWASP Agentic Skills Top 10 (AST10)?
A framework de segurança de 2026 da OWASP para o ecossistema de skills, análoga ao OWASP Web Application Security Top 10 mas a tratar especificamente da superfície de ataque criada pelos ficheiros de instruções de agentes de IA. Cobre os dez riscos de segurança mais críticos em plataformas incluindo Claude Code, Cursor/Codex e VS Code. A framework está em desenvolvimento ativo em 2026, com um lançamento v1.0 planeado para o Q4 de 2026.
Preciso de Ficheiros de Skills Se Estou a Construir um Projeto Pessoal?
Só se quiser comportamento consistente da IA. Sem restrições, as ferramentas de programação por IA otimizam para a conclusão da tarefa, não para a qualidade do código, o que funciona bem até produzir lógica duplicada, tratamento de erros em falta ou componentes de UI inacessíveis. A sobrecarga é baixa: um ficheiro por projeto, mantido à medida que descobre o que a IA continua a errar. As regras inspiradas em Karpathy são um ponto de partida razoável; as bibliotecas de skills da comunidade permitem-lhe puxar regras específicas de domínio (segurança, acessibilidade, idiomas de linguagem) sem as escrever do zero.
