Desenvolvedor Python doma o Claude Code: uma configuração aberta contra regressões

Um desenvolvedor da CREATMAN passou várias semanas estudando a documentação, as discussões do Reddit e as configurações de outras pessoas para montar uma configuração do Claude Code com proteção real contra regressões. O resultado é um repositório aberto com arquivos prontos para uso imediato.

Um problema que todo mundo conhece

O Claude Code é poderoso, mas sem a configuração certa age com autonomia demais. Um cenário típico para o desenvolvedor solo:

• Você pede para adicionar autenticação, e o agente reescreve metade do projeto
• Você pede para corrigir uma função e recebe testes apagados e uma dependência que ninguém pediu
• Você monta um protótipo funcional em uma hora e gasta três desfazendo as "melhorias" do agente

Para quem trabalha sozinho, isso é duplamente crítico. Não há um engenheiro de QA para pegar regressões depois de cada prompt. Não há um revisor para notar os testes apagados. Cada alteração não planejada custa tempo gasto entendendo decisões alheias em vez de trabalhar no produto.

O autor toca a CREATMAN sem equipe e esbarrou justamente nisso: a IA ajuda a construir rápido, mas, sem controle, cria problemas novos com a mesma rapidez.

Do que a configuração é feita

Depois de várias semanas lendo documentação, discussões em fóruns e analisando configurações alheias, o autor chegou a cinco componentes principais. Todos estão no repositório claude-code-antiregression-setup e prontos para uso:

• CLAUDE.md: o arquivo-contrato principal, com o escopo da tarefa, proibições explícitas de decisões por conta própria e a exigência de descrever as mudanças previstas antes de executá-las
• Regras por diretório: restrições no nível das pastas, para que o agente não mexa no que não foi pedido de forma explícita
• Checklist obrigatório: antes de qualquer alteração, o agente descreve o plano, e o desenvolvedor aprova ou rejeita
• Hooks: scripts automáticos que rodam após cada ação do agente e verificam se ela corresponde à tarefa
• Templates de prompts: formatos de pedido prontos que eliminam a ambiguidade e reduzem o espaço para interpretação

O importante é que tudo está documentado. O repositório não foi feito para estudo, e sim para adoção rápida: clone, adapte ao seu projeto e use.

Por que um contrato funciona melhor que uma proibição

A ideia central é dar ao agente regras claras, e não apenas restringi-lo. O Claude Code lê o CLAUDE.md no início de cada sessão. Se lá estiver escrito de forma explícita "não mexa nos testes sem pedido", "altere apenas os arquivos indicados" ou "avise antes de adicionar uma dependência", o agente segue.

"Preciso que o agente de IA me ajude a entregar mais rápido, e não que

crie problemas novos", explica o autor.

Os hooks adicionam uma segunda camada. Pequenos scripts rodam após as alterações e verificam se o agente ultrapassou os limites. Se ultrapassou, as mudanças são marcadas para revisão em vez de entrar em silêncio na base de código.

Os templates de prompts resolvem outro problema. Um pedido vago dá ao agente espaço demais para interpretação, e é aí que começa a iniciativa por conta própria. Formatos prontos, com escopo, arquivos e resultado esperado indicados, reduzem muito esse espaço.

O CLAUDE.md não é apenas um README para o agente, mas um documento vivo do projeto. Nele ficam registradas as decisões de arquitetura, os módulos críticos e as convenções de nomenclatura. O agente usa o arquivo como contexto em cada pedido, o que deixa seu entendimento do projeto mais concreto e torna as "melhorias" aleatórias menos prováveis.

A configuração não está presa a uma stack específica. O autor trabalha com back-end em Python, mas os princípios valem para qualquer projeto em que seja preciso manter o agente dentro dos limites da tarefa.

O que isso significa

A imprevisibilidade é uma das principais barreiras para adotar agentes de IA no desenvolvimento solo. Configurações abertas como esta reduzem a barreira de entrada: você pega a estrutura, adapta ao projeto e ganha uma ferramenta controlável em vez de um assistente caótico. Quanto mais configurações assim surgirem em acesso aberto, mais prático será usar agentes de IA sem uma equipe de suporte.