Communitygithub.com

scaffold

Habilidades do Claude Code para criar AGENTS.md, CONTEXT.md e DESIGN.md

O que é scaffold?

Este skill permite que agentes de IA, como o Claude Code, criem ou revisem arquivos AGENTS.md com base em critérios de qualidade apoiados por pesquisas. Ele opera em dois modos principais: Create Mode, para gerar um novo AGENTS.md, e Review Mode, para avaliar um existente. Durante a criação, o skill orienta o agente a coletar informações sobre o diretório alvo, realizar um raciocínio especializado para identificar conhecimentos não descobertos, perigos, ambiguidades e padrões não padronizados do projeto, e então escrever o arquivo seguindo uma ordem de prioridade específica (Missão, Registro de Ferramentas, Limites de Julgamento, etc.), validando-o contra restrições de tamanho e conteúdo. No modo de revisão, ele avalia o arquivo em seis dimensões (densidade de sinal, comando-primeiro, definição de encerramento, sistema de limites, disciplina de comprimento e ausência de antipadrões) e fornece uma pontuação e recomendações de melhoria. O skill enfatiza que o AGENTS.md deve conter apenas conhecimento não descoberto pelo agente, evitando repetir regras de linters, scripts de package.json ou conteúdo genérico, e que cada instrução deve ser acompanhada de um comando verificável. As referências `references/knowledge-base.md` e `references/template.md` são obrigatórias durante a criação e revisão, enquanto `references/example.md` só deve ser carregada quando solicitado ou para monorepos JS/TS.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add robcsaszar/scaffold

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

AGENTS.md: Criar / Revisar (com IA)

Dois modos: criar um novo AGENTS.md ou revisar um existente com base em padrões de qualidade apoiados por pesquisas.

Detecção de Modo

  • O usuário fornece um AGENTS.md existente ou aponta para um → Modo Revisão
  • O usuário pede para criar/esqueletizar/gerar → Modo Criação
  • Ambíguo → pergunte: (c)riar um novo AGENTS.md ou (r)evisar um existente?

Modo Criação

Passo 1: Perguntar o local

Onde o AGENTS.md deve ser colocado?
(r)aiz — base para todo o repositório
(c)aminho — diretório específico (forneça o caminho)

Para monorepositórios: sugerir raiz + arquivos por pacote. O AGENTS.md mais próximo vence.

Se AGENTS.md já existir no caminho alvo → pergunte: Arquivo existe. (r)evisar existente / (s)obrescrever / (Q)uitar?

Passo 2: Pensamento especializado

Antes de escrever, determine para ESTE projeto:

  • O que é não descoberto? O que não pode ser inferido a partir de package.json, configurações ou estrutura de diretórios?
  • O que é perigoso? Quais comandos ou padrões causam falhas silenciosas?
  • O que é ambíguo? Onde existem duas abordagens válidas e o agente adivinharia errado?
  • O que não é padrão? Quais convenções diferem dos padrões do framework?

Se todas as respostas forem "nada" — o projeto pode não precisar de um AGENTS.md. Diga isso.

Para repositórios sem package.json ou configurações de build (apenas docs, repositórios de dados, scripts simples): concentre-se apenas nos limites de Missão + Julgamento — as seções de ferramentas e encerramento não se aplicarão.

Passo 3: Escrever em ordem de prioridade

Adicione seções APENAS se elas passarem no teste de não descoberta, nesta ordem:

  1. Missão (2–4 frases) — propósito do projeto + restrição central que o agente não pode inferir
  2. Registro de ferramentas — comandos como tabela, NÃO o que as ferramentas impõem
  3. Limites de julgamento — níveis NUNCA / PERGUNTE / SEMPRE
  4. Definição de encerramento — "Pronto" = códigos de saída específicos
  5. Regras de escalonamento — o que fazer quando bloqueado
  6. Seções organizadas por tarefa — "Ao escrever… / Ao revisar… / Ao lançar…"

Passo 4: Validar

  • Total ≤ 150 linhas (ideal: 60–100)
  • Cada seção ≤ 50 linhas
  • Cada instrução responde: "Qual comando prova que isso foi feito?"
  • Cada "não" é pareado com um "sim"
  • Nenhuma regra de linter reafirmada (ferramentas primeiro)
  • Nenhum parágrafo em prosa sem comandos

OBRIGATÓRIO — LEIA references/knowledge-base.md para padrões e evidências baseados em pesquisa. OBRIGATÓRIO — LEIA references/template.md para estrutura inicial. Carregue references/example.md apenas quando o usuário perguntar como é um AGENTS.md finalizado, ou quando o repositório for um monorepo JS/TS (é um exemplo de turborepo + pnpm trabalhado) — pule caso contrário. NÃO carregue references/knowledge-base.md durante o Modo Revisão se o AGENTS.md alvo tiver < 20 linhas — a lista de verificação do corpo e a lista de antipadrões são suficientes para arquivos trivialmente curtos.


