O Claude Code escreve o código. O mapa do ambiente fica contigo

Em agosto, este site passou horas a mostrar duas peças antigas, em português, em vez de todas. A causa foi uma alteração de uma linha. Pedi ao Claude Code para corrigir o nome da base de dados num ficheiro de configuração, e ele fê-lo em segundos, sem erros.

O que nenhum de nós verificou foi a forma como a plataforma de alojamento lê esse ficheiro.

O que aconteceu, exatamente?

O site corre no Render, uma plataforma que permite descrever a infraestrutura inteira num único ficheiro, a que chama Blueprint. O servidor, a base de dados e as definições ficam escritos em texto, e a plataforma ajusta o que existe ao que o ficheiro diz. No meu caso, um nome novo para a base de dados foi lido como uma base de dados nova. A plataforma criou-a vazia, apontou o site para ela, e o site passou a mostrar o conteúdo de uma cópia de segurança antiga.

A base original esteve intacta o tempo todo. Repor o site foi colar o endereço dela, outra vez, na configuração do serviço. Saber que era isso que faltava exigiu perceber como as peças se ligam. (A cópia de segurança fez o que devia, e por isso mesmo o erro demorou a ver-se: o site continuou de pé, só que mais pobre.)

O que é que a AI tornou fácil?

Quase tudo o que se escreve. Comecei a programar em Python em fevereiro deste ano, e hoje este site tem uma interface de programação (API) por onde um agente publica rascunhos, um assistente que responde a perguntas sobre o que aqui está publicado e um processo de publicação em duas línguas. Com o Claude Code, isto fez-se em oito meses, por uma pessoa só. O ganho é real, e qualquer pessoa com paciência para ler o que a AI escreve consegue hoje construir coisas que há dois anos pediam uma equipa.

O que a AI escreve depressa, porém, corre dentro de um ambiente que ela só conhece pelo que lhe dizes.

O que é o mapa do ambiente?

É saber, em cada momento, quatro coisas sobre o sistema em que estás a mexer:

• Onde vivem os dados. O ROMEO, o assistente deste site, tem uma base de dados própria, separada da do site, e cada uma tem o seu endereço.
• O que cada alteração toca. Num ficheiro de configuração, um nome pode ser só um nome ou pode ser a identidade de um recurso inteiro.
• O que acontece quando algo falha. O disco do servidor é temporário e perde-se a cada nova versão do site, por isso há comandos que só correm no meu portátil e nunca na consola do servidor.
• Quem chega a quê. A interface por onde o agente publica só cria rascunhos, e o assistente lê o site com uma chave que só permite ler. É o princípio do menor privilégio, que expliquei com mais calma em Porque é que o modelo precisa deste dado?

Nenhuma destas quatro coisas se escreve em código. São decisões sobre o sítio onde o código vai correr, e é aí que um erro pequeno fica caro.

Que perguntas fazer à AI antes de mexer num servidor?

Não precisas de ser programador para ter este mapa. Precisas de o pedir. Antes de qualquer alteração que toque num servidor, numa base de dados ou em credenciais, faz três perguntas:

1. O que mais é afetado por esta alteração?
2. Qual é o pior que pode acontecer?
3. Como é que a desfaço?

A AI responde bem a todas. Raramente as faz por iniciativa própria.

Depois, guarda as respostas que importam num ficheiro que a AI lê sempre que começa a trabalhar. No Claude Code esse ficheiro chama-se CLAUDE.md, e é lá que este site guarda regras como "este comando nunca corre na consola do servidor". O mapa deixa de viver só na tua cabeça. Uma nota honesta: a própria Anthropic avisa que o CLAUDE.md funciona como contexto e não como regra imposta. Para impedir uma ação de vez, existem os hooks, pequenos programas que correm antes de cada ação e a podem bloquear.

Qual é a pergunta que gostavas de ter feito antes de uma alteração correr mal?