🏗️ Projetos de Longo Prazo

A estrutura de pastas é o mapa físico do seu projeto. Ela determina como módulos se encontram, como dependências fluem e como novos colaboradores (ou o Claude) entendem o sistema sem ler linha de código.

Projetos sem estrutura viram monólitos caóticos em semanas. Uma pasta bem pensada desde o início economiza horas de refatoração depois. O Claude Code navega melhor em projetos organizados — contexto menor, respostas mais precisas.

Single Responsibility Principle aplicado a arquivos e módulos: cada peça do código tem uma razão para existir e uma razão para mudar.

Módulos coesos facilitam o Claude a entender, modificar e testar partes isoladas sem introduzir regressões. Menos acoplamento = iteração mais rápida.

Escolher linguagem, runtime, frameworks e ferramentas de build com base em critérios explícitos: ecossistema, performance, facilidade de deploy e suporte do Claude.

Trocar de stack no meio de um projeto é custoso. A escolha certa no início reduz dívida técnica e maximiza a ajuda que o Claude pode dar — ele conhece melhor stacks populares.

Architecture Decision Records (ADRs) são pequenos documentos que registram: o contexto da decisão, as opções consideradas e a escolha feita. O CLAUDE.md é o ADR principal.

Sem documentação de decisões, o Claude (e você no futuro) vai questionar por que certas escolhas foram feitas e pode desfazê-las inadvertidamente.

Estratégia de construir o núcleo funcional primeiro e adicionar camadas progressivamente — sem planejar uma arquitetura gigante antes de validar hipóteses.

Projetos com o Claude evoluem rápido. Começar pequeno permite validar o design antes de comprometer energia em abstrações que podem não ser necessárias.

Princípios que mantêm um projeto saudável por meses ou anos: code review assíncrono, documentação viva, automação de tarefas repetitivas e métricas de saúde.

A maioria dos projetos morre por falta de manutenção planejada, não por falta de features. Com o Claude, o risco é adicionar código rápido demais sem manter a base sólida.

O CLAUDE.md é o arquivo de instruções persistentes do projeto. É lido pelo Claude no início de cada sessão, fornecendo contexto sobre o projeto, convenções e regras de comportamento.

Sem CLAUDE.md, você repete o mesmo contexto em toda sessão. Com ele, o Claude sabe onde está, o que pode e não pode fazer, e como o projeto está estruturado.

O Claude não tem memória nativa entre sessões. Memória persistente é construída explicitamente: arquivos de estado, logs de decisões, contexto salvo em JSON ou Markdown.

Projetos longos acumulam decisões e estado. Sem memória explícita, cada sessão começa do zero e o Claude pode contradizer decisões anteriores.

Manter o CLAUDE.md conciso e relevante: incluir apenas o que o Claude precisa saber agora, não a história completa do projeto.

CLAUDE.md muito longo dilui a atenção. O Claude prioriza informações no início do contexto — informações críticas devem aparecer primeiro.

Seção do CLAUDE.md que define padrões de código, nomenclatura, fluxo de git, regras de PR e tom de comunicação que o Claude deve respeitar.

Sem convenções explícitas, o Claude adota seus próprios padrões — que podem divergir dos do time e criar inconsistências difíceis de manter.

Diretrizes sobre quais informações devem estar no CLAUDE.md (arquitetura, convenções, contexto) e o que nunca deve aparecer (secrets, tokens, dados pessoais).

CLAUDE.md é lido e potencialmente enviado para o modelo. Informações sensíveis nele criam riscos de vazamento — especialmente em projetos com múltiplos colaboradores.

Como manter o CLAUDE.md atualizado conforme o projeto cresce: quando revisar, quem pode editar e como versionar mudanças no arquivo de instruções.

Um CLAUDE.md desatualizado é pior que nenhum — o Claude segue instruções obsoletas e pode tomar decisões erradas baseado em contexto incorreto.

