Como começar um projeto com Claude Code sem perder o controlo

Podes descrever uma aplicação em linguagem natural e receber uma primeira versão rapidamente. A parte que exige mais atenção aparece quando começas a acrescentar pedidos, corrigir detalhes e ligar serviços. Sem um método, torna-se difícil perceber qual a versão que funciona, que decisões continuam válidas e o que falta confirmar.

Este guia acompanha um exemplo fictício: uma pequena ferramenta interna para organizar pedidos de conteúdo de uma equipa. A primeira versão permite criar um pedido com título, responsável e estado, e consultar uma lista. Não vamos assumir integrações, contas de utilizador ou publicação automática antes de definir o que cada uma dessas partes exige.

O objetivo é conseguires orientar o trabalho e reconhecer uma entrega verificável. Não precisas de escrever todas as linhas de código para descrever o comportamento esperado, mas vais precisar de observar o resultado e compreender as decisões que afetam o teu uso. É essa capacidade de avaliação que deves desenvolver desde o primeiro projeto.

Escolhe um primeiro resultado que consigas observar

Começa por um percurso pequeno que represente uma necessidade real e que possas testar do início ao fim. Descreve quem o usa, o que introduz e o que espera receber. Define também o que fica para depois, para que a primeira versão tenha um critério de conclusão compreensível.

Na ferramenta de pedidos de conteúdo, o primeiro percurso pode ser criar um pedido e vê-lo aparecer na lista com os campos certos. Isso permite testar a entrada, a apresentação e o estado inicial. Um pedido como «cria uma plataforma completa de gestão da equipa» deixaria por decidir demasiadas funções e relações para conseguires avaliar a primeira entrega.

Escreve dois ou três exemplos concretos. Um pedido com título e responsável deve poder ser criado; um pedido sem título deve mostrar uma indicação útil; um pedido concluído deve continuar identificável com o estado correto. Os exemplos ajudam a transformar uma ideia numa sequência de comportamentos que consegues conferir no ecrã.

Decide se estás a construir um protótipo ou uma ferramenta que vai guardar trabalho real. Um protótipo pode usar dados fictícios e ter limites explícitos, como perder os registos quando a página é recarregada. Uma ferramenta operacional precisa de uma decisão sobre persistência e recuperação. Essa diferença deve aparecer no pedido e na descrição da entrega.

Podes começar com um protótipo, desde que saibas o que ele demonstra. Ver um cartão aparecer depois de carregar num botão confirma parte da interação, mas não demonstra que os dados ficam guardados para amanhã. O critério de conclusão deve dizer o que estás a testar e o que continua pendente.

Se ainda não consegues descrever este percurso, prepara primeiro o briefing da aplicação que vais construir com IA. Esse trabalho reduz as decisões que o agente teria de adivinhar. Depois podes usar o briefing como referência e concentrar a conversa na primeira implementação.

Prepara a pasta, o acesso e o ambiente de trabalho

Usa uma pasta dedicada ao projeto e confirma onde vão ficar os ficheiros, onde serão executados os comandos e que conta dá acesso ao serviço. Se já existe código, preserva o estado inicial antes de alterar. Mantém os dados de teste separados de informação real que não seja necessária ao exercício.

Uma pasta dedicada facilita reconhecer o que pertence ao projeto. Evita começar dentro de uma diretoria com documentos de vários clientes ou trabalhos sem relação, porque isso aumenta a possibilidade de misturar contexto e ficheiros. Dá um nome claro ao projeto e confirma esse caminho quando abres o terminal ou o editor.

O guia oficial de arranque do Claude Code descreve a instalação, a autenticação e o início de uma sessão na pasta escolhida. Depois de instalado, o comando `claude --version` permite confirmar a versão e `claude` inicia uma sessão no terminal. Segue as instruções atuais para o teu sistema, em vez de copiar um comando antigo sem verificar a origem.

Confirma a modalidade de acesso que estás a usar antes de começar. Uma subscrição e uma conta de utilização por API são percursos distintos, com condições próprias. Para este exercício, usa o acesso que já tens e verifica se satisfaz a tarefa; não precisas de contratar várias ferramentas apenas para acompanhar o método.

Também deves distinguir o local dos ficheiros do local onde o modelo é executado. Trabalhar numa pasta do teu computador não significa, por si só, que toda a operação acontece sem rede. Identifica os serviços envolvidos e utiliza apenas dados que podes tratar nesse ambiente, sobretudo quando passares dos exemplos fictícios para um projeto de cliente.

Se o projeto já existe, pede uma descrição do estado antes de qualquer modificação. Confirma se há alterações por guardar e quem as fez, para não substituir trabalho que ainda não foi registado. Um ponto de partida conhecido ajuda-te a comparar o que o agente acrescentou e a recuperar quando uma experiência não resultar.

