Johan409IA/skills

Documentação do Projeto

Ajuda a criar e manter atualizado o conjunto completo de documentação de um projeto de software, seguindo uma estrutura fixa e uma relação fixa entre AGENTS.md e MEMORY.md. Use esta habilidade sempre que o usuário quiser gerar documentação do zero, atualizá-la após mudanças ou mantê-la consistente entre arquivos.

Estrutura alvo

Todo projeto gerenciado por esta habilidade deve convergir para esta estrutura:

meu-projeto/
├── README.md          # o que é, como executar
├── AGENTS.md           # regras e instruções para agentes
├── MEMORY.md            # decisões vigentes e o que foi descartado
├── CHANGELOG.md          # o que mudou entre versões
├── DESIGN.md             # sistema de design visual (apenas se houver IU)
└── docs/
    ├── architecture.md
    ├── plans/            # planos dos agentes, um por arquivo
    └── (OpenAPI + Scalar servido da API em /docs)

Se o projeto já tiver alguns desses arquivos, leia-os primeiro e atualize no local — não sobrescreva cegamente. Se um arquivo estiver faltando, crie-o seguindo o template correspondente abaixo.

Fluxo de trabalho

1. Levante o que existe. Liste a raiz do projeto e docs/ para ver quais arquivos já estão lá. Leia quaisquer AGENTS.md/MEMORY.md/CHANGELOG.md/README.md/docs/architecture.md existentes por completo — eles são curtos por design.
2. Defina o escopo. Se o usuário nomear um arquivo específico ("atualiza o CHANGELOG"), foque nele, mas ainda verifique se essa mudança deve se propagar para MEMORY.md ou AGENTS.md (veja a regra de propagação abaixo). Se o usuário disser algo genérico como "documente meu projeto" ou "atualizar a documentação", percorra cada arquivo na estrutura acima.
3. Colete os fatos necessários do próprio código-fonte (manifestos de pacotes, pontos de entrada, scripts, rotas, commits recentes) em vez de adivinhar. Não invente comandos, detalhes de stack ou endpoints — verifique-os lendo o código ou arquivos de configuração.
4. Escreva ou atualize cada arquivo usando o template de referência correspondente. Mantenha os limites rígidos de tamanho em AGENTS.md (~30-40 linhas) e MEMORY.md (~50 linhas) — estas são restrições essenciais, não sugestões, porque os agentes releem esses arquivos a cada sessão e versões inchadas deixam de ser úteis.
5. Reporte o resultado informando quais arquivos foram criados vs. atualizados, e sinalize qualquer coisa que não pôde ser verificada (ex.: "não encontrei um comando de teste, confirme").

Os documentos

README.md

Responde "o que é isso e como executar" para um humano. Veja references/readme-template.md. Extraia os comandos de execução/instalação/teste diretamente dos scripts reais do projeto (package.json, Makefile, pyproject.toml, etc.) — nunca adivinhe nomes de comandos.

AGENTS.md

Instruções para agentes de codificação que trabalham neste repositório. Veja references/agents-template.md para as seções exatas e sua ordem. Limite rígido: ~30-40 linhas no total. Se já estiver maior, seu trabalho ao atualizá-lo é tanto encurtar quanto adicionar — mova qualquer coisa que pareça uma decisão transitória ou nota em andamento para MEMORY.md e mantenha apenas regras duráveis aqui.

MEMORY.md

Memória entre sessões: o que é verdade agora, por que decisões importantes foram tomadas, o que foi tentado e rejeitado, o que vem a seguir. Veja references/memory-template.md. Limite rígido: ~50 linhas. Ao atualizar, faça uma poda ativa — exclua ou compacte entradas que não importam mais, em vez de deixar o arquivo crescer para sempre.

Como AGENTS.md e MEMORY.md se relacionam (esta é a convenção central — acerte-a):

