Sistema de Documentação Auto-Mantida Usando Blocos Delimitados para Deriva Zero

Um desenvolvedor no r/ClaudeAI compartilhou uma solução para manter a documentação precisa em espaços de trabalho com múltiplos projetos, onde agentes de IA de codificação como o Claude Code esquecem o contexto entre sessões. O sistema aborda problemas com 8 projetos, 20 funções Lambda, 42 chaves de API, 12 endpoints de API e 19 variáveis de ambiente, onde o agente adivinharia nomes de funções, editaria arquivos errados e perderia o contexto.

O Sistema de Delimitação

Em vez de pedir ao Claude para atualizar a documentação após a implementação, o desenvolvedor criou um script bash de 740 linhas que extrai dados estruturados diretamente dos arquivos-fonte e os injeta no CLAUDE.md por meio de blocos de comentários HTML delimitados. Cada CLAUDE.md tem delimitações que marcam seções geradas automaticamente:

## Funções Serverless <!-- auto:lambdas generated="2026-03-26" source="infrastructure/lib/api-stack.ts" -->
| Função | Rota | Memória | Timeout |
|----------|-------|--------|---------|
| quote-save | /quotes/save | 256MB | 15s |
| quote-get | /quotes/get | 256MB | 15s |
...20 linhas extraídas da configuração CDK...
<!-- /auto:lambdas -->

## Arquitetura <-- escrita manualmente, nunca tocada pelo script

Como Funciona

O script:

• Analisa os arquivos-fonte reais (CDK TypeScript, FastAPI Python, package.json, etc.)
• Extrai dados estruturados (nomes de funções, rotas, variáveis de ambiente, versões de dependências)
• Substitui tudo entre as delimitações
• Atualiza a data de geração para mostrar atualização
• Valida: verifica se cada nome de Lambda tem um arquivo de manipulador correspondente, se cada variável de ambiente existe no .env

Seções escritas manualmente (descrições de arquitetura, problemas conhecidos, contexto de lógica de negócios) ficam fora das delimitações e nunca são tocadas.

Conteúdo Gerado Automaticamente

• Ferramenta de citação (20 Lambdas): Inventário de Lambdas, stacks CDK, variáveis de ambiente, contagens de testes, dependências do CDK TypeScript e package.json
• Painel de vendas (12 endpoints): Rotas de API, lista de temas, dependências de decoradores FastAPI, tipos TypeScript e requirements.txt
• Análise de dados (42 Usuários): Dados do usuário, dependências do arquivo de credenciais Python e requirements.txt
• 5 outros projetos: Versões de dependências de package.json/requirements.txt

Sistema de Aviso de Desatualização

Um hook de sincronização de documentos (acionado após cada edição de código) verifica a data de geração em cada delimitação. Se alguma seção tiver mais de 7 dias:

Aviso: 3 seções geradas automaticamente em agent-quoting-tool/CLAUDE.md estão desatualizadas (mais antiga: 2026-03-19).
Execute: ./scripts/generate-inventory.sh quoting

Isso não é bloqueante — avisa, mas nunca impede você de trabalhar. A verificação de desatualização roda junto com hooks existentes na mesma janela de limitação de 10 minutos, sem sobrecarga adicional.

Detalhes de Implementação

A configuração usa bash puro com grep/sed/awk/jq, sem dependências. Comandos:

scripts/generate-inventory.sh all # Atualiza tudo
scripts/generate-inventory.sh quoting # Apenas um projeto

O script faz backup de cada CLAUDE.md primeiro (um backup por dia, por projeto). O desenvolvedor observa para não analisar ASTs a partir do bash — seu analisador TypeScript é um loop grep/sed linha por linha que funciona para arquivos controlados, mas seria frágil para TypeScript arbitrário.

Principais Insights

As delimitações permitem que conteúdo gerado automaticamente e escrito manualmente coexistam no mesmo arquivo. O Claude lê todo o CLAUDE.md no início da sessão e obtém ambos: dados extraídos precisos E contexto humano que ele não pode inferir do código. O desenvolvedor recomenda começar com as extrações de maior valor (inventários de Lambda e tabelas de variáveis de ambiente que causam bugs quando divergem) e observa que o aviso de desatualização é mais valioso do que a execução automática.

Todo o sistema levou cerca de 3 horas para ser construído (design, implementação, testes, primeira execução).