- 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
Ainda não há comentários.