Semantic Versioning (semver): MAJOR.MINOR.PATCH — cada número tem significado preciso sobre o tipo de mudança e compatibilidade.

Versões semânticas comunicam impacto. Quando você pede ao Claude para "bump a version", ele precisa saber qual dígito incrementar e por quê.

Arquivo CHANGELOG.md estruturado por versão, com seções Added / Changed / Fixed / Removed. Lido por humanos, não por máquinas.

O CHANGELOG é o diário do projeto. Permite auditar quando algo quebrou, justificar mudanças para stakeholders e guiar o Claude em sessões de manutenção.

Estratégias para reverter o estado do projeto com segurança: git revert, git reset, feature flags, deploy de versão anterior.

Com o Claude gerando código rapidamente, a capacidade de rollback é o safety net. Você precisa saber desfazer sem perder trabalho válido.

Processo de melhorar a estrutura interna do código sem alterar seu comportamento externo — com testes como rede de segurança.

Refatorar com o Claude é rápido e arriscado. Sem testes, uma refatoração que parece segura pode quebrar fluxos que não estavam visíveis na sessão.

Testes bem escritos documentam o comportamento esperado do sistema. São a spec mais confiável porque precisam passar — ao contrário de docs que ficam obsoletas.

O Claude usa testes existentes para entender o que um módulo deve fazer antes de modificá-lo. Projetos com bons testes recebem ajuda melhor e mais segura.

Dívida técnica é o custo futuro de atalhos tomados hoje. Não é sempre ruim — mas precisa ser registrada, priorizada e paga antes de se tornar impagável.

Projetos com Claude podem acumular dívida técnica rapidamente — código gerado rápido nem sempre é sustentável. Monitorar e pagar dívida periodicamente é hábito de projeto saudável.

ClaudeOS (Hermes) é um dashboard pessoal read-only para quem roda um stack de IA local. Consolida dados de Claude Code, Codex, OpenRouter, Pinecone e Obsidian em uma interface única.

É um projeto concreto que aplica todos os princípios desta trilha: arquitetura em camadas, CLAUDE.md rigoroso, versionamento com CHANGELOG e separação de responsabilidades.

O arquivo scripts/aggregate.ts é o coração do sistema: lê ~/.claude/, vaults Obsidian, Pinecone e OpenRouter, depois gera src/data/live-data.json consumido pelo dashboard React.

Este padrão "script gerador → arquivo estático → UI" é uma arquitetura elegante que separa coleta de dados da apresentação. Replicável em qualquer projeto de dashboard.

A skill /dream audita as últimas 24h do stack de IA em 8 buckets de sinal e escreve as 4 prescrições de maior impacto em JSON. O dashboard renderiza essas prescrições como cards de ação.

É um exemplo de skill com output estruturado (JSON) consumido por uma UI — padrão reutilizável para qualquer integração Claude Code + dashboard.

O CLAUDE.md do ClaudeOS define: saudação de onboarding, regras críticas (nunca ler/escrever ~/.claude direto, dados locais, anonimização ligada, sem telemetria, dashboard read-only).

Este CLAUDE.md é um exemplo de nível produção. Mostra como usar restrições explícitas para proteger dados do usuário e manter o agente no seu papel.

O CHANGELOG do ClaudeOS narra a evolução do projeto: V2.3 (Documents Gallery, 31 mai 2026) mostra como cada feature foi adicionada, o que mudou e o que foi corrigido.

O CHANGELOG é evidência de projeto maduro. Cada versão conta a história da manutenção — e funciona como contexto para o Claude ao planejar próximas features.

Extração de padrões replicáveis do ClaudeOS: a separação scripts/src, o CLAUDE.md com restrições, o JSON como artefato de estado, o CHANGELOG como narrativa.

Estudar projetos reais bem estruturados acelera muito mais do que tutoriais abstratos. O ClaudeOS é um template mental para qualquer projeto de longa duração com Claude Code.