Pede uma leitura do projeto antes de implementar

Solicita que o agente identifique os ficheiros relevantes, as instruções existentes e a forma de executar a aplicação antes de propor alterações. Pede que distinga o que encontrou do que está a inferir. Usa essa leitura para confirmar o âmbito do trabalho e resolver apenas as dúvidas que afetam a primeira entrega.

Num projeto novo, a leitura pode começar pelo briefing e pelas referências que preparaste. Num projeto existente, deve incluir a estrutura atual e os componentes que já resolvem partes da tarefa. A intenção é aproveitar o contexto disponível e evitar reconstruir algo apenas porque não foi mencionado na última mensagem.

Um pedido inicial possível seria: «Lê o briefing e os ficheiros deste projeto. Explica como posso executar a versão atual, identifica onde será implementado o formulário de pedidos e propõe o menor conjunto de alterações para testar o percurso definido. Assinala as decisões que ainda não têm informação suficiente.» A proposta deve estar ligada a ficheiros e comportamentos concretos.

Não precisas de exigir um plano longo para uma alteração pequena. Se a tarefa for corrigir o texto de um botão, uma explicação curta pode chegar. Quando envolve dados, integrações ou mudanças em vários percursos, a leitura inicial deve ser mais cuidadosa. O esforço de preparação deve acompanhar o efeito da alteração.

Define também a autonomia pretendida. Podes autorizar a implementação e a verificação local de uma funcionalidade, reservando a publicação para uma fase posterior, ou autorizar o percurso completo num projeto já preparado. O importante é que o âmbito seja claro e que autorizações já dadas não se percam no meio da conversa.

O Claude Code disponibiliza modos e regras de permissão para controlar ações e acessos. Consulta a documentação oficial de permissões para compreender a configuração do teu ambiente. Uma instrução em linguagem natural ajuda a orientar o trabalho, mas deve ser coerente com os acessos técnicos que realmente concedeste.

Guarda as decisões que não queres repetir

Regista em ficheiros curtos o objetivo, as regras do projeto, os comandos úteis e as decisões já tomadas. Mantém o estado do trabalho separado das instruções permanentes. Ao retomar, pede que esses documentos sejam comparados com os ficheiros atuais, para evitar continuar a partir de uma descrição antiga ou incompleta.

Na ferramenta fictícia, uma decisão permanente pode ser usar os estados «por fazer», «em curso» e «concluído». O estado da tarefa atual pode ser «formulário criado; falta verificar a edição do responsável». São informações diferentes: a primeira orienta futuras alterações, enquanto a segunda precisa de ser atualizada quando o trabalho avança.

O ficheiro `CLAUDE.md` é uma das formas documentadas de fornecer instruções de projeto ao Claude Code. A documentação sobre memória e contexto explica o seu papel e distingue essas instruções da memória automática. Trata o ficheiro como contexto a manter e verificar, sem assumir que uma regra escrita constitui um bloqueio técnico infalível.

Inclui instruções concretas que alguém consiga aplicar. Por exemplo, «os estados disponíveis são estes três e o estado inicial é por fazer» esclarece uma decisão do produto. «Faz sempre tudo bem» não permite avaliar uma alteração. Comandos de execução e verificações existentes também ajudam a retomar o projeto sem reconstruir o procedimento a cada sessão.

Não transformes o documento numa cópia de toda a conversa. Guarda as decisões que continuam válidas e liga para detalhes quando necessário. Se uma escolha mudar, atualiza a instrução correspondente e regista brevemente o motivo, em vez de manter duas regras contraditórias à espera de que o agente perceba qual é a mais recente.

O guia para dar contexto de negócio ao Claude Code aprofunda esta organização. Para o primeiro projeto, começa com poucas regras úteis e um estado de retoma claro. A qualidade do contexto depende mais da relevância e da coerência do que da quantidade de texto acumulada.

Constrói uma versão pequena e observa o comportamento

Pede a implementação do percurso escolhido, com dados de teste e uma forma clara de abrir a aplicação. Observa o que acontece em cada ação antes de acrescentar funcionalidades. Compara o resultado com os exemplos definidos e regista as diferenças, incluindo situações em que o ecrã parece correto mas o comportamento está incompleto.

Na primeira versão, cria um pedido de conteúdo com título, responsável e estado inicial. Verifica se aparece na lista e se os valores correspondem ao que introduziste. Depois tenta criar um pedido sem título e observa a resposta. Estes passos já permitem discutir a experiência com base em ações concretas, sem depender de uma impressão geral sobre o aspeto.

