Este artigo faz parte da série “Plugin do Zero ao WP.org com IA”, onde documento a jornada real de criação do PAP Afiliados Pro — com acertos, erros e aprendizados.
No artigo anterior, contei que não sei programar e mesmo assim publiquei um plugin no WordPress.org. Algumas pessoas devem ter pensado: “Tá, ele usou o ChatGPT.” E estariam parcialmente certos — eu usei IA. Mas a forma como usei é o que faz toda a diferença. E é sobre isso que quero falar aqui.
Porque “usar IA para programar” virou uma frase tão genérica que já não diz mais nada. Todo mundo usa. Pede um código, copia, cola, reza para funcionar. Às vezes funciona. Na maioria das vezes, funciona por um tempo e depois vira uma dor de cabeça que ninguém sabe por onde começar a resolver.
O que eu fiz foi diferente. Não melhor por talento — melhor por necessidade. Eu precisava que funcionasse de verdade, passasse por revisão profissional, e fosse mantível no longo prazo. E para isso, uma IA sozinha não dava conta.
O problema que ninguém conta
A maioria dos tutoriais de “como usar IA para programar” mostra o caminho feliz: você pede, a IA entrega, funciona, parabéns. O que eles não mostram é o que acontece quando o projeto cresce.
Quando você tem 5 arquivos, uma IA consegue manter contexto. Quando você tem 20 classes PHP, um banco de dados com 4 tabelas, JavaScript no frontend, CSS customizado, e um sistema de templates — a IA perde o fio. Não por limitação de inteligência, mas por limitação de contexto. Cada conversa começa do zero. A IA não lembra do que você combinou ontem. Não sabe que aquela função que ela sugeriu às 14h conflita com a arquitetura que vocês definiram às 10h.
Eu descobri isso da forma mais cara: jogando fora semanas de trabalho porque o código tinha virado uma colcha de retalhos. Cada pedaço feito numa sessão diferente, com premissas diferentes, sem consciência do todo.
Foi aí que entendi: o problema não era a IA. O problema era eu. Eu estava usando uma ferramenta poderosa do jeito errado — como se fosse um programador freelancer que recebe demandas soltas. “Faz essa tela.” “Agora ajusta essa query.” “Adiciona validação aqui.” Sem projeto, sem arquitetura, sem memória.
A sacada: papéis diferentes para ferramentas diferentes
A virada veio quando parei de tratar “IA” como uma coisa só e comecei a pensar em termos de equipe. Numa equipe de desenvolvimento real, você tem papéis distintos: arquiteto, desenvolvedor, revisor de código, especialista em segurança. Cada um com competências diferentes, atuando em momentos diferentes do processo.
Olha só o que montei, na prática:
Claude Chat (este aqui, em sessões de projeto) assumiu o papel de arquiteto e consultor estratégico. É onde eu penso em voz alta, discuto alternativas, valido decisões de arquitetura, e defino a direção do projeto. Não peço código aqui — peço análise. “Se eu fizer assim, quais são os riscos?” “Essa abordagem viola alguma guideline do WordPress?” “Me ajuda a estruturar esse contrato técnico.”
CCW (Claude Code na Web, com acesso direto ao repositório GitHub) assumiu o papel de desenvolvedor implementador. Recebe prompts estruturados com contexto completo, documentação de referência, e instruções detalhadas. Implementa, comita, e valida contra os padrões definidos. É a mão que escreve o código.
Ferramentas especializadas entraram em momentos pontuais para problemas específicos — debug de CSS complexo, troubleshooting de conflitos entre JavaScript e WordPress, validação de acessibilidade. Quando o implementador travava num problema muito específico, eu buscava a ferramenta mais adequada para aquele tipo de desafio.
Três “profissionais” diferentes, três papéis claros, um fluxo de trabalho definido.
Como funciona na prática
Deixa eu mostrar um ciclo real de desenvolvimento. Eu precisava implementar o sistema de tracking de cliques — cada vez que um visitante clica num link de afiliado, o plugin precisa registrar esse clique com conformidade LGPD.
Passo 1: Análise com o Arquiteto (Claude Chat)
Antes de escrever qualquer código, discuti aqui a abordagem. Que dados capturar. Que dados não capturar (por LGPD). Como armazenar. Como limpar dados antigos automaticamente. Quais validações de segurança seriam obrigatórias. Qual o contrato técnico que o implementador deveria seguir.
Dessa conversa saiu um documento — o contrato de tracking — que especifica tudo: nome da tabela, campos, tipos, índices, nonces necessários, endpoints AJAX, sanitização de cada input, escaping de cada output.
Passo 2: Implementação com o Desenvolvedor (CCW)
Com o contrato pronto, montei um prompt estruturado para o CCW. Não um “me faz um sistema de tracking”. Um prompt que incluía: contexto do projeto, documentos de referência a consultar, requisitos de segurança obrigatórios, detalhes técnicos da implementação, e critérios de validação.
Esse prompt tinha uma seção que eu chamo de “Conformidade Obrigatória” — um checklist que o CCW precisa atender antes de considerar qualquer implementação como concluída. Nonces em todos os handlers. Capabilities em todas as operações admin. Inputs sanitizados. Outputs escapados. SQL preparado. Prefixos corretos. Text domain correto. Parece repetitivo? É intencional. Cada vez que essa lista aparece num prompt, reforça os padrões. É como um piloto de avião fazendo o checklist antes de decolar — não importa se já fez mil vezes, o checklist está lá porque o dia que pular é o dia que dá problema.
O CCW implementou, comitou direto no GitHub, e eu validei visualmente no meu WordPress local.
Passo 3: Validação e ajustes
Olhei o resultado. Funcionou? Sim. Mas o gráfico de estatísticas não estava renderizando direito no mobile. O Claude Chat não sabe resolver CSS de chart responsivo com eficiência — não é o forte dele. Usei uma ferramenta especializada em debug visual que identificou o conflito em minutos.
Voltei ao CCW com a correção pontual. Pronto.
Esse ciclo — análise → implementação → validação → correção pontual — se repetiu para cada funcionalidade do plugin. Template Builder, gestão de produtos, importação CSV, painel de estatísticas, sistema de presets. Sempre com a mesma lógica: pensar antes com o arquiteto, executar com o implementador, resolver pontos cegos com especialistas.
O segredo que não é segredo: documentação
Eu sei que mencionei isso no artigo anterior, mas preciso aprofundar porque é literalmente o que faz tudo funcionar. Sem documentação estruturada, essa orquestração de múltiplos AIs simplesmente não existe.
O motivo é simples: nenhuma dessas ferramentas tem memória entre sessões. O Claude Chat de hoje não sabe o que o Claude Chat de ontem decidiu. O CCW que implementou o Template Builder não lembra das decisões quando vai implementar o sistema de tracking. Cada sessão é uma folha em branco.
A documentação resolve isso. Ela é a memória do projeto.
No PAP Afiliados Pro, criei 16 documentos técnicos — eu chamo de “contratos” — que cobrem cada aspecto do sistema. Tem contrato para a camada de dados (tabelas, campos, relações). Contrato para o frontend (como os cards renderizam, quais variáveis estão disponíveis). Contrato para segurança (as 8 regras que o WordPress.org exige, com exemplos de código correto). Contrato para nomenclatura (prefixos, padrões, convenções). Contrato para o painel admin. Para tracking. Para estatísticas.
Quando inicio uma sessão com qualquer ferramenta, alimento com os contratos relevantes. A IA não precisa adivinhar o contexto. Sabe quais prefixos usar (papafpro), qual text domain (pap-afiliados-pro), como sanitizar inputs, como escapar outputs, quais tabelas existem, como se relacionam.
É a mesma lógica de quando você contrata um desenvolvedor novo numa empresa e entrega o handbook técnico para ele. Sem o handbook, ele vai tomar decisões baseadas em achismo. Com o handbook, ele opera dentro dos padrões do projeto desde o primeiro dia.
A diferença é que meu “desenvolvedor” muda a cada sessão. Então o handbook precisa ser impecável.
O que eu aprendi sobre prompt engineering de verdade
Tem uma lição que eu gostaria de ter aprendido antes e que teria me economizado aqueles 2 meses de versões descartadas: prompt engineering de verdade não é sobre escrever a frase perfeita. É sobre dar contexto suficiente para a IA tomar decisões boas.
No início, meus prompts eram assim: “Cria uma função PHP que salva um produto no banco de dados.” E a IA criava. Funcionava. Mas sem nonce. Sem sanitização. Com o prefixo errado. Porque eu não disse que precisava disso — e a IA não tinha como adivinhar os padrões do meu projeto.
Depois de muita tentativa e erro, meus prompts evoluíram para algo completamente diferente. Um prompt típico para o CCW tem: contexto do projeto, documentos de referência para consultar, seção de conformidade obrigatória (segurança, prefixos, text domain), detalhes da implementação, critérios de validação, e documentação a atualizar.
Parece burocrático? É. E funciona. Porque o prompt não é uma conversa casual — é uma especificação técnica disfarçada de texto. Quanto mais preciso o prompt, menos retrabalho depois.
Uma sacada específica que fez diferença: descobri que prompts arquiteturais funcionam melhor que prompts literais. Em vez de dizer “altere a linha 47 do arquivo X para adicionar esc_html()”, eu digo “garanta que todo output HTML neste componente está escapado conforme Regra #4 do contrato de segurança.” A IA é inteligente o suficiente para encontrar os pontos certos e aplicar a correção de forma consistente — e faz isso melhor quando entende a intenção do que quando recebe instrução mecânica.
O que esse modelo não resolve
Seria desonesto da minha parte pintar isso como solução perfeita. Não é. Tem limitações reais que preciso compartilhar para que ninguém entre com expectativa errada.
Primeiro: exige tempo. Criar 16 documentos técnicos antes de escrever uma linha de código parece — e é — um investimento alto. Nos primeiros dias, dá a sensação de que você está fazendo tudo menos o trabalho de verdade. Mas é o mesmo princípio de qualquer planejamento: tempo investido no começo economiza multiplicado no final. No meu caso, a versão final levou 6 dias porque os documentos já existiam. Sem eles, teria sido mais 2 meses de colcha de retalhos.
Segundo: exige capacidade de abstração. Você precisa conseguir descrever o que quer em termos técnicos, mesmo sem saber implementar. Isso vem de experiência, não de tutorial. No meu caso, foram 26 anos convivendo com sistemas, redes, banco de dados. Se você está começando do zero em tecnologia, a curva é mais íngreme.
Terceiro: a validação visual é essencial. Eu não leio código com profundidade — confio na IA para a correção sintática. Mas olho o resultado no navegador obsessivamente. Cada botão, cada card, cada transição, cada tela no celular. Se o visual não está certo, o código não está certo, não importa o que a IA diga.
Quarto: quando algo dá errado de forma sutil — um bug que só aparece em condição específica, uma race condition, um problema de cache — a depuração é mais difícil. Você precisa descrever o problema com precisão para que a IA encontre a causa. Isso é uma habilidade que se desenvolve com prática, mas que no início é frustrante.
Para quem quer tentar
Se você leu até aqui e está pensando “eu poderia fazer isso”, provavelmente pode. Mas deixa eu ser direto sobre o pré-requisito real: você precisa saber o que quer construir. Não em termos de código — em termos de problema e solução.
“Eu quero um plugin que exiba cards de produto com link de afiliado” é um bom começo. “Eu quero fazer alguma coisa com IA” não é.
A IA amplifica o que você já sabe. Se você entende o domínio do problema, ela acelera brutalmente. Se você não entende, ela gera código que parece correto mas resolve o problema errado. E isso é pior do que não ter código nenhum, porque cria uma falsa sensação de progresso.
O método que descrevi aqui — papéis definidos, documentação estruturada, prompts com contexto — não é a única forma de trabalhar com IA para desenvolvimento. Mas é a forma que funcionou para um não-programador criar algo que passou pela revisão mais rigorosa do ecossistema WordPress. E está documentado para que outros possam adaptar.
No próximo artigo, vou contar a parte menos glamorosa dessa jornada: quando o WordPress.org rejeitou meu plugin. E como 3 lições dolorosas me fizeram entender segurança de verdade.
Próximo artigo da série: WordPress.org rejeitou meu plugin por segurança — 3 lições que aprendi do jeito difícil
Navegação da série:
◀ Artigo anterior: Eu não sei programar. Mesmo assim criei e publiquei um plugin no WordPress.org — veja como
▶ Próximo artigo: WordPress.org rejeitou meu plugin por segurança — 3 lições que aprendi do jeito difícil