Transformando o Claude Code no melhor parceiro de design
(betweentheprompts.com)- Quando começou a usar o Claude Code, a abordagem era simplesmente iterar entre instruções no prompt e correções, mas em tarefas complexas surgiram problemas de dependência do histórico da conversa e limites de contexto
- Para resolver isso, passou a fazer com que fosse criado um documento de plano (plan document) antes da implementação da funcionalidade, usando-o como a única fonte de verdade (SSOT) em novas sessões
- O documento de plano inclui reformulação dos requisitos, explicação dos detalhes de implementação, comandos para verificar a qualidade do código etc., e continua sendo atualizado durante a implementação como um documento vivo (living document)
- Com isso, o problema de perda de contexto é resolvido, e mesmo em uma nova sessão é possível continuar o projeto usando apenas um único documento
- Como resultado, a IA deixa de ser apenas uma ferramenta de execução e passa a atuar como um parceiro colaborativo de design, levando o desenvolvedor a refletir e registrar melhor o projeto
Consciência do problema: os limites do modelo simples de conversa
- Ao trabalhar de forma conversacional com o Claude Code, ele é adequado para tarefas simples, mas à medida que tarefas complexas crescem, surgem várias limitações importantes
- A conversa se torna a única fonte de verdade, então novas mensagens podem facilmente sobrescrever instruções anteriores, e é difícil perceber claramente quando isso acontece
- Devido ao limite de tamanho de contexto da IA, conforme a conversa se alonga, informações anteriores podem ser perdidas
- Embora o Claude Code tenha um recurso de compressão da conversa, isso não elimina completamente essa limitação
Experimento com uma abordagem centrada em documento de plano
- Para resolver esse problema, foi testada uma abordagem baseada em documento de plano
- No início, pede-se ao Claude Code uma descrição tão detalhada quanto possível da funcionalidade a implementar ou do bug a corrigir
- Também são mencionados arquivos-fonte existentes que podem servir de referência ou documentos de plano escritos anteriormente
- Evitam-se instruções de implementação excessivamente específicas, incentivando o papel da IA em propor o design
- Quando o documento de plano fica suficientemente satisfatório, o histórico da conversa é apagado e um novo início é feito usando apenas esse plano como contexto
- O plano inclui resumo da funcionalidade, plano de implementação, código e pseudocódigo, comandos de tipo/lint/teste etc.
Processo de design colaborativo
- Quando o design proposto pela IA não agrada, fornece-se feedback específico para induzir uma abordagem revisada
- Durante a discussão, às vezes percebe-se que a primeira proposta da IA era mais adequada, o que se mostra mais eficiente do que avançar para a codificação apenas com um design próprio
- Uma conversa estruturada oferece uma experiência semelhante à de discutir um plano com um colega desenvolvedor
- A IA não costuma apresentar sozinha uma abordagem totalmente diferente, mas, quando questionada, também pode sugerir alternativas
Abordagem de documento vivo (Living Document)
- O documento de plano não é escrito uma vez e abandonado; ele continua sendo atualizado ao longo da implementação da funcionalidade
- Mudanças reveladas durante a implementação, verificação de tipos, lint e testes são refletidas em tempo real
- Forma-se o hábito de pedir uma checagem do estado mais recente do plano sempre que o código é commitado
- Como o plano mais atual é sempre mantido, em uma nova sessão basta anexá-lo para continuar exatamente de onde parou, sem perda de contexto
Revisão de código e mudança de hábitos de desenvolvimento
- Depois que a implementação começa, as mudanças são verificadas periodicamente e, quando o resultado é satisfatório, o trabalho da IA passa a merecer mais confiança
- Na revisão final do código, o documento de plano atualizado ajuda a entender a base das decisões técnicas
- Ao planejar e documentar cuidadosamente com antecedência, surge a experiência de se tornar um desenvolvedor melhor
- Como é preciso explicar para a IA, o próprio processo de tomada de decisão acaba sendo organizado com mais clareza
Do caos à organização
- Essa abordagem faz com que o documento de plano se torne a única fonte de verdade, resolva o problema de perda de contexto e estimule o pensamento arquitetural
- O documento de plano inclui tanto a especificação quanto o log de implementação, registrando não apenas o “o quê”, mas também o “por quê” e o “como”
- O resultado final é um processo de desenvolvimento planejado, bem documentado e confiável
- A IA se estabelece não como uma simples implementadora, mas como uma parceira colaborativa de design
2 comentários
Parece que, no fluxo de trabalho dos desenvolvedores, o peso dos papéis de PM e de arquiteto está ficando maior.
Comentários do Hacker News
Nas últimas duas semanas, fiquei totalmente focado nas noites em criar o “prompt perfeito” para concluir um projeto inteiro de uma vez usando o claude code. No fim, montei uma estrutura em que um único
CLAUDE.mdreferencia 8 arquivos Markdown diferentes, cobrindo arquitetura do projeto, especificação de modelos, ordem de build, camadas de teste, cenários etc. Esse projeto é para governança baseada em modelos no Databricks Unity Catalog; tenho bastante experiência na área, mas não acho as ferramentas existentes flexíveis o suficiente. No final, recebi apoio de 3 subagentes — especialista em Databricks, especialista em Pydantic e especialista em prompts — para trabalhar de fato nos arquivos de planejamento. Graças a isso, a qualidade dos arquivos Markdown melhorou muito em vários pontos, desde problemas com versões antigas do Pydantic até equívocos meus sobre o Unity Catalog. Ontem finalmente rodei tudo na prática, e, tirando algumas vezes em que precisei aprovar o uso de ferramentas, em 2 horas a maior parte das ferramentas e dos testes ficou pronta. Foi impressionante porque esse jeito de trabalhar é muito diferente do antigo; senti que há um futuro real em escrever documentação técnica com cuidado e alinhar todo mundo na mesma direção. Acho até que é mais produtivo do que ficar cavando no código diretamente. Por outro lado, quando estou mexendo em código entro mais fácil em estado de fluxo, enquanto lidar com vários documentos Markdown faz minha concentração se dispersar mais. Tempos realmente fascinantesDá para sentir que está surgindo um novo padrão, parecido com Test-Driven Development, que força você a projetar o sistema antes. Antes, eu ia desenhando o sistema aos poucos enquanto escrevia o código; agora, com desenvolvimento baseado em IA, você projeta e mapeia o domínio antes, e o código em si vira quase um trabalho de boilerplate para materializar o design. E a IA é realmente muito boa nesse boilerplate
Estou com exatamente o mesmo problema: sou mais produtivo, mas minha concentração fica mais espalhada. É estranho, mas por enquanto funciona. No longo prazo, acho que vou precisar encontrar uma solução. O método que melhor tem funcionado para mim é deixar vários agentes trabalharem em tarefas diferentes, em repositórios diferentes do projeto, enquanto eu sigo aprovando o que eles fazem. Parece um gerente de projeto conduzindo um time enorme. Tempos fascinantes mesmo
É uma abordagem realmente nova. Fico curioso para saber qual é o framework em que os agentes estão rodando nesses experimentos reais
Ultimamente também tenho gravado por voz detalhes do produto, jornadas de usuário etc., e usado isso para iniciar o processo de documentação técnica. Um
CLAUDE.mdmínimo, workflow de desenvolvimento de software usando o GitHub, mas ainda acho difícil montar um bom workflow de CI. Meu playbook é https://nocodo.com/playbook/Não me convence muito a ideia de que “se você planejar primeiro, o resultado melhora”. Para funcionalidades grandes ou projetos, eu sempre pensei antes na estrutura, no porquê e no como — seja na cabeça, no papel, no Confluence ou num quadro branco. Em engenharia de software, 80% do trabalho é decidir e fechar o “o quê, por quê e como”. Você valida ideias e objetivos com stakeholders, faz pesquisa também. Só os 20% finais são codificação de fato. Sempre foi assim para mim, e não sei se IA é mesmo necessária para um planejamento decente ou para definir objetivos corretamente
Isso pode valer em times grandes ou em ambientes com uma cultura já consolidada, mas uma grande parte do desenvolvimento se concentra em projetos individuais, times pequenos, side projects, POCs rápidas e ferramentas de automação descartáveis. Esse tipo de trabalho não começa com documentação/especificação/testes desde o início; ele mistura código com reflexão e implementação ao longo do caminho. Há casos em que TDD faz sentido, e outros em que simplesmente não é necessário. Mas, depois da adoção de agentes de código com IA, o processo de definir claramente a ideia e organizá-la em especificações ficou muito mais importante. Virou essencial colocar em palavras tudo o que está na minha cabeça. Hoje, a linguagem de programação mais quente é o inglês
Eu costumo misturar desenvolvimento e design. Começo a codar logo e vou refinando e evoluindo continuamente. Na maioria dos casos, a solução geral é bastante óbvia, então não sinto necessidade de gastar tempo planejando em profundidade
Antes, prompt engineering era meio piada, mas agora estou sentindo isso na prática. Às vezes passo de 10 a 20 minutos caprichando no prompt e no planejamento inicial para usar cloud code de forma estruturada. Como o OP, eu também salvo os planos em arquivos e executo em um contexto novo. O que eu realmente queria é um bom CLI (hoje uso charm e cc). Seria ótimo poder usar modelos diferentes para implementação, planejamento e subagentes. Algo como implementar com um modelo local e planejar com um modelo em nuvem, ou trocar conforme a necessidade para economizar dinheiro. O Charm, entre os que já usei, é o melhor para ir e voltar sem perder contexto. O recurso de subagentes paralelos também é uma das melhores funcionalidades do claudecode. (Tentei o CCR, mas me decepcionei porque ele não vai além do modelo padrão)
O motivo de prompt engineering ter virado assunto agora é por causa de hot takes no Twitter e da produção de conteúdo. Mas, na prática, prompt engineering sempre foi importante. GIGO (“Garbage In, Garbage Out”) é uma verdade em qualquer projeto de machine learning. Por isso continuo recomendando para colegas e amigos: “você precisa usar por conta própria”. O que não funcionava há 6 meses pode funcionar hoje. Só colocando a mão na massa você entende o que mudou e o que é possível. Acho casos reais de sucesso, blogs, gists e exemplos muito mais valiosos do que negatividade. Não basta fazer contas simples ou achar erros de digitação; precisa melhorar meu workflow e me ajudar de verdade. Prompt engineering é como se aprofundar no Google de 10 a 15 anos atrás e continuar aprendendo as mudanças novas e os padrões eficazes que aparecem
Para colaborar com IA, prompt engineering é realmente central
Os projetos em que usei IA foram os projetos mais bem documentados e mais bem testados em que já trabalhei. Como LLMs precisam de contexto para entregar desempenho, a documentação melhora naturalmente; e como o custo de produzir testes caiu, acabamos tendo mais testes. Ao contrário das previsões de que a qualidade do código cairia, acho que ela vai melhorar
Sinceramente, o termo “prompt engineering” é arquitetura usando uma nova mídia. No passado, “diagramar arquitetura” era uma habilidade valorizada; agora isso é apenas uma nova forma de arquitetar
Testei Claude Code rapidamente recentemente e pretendo experimentar o workflow recomendado. Parece um jeito muito bom de trabalhar. Mas o custo do CC é mais alto do que eu esperava. Fiz uma refatoração simples, com 5 minutos de trabalho e 15 minutos de revisão, e custou 4 dólares. Se eu tivesse feito sozinho, teria levado uns 15 a 20 minutos. Fico curioso sobre quanto as pessoas costumam gastar com CC por funcionalidade. Ninguém fala de preço
Com assinatura, há um valor fixo de $20 a $200 com limites diários/semanais de uso de tokens. https://support.anthropic.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan
A direção que investidores de IA querem é uma estrutura em que a IA substitui o mercado de trabalho com margem de 15%. Vai chegar uma era em que orçamento de IA e orçamento de desenvolvedor serão equivalentes 1:1. Por exemplo, o equivalente a um desenvolvedor sênior de 100 mil dólares por ano será substituído por 100 mil dólares de orçamento de IA. O orçamento de IA vai sair do custo de desenvolvimento, salários de sênior provavelmente vão cair, e o tamanho dos times de engenharia pode encolher drasticamente. Neste momento ainda estamos numa fase de “tomada de território” totalmente subsidiada por VC, mas, olhando o clima dos VCs no Twitter, parece que essa fase está perto do fim. Até mesmo captar repetidamente mais 500 milhões de dólares para sustentar 9 meses de operação está chegando ao limite
Desde que migrei parte do meu uso do Cursor para o Claude Code, os custos aumentaram bastante. Como uso principalmente no trabalho, foi fácil convencer meu chefe, mas em side projects eu fico pensando duas vezes. Não quero pagar 20 dólares toda vez só para brincar de bootstrapar um app
Você pode assinar escolhendo entre os modelos Sonnet (20 euros/mês) e Opus (100 euros/mês). Eu usava Sonnet e depois mudei para Opus. Sonnet já é bem utilizável. Dentro do limite de tokens, para o meu uso, não está faltando nada. Só não sei como isso será daqui para frente
Você disse “se eu tivesse feito sozinho, levaria 15~20 minutos”, mas vale pensar se esses 15~20 minutos não poderiam ser usados em outra coisa
A forma como uso a combinação Visual Studio Code/ChatGPT5 preview é parecida com meu workflow {acho que estou pagando isso pela assinatura do GitHub Copilot, mas hoje em dia nem tenho certeza}. Sinto que LLMs não agentes tendem muito a estragar o código rapidamente. Quando uso modo agente, a construção de código muda completamente. Não sou desenvolvedor Python, mas fiquei realmente impressionado vendo o LLM gerar um bloco novo de código. Depois de terminar, pretendo rodar um LLM pequeno no BitGrid e só então entender completamente o código. A ideia é repetir pequenas etapas exploratórias e fazer apenas alguns ajustes para manter o design geral do jeito que eu quero. Isso me deixou confiante no futuro em que LLMs serão parceiros de programação. Fico curioso se mais alguém usa a combinação Visual Studio Code/ChatGPT5
Acho interessante que, ao tentar otimizar ferramentas de IA, os desenvolvedores parecem estar redescobrindo o valor de “boa comunicação” e “definição de expectativas”. Talvez seja hora de repensar a imagem do desenvolvedor 10x como alguém antissocial ou excêntrico
Tive uma experiência parecida no Replit. Quando o app cresce, se o documento de design não vira a fonte da verdade e das tarefas, tudo desmorona rapidamente. No OpenAI, o chat fica lento e para de funcionar logo, então ajuda criar documentos separados e importá-los para um novo chat. Também senti, no nível humano, que nós mesmos deveríamos fazer isso. Ao refletir e documentar por conta própria, registrando a “memória” em documentos de design, tanto nós quanto os LLMs podemos ficar mais livres
Também descobri esse workflow recentemente e fiquei muito impressionado. O importante é fornecer ao claude apenas os requisitos mínimos e deixar o modo de planejamento rodar livremente. Se for um relatório de métricas de vendas, basta algo como “Ultrathink relevant sales metrics”, e ele já sugere várias métricas, ranqueia e permite afunilar. Eu crio um diretório separado para cada nova funcionalidade e faço o sistema escrever o plano daquela funcionalidade em um arquivo. Depois, peço etapa por etapa: plano de implementação, queries de dados necessárias, implementação real, testes, documentação para o usuário e envio para QA. Antes, para criar uma única funcionalidade de previsão de vendas, eu precisaria de um time grande e muito tempo; agora o claude implementa isso em um contêiner Docker em meio dia. Essa mudança está alterando minha visão sobre software. Antes, por causa de NDA, IP etc., as empresas jamais deixavam o código-fonte sair para fora. Mas agora até um sistema ERP complexo, construído ao longo de 20 anos, o claude consegue reimplementar rapidamente, anexando documentação e testes. Na prática ainda não fica perfeito, mas o avanço é realmente muito rápido
Para tirar bons resultados do Claude Code, o essencial é escrever bem o plano antes. Ultimamente uso o GPT-5 High no Cursor para fazer o plano, e depois jogo isso no Claude Code para implementar. Se você documentar antes quais partes da base de código precisam ser alteradas, dá para obter resultados 15~20% melhores. Quando o modelo de planejamento documenta o modo de funcionamento, a arquitetura, os padrões e também incorpora o design da funcionalidade, o resultado melhora. Por fim, revisar e editar pessoalmente a documentação e o plano também ajuda muito
Fico curioso se alguém encontrou uma boa forma de encaixar design de frontend com elegância nesse processo. Na maioria das vezes, tudo para em menção a frameworks de frontend ou em imagens do Figma. Isso ainda não parece uma solução de design integrada de verdade