Confirma o comportamento ao recarregar a página conforme o âmbito acordado. Se o protótipo foi definido sem persistência, essa limitação deve estar visível na entrega. Se a versão devia guardar os pedidos, perder os dados é uma falha a resolver antes de a utilizar com trabalho real. O mesmo ecrã pode representar níveis de conclusão muito diferentes.

Pede ao agente que explique o que está implementado, o que foi simulado e o que ainda falta. Um botão pode existir sem executar a ação final, e uma lista pode estar preenchida com exemplos fixos. Esses recursos podem ser úteis num protótipo visual, desde que não sejam confundidos com funções operacionais.

Mantém o primeiro ciclo centrado num objetivo. Se durante o teste surgirem ideias para notificações, relatórios e filtros avançados, regista-as para depois. Acrescentar tudo imediatamente torna mais difícil perceber se o percurso inicial ficou resolvido e aumenta o número de interações que tens de rever.

Quando o resultado pequeno estiver compreendido, escolhe a próxima melhoria pelo uso real. Pode ser editar o responsável, filtrar pedidos em curso ou guardar os registos de forma persistente. Cada passo deve ter um comportamento esperado e uma verificação adequada, permitindo construir sobre uma versão que já sabes avaliar.

Corrige com exemplos do esperado e do observado

Ao pedir uma correção, descreve a ação feita, o resultado observado e o comportamento que esperavas. Inclui o contexto necessário para reproduzir o problema e indica o que deve ser preservado. Depois confirma o percurso corrigido e as partes relacionadas, para garantir que a mudança resolveu a dificuldade sem criar outra.

«O formulário está mal» pode significar um problema visual, uma validação em falta ou dados que não são guardados. Um pedido mais útil seria: «Quando crio um pedido sem responsável, ele aparece na lista sem qualquer indicação; quero que o campo seja obrigatório antes de guardar.» Agora existe uma diferença concreta que pode orientar a alteração e o teste.

Se o comportamento depende do dispositivo, diz onde o observaste. Um botão que fica fora do ecrã num telemóvel exige uma verificação diferente de uma mensagem de erro incorreta no computador. Uma captura de ecrã pode ajudar a localizar a situação, mas deve ser acompanhada da ação que a provocou e do resultado pretendido.

Evita pedir uma reconstrução completa quando uma correção delimitada resolve o problema. A versão existente já contém decisões e comportamentos que podem estar certos. Pede ao agente para identificar a causa e alterar as partes necessárias, explicando o efeito esperado. Se a estrutura precisar mesmo de mudar, essa necessidade deve ser justificada pelo problema observado.

Depois da correção, repete o caso que falhava. Testa também um caso normal relacionado, como criar um pedido com todos os campos preenchidos. Uma validação nova não deve impedir o percurso válido que já funcionava. O conjunto de verificações deve acompanhar a mudança, sem se reduzir a observar que o código deixou de mostrar um erro.

Guarda feedback que revele uma decisão de produto. Se concluíste que o responsável é obrigatório, essa regra pertence às instruções do projeto e aos critérios de validação. Assim, uma alteração futura tem uma referência clara e não precisa de recuperar essa decisão no meio de uma conversa antiga.

Pede evidência de que a alteração funciona

Define verificações que correspondam ao comportamento pedido e pede que o agente mostre os resultados relevantes. Combina testes automáticos adequados com observação da aplicação quando existe interface. Distingue uma verificação concluída de outra que não foi possível executar, e não uses um teste estreito como prova de que todo o produto está pronto.

A Anthropic recomenda dar ao agente uma forma concreta de verificar o trabalho, como testes, compilação ou comparação visual. A documentação de boas práticas do Claude Code desenvolve esse princípio. No teu projeto, escolhe a verificação pelo que mudou: um teste de dados e uma captura de ecrã respondem a perguntas diferentes.

Para a ferramenta de pedidos, podes pedir evidência de que um título vazio é rejeitado, de que um pedido válido aparece com o estado inicial correto e de que a edição preserva os restantes campos. Se foi implementada persistência, acrescenta a verificação após recarregar ou reabrir a aplicação. Os critérios devem corresponder ao que a versão afirma fazer.

Um relatório de conclusão deve dizer o que foi testado e com que resultado, sem esconder limitações. «A compilação passou» é informação útil, mas não confirma por si só que uma pessoa consegue concluir o formulário no telemóvel. «O percurso foi testado com dados fictícios» também não prova que uma integração externa funciona com os acessos de produção.

Não é necessário criar uma grande bateria de testes para cada alteração de texto. Escolhe verificações proporcionais e preserva as que cobrem regras importantes, sobretudo quando há dados ou vários percursos dependentes. A finalidade é detetar erros relevantes e permitir mudanças futuras com mais confiança, sem transformar a verificação num exercício de quantidade.

