jimweller/documenter-plugin

Atualizar Documentação do Projeto

Duas responsabilidades:

1. CLAUDE.md — visão geral concisa do projeto (sempre carregado)
2. .llmdocs/ — documentos detalhados por conceito (carregados sob demanda). Todos os arquivos aqui são documentos de design persistentes.

---

1. CLAUDE.md — O Mapa

Escopo

Encontre todos os diretórios CLAUDE.md e .llmdocs/ no projeto e atualize cada um. Preste atenção às camadas de subpastas, escopo e contextos delimitados. Não vaze conceitos entre documentos em diferentes camadas. Cada CLAUDE.md e .llmdocs/ cobre seu próprio nível de diretório e abaixo, nunca preocupações dos pais.

Se o usuário forneceu orientação específica ou áreas de foco, aplique esse contexto ao decidir quais documentos atualizar e o que enfatizar.

Coletar Contexto

Nunca execute git diretamente. O script base que acompanha este plugin cobre tudo que esta skill precisa do git. Execute cada comando a partir da raiz do repositório e escreva o caminho completo do script todas as vezes, porque variáveis de shell não persistem entre comandos.

Comece com o plano. Ele encontra cada CLAUDE.md e seu .llmdocs/, incluindo arquivos obrigatórios que ainda não existem, resolve a linha de base de cada documento, lista o que mudou desde ela e informa o que fazer com cada documento. Quando a orientação do usuário nomear diretórios para focar, passe-os após llmdocs. Caso contrário, não passe nada.

bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" plan llmdocs [<focus-dir>...]

O plano imprime um bloco por ação.

• ## update nomeia uma linha de base, um escopo e os documentos que a compartilham, seguido pelos commits, diff stat e status desde essa linha de base. Atualize esses documentos. Um documento que as alterações não afetam mantém seu conteúdo.
• ## new lista documentos a serem escritos a partir do código atual. Eles não precisam de histórico.
• ## unchanged e ## outside the focus listam documentos para deixar exatamente como estão.

head none significa que o repositório não tem commits. Todo documento é novo.

Para um bloco de atualização, conte os arquivos em seu stat. Acima de 20, pule o diff completo e leia os arquivos alterados diretamente. Com 20 ou menos, leia o diff. Arquivos não rastreados, marcados com ??, não aparecem em nenhum diff, então leia-os diretamente de qualquer forma. O escopo pode ser o escopo do bloco ou um único arquivo, porque é um pathspec do git.

bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" diff <sha> <scope>

Em seguida, para cada par CLAUDE.md/.llmdocs/ com documentos para atualizar ou escrever:

1. Leia o CLAUDE.md atual e todos os arquivos em .llmdocs/ (se existirem)
2. Explore o código base naquele nível de diretório e abaixo
3. Revise o histórico da conversa em busca de decisões, mudanças ou lições aprendidas relevantes
4. Use as alterações e o contexto da conversa para identificar o que mudou. llmdocs são especificação do estado atual, não um registro de alterações, não um registro de decisões, não um registro histórico. Nunca registre informações históricas ou escolhas feitas, apenas a especificação como está no momento da escrita dos llmdocs.

Escrever/Atualizar CLAUDE.md

Alvo: abaixo de 500 linhas. Cada linha deve ganhar seu lugar.

# <Nome>

<1-2 linhas de propósito deste diretório/componente>

## Stack

<lista com marcadores: linguagem, frameworks, dependências chave relevantes para este nível>

## Layout

<diretrórios chave e o que contêm neste nível>

## Comandos

<build, test, lint, deploy — apenas comandos>

## Convenções

<estilo, nomenclatura, padrões — apenas o que previne erros>

## Conceitos Chave

<termos de domínio, lógica de negócio que Claude precisa saber neste nível>

## LLM Docs

Documentos detalhados em `.llmdocs/`:

- @.llmdocs/architecture.md — <descrição de 1 linha>
- @.llmdocs/data-model.md — <descrição de 1 linha>

Regras do CLAUDE.md

• NENHUMA explicação verbosa — Claude infere
• NÃO duplicar conteúdo de .llmdocs/ — apenas referencie com descrição curta
• A seção ## LLM Docs DEVE listar todos os arquivos .llmdocs/ com uma descrição de 1 linha cada
• Um CLAUDE.md que lista seus arquivos .llmdocs/ sob ## Docs é anterior ao cabeçalho atual. Renomeie esse cabeçalho para ## LLM Docs sempre que atualizar o arquivo
• Preserve instruções personalizadas existentes (fluxo de trabalho git, variáveis de ambiente, etc.)
• Remova conteúdo apenas quando o código o contradizer, e nomeie cada remoção no resumo
• Quando o código abandonar uma função, flag ou módulo, use grep em todo documento deste nível em busca de seu nome, então releia cada ocorrência e a linha de propósito de cada documento em busca de uma descrição em linguagem simples da mesma coisa. Remover o nome de um documento não é suficiente

grep -rn '<nome abandonado>' <dir>/CLAUDE.md <dir>/.llmdocs

• Nunca inclua a linha de marcador em texto que você escreve ou edita. finish a adiciona após escrever. Ao editar um documento que já termina com uma, deixe essa linha em paz
• Use @.llmdocs/filename.md import se um documento deve ser sempre carregado

---

2. .llmdocs/ — O Território

Processo