Modo Revisão

Avalie o AGENTS.md fornecido em relação a critérios de qualidade apoiados por pesquisas.

Dimensões de Pontuação

DimensãoPesoO que verificar
Densidade de sinal25%%% de linhas que são conhecimento especializado não descoberto vs. genérico/redundante
Comando-primeiro20%Cada instrução tem um comando verificável ou código de saída
Definição de encerramento15%Critérios explícitos de "pronto" com verificações específicas
Sistema de limites15%Níveis NUNCA/PERGUNTE/SEMPRE presentes e específicos
Disciplina de comprimento10%≤150 total, ≤50 por seção, sem inchaço
Ausência de antipadrões15%Livre de padrões comprovadamente falhos

Orientações de Pontuação

  • Pontue com rigor na densidade de sinal para repositórios maduros com ferramentas estabelecidas — provavelmente a maior parte do conteúdo é redundante
  • Pontue com leniência em encerramento/limites para projetos greenfield — eles podem ainda não ter gates de CI
  • Pontue com rigor em comprimento para arquivos raiz de monorepo — estes são carregados em todas as sessões em todos os pacotes
  • Se pontuação total < 40: recomende reescrita em vez de correções incrementais

Lista de Verificação de Antipadrões

Sinalize qualquer um destes (comprovadamente prejudiciais ao desempenho do agente):

  • Parágrafos em prosa sem comandos
  • Diretivas ambíguas ("tenha cuidado", "quando possível")
  • Prioridades contraditórias sem ordenação explícita
  • Regras de estilo já impostas pela configuração do linter
  • Visões gerais de arquitetura (causam exploração excessiva)
  • 15+ avisos sem alternativas pareadas
  • Modelo gerado por LLM a partir de comandos /init
  • Reafirmar o que a ferramenta impõe
  • Violações de elefante rosa (longas listas de "não fazer" mantendo conceitos proibidos ativos)

Formato de Saída

## Revisão AGENTS.md: <nome do arquivo ou caminho>

**Pontuação**: X/100
**Veredito**: [Pronto para produção / Precisa de trabalho / Reescrita recomendada]

### Pontos Fortes
- ...

### Problemas (por gravidade)
1. [CRÍTICO] ...
2. [ALTO] ...
3. [BAIXO] ...

### Sugestões de Reescrita
1. ...
2. ...

Aplicar

A revisão não é o resultado final — um AGENTS.md melhor é. Após apresentá-la, ofereça:

Aplicar? (t)udo / (s)elecionar por número / (n)enhum

Em (t) ou (s): edite o arquivo no local, um item numerado de cada vez, então reexecute as dimensões de pontuação e relate a nova pontuação junto com a antiga. Cada linha que a revisão não sinalizou sobrevive literalmente — uma revisão não é um mandato de reescrita, e "melhorar" silenciosamente prosa não sinalizada é como uma revisão destrói a voz e a intenção do autor.

Pule a oferta quando o usuário forneceu o conteúdo inline em vez de um caminho, ou o arquivo não é gravável. Diga isso em vez de relatar melhorias como aplicadas.

OBRIGATÓRIO — LEIA references/knowledge-base.md para a evidência de pesquisa por trás de cada critério.


NUNCA

  • NUNCA inclua conteúdo que o agente possa descobrir a partir da estrutura do repositório — scripts package.json, layout de diretórios e arquivos de configuração são autodocumentados; reafirmá-los desperdiça tokens e cria desvio de manutenção. EM VEZ DISSO: faça referência ao arquivo (veja biome.json) e prossiga.
  • NUNCA reafirme regras de linter/formatador — a ferramenta É a restrição; duplicação cria desatualização e requisitos desnecessários prejudicam ativamente o desempenho do agente. EM VEZ DISSO: liste apenas o comando de execução (Lint: \pnpm lint``).
  • NUNCA escreva um "não" sem um "sim" pareado — documentação só com avisos causa exploração excessiva; 15+ não sem alternativas torna os agentes conservadores e menos produtivos. EM VEZ DISSO: pareie cada proibição com a alternativa correta.
  • NUNCA exceda 150 linhas — além deste limite, os ganhos revertem e o arquivo prejudica ativamente a qualidade. EM VEZ DISSO: extraia detalhes para arquivos referenciados ou apague.
  • NUNCA use conteúdo gerado por LLM como final — a saída /init é um inventário do que o agente já sabe; reduz desempenho e infla custo. EM VEZ DISSO: trate como rascunho de inventário, depois remova tudo que a ferramenta já impõe.
  • NUNCA escreva parágrafos em prosa — agentes os ignoram; use comandos, tabelas e marcadores com resultados verificáveis. EM VEZ DISSO: converta para comando + código de saída + descrição de uma linha.

Habilidades Relacionadas