• AGENTS.md deve conter uma seção curta "Memória" instruindo os agentes a lerem MEMORY.md no início de uma tarefa e atualizá-lo no final. Use esta redação exata como base, adaptando apenas se o projeto já a expressar de forma diferente:

  ## Memória
  - Ao começar, leia `MEMORY.md` para conhecer o estado do projeto e as decisões tomadas.
  - Ao terminar uma tarefa, atualize-o: estado atual, decisões importantes (com seu porquê) e erros a evitar.
  - Mantenha-o breve (máximo ~50 linhas): resuma ou elimine o que já não agregar.
  - Se algo se tornar uma regra permanente, proponha movê-lo para `AGENTS.md` em vez de deixá-lo na memória.
  - Nunca guarde dados sensíveis (chaves, tokens, dados pessoais).
  

• A seção "Limites" de AGENTS.md deve incluir ✅ Sempre: atualizar MEMORY.md ao terminar cada tarefa.
• Regra de propagação: MEMORY.md contém coisas que são verdade por enquanto — estado atual, decisões com sua justificativa, lições aprendidas, próximos passos. AGENTS.md contém coisas que são verdade sempre — regras permanentes, convenções, stack, limites. Quando algo em MEMORY.md deixar de ser uma decisão pontual e se tornar uma regra permanente (ex.: "decidimos nunca usar X" se transforma em "nunca use X, ponto final"), mova-o para AGENTS.md e remova-o de MEMORY.md. Ao atualizar qualquer um dos arquivos, sempre verifique se essa promoção deve ocorrer.
• Nunca escreva secrets, tokens ou dados pessoais em nenhum dos arquivos.

CHANGELOG.md

Responde "o que mudou entre versões". Siga a convenção Keep a Changelog (Adicionado/Alterado/Corrigido/Removido sob cada versão, mais recente no topo, com uma seção Não publicado no topo para trabalho em andamento). Veja references/changelog-template.md. Ao atualizar, adicione entradas sob Não publicado conforme o trabalho acontece, e só corte uma nova seção de versão datada quando o usuário indicar um lançamento.

DESIGN.md

Responde "qual é a aparência e como a IU deve ser construída" — o sistema de design visual, lido por agentes que geram IU. Ele fica na raiz do projeto (não em docs/), ao lado de AGENTS.md. Segue o formato aberto Google Stitch DESIGN.md (especificação: github.com/google-labs-code/design.md, atualmente alpha). Veja references/design-template.md para o template e uma explicação de cada bloco.

• Apenas para projetos com interface de usuário (web, mobile, desktop). Se o projeto for uma API/CLI/biblioteca pura sem IU, não crie e informe isso no relatório.
• Duas camadas: frontmatter YAML com tokens legíveis por máquina (colors, typography, rounded, spacing, components) — estes são os valores normativos — mais um corpo markdown que explica o porquê. Tokens dizem o quê; prosa diz quando e por que e se refere aos tokens por nome em vez de repetir códigos hexadecimais.
• A ordem das seções é fixa: Visão Geral → Cores → Tipografia → Layout → Elevação e Profundidade → Formas → Componentes → O Que Fazer e o Que Não Fazer. Mantenha esses cabeçalhos em inglês exatamente como escritos (as ferramentas os buscam pelo nome; os alias Brand & Style, Layout & Spacing e Elevation também são aceitos) e escreva a prosa no idioma do projeto. Seções podem ser omitidas, mas não reordenadas, e um cabeçalho duplicado é um erro. Seções extras (ex.: Iconografia e Imagens, Movimento, Acessibilidade) são permitidas — coloque-as sempre depois de "O Que Fazer e o Que Não Fazer".
• Extraia valores do código, nunca os invente: configuração do Tailwind, variáveis CSS (:root, globals.css), arquivos de tema da biblioteca de IU, fontes carregadas, exportações de tokens Figma/DTCG. Se o projeto tiver IU mas nenhuma identidade visual definida ainda, proponha valores e sinalize-os no relatório como "proposta, confirmar".
• Se um DESIGN.md já existir, leia e atualize no local — nunca sobrescreva silenciosamente. Mantenha os tokens sincronizados com o código quando cores, fontes ou espaçamento mudarem.
• Sem limite rígido de linhas (é um documento de referência como docs/architecture.md), mas mantenha cada seção focada: 3–6 tópicos ou um parágrafo curto.
• Valide: se Node estiver disponível, execute npx @google/design.md lint DESIGN.md e corrija erros (broken-ref) e avisos razoáveis (missing-primary, contrast-ratio, section-order); caso contrário, informe o usuário sobre o comando.
• Se AGENTS.md existir e não mencionar DESIGN.md, sugira ao usuário (não aplique por conta própria) adicionar uma linha de referência para que agentes de IU o leiam antes de gerar IU — lembrando do limite de ~30-40 linhas de AGENTS.md.