Se o agente não conseguiu abrir o navegador ou executar um comando necessário, a entrega deve indicar essa lacuna. Podes resolver o acesso, usar outro método adequado ou fazer a verificação manual correspondente. O que não deves fazer é converter uma tentativa sem resultado numa afirmação de funcionamento confirmado.

Guarda versões e distingue o que foi publicado

Mantém versões identificáveis do projeto e confirma o que cada uma inclui antes de as enviar para um repositório ou ambiente público. Distingue guardar uma alteração, enviar código, criar uma pré-visualização e publicar em produção. Verifica a versão no endereço final e conserva informação suficiente para recuperar o estado anterior quando necessário.

No trabalho local, tens os ficheiros que estás a editar. Um registo de versão permite identificar um conjunto de alterações; enviá-lo para um repositório remoto guarda esse código noutro local autorizado. A aplicação só fica disponível para o público através do processo de publicação configurado. Em alguns projetos, enviar código pode acionar esse processo automaticamente, por isso confirma a configuração antes de o fazer.

Pede uma descrição simples do percurso existente. Deve indicar onde está o código, qual a versão preparada, que ambiente recebe a publicação e que endereço vais verificar. Isso evita confundir uma pré-visualização com a versão que a equipa já utiliza, ou assumir que o código enviado foi publicado com sucesso.

Antes de enviar ficheiros, confirma que segredos e dados privados não estão incluídos. As credenciais devem ficar nos mecanismos apropriados do ambiente, e os exemplos versionados devem usar valores fictícios. O objetivo é permitir reconstruir a aplicação sem transformar o repositório num local de exposição de acessos ou de informação desnecessária.

Guardar código também não substitui a cópia dos dados persistentes. Se a ferramenta já recebe pedidos reais, identifica onde ficam esses registos e como podem ser recuperados. Um projeto pode voltar a compilar depois de uma perda e continuar sem os dados que a equipa precisa para trabalhar. A recuperação deve considerar ambas as partes.

No primeiro exercício, podes terminar numa versão local verificada e preparar a publicação como passo seguinte. Quando autorizares a publicação, inclui a conferência do endereço final e dos percursos relevantes. A conclusão deve identificar o que está efetivamente disponível, em vez de tratar o envio do código como prova suficiente da entrega.

Retoma o projeto sem depender de uma conversa inteira

No fim de cada etapa, guarda o objetivo atual, as decisões tomadas, as verificações realizadas e a próxima ação concreta. Ao regressar, compara esse registo com o estado real dos ficheiros e da aplicação. Usa o contexto necessário à tarefa seguinte, preservando as restrições e evitando reabrir escolhas que já foram resolvidas.

Uma nota de retoma para o nosso exemplo pode dizer: «Criar e listar pedidos está verificado com dados fictícios; o responsável é obrigatório; falta implementar a persistência; a versão ainda não foi publicada.» Esta descrição permite continuar sem reler toda a conversa e sem confundir um protótipo funcional com uma ferramenta pronta para trabalho real.

Regista também uma dúvida que impeça o próximo passo. Se ainda não decidiste quem vai usar a aplicação e onde os dados devem ficar, essa decisão é relevante antes de escolher a solução de persistência. O guia para dar contexto de negócio ao Claude Code ajuda a explicar estas condições sem transformar o pedido numa lista desconexa de funcionalidades.

Quando mudares de sessão ou ferramenta, confirma que os documentos continuam corretos. Uma nota antiga pode dizer que um teste falta quando já foi realizado, ou afirmar que uma função existe depois de ter sido removida. Os ficheiros e o comportamento atual são a referência para decidir o próximo passo; o registo ajuda a encontrá-la.

Para começares hoje, escolhe uma pasta, escreve um percurso simples e define três situações que vais verificar. Pede a leitura do contexto, constrói a primeira versão e observa o resultado antes de aumentar o âmbito. No fim, deves conseguir explicar o que funciona, o que falta e onde está guardada a versão que acabaste de avaliar.

Como podes aprender isto no Laboratório da IA

No Laboratório da IA, podes aprender a orientar projetos com agentes, preparar contexto e melhorar aplicações a partir de comportamentos observados. As aulas semanais e os Zooms de acompanhamento semanais apoiam a aplicação a casos concretos. Leva uma necessidade clara e trabalha uma primeira versão que consigas testar e compreender.

O processo continua a ser útil quando mudam as ferramentas: definir o resultado, observar, corrigir, verificar e guardar decisões. É essa prática que te permite evoluir de uma primeira experiência para projetos com mais autonomia e critérios de entrega mais claros.