felvieira/documenter
skills/10-documenter/SKILL.md
Skill de Documentação por nível de decisão. Use quando precisar documentar features, APIs, arquitetura, setup, operação, ou manter documentação existente atualizada. Trigger em: "documentar", "documentação", "docs", "ADR", "architecture decision record", "README", "feature doc", "api doc", "setup doc", "runbook", "troubleshooting", "doc de operação", "registrar decisão", "atualizar docs".
$ install --global
skillsauthnpx skillsauth add felvieira/claude-skills-fv documenterInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: May 29, 2026, 3:00 AM22.2s1 file scanned
SKILL.md
- name:
- documenter
- description:
- |
- setup, operação, ou manter documentação existente atualizada. Trigger em:
- documentar", "documentação",
Documenter - Documentação por Nível de Decisão
Documentação existe para responder perguntas antes que alguém precise fazer a pergunta. Cada nível de decisão tem seu próprio tipo de documentação.
Governanca Global
Esta skill herda comportamento base de GLOBAL.md e destas policies:
policies/execution.mdpolicies/handoffs.mdpolicies/persistence.mdpolicies/token-efficiency.mdpolicies/writing-clarity.mdpolicies/anti-ai-writing.md← antes de finalizar qualquer doc que humanos vão lerpolicies/evals.md
Se houver conflito entre instrucoes, a hierarquia global do kit prevalece.
Para templates completos de feature, ADR, runbook e playbook, consultar docs/skill-guides/documenter-templates.md apenas quando necessario.
Quando Usar
- Registrar feature, contrato, arquitetura, operacao ou runbook
- Atualizar documentacao apos decisao, mudanca de fluxo ou alteracao de contrato
- Consolidar conhecimento util para proxima iteracao
Quando Nao Usar
- Para comentar linha de codigo obvia
- Para duplicar informacao ja existente em outra doc sem necessidade
- Para substituir review tecnico ou QA
Entradas Esperadas
- Artefatos da feature ou da mudanca
- Decisoes tecnicas e trade-offs
- Contratos de API e regras de negocio
- Contexto operacional relevante
Saidas Esperadas
- Documentacao atualizada no nivel correto
- Registro de decisao quando houver impacto arquitetural ou operacional
- Handoff curto com o que mudou e onde foi registrado
Responsabilidades
- Documentar features com objetivo, regras de negócio e critérios de aceitação
- Documentar contratos de API como fonte de verdade entre front e back
- Documentar arquitetura e decisões técnicas relevantes (ADRs)
- Documentar setup, deploy e operação do sistema
- Manter documentação atualizada junto com o código
- Nunca documentar o óbvio — código limpo é a melhor documentação de implementação
Os 4 Níveis de Documentação
Nível 1: Produto/Feature — POR QUE existe
Responde: qual problema resolve, para quem, com quais regras.
Conteúdo obrigatório:
- Objetivo: o que a feature faz e por que existe
- Regras de negócio: todas as regras, sem exceção
- Fluxo do usuário: happy path completo
- Casos de borda: tudo que pode dar errado ou fugir do fluxo principal
- Critérios de aceitação: condições verificáveis de DADO/QUANDO/ENTÃO
Nível 2: Contrato/API — COMO se comunica
Responde: qual endpoint chamar, com quais dados, e o que esperar de volta.
Conteúdo obrigatório:
- Endpoints: método, path, descrição
- Autenticação: tipo de token, headers necessários
- Request: body, query params, path params com tipos e validações
- Response: formato de sucesso e erro com exemplos reais
- Códigos de erro: todos os códigos possíveis com descrição
- Paginação: formato padrão de paginação
- Exemplos: curl ou equivalente para cada endpoint
Nível 3: Implementação — COMO foi construído
Responde: qual a estrutura, quais padrões, por que essa decisão técnica.
Conteúdo obrigatório:
- Arquitetura frontend: estrutura de pastas, gerenciamento de estado, roteamento
- Arquitetura backend: camadas, patterns, fluxo de request
- Componentes reutilizáveis: catálogo de componentes compartilhados e como usar
- Padrões adotados: patterns do projeto com justificativa
- ADRs: toda decisão técnica significativa registrada
Nível 4: Operação — COMO roda
Responde: como subir, como deployar, como monitorar, como resolver problemas.
Conteúdo obrigatório:
- Setup local: do zero ao projeto rodando, passo a passo
- Deploy: pipeline, ambientes, processo de release
- Observabilidade: logs, métricas, alertas, dashboards
- Troubleshooting: problemas conhecidos e como resolver
Runbooks e Playbooks
Manter runbooks em docs/ops/runbooks/.
Para templates completos de runbook e playbook, consultar docs/skill-guides/documenter-templates.md.
Estrutura de Diretórios
docs/
README.md
features/
<feature-name>/
README.md
rules.md
flow.md
api.md
ui.md
architecture/
overview.md
frontend.md
backend.md
decisions/
adr-NNN-*.md
api/
README.md
errors.md
pagination.md
ops/
setup.md
deploy.md
observability.md
context/
current-focus.md
history.md
plans/
O diretório context/ é gerenciado pelo Context Manager. O diretório plans/ armazena planos de implementação.
Templates de Feature e ADR
Usar templates/doc-update.md para atualizacao curta e docs/skill-guides/documenter-templates.md quando precisar dos templates completos de feature, ADR, runbook e playbook.
Regras de Documentação
- Documente PADRÕES, não JSX — código muda toda hora, padrões não. Documente a convenção, não a linha de código
- Feature é a unidade central — toda documentação gravita ao redor de features. Uma feature tem regras, fluxos, API, UI, tudo junto
- API é contrato — a documentação de API é o contrato entre front e back. Se mudou na doc, muda no código. Se mudou no código, muda na doc
- Nunca repita informação — se a regra de negócio está em
rules.md, não repita emapi.md. Faça referência - Nunca misture regras de negócio com detalhes de implementação — "Usuário só pode ter 3 posts por dia" é regra de negócio. "Usamos Redis para cache do contador" é implementação. Cada um no seu lugar
- Toda documentação responde: O que é? Por que existe? Como funciona? Onde fica? O que fala com o que? O que pode quebrar?
Quando Documentar
Documentação é escrita DURANTE o desenvolvimento, não depois.
- Antes de codar: regras de negócio e critérios de aceitação
- Durante o design: contratos de API e decisões de arquitetura (ADRs)
- Durante a implementação: padrões e componentes reutilizáveis
- Antes do deploy: setup e operação
Documentação escrita depois do fato é incompleta por definição. Ninguém lembra de tudo.
Código Limpo: Zero Comentários
Codigo bem escrito prioriza clareza. Comentarios so fazem sentido quando explicam contexto nao obvio, restricoes externas ou workarounds temporarios.
Exceções permitidas:
- Links para documentação externa ou RFCs
- Workarounds temporários com link para o ticket de correção
- Regex complexa com explicação do que faz
Tudo mais é sinal de que o código precisa de refatoração, não de comentário.
Evidencia de Conclusao
- Mudanca documentada no nivel correto
- Arquivos de documentacao atualizados ou criados
- Relacao entre decisao e impacto registrada quando necessario
Handoff
Seguir policies/handoffs.md e, quando util, templates/doc-update.md.
Integração com Pipeline
- skill 48 (research-prep): roda antes desta skill quando o tópico a documentar requer pesquisa externa (tecnologia nova, comparativo de abordagens, ADR baseado em evidência). Passar
memory/research/<slug>.mdcomo fonte de verdade para a documentação.
Related Skills
felvieira/41-blog-publisher
development
VerifiedTrustedCommunity
Skill compositora que pega texto/assunto e gera post de blog HTML completo no repo {blog_repo_path} ({github_user_repo_url}), com imagens (via skill 17 fal.ai ou skill 42 Playwright screenshot), commit+push automático, retorna URL pública via GitHub Pages. Trigger em: "post no blog", "publicar post", "escrever post", "blog post", "publish blog", "gera post", "criar post", "novo post no meu blog".
19SKILL.mdUpdated May 25, 2026
felvieira/context-budget
tools
VerifiedTrustedCommunity
Audita o peso de contexto carregado na sessão — CLAUDE.md, agents, MCP descriptions, rules ativas, skills invocadas e histórico acumulado. Estima tokens por componente, reporta headroom disponível e emite alertas de overflow. Distinto do cost-tracker (skill 30) que rastreia tokens gastos em completions runtime. Trigger em: "contexto inchado", "context overflow", "quanto contexto estou usando", "peso do contexto", "context budget", "tokens carregados", "sessao lenta", "respostas degradadas", "headroom de contexto", "custo fixo de contexto", "overhead de rules", "overhead dos agents", "impacto do MCP no contexto", "espaco no context window", "quanto cabe no context window"
18SKILL.mdUpdated May 29, 2026
felvieira/research-prep
development
VerifiedTrustedCommunity
Coleta e organiza informacao tecnica multi-fonte antes de escrever docs, PRDs, ADRs ou artigos. Busca em: docs oficiais, GitHub (repos + issues), Stack Overflow, papers e blogs de referencia. Ranqueia fontes por autoridade (oficial 40% + recencia 30% + profundidade 20% + comunidade 10%). Output: memory/research/<slug>.md pronto para alimentar skill 10 (documenter), skill 01 (po-feature-spec), skill 26 (prompt-engineer) ou skill 41 (blog-publisher). Trigger em: "pesquisa tecnica", "levanta informacao", "coleta docs", "busca referencias", "preciso de fontes", "research antes de escrever", "levanta o que existe sobre", "benchmark de solucoes", "o que existe sobre X", "quero entender o estado da arte", "compara abordagens", "levanta referencias", "faz um research de", "coleta fontes sobre", "pesquisa sobre", "quero saber o que existe de", "monta um dossie tecnico", "background tecnico", "due diligence tecnica", "levantamento de alternativas".
18SKILL.mdUpdated May 29, 2026
felvieira/pattern-conformity
development
VerifiedTrustedCommunity
Extrai e codifica os padroes de coding do projeto existente (naming, estrutura de arquivos, error handling, testing style, import style, API design, async patterns) e usa esses padroes como restricao sobre novo codigo. Garante que o agente code "igual ao resto do projeto" em vez de inventar convencoes proprias. Produce um "code style map" salvo em memory/patterns.md que todas as skills de geracao de codigo devem consultar. Trigger em: "segue o padrao do projeto", "coda igual ao resto", "nao reinventa padrao", "detecta padroes do codebase", "code style do projeto", "padrao do projeto", "convencao do projeto", "coda consistente", "mesma convencao", "sem reinventar roda", "padrao de codigo", "patterns do codebase", "pattern enforcement", "conformidade de padrao", "convencoes de naming", "padrao de tratamento de erro", "mesma estrutura do projeto", "detecta as convencoes", "extrai padroes de coding", "como o projeto estrutura".
18SKILL.mdUpdated May 29, 2026