{"content_id":"vduimuvis9","slug":"claude-code-prompt-six-principles-and-templates","locale":"pt","schema_type":"HowTo","category":"tutorial","category_name":"Tutorial","title":"6 princípios de prompts para elevar a qualidade dos resultados do Claude Code","summary":"Explica como transmitir de forma estruturada o contexto, o contrato de saída, o tratamento de exceções e os critérios de validação, em vez de simplesmente pedir ao Claude Code que crie o código. Também oferece modelos de prompts que podem ser aplicados diretamente ao desenvolvimento de novos agentes, à adição de funcionalidades e à correção de erros.","sponsorship_disclosure":null,"author":{"name":"injoys","url":"https://injoys.com/ko/about"},"key_points":["1. Antes de iniciar o trabalho, reúna em um único documento o contexto do usuário, o problema a ser resolvido, os critérios de sucesso e as restrições técnicas.","2. Especifique a estrutura de arquivos, o formato dos dados, o escopo permitido e as condições de conclusão do resultado em um contrato de saída concreto.","3. Defina as exceções previsíveis, como falhas de APIs externas, resultados vazios, dados duplicados e erros de autenticação, bem como as políticas de resposta.","4. Divida o trabalho na ordem de revisão do plano, implementação da funcionalidade mínima, testes automatizados e expansão de funcionalidades, verificando os resultados em cada etapa.","5. Em vez de solicitar um retrabalho de forma vaga, apresente casos de falha e metas de melhoria mensuráveis e faça a validação com base nas condições finais de aceitação."],"content_markdown":"Agentes de programação como o Claude Code não são ferramentas que apenas geram um trecho de código, mas ambientes de trabalho capazes de explorar repositórios, modificar vários arquivos e executar testes e comandos. Portanto, a qualidade do resultado depende muito mais de **quão claramente o escopo do trabalho e os métodos de validação foram definidos** do que de quão plausível o texto parece.\n\nUm bom prompt não é uma explicação longa, mas uma especificação de trabalho executável. Ele deve informar não apenas o que criar, mas também por que isso é necessário, quais condições devem ser respeitadas, como tratar falhas e quais critérios devem ser atendidos para que o trabalho seja considerado concluído.\n\n## Primeiro, diferencie: prompt e ambiente de execução\n\nVibe coding é uma forma de colaboração na qual a intenção é transmitida em linguagem natural e o agente de AI fica responsável pela implementação. No entanto, o fato de uma solicitação ter sido feita em linguagem natural não garante a correção do código nem a estabilidade operacional.\n\nOs seguintes elementos atuam em conjunto no trabalho com Claude Code.\n\n| Elemento | Função | O que verificar no prompt |\n|---|---|---|\n| Solicitação do usuário | Comunicar o objetivo e o escopo da alteração | Finalidade, prioridades, proibições |\n| Contexto do repositório | Fornecer a estrutura e as regras existentes | Framework, comandos de execução, arquivos relacionados |\n| `CLAUDE.md` | Fornecer diretrizes de projeto aplicadas repetidamente | Regras de programação, método de teste, convenções de diretórios |\n| Permissões de ferramentas | Controlar o escopo permitido para modificação de arquivos e execução de comandos | Comandos que podem ser executados e tarefas que exigem confirmação prévia |\n| Conexões externas | Acessar APIs, bancos de dados, servidores MCP etc. | Método de autenticação, limites de confiança, política de falhas |\n| Procedimento de validação | Determinar se o resultado atende aos requisitos | Testes, análise estática, itens de verificação manual |\n\nEscrever bem apenas o prompt não resolve todos os problemas. Por exemplo, o Claude Code pode criar código de execução agendada, mas, para que a tarefa seja executada mesmo quando o computador estiver desligado, é necessário um servidor separado, um serviço de CI ou um agendador do sistema operacional. Da mesma forma, o envio de e-mails não pode ser concluído sem as credenciais de autenticação e a permissão de envio de um provedor real.\n\n## Princípio 1. Explique primeiro o contexto, o objetivo e as restrições\n\nSe apenas o nome do resultado for informado, como em `Crie um agente de coleta de notícias`, o agente terá de inferir o usuário, as fontes de dados, o ambiente de execução e os critérios de sucesso. Mesmo para um coletor de notícias semelhante, as fontes e os critérios de classificação necessários para um profissional de desenvolvimento de negócios, um investidor ou um editor de jornal universitário são diferentes.\n\n### Solicitação insuficiente\n\n```text\nCrie um agente de coleta de notícias sobre AI.\n```\n\n### Solicitação aprimorada\n\n```text\nSou responsável pelo desenvolvimento de negócios de uma startup de TI.\nAntes de começar a trabalhar todos os dias, quero verificar rapidamente notícias\nnas áreas de AI, computação em nuvem e fintech que possam afetar\nparcerias comerciais ou a estratégia de produto.\n\nObjetivos:\n- Coletar notícias recentes candidatas para cada palavra-chave especificada.\n- Remover notícias com a mesma URL e duplicatas com títulos semelhantes.\n- Classificar o impacto como alto, médio ou baixo com base na necessidade\n  de tomar uma decisão sobre produto ou parceria dentro de 3 meses.\n- Criar um briefing por e-mail em coreano com o resultado.\n\nRestrições:\n- Manter a versão do Python e o método de gerenciamento de pacotes do repositório atual.\n- Antes de adicionar uma nova biblioteca, explicar sua necessidade e as alternativas.\n- Não registrar chaves de API nem senhas de e-mail no código ou nos logs.\n- Antes de enviar um e-mail real, gerar apenas um arquivo de pré-visualização.\n\nPrimeiro, examine a estrutura do repositório e o método de execução e, depois,\nproponha um plano de implementação.\nNão presuma informações desconhecidas sobre o ambiente; organize-as como uma lista de perguntas.\n```\n\nUm bom contexto inclui os quatro itens a seguir.\n\n1. **Usuário e situação de uso:** quem usa, quando usa e para qual decisão\n2. **Objetivo:** qual problema deve ser resolvido, em vez da simples escrita do código\n3. **Restrições:** quais tecnologias, regras de segurança e limites de custo ou prazo devem ser mantidos\n4. **Não objetivos:** quais funcionalidades estão explicitamente excluídas desta alteração\n\nDefinir os não objetivos impede que o escopo cresça indefinidamente. Por exemplo, ao definir que `nesta etapa, a execução agendada e o envio real de e-mails estão excluídos`, é possível validar primeiro, de forma estável, a lógica de coleta e classificação.\n\n## Princípio 2. Transforme o formato de saída em um contrato de saída\n\n`Envie de forma agradável por e-mail` pode ser interpretado de maneira diferente por cada pessoa. Em vez de apenas mostrar um exemplo do formato de saída, é preciso definir também os campos obrigatórios, os valores permitidos, o tratamento de dados ausentes e a ordem de classificação.\n\n```text\nAssunto do e-mail:\n[Briefing de notícias] {YYYY-MM-DD} Principais notícias de hoje\n\nFormato das notícias no corpo:\n1. {Título}\nResumo: {1 a 2 frases em coreano}\nImpacto: {alto|médio|baixo}\nMotivo da avaliação: {1 frase}\nFonte: {nome do veículo}\nLink: {URL original}\n\nRegras de classificação:\n1. Em ordem decrescente de impacto\n2. Em caso de mesmo impacto, da publicação mais recente para a mais antiga\n\nEstatísticas no rodapé:\n- Número total de notícias\n- Número de notícias por impacto\n- Palavras-chave sem resultados de pesquisa\n\nRestrições:\n- Não inventar no resumo números ou afirmações ausentes do texto original.\n- Se a data não puder ser confirmada, não estimá-la e marcá-la como 'não foi possível confirmar'.\n- Excluir do briefing final os itens sem link.\n```\n\nSe o resultado precisar ser transferido entre programas, é recomendável solicitar um esquema JSON ou uma definição de tipos junto com um exemplo legível por pessoas.\n\n```json\n{\n  \"title\": \"string\",\n  \"summary\": \"string\",\n  \"impact\": \"high | medium | low\",\n  \"reason\": \"string\",\n  \"source\": \"string\",\n  \"url\": \"absolute URL\",\n  \"published_at\": \"ISO 8601 string | null\"\n}\n```\n\nO contrato de saída inclui não apenas o formato, mas também o significado. Se não houver critérios de avaliação que definam o que significa `impact: high`, a sintaxe JSON poderá estar correta, mas os resultados da classificação poderão ser inconsistentes.\n\n## Princípio 3. Especifique situações excepcionais e políticas de recuperação\n\nA qualidade do código operacional se revela mais nos caminhos de falha do que no fluxo normal. O prompt deve especificar as falhas previsíveis, se é possível tentar novamente, as condições para notificar o usuário e quais informações não devem ser registradas.\n\n| Situação excepcional | Exemplo de política recomendada |\n|---|---|\n| Nenhum resultado de pesquisa | Ignorar a palavra-chave e registrá-la nas estatísticas finais |\n| Erro temporário de rede | Tentar novamente apenas um número limitado de vezes, em intervalos definidos |\n| Falha de autenticação | Não tentar novamente; interromper imediatamente e orientar a verificação da configuração |\n| Limite de uso da API | Respeitar as instruções de espera da resposta e proibir tentativas infinitas |\n| Notícias duplicadas | Remover com base na URL normalizada e na similaridade dos títulos |\n| Dados em formato incorreto | Preservar o original e isolar apenas o item correspondente |\n| Falha no envio de e-mail | Se continuar falhando após novas tentativas, registrar uma notificação alternativa ou o estado de falha |\n| Sucesso parcial | Informar separadamente os resultados bem-sucedidos e os itens com falha |\n\nA política pode ser solicitada de forma concreta como a seguir.\n\n```text\nTrate o tempo limite da rede como um erro que permite nova tentativa.\nAguarde entre as tentativas e, ao exceder o número máximo,\nmarque como falha apenas a fonte correspondente.\nComo erros de autenticação e solicitações inválidas não serão resolvidos\ncom repetição, interrompa imediatamente.\n\nTodos os logs de erro devem registrar horário, etapa da tarefa, fonte e tipo de erro,\nmas não devem registrar chaves de API, endereços de e-mail completos,\ncabeçalhos de autenticação nem o texto integral das notícias.\nDiferencie sucesso total, sucesso parcial e falha total pelo status de encerramento do processo.\n```\n\nValores como `tentar novamente três vezes` ou `aguardar 5 segundos` não são respostas universalmente corretas. Eles devem ser definidos no projeto de acordo com os limites oficiais do serviço externo, a urgência da tarefa e o risco de execução duplicada. Tarefas com efeitos colaterais, como pagamentos ou envio de mensagens, podem ser processadas em duplicidade se forem repetidas automaticamente sem garantia de idempotência.\n\n## Princípio 4. Desenvolva gradualmente na ordem: planejamento, implementação mínima e validação\n\nAo conectar vários serviços externos e a execução automática de uma só vez, fica difícil isolar a causa dos erros. Dividir a implementação em pequenas unidades de validação permite verificar as entradas e saídas de cada etapa.\n\n### Ordem de execução recomendada\n\n1. Examine a estrutura do repositório, os arquivos relacionados e os comandos de execução.\n2. Antes de alterar o código, solicite um plano e a indicação dos arquivos que serão afetados.\n3. Implemente a função de coleta usando uma única palavra-chave e dados de amostra fixos.\n4. Teste separadamente a remoção de duplicatas e a classificação de impacto.\n5. Valide o e-mail por meio de uma pré-visualização local, em vez de enviá-lo de fato.\n6. Depois que os testes passarem, adicione a integração com o provedor real e a execução agendada.\n\nA primeira solicitação pode ser limitada da seguinte forma.\n\n```text\nExecute apenas a etapa 1 agora.\nExamine o repositório e informe:\n- O ponto de entrada da aplicação atual\n- Os módulos e arquivos de teste relacionados\n- Os comandos usados para gerenciamento de pacotes e testes\n- Os arquivos que provavelmente precisarão ser alterados\n- As questões que devem ser decididas antes da implementação\n\nAinda não modifique os arquivos.\n```\n\nDepois de revisar o plano, implemente restringindo o escopo da alteração.\n\n```text\nDo plano aprovado, implemente apenas a coleta de notícias\ne a remoção de duplicatas.\nNão adicione classificação, envio de e-mail nem execução agendada.\nPermita a execução com dados de teste fixos e, ao final,\nresuma os arquivos modificados e os resultados dos testes executados.\n```\n\nSe for possível usar um modo exclusivo de planejamento no ambiente do Claude Code, ele poderá ser utilizado nas etapas de exploração e projeto. No entanto, o fato de um plano parecer plausível não significa que a implementação esteja correta, portanto testes reais e revisão de código devem ser realizados em seguida.\n\n## Princípio 5. Forneça feedback com casos de falha e números\n\nÉ difícil definir a direção da correção com comentários como `o resultado não está bom`, `o desempenho está lento` ou `a classificação está errada`. É preciso informar o estado atual, o estado esperado, a entrada de reprodução e o intervalo aceitável de alterações.\n\n### Solicitação de ajuste de tamanho\n\n```text\nAtualmente, o corpo do e-mail é gerado com cerca de 3.000 caracteres.\nQuero reduzi-lo para no máximo 500 caracteres para que possa ser lido rapidamente no celular.\nLimite o resumo de cada notícia a 1 ou 2 frases e mantenha o motivo da avaliação.\nAssocie a URL original ao título e remova a linha separada do link.\nMantenha as estatísticas no rodapé.\n```\n\n### Solicitação de ajuste dos critérios de classificação\n\n```text\nDos 10 itens dos dados de teste, 8 foram classificados como 'alto'.\nClassifique perspectivas tecnológicas de longo prazo\nou apresentações gerais de produtos como 'baixo'.\nClassifique como 'alto' somente quando houver evidências concretas\nde que será necessário mudar, dentro de 3 meses, uma decisão sobre preços,\nroadmap do produto, resposta regulatória ou parceria.\n\nNos casos anexados, A e B devem ser classificados como alto, e C como baixo.\nCorrija as regras de classificação e adicione esses casos como testes de regressão.\n```\n\n### Solicitação de ajuste de desempenho\n\n```text\nO tempo médio atual de execução com a mesma entrada de amostra é de cerca de 45 segundos.\nA meta é no máximo 30 segundos no mesmo ambiente.\nPrimeiro, meça o tempo de cada etapa e mostre o gargalo.\nNão remova a precisão dos resultados nem o tratamento de erros;\ncompare os efeitos e os riscos das alternativas de melhoria\ne aplique primeiro a menor alteração.\n```\n\nOs números de desempenho só podem ser comparados quando o ambiente de medição e os dados de entrada são os mesmos. Não considere que houve melhoria com base no resultado de uma única execução; fixe também o método de medição, a amostra e o estado do cache.\n\n## Princípio 6. Use modelos de prompt por tipo de tarefa\n\n### Modelo para criar um novo agente\n\n```text\n[Função e situação]\nSou {profissão/função} e quero resolver {situação problemática}.\nEste resultado será usado por {usuário ou sistema posterior}.\n\n[Objetivo]\n{resultado a ser alcançado e critérios de sucesso}\n\n[Gatilho de execução]\n{execução manual, evento, horário agendado etc.}\n\n[Entrada]\n- Fonte de dados: {arquivo/API/banco de dados}\n- Campos obrigatórios: {lista de campos}\n- Método de autenticação: {variável de ambiente ou método de gerenciamento de segredos}\n\n[Lógica de processamento]\n1. {etapa 1}\n2. {etapa 2}\n3. {etapa 3}\n\n[Contrato de saída]\n{formato de arquivo, esquema, modelo, regras de classificação e dados ausentes}\n\n[Tratamento de exceções]\n{resultado vazio, tempo limite, erro de autenticação, política de falha parcial}\n\n[Restrições e não objetivos]\n- Tecnologias a manter: {itens}\n- Proibições: {itens}\n- Funcionalidades excluídas desta tarefa: {itens}\n\n[Validação]\n- Testes que devem passar: {itens}\n- Conteúdo do relatório de conclusão: arquivos alterados, comandos executados,\n  resultados dos testes, riscos restantes\n\nPrimeiro, examine o repositório e apresente um plano de implementação.\nNão presuma informações desconhecidas; faça perguntas.\n```\n\n### Modelo para adicionar uma funcionalidade existente\n\n```text\nAdicione {nova funcionalidade} ao {nome do agente ou módulo} existente.\nA nova funcionalidade deve ser executada depois de {etapa existente A}\ne antes de {etapa existente B}.\n\nLógica detalhada:\n- {condições e regras de processamento}\n- {formato de entrada e saída}\n- {comportamento em caso de falha}\n\nCondições de manutenção:\n- Não alterar a interface pública nem o formato de configuração existentes.\n- Manter todos os testes existentes.\n- Não modificar arquivos não relacionados.\n\nPrimeiro, explique o escopo do impacto e os riscos de regressão.\nEm seguida, adicione testes que preservem o comportamento existente e implemente a funcionalidade.\n```\n\n### Modelo para correção de erros\n\n```text\nReproduza o erro a seguir e corrija sua causa raiz.\n\nMensagem de erro completa:\n{mensagem de erro e rastreamento de pilha após remover informações secretas e pessoais}\n\nCondições de ocorrência:\n- Comando de execução: {comando}\n- Entrada: {entrada mínima para reprodução}\n- Ambiente: {sistema operacional, runtime, versões relacionadas}\n- Momento da ocorrência: {em qual etapa}\n\nComportamento esperado:\n{resultado que deveria aparecer em condições normais}\n\nComportamento real:\n{resultado observado atualmente}\n\nSolicitação:\n1. Primeiro, reproduza o erro.\n2. Explique a causa com base em evidências.\n3. Corrija-o com o menor escopo possível.\n4. Adicione um teste de regressão que impeça o mesmo erro.\n5. Informe os testes executados e os riscos restantes.\n```\n\nAo colar uma mensagem de erro, é preciso remover informações sensíveis, como chaves de API, tokens de sessão, dados de clientes e endereços internos.\n\n## Exemplo completo: solicitação de um agente de briefing de notícias\n\nO exemplo a seguir combina os seis princípios em uma única solicitação.\n\n```text\nSou responsável pelo desenvolvimento de negócios de uma startup de SaaS.\nQuero verificar diariamente apenas as notícias sobre mudanças nos mercados\nde AI, computação em nuvem e fintech que possam alterar, dentro de 3 meses,\ndecisões sobre produtos ou parcerias.\n\nExamine o repositório atual e projete uma ferramenta de briefing de notícias.\nNa primeira etapa, implemente apenas a funcionalidade que lê uma amostra JSON,\nremove duplicatas, classifica o impacto e cria um arquivo HTML de pré-visualização.\nPesquisa na web, envio real de e-mail e execução agendada estão excluídos desta etapa.\n\nCampos de entrada:\n- title, url, source, published_at, body\n\nRegras de processamento:\n- Considere como duplicatas as URLs normalizadas que forem iguais.\n- Mesmo que as URLs sejam diferentes, marque como candidatas a duplicatas\n  as notícias com títulos semelhantes.\n- Classifique como impacto 'alto' apenas notícias que exijam mudanças concretas,\n  dentro de 3 meses, em preços, resposta regulatória, roadmap do produto\n  ou decisões sobre parcerias.\n- Se não houver evidências suficientes, não presuma uma classificação alta.\n\nSaída:\n- Exibir título, resumo de 1 a 2 frases, impacto, motivo da avaliação, fonte e URL.\n- Ordenar em ordem decrescente de impacto.\n- Exibir no rodapé o total de itens, o número de duplicatas removidas\n  e a quantidade por classificação.\n\nTratamento de exceções:\n- Não excluir itens sem campos obrigatórios; registrá-los em uma lista de erros separada.\n- Não estimar datas inválidas; mantê-las como null.\n- Não registrar nos logs o texto integral das notícias nem informações de autenticação.\n\nValidação:\n- Testar entrada normal, entrada vazia, URL duplicada, data inválida\n  e ausência de campos obrigatórios.\n- Se houver testes existentes, todos deverão passar.\n\nOrdem de trabalho:\n1. Examinar a estrutura do repositório e os arquivos relacionados.\n2. Apresentar os arquivos a serem modificados e o plano de testes.\n3. Não alterar o código antes que eu revise o plano.\n4. Após a aprovação, implementar a funcionalidade mínima e informar os resultados dos testes.\n```\n\nEssa solicitação não exige que todas as funcionalidades necessárias sejam implantadas de uma só vez no ambiente operacional. O escopo é limitado, e o significado da saída, o tratamento de falhas e os itens de teste são definidos em conjunto, facilitando a avaliação do resultado.\n\n## Critérios de qualidade fáceis de ignorar quando se depende apenas do prompt\n\nMuitas orientações sobre vibe coding se concentram em escrever instruções mais detalhadas. No entanto, outros elementos que determinam a qualidade real são **capacidade de validação, controle de alterações, observabilidade e limites de segurança**.\n\n### 1. Transforme critérios de aceitação em testes\n\nEm vez de dizer `faça funcionar bem`, forneça pares de entrada e saída esperada. Mantenha casos importantes de classificação como testes de regressão para verificar se o resultado continua preservado nas alterações posteriores.\n\n### 2. Não use a autoavaliação do agente como evidência final\n\nO agente dizer que `concluiu` é diferente de os testes terem passado. Solicite que ele informe os comandos executados, os resultados dos testes, os arquivos alterados e os riscos não resolvidos, e uma pessoa deve revisar o diff.\n\n### 3. Minimize permissões e informações secretas\n\nNão forneça de uma só vez acesso a diretórios desnecessários, bancos de dados de produção e credenciais de implantação. Não insira chaves de API diretamente no prompt ou no repositório; use variáveis de ambiente ou um sistema aprovado de gerenciamento de segredos. Não conceda acesso a repositórios sensíveis para servidores MCP ou scripts de origem desconhecida.\n\n### 4. Exija código observável\n\nEm tarefas automatizadas, registre informações necessárias para identificar a causa das falhas, como o estado de cada etapa, erros estruturados, tempo de execução e número de itens processados. Por outro lado, remova dos logs informações de autenticação e dados pessoais.\n\n### 5. Torne as alterações reversíveis\n\nNão misture refatorações não relacionadas e adições de funcionalidades em uma mesma alteração. Revisar o diff em pequenas unidades e registrar as mudanças no controle de versão facilita isolar e reverter alterações incorretas.\n\n## Dicas para operar projetos com Claude Code\n\n- Registre regras recorrentes do projeto no `CLAUDE.md` de forma breve e concreta.\n- Forneça comandos de build, teste e lint em uma forma que possa realmente ser executada.\n- Não coloque informações secretas, logs de erros ocasionais nem documentos de referência longos no `CLAUDE.md`.\n- Antes de grandes alterações, solicite primeiro uma análise dos arquivos relacionados e das dependências.\n- Ao adicionar um novo pacote, revise sua necessidade, licença e riscos de manutenção.\n- Não aprove automaticamente comandos perigosos de exclusão, implantação ou alteração de dados.\n- Antes de conectar uma API externa ou MCP, verifique para onde os dados serão enviados.\n- Ao concluir, solicite um resumo dos arquivos alterados, comandos executados, resultados dos testes e limitações restantes.\n\n## Checklist antes do envio\n\n- [ ] O usuário e a situação de uso estão explicados?\n- [ ] Os objetivos e não objetivos estão separados?\n- [ ] As tecnologias existentes e o escopo no qual alterações são proibidas estão especificados?\n- [ ] Os dados de entrada e o formato de saída estão definidos?\n- [ ] O significado dos valores de classificação e de status está explicado?\n- [ ] Existem políticas para resultados vazios, falhas de autenticação, tempo limite e falhas parciais?\n- [ ] O planejamento e a implementação estão separados por etapas?\n- [ ] Existem testes para casos normais, extremos e de falha?\n- [ ] Informações secretas e dados pessoais estão excluídos do prompt e dos logs?\n- [ ] Foram solicitados um diff para revisão humana e evidências de execução?\n\nO essencial de um bom prompt para Claude Code não é escrever comandos longos. É reduzir o que o agente precisa inferir e permitir que terceiros também reproduzam e avaliem se o resultado está correto.","content_html":"\u003cp\u003eAgentes de programação como o Claude Code não são ferramentas que apenas geram um trecho de código, mas ambientes de trabalho capazes de explorar repositórios, modificar vários arquivos e executar testes e comandos. Portanto, a qualidade do resultado depende muito mais de \u003cstrong\u003equão claramente o escopo do trabalho e os métodos de validação foram definidos\u003c/strong\u003e do que de quão plausível o texto parece.\u003c/p\u003e\n\u003cp\u003eUm bom prompt não é uma explicação longa, mas uma especificação de trabalho executável. Ele deve informar não apenas o que criar, mas também por que isso é necessário, quais condições devem ser respeitadas, como tratar falhas e quais critérios devem ser atendidos para que o trabalho seja considerado concluído.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#primeiro-diferencie-prompt-e-ambiente-de-execu%C3%A7%C3%A3o\" class=\"anchor\" id=\"primeiro-diferencie-prompt-e-ambiente-de-execução\"\u003e\u003c/a\u003ePrimeiro, diferencie: prompt e ambiente de execução\u003c/h2\u003e\n\u003cp\u003eVibe coding é uma forma de colaboração na qual a intenção é transmitida em linguagem natural e o agente de AI fica responsável pela implementação. No entanto, o fato de uma solicitação ter sido feita em linguagem natural não garante a correção do código nem a estabilidade operacional.\u003c/p\u003e\n\u003cp\u003eOs seguintes elementos atuam em conjunto no trabalho com Claude Code.\u003c/p\u003e\n\u003cdiv class=\"overflow-x-auto\"\u003e\u003ctable\u003e\n\u003cthead\u003e\n\u003ctr\u003e\n\u003cth\u003eElemento\u003c/th\u003e\n\u003cth\u003eFunção\u003c/th\u003e\n\u003cth\u003eO que verificar no prompt\u003c/th\u003e\n\u003c/tr\u003e\n\u003c/thead\u003e\n\u003ctbody\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Elemento\"\u003eSolicitação do usuário\u003c/td\u003e\n\u003ctd data-label=\"Função\"\u003eComunicar o objetivo e o escopo da alteração\u003c/td\u003e\n\u003ctd data-label=\"O que verificar no prompt\"\u003eFinalidade, prioridades, proibições\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Elemento\"\u003eContexto do repositório\u003c/td\u003e\n\u003ctd data-label=\"Função\"\u003eFornecer a estrutura e as regras existentes\u003c/td\u003e\n\u003ctd data-label=\"O que verificar no prompt\"\u003eFramework, comandos de execução, arquivos relacionados\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Elemento\"\u003e\u003ccode\u003eCLAUDE.md\u003c/code\u003e\u003c/td\u003e\n\u003ctd data-label=\"Função\"\u003eFornecer diretrizes de projeto aplicadas repetidamente\u003c/td\u003e\n\u003ctd data-label=\"O que verificar no prompt\"\u003eRegras de programação, método de teste, convenções de diretórios\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Elemento\"\u003ePermissões de ferramentas\u003c/td\u003e\n\u003ctd data-label=\"Função\"\u003eControlar o escopo permitido para modificação de arquivos e execução de comandos\u003c/td\u003e\n\u003ctd data-label=\"O que verificar no prompt\"\u003eComandos que podem ser executados e tarefas que exigem confirmação prévia\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Elemento\"\u003eConexões externas\u003c/td\u003e\n\u003ctd data-label=\"Função\"\u003eAcessar APIs, bancos de dados, servidores MCP etc.\u003c/td\u003e\n\u003ctd data-label=\"O que verificar no prompt\"\u003eMétodo de autenticação, limites de confiança, política de falhas\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Elemento\"\u003eProcedimento de validação\u003c/td\u003e\n\u003ctd data-label=\"Função\"\u003eDeterminar se o resultado atende aos requisitos\u003c/td\u003e\n\u003ctd data-label=\"O que verificar no prompt\"\u003eTestes, análise estática, itens de verificação manual\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\u003c/div\u003e\n\u003cp\u003eEscrever bem apenas o prompt não resolve todos os problemas. Por exemplo, o Claude Code pode criar código de execução agendada, mas, para que a tarefa seja executada mesmo quando o computador estiver desligado, é necessário um servidor separado, um serviço de CI ou um agendador do sistema operacional. Da mesma forma, o envio de e-mails não pode ser concluído sem as credenciais de autenticação e a permissão de envio de um provedor real.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#princ%C3%ADpio-1-explique-primeiro-o-contexto-o-objetivo-e-as-restri%C3%A7%C3%B5es\" class=\"anchor\" id=\"princípio-1-explique-primeiro-o-contexto-o-objetivo-e-as-restrições\"\u003e\u003c/a\u003ePrincípio 1. Explique primeiro o contexto, o objetivo e as restrições\u003c/h2\u003e\n\u003cp\u003eSe apenas o nome do resultado for informado, como em \u003ccode\u003eCrie um agente de coleta de notícias\u003c/code\u003e, o agente terá de inferir o usuário, as fontes de dados, o ambiente de execução e os critérios de sucesso. Mesmo para um coletor de notícias semelhante, as fontes e os critérios de classificação necessários para um profissional de desenvolvimento de negócios, um investidor ou um editor de jornal universitário são diferentes.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#solicita%C3%A7%C3%A3o-insuficiente\" class=\"anchor\" id=\"solicitação-insuficiente\"\u003e\u003c/a\u003eSolicitação insuficiente\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003eCrie um agente de coleta de notícias sobre AI.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003ch3\u003e\n\u003ca href=\"#solicita%C3%A7%C3%A3o-aprimorada\" class=\"anchor\" id=\"solicitação-aprimorada\"\u003e\u003c/a\u003eSolicitação aprimorada\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003eSou responsável pelo desenvolvimento de negócios de uma startup de TI.\n\u003c/span\u003e\u003cspan\u003eAntes de começar a trabalhar todos os dias, quero verificar rapidamente notícias\n\u003c/span\u003e\u003cspan\u003enas áreas de AI, computação em nuvem e fintech que possam afetar\n\u003c/span\u003e\u003cspan\u003eparcerias comerciais ou a estratégia de produto.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eObjetivos:\n\u003c/span\u003e\u003cspan\u003e- Coletar notícias recentes candidatas para cada palavra-chave especificada.\n\u003c/span\u003e\u003cspan\u003e- Remover notícias com a mesma URL e duplicatas com títulos semelhantes.\n\u003c/span\u003e\u003cspan\u003e- Classificar o impacto como alto, médio ou baixo com base na necessidade\n\u003c/span\u003e\u003cspan\u003e  de tomar uma decisão sobre produto ou parceria dentro de 3 meses.\n\u003c/span\u003e\u003cspan\u003e- Criar um briefing por e-mail em coreano com o resultado.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eRestrições:\n\u003c/span\u003e\u003cspan\u003e- Manter a versão do Python e o método de gerenciamento de pacotes do repositório atual.\n\u003c/span\u003e\u003cspan\u003e- Antes de adicionar uma nova biblioteca, explicar sua necessidade e as alternativas.\n\u003c/span\u003e\u003cspan\u003e- Não registrar chaves de API nem senhas de e-mail no código ou nos logs.\n\u003c/span\u003e\u003cspan\u003e- Antes de enviar um e-mail real, gerar apenas um arquivo de pré-visualização.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003ePrimeiro, examine a estrutura do repositório e o método de execução e, depois,\n\u003c/span\u003e\u003cspan\u003eproponha um plano de implementação.\n\u003c/span\u003e\u003cspan\u003eNão presuma informações desconhecidas sobre o ambiente; organize-as como uma lista de perguntas.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003eUm bom contexto inclui os quatro itens a seguir.\u003c/p\u003e\n\u003col\u003e\n\u003cli\u003e\n\u003cstrong\u003eUsuário e situação de uso:\u003c/strong\u003e quem usa, quando usa e para qual decisão\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eObjetivo:\u003c/strong\u003e qual problema deve ser resolvido, em vez da simples escrita do código\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eRestrições:\u003c/strong\u003e quais tecnologias, regras de segurança e limites de custo ou prazo devem ser mantidos\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eNão objetivos:\u003c/strong\u003e quais funcionalidades estão explicitamente excluídas desta alteração\u003c/li\u003e\n\u003c/ol\u003e\n\u003cp\u003eDefinir os não objetivos impede que o escopo cresça indefinidamente. Por exemplo, ao definir que \u003ccode\u003enesta etapa, a execução agendada e o envio real de e-mails estão excluídos\u003c/code\u003e, é possível validar primeiro, de forma estável, a lógica de coleta e classificação.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#princ%C3%ADpio-2-transforme-o-formato-de-sa%C3%ADda-em-um-contrato-de-sa%C3%ADda\" class=\"anchor\" id=\"princípio-2-transforme-o-formato-de-saída-em-um-contrato-de-saída\"\u003e\u003c/a\u003ePrincípio 2. Transforme o formato de saída em um contrato de saída\u003c/h2\u003e\n\u003cp\u003e\u003ccode\u003eEnvie de forma agradável por e-mail\u003c/code\u003e pode ser interpretado de maneira diferente por cada pessoa. Em vez de apenas mostrar um exemplo do formato de saída, é preciso definir também os campos obrigatórios, os valores permitidos, o tratamento de dados ausentes e a ordem de classificação.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003eAssunto do e-mail:\n\u003c/span\u003e\u003cspan\u003e[Briefing de notícias] {YYYY-MM-DD} Principais notícias de hoje\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eFormato das notícias no corpo:\n\u003c/span\u003e\u003cspan\u003e1. {Título}\n\u003c/span\u003e\u003cspan\u003eResumo: {1 a 2 frases em coreano}\n\u003c/span\u003e\u003cspan\u003eImpacto: {alto|médio|baixo}\n\u003c/span\u003e\u003cspan\u003eMotivo da avaliação: {1 frase}\n\u003c/span\u003e\u003cspan\u003eFonte: {nome do veículo}\n\u003c/span\u003e\u003cspan\u003eLink: {URL original}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eRegras de classificação:\n\u003c/span\u003e\u003cspan\u003e1. Em ordem decrescente de impacto\n\u003c/span\u003e\u003cspan\u003e2. Em caso de mesmo impacto, da publicação mais recente para a mais antiga\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eEstatísticas no rodapé:\n\u003c/span\u003e\u003cspan\u003e- Número total de notícias\n\u003c/span\u003e\u003cspan\u003e- Número de notícias por impacto\n\u003c/span\u003e\u003cspan\u003e- Palavras-chave sem resultados de pesquisa\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eRestrições:\n\u003c/span\u003e\u003cspan\u003e- Não inventar no resumo números ou afirmações ausentes do texto original.\n\u003c/span\u003e\u003cspan\u003e- Se a data não puder ser confirmada, não estimá-la e marcá-la como 'não foi possível confirmar'.\n\u003c/span\u003e\u003cspan\u003e- Excluir do briefing final os itens sem link.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003eSe o resultado precisar ser transferido entre programas, é recomendável solicitar um esquema JSON ou uma definição de tipos junto com um exemplo legível por pessoas.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e{\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003etitle\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003estring\u003c/span\u003e\u003cspan\u003e\",\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003esummary\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003estring\u003c/span\u003e\u003cspan\u003e\",\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003eimpact\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003ehigh | medium | low\u003c/span\u003e\u003cspan\u003e\",\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003ereason\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003estring\u003c/span\u003e\u003cspan\u003e\",\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003esource\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003estring\u003c/span\u003e\u003cspan\u003e\",\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003eurl\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003eabsolute URL\u003c/span\u003e\u003cspan\u003e\",\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003epublished_at\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003eISO 8601 string | null\u003c/span\u003e\u003cspan\u003e\"\n\u003c/span\u003e\u003cspan\u003e}\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003eO contrato de saída inclui não apenas o formato, mas também o significado. Se não houver critérios de avaliação que definam o que significa \u003ccode\u003eimpact: high\u003c/code\u003e, a sintaxe JSON poderá estar correta, mas os resultados da classificação poderão ser inconsistentes.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#princ%C3%ADpio-3-especifique-situa%C3%A7%C3%B5es-excepcionais-e-pol%C3%ADticas-de-recupera%C3%A7%C3%A3o\" class=\"anchor\" id=\"princípio-3-especifique-situações-excepcionais-e-políticas-de-recuperação\"\u003e\u003c/a\u003ePrincípio 3. Especifique situações excepcionais e políticas de recuperação\u003c/h2\u003e\n\u003cp\u003eA qualidade do código operacional se revela mais nos caminhos de falha do que no fluxo normal. O prompt deve especificar as falhas previsíveis, se é possível tentar novamente, as condições para notificar o usuário e quais informações não devem ser registradas.\u003c/p\u003e\n\u003cdiv class=\"overflow-x-auto\"\u003e\u003ctable\u003e\n\u003cthead\u003e\n\u003ctr\u003e\n\u003cth\u003eSituação excepcional\u003c/th\u003e\n\u003cth\u003eExemplo de política recomendada\u003c/th\u003e\n\u003c/tr\u003e\n\u003c/thead\u003e\n\u003ctbody\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Situação excepcional\"\u003eNenhum resultado de pesquisa\u003c/td\u003e\n\u003ctd data-label=\"Exemplo de política recomendada\"\u003eIgnorar a palavra-chave e registrá-la nas estatísticas finais\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Situação excepcional\"\u003eErro temporário de rede\u003c/td\u003e\n\u003ctd data-label=\"Exemplo de política recomendada\"\u003eTentar novamente apenas um número limitado de vezes, em intervalos definidos\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Situação excepcional\"\u003eFalha de autenticação\u003c/td\u003e\n\u003ctd data-label=\"Exemplo de política recomendada\"\u003eNão tentar novamente; interromper imediatamente e orientar a verificação da configuração\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Situação excepcional\"\u003eLimite de uso da API\u003c/td\u003e\n\u003ctd data-label=\"Exemplo de política recomendada\"\u003eRespeitar as instruções de espera da resposta e proibir tentativas infinitas\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Situação excepcional\"\u003eNotícias duplicadas\u003c/td\u003e\n\u003ctd data-label=\"Exemplo de política recomendada\"\u003eRemover com base na URL normalizada e na similaridade dos títulos\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Situação excepcional\"\u003eDados em formato incorreto\u003c/td\u003e\n\u003ctd data-label=\"Exemplo de política recomendada\"\u003ePreservar o original e isolar apenas o item correspondente\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Situação excepcional\"\u003eFalha no envio de e-mail\u003c/td\u003e\n\u003ctd data-label=\"Exemplo de política recomendada\"\u003eSe continuar falhando após novas tentativas, registrar uma notificação alternativa ou o estado de falha\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Situação excepcional\"\u003eSucesso parcial\u003c/td\u003e\n\u003ctd data-label=\"Exemplo de política recomendada\"\u003eInformar separadamente os resultados bem-sucedidos e os itens com falha\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\u003c/div\u003e\n\u003cp\u003eA política pode ser solicitada de forma concreta como a seguir.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003eTrate o tempo limite da rede como um erro que permite nova tentativa.\n\u003c/span\u003e\u003cspan\u003eAguarde entre as tentativas e, ao exceder o número máximo,\n\u003c/span\u003e\u003cspan\u003emarque como falha apenas a fonte correspondente.\n\u003c/span\u003e\u003cspan\u003eComo erros de autenticação e solicitações inválidas não serão resolvidos\n\u003c/span\u003e\u003cspan\u003ecom repetição, interrompa imediatamente.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eTodos os logs de erro devem registrar horário, etapa da tarefa, fonte e tipo de erro,\n\u003c/span\u003e\u003cspan\u003emas não devem registrar chaves de API, endereços de e-mail completos,\n\u003c/span\u003e\u003cspan\u003ecabeçalhos de autenticação nem o texto integral das notícias.\n\u003c/span\u003e\u003cspan\u003eDiferencie sucesso total, sucesso parcial e falha total pelo status de encerramento do processo.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003eValores como \u003ccode\u003etentar novamente três vezes\u003c/code\u003e ou \u003ccode\u003eaguardar 5 segundos\u003c/code\u003e não são respostas universalmente corretas. Eles devem ser definidos no projeto de acordo com os limites oficiais do serviço externo, a urgência da tarefa e o risco de execução duplicada. Tarefas com efeitos colaterais, como pagamentos ou envio de mensagens, podem ser processadas em duplicidade se forem repetidas automaticamente sem garantia de idempotência.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#princ%C3%ADpio-4-desenvolva-gradualmente-na-ordem-planejamento-implementa%C3%A7%C3%A3o-m%C3%ADnima-e-valida%C3%A7%C3%A3o\" class=\"anchor\" id=\"princípio-4-desenvolva-gradualmente-na-ordem-planejamento-implementação-mínima-e-validação\"\u003e\u003c/a\u003ePrincípio 4. Desenvolva gradualmente na ordem: planejamento, implementação mínima e validação\u003c/h2\u003e\n\u003cp\u003eAo conectar vários serviços externos e a execução automática de uma só vez, fica difícil isolar a causa dos erros. Dividir a implementação em pequenas unidades de validação permite verificar as entradas e saídas de cada etapa.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#ordem-de-execu%C3%A7%C3%A3o-recomendada\" class=\"anchor\" id=\"ordem-de-execução-recomendada\"\u003e\u003c/a\u003eOrdem de execução recomendada\u003c/h3\u003e\n\u003col\u003e\n\u003cli\u003eExamine a estrutura do repositório, os arquivos relacionados e os comandos de execução.\u003c/li\u003e\n\u003cli\u003eAntes de alterar o código, solicite um plano e a indicação dos arquivos que serão afetados.\u003c/li\u003e\n\u003cli\u003eImplemente a função de coleta usando uma única palavra-chave e dados de amostra fixos.\u003c/li\u003e\n\u003cli\u003eTeste separadamente a remoção de duplicatas e a classificação de impacto.\u003c/li\u003e\n\u003cli\u003eValide o e-mail por meio de uma pré-visualização local, em vez de enviá-lo de fato.\u003c/li\u003e\n\u003cli\u003eDepois que os testes passarem, adicione a integração com o provedor real e a execução agendada.\u003c/li\u003e\n\u003c/ol\u003e\n\u003cp\u003eA primeira solicitação pode ser limitada da seguinte forma.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003eExecute apenas a etapa 1 agora.\n\u003c/span\u003e\u003cspan\u003eExamine o repositório e informe:\n\u003c/span\u003e\u003cspan\u003e- O ponto de entrada da aplicação atual\n\u003c/span\u003e\u003cspan\u003e- Os módulos e arquivos de teste relacionados\n\u003c/span\u003e\u003cspan\u003e- Os comandos usados para gerenciamento de pacotes e testes\n\u003c/span\u003e\u003cspan\u003e- Os arquivos que provavelmente precisarão ser alterados\n\u003c/span\u003e\u003cspan\u003e- As questões que devem ser decididas antes da implementação\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eAinda não modifique os arquivos.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003eDepois de revisar o plano, implemente restringindo o escopo da alteração.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003eDo plano aprovado, implemente apenas a coleta de notícias\n\u003c/span\u003e\u003cspan\u003ee a remoção de duplicatas.\n\u003c/span\u003e\u003cspan\u003eNão adicione classificação, envio de e-mail nem execução agendada.\n\u003c/span\u003e\u003cspan\u003ePermita a execução com dados de teste fixos e, ao final,\n\u003c/span\u003e\u003cspan\u003eresuma os arquivos modificados e os resultados dos testes executados.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003eSe for possível usar um modo exclusivo de planejamento no ambiente do Claude Code, ele poderá ser utilizado nas etapas de exploração e projeto. No entanto, o fato de um plano parecer plausível não significa que a implementação esteja correta, portanto testes reais e revisão de código devem ser realizados em seguida.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#princ%C3%ADpio-5-forne%C3%A7a-feedback-com-casos-de-falha-e-n%C3%BAmeros\" class=\"anchor\" id=\"princípio-5-forneça-feedback-com-casos-de-falha-e-números\"\u003e\u003c/a\u003ePrincípio 5. Forneça feedback com casos de falha e números\u003c/h2\u003e\n\u003cp\u003eÉ difícil definir a direção da correção com comentários como \u003ccode\u003eo resultado não está bom\u003c/code\u003e, \u003ccode\u003eo desempenho está lento\u003c/code\u003e ou \u003ccode\u003ea classificação está errada\u003c/code\u003e. É preciso informar o estado atual, o estado esperado, a entrada de reprodução e o intervalo aceitável de alterações.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#solicita%C3%A7%C3%A3o-de-ajuste-de-tamanho\" class=\"anchor\" id=\"solicitação-de-ajuste-de-tamanho\"\u003e\u003c/a\u003eSolicitação de ajuste de tamanho\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003eAtualmente, o corpo do e-mail é gerado com cerca de 3.000 caracteres.\n\u003c/span\u003e\u003cspan\u003eQuero reduzi-lo para no máximo 500 caracteres para que possa ser lido rapidamente no celular.\n\u003c/span\u003e\u003cspan\u003eLimite o resumo de cada notícia a 1 ou 2 frases e mantenha o motivo da avaliação.\n\u003c/span\u003e\u003cspan\u003eAssocie a URL original ao título e remova a linha separada do link.\n\u003c/span\u003e\u003cspan\u003eMantenha as estatísticas no rodapé.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003ch3\u003e\n\u003ca href=\"#solicita%C3%A7%C3%A3o-de-ajuste-dos-crit%C3%A9rios-de-classifica%C3%A7%C3%A3o\" class=\"anchor\" id=\"solicitação-de-ajuste-dos-critérios-de-classificação\"\u003e\u003c/a\u003eSolicitação de ajuste dos critérios de classificação\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003eDos 10 itens dos dados de teste, 8 foram classificados como 'alto'.\n\u003c/span\u003e\u003cspan\u003eClassifique perspectivas tecnológicas de longo prazo\n\u003c/span\u003e\u003cspan\u003eou apresentações gerais de produtos como 'baixo'.\n\u003c/span\u003e\u003cspan\u003eClassifique como 'alto' somente quando houver evidências concretas\n\u003c/span\u003e\u003cspan\u003ede que será necessário mudar, dentro de 3 meses, uma decisão sobre preços,\n\u003c/span\u003e\u003cspan\u003eroadmap do produto, resposta regulatória ou parceria.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eNos casos anexados, A e B devem ser classificados como alto, e C como baixo.\n\u003c/span\u003e\u003cspan\u003eCorrija as regras de classificação e adicione esses casos como testes de regressão.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003ch3\u003e\n\u003ca href=\"#solicita%C3%A7%C3%A3o-de-ajuste-de-desempenho\" class=\"anchor\" id=\"solicitação-de-ajuste-de-desempenho\"\u003e\u003c/a\u003eSolicitação de ajuste de desempenho\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003eO tempo médio atual de execução com a mesma entrada de amostra é de cerca de 45 segundos.\n\u003c/span\u003e\u003cspan\u003eA meta é no máximo 30 segundos no mesmo ambiente.\n\u003c/span\u003e\u003cspan\u003ePrimeiro, meça o tempo de cada etapa e mostre o gargalo.\n\u003c/span\u003e\u003cspan\u003eNão remova a precisão dos resultados nem o tratamento de erros;\n\u003c/span\u003e\u003cspan\u003ecompare os efeitos e os riscos das alternativas de melhoria\n\u003c/span\u003e\u003cspan\u003ee aplique primeiro a menor alteração.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003eOs números de desempenho só podem ser comparados quando o ambiente de medição e os dados de entrada são os mesmos. Não considere que houve melhoria com base no resultado de uma única execução; fixe também o método de medição, a amostra e o estado do cache.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#princ%C3%ADpio-6-use-modelos-de-prompt-por-tipo-de-tarefa\" class=\"anchor\" id=\"princípio-6-use-modelos-de-prompt-por-tipo-de-tarefa\"\u003e\u003c/a\u003ePrincípio 6. Use modelos de prompt por tipo de tarefa\u003c/h2\u003e\n\u003ch3\u003e\n\u003ca href=\"#modelo-para-criar-um-novo-agente\" class=\"anchor\" id=\"modelo-para-criar-um-novo-agente\"\u003e\u003c/a\u003eModelo para criar um novo agente\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e[Função e situação]\n\u003c/span\u003e\u003cspan\u003eSou {profissão/função} e quero resolver {situação problemática}.\n\u003c/span\u003e\u003cspan\u003eEste resultado será usado por {usuário ou sistema posterior}.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[Objetivo]\n\u003c/span\u003e\u003cspan\u003e{resultado a ser alcançado e critérios de sucesso}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[Gatilho de execução]\n\u003c/span\u003e\u003cspan\u003e{execução manual, evento, horário agendado etc.}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[Entrada]\n\u003c/span\u003e\u003cspan\u003e- Fonte de dados: {arquivo/API/banco de dados}\n\u003c/span\u003e\u003cspan\u003e- Campos obrigatórios: {lista de campos}\n\u003c/span\u003e\u003cspan\u003e- Método de autenticação: {variável de ambiente ou método de gerenciamento de segredos}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[Lógica de processamento]\n\u003c/span\u003e\u003cspan\u003e1. {etapa 1}\n\u003c/span\u003e\u003cspan\u003e2. {etapa 2}\n\u003c/span\u003e\u003cspan\u003e3. {etapa 3}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[Contrato de saída]\n\u003c/span\u003e\u003cspan\u003e{formato de arquivo, esquema, modelo, regras de classificação e dados ausentes}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[Tratamento de exceções]\n\u003c/span\u003e\u003cspan\u003e{resultado vazio, tempo limite, erro de autenticação, política de falha parcial}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[Restrições e não objetivos]\n\u003c/span\u003e\u003cspan\u003e- Tecnologias a manter: {itens}\n\u003c/span\u003e\u003cspan\u003e- Proibições: {itens}\n\u003c/span\u003e\u003cspan\u003e- Funcionalidades excluídas desta tarefa: {itens}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[Validação]\n\u003c/span\u003e\u003cspan\u003e- Testes que devem passar: {itens}\n\u003c/span\u003e\u003cspan\u003e- Conteúdo do relatório de conclusão: arquivos alterados, comandos executados,\n\u003c/span\u003e\u003cspan\u003e  resultados dos testes, riscos restantes\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003ePrimeiro, examine o repositório e apresente um plano de implementação.\n\u003c/span\u003e\u003cspan\u003eNão presuma informações desconhecidas; faça perguntas.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003ch3\u003e\n\u003ca href=\"#modelo-para-adicionar-uma-funcionalidade-existente\" class=\"anchor\" id=\"modelo-para-adicionar-uma-funcionalidade-existente\"\u003e\u003c/a\u003eModelo para adicionar uma funcionalidade existente\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003eAdicione {nova funcionalidade} ao {nome do agente ou módulo} existente.\n\u003c/span\u003e\u003cspan\u003eA nova funcionalidade deve ser executada depois de {etapa existente A}\n\u003c/span\u003e\u003cspan\u003ee antes de {etapa existente B}.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eLógica detalhada:\n\u003c/span\u003e\u003cspan\u003e- {condições e regras de processamento}\n\u003c/span\u003e\u003cspan\u003e- {formato de entrada e saída}\n\u003c/span\u003e\u003cspan\u003e- {comportamento em caso de falha}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eCondições de manutenção:\n\u003c/span\u003e\u003cspan\u003e- Não alterar a interface pública nem o formato de configuração existentes.\n\u003c/span\u003e\u003cspan\u003e- Manter todos os testes existentes.\n\u003c/span\u003e\u003cspan\u003e- Não modificar arquivos não relacionados.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003ePrimeiro, explique o escopo do impacto e os riscos de regressão.\n\u003c/span\u003e\u003cspan\u003eEm seguida, adicione testes que preservem o comportamento existente e implemente a funcionalidade.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003ch3\u003e\n\u003ca href=\"#modelo-para-corre%C3%A7%C3%A3o-de-erros\" class=\"anchor\" id=\"modelo-para-correção-de-erros\"\u003e\u003c/a\u003eModelo para correção de erros\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003eReproduza o erro a seguir e corrija sua causa raiz.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eMensagem de erro completa:\n\u003c/span\u003e\u003cspan\u003e{mensagem de erro e rastreamento de pilha após remover informações secretas e pessoais}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eCondições de ocorrência:\n\u003c/span\u003e\u003cspan\u003e- Comando de execução: {comando}\n\u003c/span\u003e\u003cspan\u003e- Entrada: {entrada mínima para reprodução}\n\u003c/span\u003e\u003cspan\u003e- Ambiente: {sistema operacional, runtime, versões relacionadas}\n\u003c/span\u003e\u003cspan\u003e- Momento da ocorrência: {em qual etapa}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eComportamento esperado:\n\u003c/span\u003e\u003cspan\u003e{resultado que deveria aparecer em condições normais}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eComportamento real:\n\u003c/span\u003e\u003cspan\u003e{resultado observado atualmente}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eSolicitação:\n\u003c/span\u003e\u003cspan\u003e1. Primeiro, reproduza o erro.\n\u003c/span\u003e\u003cspan\u003e2. Explique a causa com base em evidências.\n\u003c/span\u003e\u003cspan\u003e3. Corrija-o com o menor escopo possível.\n\u003c/span\u003e\u003cspan\u003e4. Adicione um teste de regressão que impeça o mesmo erro.\n\u003c/span\u003e\u003cspan\u003e5. Informe os testes executados e os riscos restantes.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003eAo colar uma mensagem de erro, é preciso remover informações sensíveis, como chaves de API, tokens de sessão, dados de clientes e endereços internos.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#exemplo-completo-solicita%C3%A7%C3%A3o-de-um-agente-de-briefing-de-not%C3%ADcias\" class=\"anchor\" id=\"exemplo-completo-solicitação-de-um-agente-de-briefing-de-notícias\"\u003e\u003c/a\u003eExemplo completo: solicitação de um agente de briefing de notícias\u003c/h2\u003e\n\u003cp\u003eO exemplo a seguir combina os seis princípios em uma única solicitação.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003eSou responsável pelo desenvolvimento de negócios de uma startup de SaaS.\n\u003c/span\u003e\u003cspan\u003eQuero verificar diariamente apenas as notícias sobre mudanças nos mercados\n\u003c/span\u003e\u003cspan\u003ede AI, computação em nuvem e fintech que possam alterar, dentro de 3 meses,\n\u003c/span\u003e\u003cspan\u003edecisões sobre produtos ou parcerias.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eExamine o repositório atual e projete uma ferramenta de briefing de notícias.\n\u003c/span\u003e\u003cspan\u003eNa primeira etapa, implemente apenas a funcionalidade que lê uma amostra JSON,\n\u003c/span\u003e\u003cspan\u003eremove duplicatas, classifica o impacto e cria um arquivo HTML de pré-visualização.\n\u003c/span\u003e\u003cspan\u003ePesquisa na web, envio real de e-mail e execução agendada estão excluídos desta etapa.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eCampos de entrada:\n\u003c/span\u003e\u003cspan\u003e- title, url, source, published_at, body\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eRegras de processamento:\n\u003c/span\u003e\u003cspan\u003e- Considere como duplicatas as URLs normalizadas que forem iguais.\n\u003c/span\u003e\u003cspan\u003e- Mesmo que as URLs sejam diferentes, marque como candidatas a duplicatas\n\u003c/span\u003e\u003cspan\u003e  as notícias com títulos semelhantes.\n\u003c/span\u003e\u003cspan\u003e- Classifique como impacto 'alto' apenas notícias que exijam mudanças concretas,\n\u003c/span\u003e\u003cspan\u003e  dentro de 3 meses, em preços, resposta regulatória, roadmap do produto\n\u003c/span\u003e\u003cspan\u003e  ou decisões sobre parcerias.\n\u003c/span\u003e\u003cspan\u003e- Se não houver evidências suficientes, não presuma uma classificação alta.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eSaída:\n\u003c/span\u003e\u003cspan\u003e- Exibir título, resumo de 1 a 2 frases, impacto, motivo da avaliação, fonte e URL.\n\u003c/span\u003e\u003cspan\u003e- Ordenar em ordem decrescente de impacto.\n\u003c/span\u003e\u003cspan\u003e- Exibir no rodapé o total de itens, o número de duplicatas removidas\n\u003c/span\u003e\u003cspan\u003e  e a quantidade por classificação.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eTratamento de exceções:\n\u003c/span\u003e\u003cspan\u003e- Não excluir itens sem campos obrigatórios; registrá-los em uma lista de erros separada.\n\u003c/span\u003e\u003cspan\u003e- Não estimar datas inválidas; mantê-las como null.\n\u003c/span\u003e\u003cspan\u003e- Não registrar nos logs o texto integral das notícias nem informações de autenticação.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eValidação:\n\u003c/span\u003e\u003cspan\u003e- Testar entrada normal, entrada vazia, URL duplicada, data inválida\n\u003c/span\u003e\u003cspan\u003e  e ausência de campos obrigatórios.\n\u003c/span\u003e\u003cspan\u003e- Se houver testes existentes, todos deverão passar.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eOrdem de trabalho:\n\u003c/span\u003e\u003cspan\u003e1. Examinar a estrutura do repositório e os arquivos relacionados.\n\u003c/span\u003e\u003cspan\u003e2. Apresentar os arquivos a serem modificados e o plano de testes.\n\u003c/span\u003e\u003cspan\u003e3. Não alterar o código antes que eu revise o plano.\n\u003c/span\u003e\u003cspan\u003e4. Após a aprovação, implementar a funcionalidade mínima e informar os resultados dos testes.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003eEssa solicitação não exige que todas as funcionalidades necessárias sejam implantadas de uma só vez no ambiente operacional. O escopo é limitado, e o significado da saída, o tratamento de falhas e os itens de teste são definidos em conjunto, facilitando a avaliação do resultado.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#crit%C3%A9rios-de-qualidade-f%C3%A1ceis-de-ignorar-quando-se-depende-apenas-do-prompt\" class=\"anchor\" id=\"critérios-de-qualidade-fáceis-de-ignorar-quando-se-depende-apenas-do-prompt\"\u003e\u003c/a\u003eCritérios de qualidade fáceis de ignorar quando se depende apenas do prompt\u003c/h2\u003e\n\u003cp\u003eMuitas orientações sobre vibe coding se concentram em escrever instruções mais detalhadas. No entanto, outros elementos que determinam a qualidade real são \u003cstrong\u003ecapacidade de validação, controle de alterações, observabilidade e limites de segurança\u003c/strong\u003e.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#1-transforme-crit%C3%A9rios-de-aceita%C3%A7%C3%A3o-em-testes\" class=\"anchor\" id=\"1-transforme-critérios-de-aceitação-em-testes\"\u003e\u003c/a\u003e1. Transforme critérios de aceitação em testes\u003c/h3\u003e\n\u003cp\u003eEm vez de dizer \u003ccode\u003efaça funcionar bem\u003c/code\u003e, forneça pares de entrada e saída esperada. Mantenha casos importantes de classificação como testes de regressão para verificar se o resultado continua preservado nas alterações posteriores.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#2-n%C3%A3o-use-a-autoavalia%C3%A7%C3%A3o-do-agente-como-evid%C3%AAncia-final\" class=\"anchor\" id=\"2-não-use-a-autoavaliação-do-agente-como-evidência-final\"\u003e\u003c/a\u003e2. Não use a autoavaliação do agente como evidência final\u003c/h3\u003e\n\u003cp\u003eO agente dizer que \u003ccode\u003econcluiu\u003c/code\u003e é diferente de os testes terem passado. Solicite que ele informe os comandos executados, os resultados dos testes, os arquivos alterados e os riscos não resolvidos, e uma pessoa deve revisar o diff.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#3-minimize-permiss%C3%B5es-e-informa%C3%A7%C3%B5es-secretas\" class=\"anchor\" id=\"3-minimize-permissões-e-informações-secretas\"\u003e\u003c/a\u003e3. Minimize permissões e informações secretas\u003c/h3\u003e\n\u003cp\u003eNão forneça de uma só vez acesso a diretórios desnecessários, bancos de dados de produção e credenciais de implantação. Não insira chaves de API diretamente no prompt ou no repositório; use variáveis de ambiente ou um sistema aprovado de gerenciamento de segredos. Não conceda acesso a repositórios sensíveis para servidores MCP ou scripts de origem desconhecida.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#4-exija-c%C3%B3digo-observ%C3%A1vel\" class=\"anchor\" id=\"4-exija-código-observável\"\u003e\u003c/a\u003e4. Exija código observável\u003c/h3\u003e\n\u003cp\u003eEm tarefas automatizadas, registre informações necessárias para identificar a causa das falhas, como o estado de cada etapa, erros estruturados, tempo de execução e número de itens processados. Por outro lado, remova dos logs informações de autenticação e dados pessoais.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#5-torne-as-altera%C3%A7%C3%B5es-revers%C3%ADveis\" class=\"anchor\" id=\"5-torne-as-alterações-reversíveis\"\u003e\u003c/a\u003e5. Torne as alterações reversíveis\u003c/h3\u003e\n\u003cp\u003eNão misture refatorações não relacionadas e adições de funcionalidades em uma mesma alteração. Revisar o diff em pequenas unidades e registrar as mudanças no controle de versão facilita isolar e reverter alterações incorretas.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#dicas-para-operar-projetos-com-claude-code\" class=\"anchor\" id=\"dicas-para-operar-projetos-com-claude-code\"\u003e\u003c/a\u003eDicas para operar projetos com Claude Code\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003eRegistre regras recorrentes do projeto no \u003ccode\u003eCLAUDE.md\u003c/code\u003e de forma breve e concreta.\u003c/li\u003e\n\u003cli\u003eForneça comandos de build, teste e lint em uma forma que possa realmente ser executada.\u003c/li\u003e\n\u003cli\u003eNão coloque informações secretas, logs de erros ocasionais nem documentos de referência longos no \u003ccode\u003eCLAUDE.md\u003c/code\u003e.\u003c/li\u003e\n\u003cli\u003eAntes de grandes alterações, solicite primeiro uma análise dos arquivos relacionados e das dependências.\u003c/li\u003e\n\u003cli\u003eAo adicionar um novo pacote, revise sua necessidade, licença e riscos de manutenção.\u003c/li\u003e\n\u003cli\u003eNão aprove automaticamente comandos perigosos de exclusão, implantação ou alteração de dados.\u003c/li\u003e\n\u003cli\u003eAntes de conectar uma API externa ou MCP, verifique para onde os dados serão enviados.\u003c/li\u003e\n\u003cli\u003eAo concluir, solicite um resumo dos arquivos alterados, comandos executados, resultados dos testes e limitações restantes.\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2\u003e\n\u003ca href=\"#checklist-antes-do-envio\" class=\"anchor\" id=\"checklist-antes-do-envio\"\u003e\u003c/a\u003eChecklist antes do envio\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003e O usuário e a situação de uso estão explicados?\u003c/li\u003e\n\u003cli\u003e Os objetivos e não objetivos estão separados?\u003c/li\u003e\n\u003cli\u003e As tecnologias existentes e o escopo no qual alterações são proibidas estão especificados?\u003c/li\u003e\n\u003cli\u003e Os dados de entrada e o formato de saída estão definidos?\u003c/li\u003e\n\u003cli\u003e O significado dos valores de classificação e de status está explicado?\u003c/li\u003e\n\u003cli\u003e Existem políticas para resultados vazios, falhas de autenticação, tempo limite e falhas parciais?\u003c/li\u003e\n\u003cli\u003e O planejamento e a implementação estão separados por etapas?\u003c/li\u003e\n\u003cli\u003e Existem testes para casos normais, extremos e de falha?\u003c/li\u003e\n\u003cli\u003e Informações secretas e dados pessoais estão excluídos do prompt e dos logs?\u003c/li\u003e\n\u003cli\u003e Foram solicitados um diff para revisão humana e evidências de execução?\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003eO essencial de um bom prompt para Claude Code não é escrever comandos longos. É reduzir o que o agente precisa inferir e permitir que terceiros também reproduzam e avaliem se o resultado está correto.\u003c/p\u003e\n","tags":["Engenharia de prompts","Engenharia de harness","Claude Code","Programação com IA","Agente de programação"],"faqs":[{"question":"Quanto mais longo o prompt do Claude Code, melhor?","answer":"Mais importante do que o tamanho é se as informações necessárias para a tarefa estão estruturadas. O contexto, o objetivo, as restrições, o contrato de saída, o tratamento de exceções e os critérios de conclusão devem ser descritos de forma específica, mas é melhor remover explicações irrelevantes e instruções repetidas."},{"question":"Não posso pedir que ele crie o programa inteiro desde o início?","answer":"Isso é possível no caso de uma ferramenta pequena e independente, mas é mais seguro desenvolver por etapas quando a tarefa envolve API externa, banco de dados, e-mail e execução agendada. Analisar primeiro o repositório e o plano e depois expandir na ordem de funcionalidade mínima, testes e integrações externas facilita isolar as causas das falhas."},{"question":"Posso pular os testes se usar o Plan Mode?","answer":"Não. O modo de planejamento é útil para analisar a estrutura e a abordagem antes das alterações, mas não comprova a exatidão do código real. Após a implementação, é necessário realizar separadamente testes automatizados, análise estática, revisão das alterações e as verificações manuais necessárias."},{"question":"O que devo escrever no CLAUDE.md?","answer":"É apropriado incluir instruções recorrentes em várias tarefas, como a estrutura do projeto, regras de codificação, comandos de compilação e teste e áreas que não devem ser modificadas. É melhor não incluir chaves de API, senhas, dados pessoais, descrições de tarefas pontuais nem materiais de referência excessivamente longos."},{"question":"Quais informações devo fornecer em uma solicitação de correção de erro?","answer":"É necessário fornecer em conjunto a mensagem de erro e o rastreamento de pilha sem informações confidenciais, o comando de execução, a entrada mínima para reprodução, o ambiente relevante, o comportamento real e o comportamento esperado. Também é recomendável solicitar uma explicação da causa, uma correção de escopo mínimo, testes de regressão e os resultados da execução."},{"question":"Posso fornecer uma chave de API ao Claude Code no prompt?","answer":"Como regra, não se deve registrar uma chave de API real diretamente no prompt nem no código-fonte. Use variáveis de ambiente aprovadas ou um sistema de gerenciamento de segredos e garanta que as informações de autenticação também não sejam expostas nos logs nem nos resultados dos testes."},{"question":"É obrigatório especificar no prompt o número de tentativas e o tempo de espera?","answer":"No caso de automação operacional, é importante distinguir entre erros que permitem nova tentativa e erros que exigem interrupção imediata. No entanto, o número específico de tentativas e o tempo de espera devem ser definidos após verificar os limites do serviço externo, a urgência da tarefa e o risco de processamento duplicado, e não se deve tentar novamente de forma indiscriminada em todos os erros."},{"question":"Como posso determinar se o código gerado está concluído?","answer":"Isso é determinado com base nos critérios de aceitação definidos previamente. É necessário verificar se os testes das funcionalidades obrigatórias e dos casos excepcionais foram aprovados, os comandos executados, os arquivos alterados e se as restrições de desempenho ou segurança foram atendidas, além de uma pessoa revisar as alterações no código."}],"sources":[{"url":"https://docs.anthropic.com/en/docs/claude-code/overview","title":"Visão geral do Claude Code","type":"source"},{"url":"https://www.anthropic.com/engineering/claude-code-best-practices","title":"Claude Code: melhores práticas para programação agêntica","type":"source"},{"url":"https://github.com/anthropics/claude-code","title":"Repositório do Anthropic Claude Code no GitHub","type":"source"}],"images":[{"id":845,"url":"https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MTExNTQsInB1ciI6ImJsb2JfaWQifX0=--9f2d2e2c8a61fc294a6019e4807ece297f36e85a/ai-4caeb237.webp","is_representative":true,"generation_method":"ai_photo","license":"ai_generated","mime_type":"image/webp","translations":{"ko":{"alt":"코드와 작업 흐름이 표시된 대형 모니터 앞에서 작업하는 개발자","caption":"개발자가 여러 화면의 코드와 문서를 검토하며 작업하고 있다.","description":null},"en":{"alt":"Developer working at a desk with code and a workflow diagram on a large monitor","caption":"A developer reviews code and documentation across multiple screens.","description":null},"ja":{"alt":"コードとワークフロー図を映した大型モニターの前で作業する開発者","caption":"開発者が複数の画面でコードとドキュメントを確認している。","description":null},"es":{"alt":"Desarrollador trabajando frente a un monitor grande con código y un diagrama de flujo","caption":"Un desarrollador revisa código y documentación en varias pantallas.","description":null},"id":{"alt":"Pengembang bekerja di depan monitor besar yang menampilkan kode dan diagram alur kerja","caption":"Seorang pengembang meninjau kode dan dokumentasi di beberapa layar.","description":null},"pt":{"alt":"Desenvolvedor trabalhando diante de um monitor grande com código e diagrama de fluxo","caption":"Um desenvolvedor analisa código e documentação em várias telas.","description":null},"zh-hant":{"alt":"開發人員在顯示程式碼與工作流程圖的大型螢幕前工作","caption":"開發人員正透過多個螢幕檢視程式碼與文件。","description":null},"de":{"alt":"Entwickler vor einem großen Monitor mit Code und einem Ablaufdiagramm","caption":"Ein Entwickler prüft Code und Dokumentation auf mehreren Bildschirmen.","description":null}}},{"id":846,"url":"https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MTExNjAsInB1ciI6ImJsb2JfaWQifX0=--285d7ecdc8209e07e0fc4eb68085cd8a304b9a81/ai-062b34c5.webp","is_representative":false,"generation_method":"ai_image","license":"ai_generated","mime_type":"image/webp","translations":{"ko":{"alt":"코드 편집기가 열린 노트북과 요구사항, 표, 오류, 버전 관리, 성과 차트를 연결한 개발 워크플로","caption":"체계적인 프롬프트가 코딩 결과물의 검증과 완성도를 높이는 과정을 보여준다.","description":null},"en":{"alt":"Laptop code editor connected to requirements, tables, errors, version control, and performance charts","caption":"The workflow shows how structured prompts support validation and more polished coding results.","description":null},"ja":{"alt":"要件、表、エラー、バージョン管理、成果グラフにつながるコードエディター搭載ノートPC","caption":"構造化されたプロンプトがコードの検証と完成度向上を支える流れを示している。","description":null},"es":{"alt":"Portátil con editor de código conectado a requisitos, tablas, errores, versiones y gráficos de rendimiento","caption":"El flujo muestra cómo los prompts estructurados ayudan a validar y perfeccionar el código.","description":null},"id":{"alt":"Laptop dengan editor kode yang terhubung ke spesifikasi, tabel, galat, kontrol versi, dan grafik kinerja","caption":"Alur ini menunjukkan bagaimana prompt terstruktur membantu validasi dan penyempurnaan hasil kode.","description":null},"pt":{"alt":"Notebook com editor de código ligado a requisitos, tabelas, erros, controle de versão e gráficos de desempenho","caption":"O fluxo mostra como prompts estruturados ajudam a validar e aprimorar os resultados do código.","description":null},"zh-hant":{"alt":"筆電程式碼編輯器連結需求、表格、錯誤、版本控制與成效圖表","caption":"此流程呈現結構化提示如何協助驗證程式碼並提升成果完成度。","description":null},"de":{"alt":"Laptop mit Code-Editor, verbunden mit Anforderungen, Tabellen, Fehlern, Versionskontrolle und Leistungsdiagrammen","caption":"Der Ablauf zeigt, wie strukturierte Prompts die Prüfung und Verfeinerung von Code unterstützen.","description":null}}}],"published_at":"2026-08-23T02:30:01+09:00","updated_at":"2026-08-23T02:30:01+09:00","license":"cc_by","translation_status":"reviewed","available_locales":["ko","en","ja","es"],"data_locales":["ko","en","ja","es","id","pt","zh-hant","de"],"url":"https://injoys.com/en/articles/claude-code-prompt-six-principles-and-templates"}