sync-project-docs
Audita e atualiza os arquivos de contexto do projeto do Claude Code. Autônomo para CLAUDE.md, skills e memória; sugere alterações nas configurações, pois estas exigem autorização explícita do usuário.
Fase 1 — Orientação
Se o projeto usar git:
git log --oneline -20
git status --short
Em seguida, git diff HEAD~5 -- <arquivos chave abaixo> para ver alterações recentes na infraestrutura.
Se não houver repositório git, leia a estrutura de diretórios e os arquivos chave diretamente.
Descubra quais destes existem:
| Procure por | Exemplos |
|---|---|
| Configuração de pacotes/dependências | package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, requirements.txt, Gemfile |
| Comandos | Makefile, justfile, scripts/, scripts do package.json, taskfile.yml |
| Infraestrutura | docker-compose.yml, fly.toml, render.yaml, Procfile, vercel.json, k8s/ |
| Configuração do app | config.*, settings.*, config/, application.yml |
| Template de env | .env.example, .env.template, .env.sample |
Objetivo: saber o que foi feito, o que está em andamento e quais arquivos chave foram alterados.
Fase 2 — Auditar e atualizar CLAUDE.md
Verifique todos os arquivos de instrução do projeto:
ls CLAUDE.md .claude/CLAUDE.md CLAUDE.local.md .claude/rules/ 2>/dev/null
Se CLAUDE.md não existir: invoque a skill init em sub-skills/init/SKILL.md e continue.
Se CLAUDE.md existir, leia-o e verifique cada seção em relação às fontes da Fase 1:
Comandos — compare com a fonte real de comandos. Corrija comandos alterados, adicione novos úteis, remova os deletados.
Arquitetura/estrutura — compare módulos descritos e arquivos chave com o que existe no disco. Adicione novas adições; remova coisas deletadas ou renomeadas.
Configuração/variáveis de ambiente — compare com os arquivos de configuração reais. Adicione novas configurações relevantes em tempo de execução; remova ou corrija as desatualizadas.
Restrições e pegadinhas — verifique se alguma restrição documentada foi resolvida pelo trabalho recente.
Template de env: verifique se ele lista todas as variáveis que a configuração exige. Variáveis ausentes aqui quebram configurações novas.
Referências @import: procure por linhas @path/to/file e verifique se cada arquivo importado ainda existe. Uma importação ausente quebra silenciosamente o carregamento do contexto.
Tamanho: se o arquivo exceder 200 linhas, sinalize — acima disso, a adesão diminui e o custo de contexto aumenta. Sugira mover detalhes para arquivos de tópicos em .claude/rules/.
.claude/rules/: se este diretório existir, verifique se algum arquivo de regras com escopo de caminho referencia comandos, nomes de módulos ou caminhos de arquivo que não correspondem mais à base de código atual. Corrija ou sinalize os desatualizados.
CLAUDE.local.md: se existir, aplique a mesma verificação do CLAUDE.md — é o suplemento pessoal ignorado pelo git e também pode ficar desatualizado.
Seja cirúrgico: atualize o que está desatualizado, deixe o conteúdo preciso em paz. Será lido por uma futura sessão do Claude.
Fase 3 — Auditar skills do projeto
ls .claude/skills/ 2>/dev/null
Leia cada skill. Duas categorias:
Skills acopladas à infraestrutura (executar, implantar, migrar, CI, integração) referenciam coisas concretas — comandos, serviços, portas, variáveis de ambiente, caminhos de arquivo. Verifique cada uma em relação à Fase 1:
- Os comandos referenciados ainda existem?
- Os nomes de serviço, portas e URLs ainda correspondem?
- As variáveis de ambiente ainda existem na configuração?
- Os caminhos de arquivo e nomes de módulos ainda são válidos?
Corrija pequenas divergências diretamente. Para uma reformulação substancial de uma skill de execução/inicialização (nova sequência de inicialização, grandes mudanças de serviço), pergunte primeiro:
"A skill de execução parece significativamente desatualizada. Regenerar do zero com
/run-skill-generator(pode perder pegadinhas personalizadas) ou reescrever seções desatualizadas manualmente?"
Se nenhuma skill de execução existir e a inicialização não for trivial: sugira /run-skill-generator se disponível, ou /run como fallback.
Skills de processo/workflow (templates de PR, estilo de commit): verifique apenas se o log do git sugerir que o processo descrito mudou; caso contrário, deixe como está.
Fase 4 — Memória
O caminho da memória é derivado da raiz do repositório git (ou pwd fora de um repositório):
REPO=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
echo "$HOME/.claude/projects/$(echo "$REPO" | sed 's|/|-|g')/memory/"
Se a memória existir: invoque consolidate-memory.
Se nenhuma existir: pergunte antes de criar algo —
"Nenhuma memória de projeto existe ainda. A memória automática já está ativa, então o Claude vai construí-la ao longo do tempo — mas quer que eu a popule agora com fatos chave desta base de código para que sua próxima sessão comece orientada imediatamente?"
Se sim: popule com fatos não óbvios que uma sessão futura perderia tempo redescobrindo:
- Restrições surpreendentes (modelos de concorrência, versões fixadas, padrões inesperados)
- Trabalho em andamento atual e por quê
- Decisões não óbvias embutidas no código
Crie MEMORY.md como um índice conciso de uma linha por entrada. Notas detalhadas vão em arquivos de tópicos separados (ex.: architecture.md, constraints.md) — MEMORY.md fica abaixo de 200 linhas para caber na janela de contexto da sessão.
Fase 5 — Configurações
Verifique .claude/settings.json em busca de hooks desatualizados que referenciam scripts ou comandos que não existem mais.
Identifique comandos somente leitura que aparecem constantemente (executores de teste, linters, verificações de saúde, git log, git diff) e que seriam seguros de permitir sem solicitação.
Não escreva em settings.json — apresente-os como sugestões. Aponte para:
update-config: para adicionar permissões, variáveis de ambiente ou corrigir hooksfewer-permission-prompts: para descobrir permissões a partir do histórico real de transcrições
Fase 6 — Compactar
Todas as descobertas agora estão no disco. Antes de finalizar, lembre o usuário de lidar com o contexto executando o comando /compact para começar a partir de um estado novo.
Resumo
Imprima um resumo das alterações:
## Sincronização do projeto concluída
**CLAUDE.md**: <o que mudou, ou "nenhuma alteração necessária">
**Skills**: <o que foi atualizado, ou "precisas">
**Memória**: <consolidada / populada / "nenhuma alteração">
**Sugestões de configuração**: <permissões sugeridas, ou "nada a adicionar">
**Estado do git**: <arquivos não comitados + trabalho em andamento, uma frase>
Execute `git diff` para revisar as alterações nos arquivos.