docs/architecture.md

Responde "como isso é construído" — componentes, fluxo de dados, decisões importantes de design e o porquê, restrições notáveis. Veja references/architecture-template.md. Este é o único documento que pode ser mais longo que os outros, pois é um documento de referência, não algo relido a cada sessão — mas ainda prefira diagramas e seções curtas a prosa longa. Use um diagrama mermaid para a visão principal de componentes/fluxo de dados quando ajudar.

docs/plans/

Quando um agente produzir um plano para uma tarefa não trivial (um plano de implementação em várias etapas, um plano de migração, um plano de refatoração), salve-o aqui como seu próprio arquivo em vez de deixá-lo apenas no chat. Crie o diretório se ele não existir. Nomeie os arquivos como YYYY-MM-DD-slug-curto.md (ex.: 2026-10-03-adicionar-webhook-pagamento.md) para que sejam ordenados cronologicamente. Cada arquivo de plano deve ser autocontido: objetivo, abordagem, etapas, perguntas em aberto. Não exclua planos antigos depois de concluídos — eles são um registro histórico; se o projeto quiser um marcador de "concluído", adicione uma nota de status de uma linha no topo do arquivo em vez de removê-lo.

Documentação da API — OpenAPI + Scalar

Estes não são um arquivo markdown estático — eles são servidos ao vivo a partir da API, tipicamente em uma rota /docs ou /reference via renderizador de referência de API do Scalar que lê uma especificação OpenAPI. Quando solicitado a configurar ou atualizar a documentação da API:

1. Verifique se o projeto já gera uma especificação OpenAPI (decorators/anotações do framework, um arquivo openapi.yaml/openapi.json, ou uma biblioteca de geração de especificação já nas dependências).
2. Se a especificação existir mas não estiver sendo servida via Scalar ainda, conecte o middleware/handler do Scalar para o framework do projeto (Scalar tem integrações oficiais para a maioria dos frameworks backend comuns — verifique os nomes/APIs atuais dos pacotes em vez de presumir, já que este ecossistema evolui rapidamente) e monte-o em /docs.
3. Se nenhuma especificação existir ainda, gere uma a partir das rotas/handlers existentes (a maioria dos frameworks tem uma biblioteca que deriva OpenAPI das definições de rota/tipos — prefira isso a escrever YAML manualmente) antes de conectar o Scalar.
4. Nunca mantenha manualmente um enorme YAML OpenAPI estático se o framework puder derivá-lo do código — isso rapidamente fica dessincronizado. Prefira geração a partir do código.
5. Anote a URL /docs no README.md assim que estiver configurada, para que humanos saibam onde encontrá-la.

Lista de verificação antes de finalizar

• AGENTS.md tem ≤ ~40 linhas e contém uma seção "Memória" apontando para MEMORY.md
• MEMORY.md tem ≤ ~50 linhas e nada permanente está preso lá que pertença a AGENTS.md
• Comandos do README.md foram verificados contra a configuração real do projeto, não presumidos
• CHANGELOG.md segue o formato Keep a Changelog com uma seção Não publicado
• DESIGN.md (apenas se o projeto tiver IU) está na raiz do projeto, seus tokens correspondem ao código real, as seções seguem a ordem canônica e npx @google/design.md lint DESIGN.md não reporta erros
• docs/architecture.md reflete a estrutura atual, não uma desatualizada
• Novos planos de agentes são salvos em docs/plans/ com um nome de arquivo datado
• Nada sensível (chaves, tokens, dados pessoais) foi escrito em nenhum documento