Um arquivo de conceito além dos sete obrigatórios é seu para adicionar, e o plano nunca o nomeia. finish o carimba de qualquer forma, junto com todos os outros documentos deste nível criados durante a execução.

1. Avalie: use os blocos de atualização do plano para identificar quais documentos são afetados
2. Identifique: determine quais documentos existentes são afetados, ou se um novo documento é necessário
3. Atualize o CLAUDE.md: garanta que a seção ## LLM Docs liste quaisquer novos arquivos de documento

Se nada mudou que justifique atualizações de documentos, diga isso e prossiga.

Localização

Use o caminho que a primeira importação sob o cabeçalho ## LLM Docs do CLAUDE.md nomeia, ou sob ## Docs em um CLAUDE.md anterior a ele. Caso contrário, o padrão é .llmdocs/ no nível do diretório alvo. CLAUDE.md e .llmdocs/ podem existir em qualquer nível de diretório no projeto.

Estrutura

Plana, 1 arquivo por conceito. Os primeiros 7 arquivos são obrigatórios e devem sempre existir. testing.md é criado quando o projeto tem um conjunto de testes e omitido quando não tem. Arquivos de conceito adicionais são criados conforme necessário.

.llmdocs/
  architecture.md    # Componentes, interações, fluxo de dados (obrigatório)
  api.md             # Endpoints, requisição/resposta, autenticação, autorização (obrigatório)
  data-model.md      # Esquema, modelos, relacionamentos (obrigatório)
  deployment.md      # Processo de deploy, ambientes (obrigatório)
  ops.md             # Runbooks, manutenção, solução de problemas (obrigatório)
  observability.md   # Logs, métricas, traces, verificações de saúde, dashboards, alertas (obrigatório)
  security.md        # Limites de confiança, tratamento de segredos, authn/authz, modelo de ameaças (obrigatório)
  testing.md         # Layout de testes, runner, fixtures, como executar o conjunto (quando o projeto tem testes)
  <conceito>.md      # Específico de domínio conforme necessário

Formato do Arquivo de Documento

# <Conceito>

<propósito de 1 linha>

## <Seção>

<conteúdo: cabeçalhos, tabelas, blocos de código — sem parágrafos de prosa>

Regras do .llmdocs/

• Máximo de 500 linhas por arquivo — divida se maior
• Inclua caminhos de arquivo com referências de linha onde útil (src/auth/login.ts:42)
• Atualize documentos existentes de forma incremental, não reescreva do zero
• Se um documento está preciso e não foi afetado por mudanças recentes, deixe seu conteúdo em paz. finish ainda atualiza seu marcador.
• Precisão sobre cobertura: documente apenas o que é verificável a partir do código
• observability.md contém os sinais que o sistema emite, e ops.md contém as ações que um operador realiza. Um endpoint de saúde, um formato de log ou um alerta pertence a observability.md. Um projeto sem métricas ou traces ainda documenta seu stdout, stderr e códigos de saída lá
• Nunca inclua a linha de marcador em texto que você escreve ou edita. finish a adiciona após escrever. Um arquivo de conceito que você cria é a armadilha aqui, porque todo irmão que você acabou de ler termina com um. Copiar essa linha escreve um sha obsoleto alegando que o documento foi verificado contra um commit que nunca viu. Termine um novo arquivo em sua última linha de conteúdo e deixe finish adicionar o marcador

---

3. Finalizar

Execute finish, todas as vezes, incluindo uma execução que não escreveu nada. plan deixou um arquivo de plano para trás e apenas finish o remove, então uma execução que pula finish deixa estado para a próxima tropeçar.

bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" finish llmdocs

Ele carimba todo documento que o plano marcou como novo ou atualizado, e todo documento criado desde o plano, como testing.md, com o HEAD que o plano verificou. O carimbo é uma linha de marcador no final do documento, um comentário HTML nomeando aquele commit. finish deixa documentos inalterados e documentos fora do foco em paz, e não carimba nada quando o repositório não tem commits. Saída 4 significa que um documento planejado está faltando. Escreva-o e execute finish novamente.

• Nunca chame stamp diretamente e nunca escreva ou edite a linha de marcador manualmente. finish a escreve.
• O marcador é metadado. A regra contra registrar histórico não se aplica a ele.

---

4. Resumo da Saída

Após executar, gere este resumo. Preencha cada linha a partir da execução e escreva "nenhum" onde uma lista estiver vazia. Em Carimbados, copie as linhas do próprio finish textualmente, uma por documento. Nunca escreva um sha lá, e nunca adicione uma palavra que finish não imprimiu.

Uma frase reformulada para abandonar uma capacidade é uma remoção. Nomeie-a em Removidos com a redação que desapareceu, mesmo quando a mesma linha ainda existe.

Exemplo preenchido, de uma execução onde o código abandonou a contagem de caracteres.

Arquivos criados: nenhum
Arquivos modificados: CLAUDE.md, .llmdocs/api.md
Seções do CLAUDE.md adicionadas, atualizadas ou removidas: Conceitos Chave atualizados
Removido porque o código contradiz:
- CLAUDE.md: "ou caracteres" da linha de propósito, e o conceito chave --chars
- .llmdocs/api.md: a linha count_chars
Carimbados:
- stamped CLAUDE.md (marker)
- stamped .llmdocs/api.md (marker)

Quando as alterações não justificam atualização de documento, escreva "nenhuma alteração de documento necessária" acima do resumo.