jimweller/documenter-plugin

Criação de Documentação

Escreva conteúdo markdown com base no contexto atual da conversa e no conteúdo da pasta.

README é a especificação do estado atual para um usuário humano, não é um changelog, 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 ela está no momento da escrita do README.

Escopo

Encontre todos os arquivos README.md no projeto e atualize cada um. O conteúdo das pastas está no nível do README e abaixo (irmãos e subpastas), nunca acima (pastas pai). Preste atenção às camadas de subpastas, escopo e contextos delimitados. Não vaze conceitos entre documentos em camadas diferentes. Cada README cobre seu próprio nível de diretório e abaixo, nunca preocupações de diretórios pai.

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

Coletar Contexto

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

Comece com o plano. Ele encontra cada README, adiciona um README raiz quando nenhum existe, resolve a linha de base de cada README, lista o que mudou desde ela e informa o que fazer com cada README. Quando a orientação do usuário nomeia diretórios para focar, passe-os após readme. Caso contrário, não passe nada.

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

O plano imprime um bloco por ação.

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

head none significa que o repositório não tem commits. Cada README é novo.

Para um bloco de atualização, conte os arquivos em seu stat. Com mais de 20, pule o diff completo e leia os arquivos alterados diretamente. Com 20 ou menos, leia o diff. Arquivos não rastreados, marcados ??, 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 README a ser atualizado ou escrito, com escopo em seu diretório:

1. Leia o README atual (se existir)

2. Explore o código naquele nível de diretório e abaixo

3. Revise o histórico da conversa em busca de decisões, alterações ou lições aprendidas relevantes

4. Use as alterações e o contexto da conversa para identificar quais seções precisam de atualização. Verifique o código em relação à documentação e a documentação em relação ao código. Quando o código remove uma função, flag ou módulo, faça grep em cada README pelo seu nome, então releia cada ocorrência e a visão geral de cada README em busca de uma descrição em linguagem simples da mesma coisa.

   grep -rn '<nome removido>' <dir>/README.md
   

Nunca inclua a linha de marcador no texto que você escreve ou edita. finish a adiciona após escrever. Ao editar um README que já termina com uma, deixe essa linha em paz.

Se nada mudou que justifique uma atualização do README, diga isso e siga em frente. finish ainda se aplica.

Estrutura do README.md

Ordem das seções e conteúdo para um README.md. Cada seção é preenchida a partir do projeto alvo. Omita uma seção para a qual o projeto não tem nada.

• # Título e uma visão geral de no máximo cinco frases
• Imagem ou vídeo opcional
• ## Arquitetura - componentes como uma lista de marcadores, cada um com sua finalidade
• ## Pré-requisitos - contas, chaves, credenciais, ferramentas, runtimes, CLIs, cada um com o motivo pelo qual é necessário
• ## Estrutura do Projeto - apenas pastas, sem arquivos, cada uma com uma finalidade de uma linha
• ## Instalação - os comandos que o instalam
• ## Uso - os comandos que o executam
• ## Testes - omitido quando o projeto não tem testes

Mire abaixo de 500 linhas. Divida um README mais longo movendo detalhes para um README aninhado junto ao código que descreve.

Forma

# Título

Breve visão geral. No máximo cinco frases.

<!-- IMAGEM OU VÍDEO OPCIONAL DE DESTAQUE -->
<img src="demo.png" alt="Demo" width="800"/>

## Arquitetura

Componentes de alto nível e finalidade

- Componente - finalidade
- Componente - finalidade

## Pré-requisitos

- Pré-requisito - descrição e motivo (contas, chaves, credenciais, ferramentas, runtimes, CLIs)

## Estrutura do Projeto

Mostre a estrutura de pastas. Não inclua arquivos.

```text
projeto/
├── src/
│   ├── componente-a/     # finalidade - veja src/componente-a/README.md
│   └── componente-b/     # finalidade - veja src/componente-b/README.md
├── scripts/             # finalidade
└── testes/               # finalidade
```

## Instalação

```bash
# como o projeto é instalado
<comando de instalação>
```

## Uso

```bash
# como o projeto é executado
<comando de execução>
```

## Testes

```bash
# como os testes são executados
<comando de teste>
```

Finalizar

Execute finish, toda vez, 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 readme

Ele carimba cada README que o plano marcou como novo ou atualização, e cada README criado desde o plano, com o HEAD que o plano verificou. O carimbo é uma linha de marcador no final do README, um comentário HTML nomeando aquele commit. finish deixa READMEs inalterados e READMEs fora do foco em paz, e não carimba nada quando o repositório não tem commits. Saída 4 significa que um README 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.