Programação de IA com 4D e VS Code: Um guia prático

Se assistiu recentemente ao nosso webinar sobre programação de IA com o 4D 21, viu como criámos uma aplicação completa de agência de viagens (estrutura da base de dados, dados, formulários e uma funcionalidade baseada em IA) desenvolvida quase inteiramente através de comandos em linguagem natural. Nesta publicação, vamos guiá-lo pelo processo de configuração e mostrar-lhe como aplicar esse mesmo fluxo de trabalho aos seus próprios projetos.

O que precisa

• 4D 21 (ou posterior)
• Visual Studio Code com o GitHub Copilot ativado (ver configuração abaixo)
• A extensão 4D Analyzer (ver abaixo)
• Um conjunto de ficheiros de instruções adaptados ao desenvolvimento 4D (ver abaixo)

Configuração do GitHub Copilot

Antes de mais nada: o GitHub Copilot funciona através da sua conta GitHub, não diretamente através da OpenAI, da Anthropic ou de qualquer outro fornecedor de IA. Não precisa de comprar créditos no Claude ou em qualquer outro serviço. Tudo é gerido através do GitHub.

1. Crie uma conta no GitHub, caso ainda não tenha uma: github.com

2. Ative o GitHub Copilot na sua conta em github.com/features/copilot. Está incluído um plano gratuito com uma generosa quota mensal, não sendo necessário cartão de crédito para começar.

3. Inicie sessão a partir do VS Code. Abra o VS Code, clique no ícone Contas no canto inferior esquerdo e inicie sessão com a sua conta GitHub. Uma vez conectado, o ícone do Copilot aparece na barra de estado e o Chat fica disponível.

4. Selecione o seu modelo. No painel do Chat do Copilot, um seletor de modelos permite-lhe escolher qual o modelo de IA que alimenta as suas respostas (GPT-4o, Claude, Gemini e outros, dependendo do seu plano). A configuração padrão funciona bem para começar; pode mudar mais tarde.

Para verificar a utilização e gerir o seu plano: Aceda a github.com/settings/copilot. Pode ver quantos pedidos já utilizou, mudar para um plano pago e gerir a faturação se precisar de mais capacidade.

A extensão 4D Analyzer

A extensão 4D Analyzer é o que torna o VS Code verdadeiramente compatível com a linguagem 4D. Instale-a a partir do VS Code Marketplace e terá:

• Coloração de sintaxe para código 4D: métodos, classes, classes de formulário, etc.
• Autocompletar código e ajuda com assinaturas
• Diagnósticos (erros e avisos) em tempo real enquanto escreve

Isto é muito importante quando se trabalha com IA. Quando o GitHub Copilot gera código 4D, o Analyzer valida-o imediatamente. Vê os erros destacados diretamente no editor, o que significa que pode detetar erros antes mesmo de tentar executar o código e enviá-los de volta ao Copilot para obter uma correção.

Para instalar:

1. Abra o VS Code
2. Vá para o painel Extensões (Cmd+Shift+X no macOS, Ctrl+Shift+X no Windows)
3. Procure por “4D Analyzer”
4. Clique em Instalar

E pronto. Abra qualquer pasta de projeto 4D e a extensão ativa-se automaticamente.

Ficheiros de instruções: ensinar o Copilot a escrever código 4D

Por padrão, o GitHub Copilot conhece muitas linguagens de programação, mas não o seu estilo de codificação, as suas melhores práticas ou os pormenores do desenvolvimento 4D. É aí que entram os ficheiros de instruções.

Os ficheiros de instruções são documentos Markdown colocados numa pasta .github/instructions/ na raiz do seu projeto. O Copilot lê-os automaticamente e utiliza-os como contexto para todas as respostas. Pense neles como um guia de estilo que a IA segue.

Onde os obter

Está disponível no GitHub um conjunto de ficheiros de instruções 4D prontos a usar:

👉 github.com/mathieu-ferry/4D-github-instructions

Como configurá-los

1. Na raiz do seu projeto 4D, crie uma pasta .github/instructions/
2. Copie os ficheiros de instruções do repositório acima para essa pasta
3. Abra o Copilot Chat e pergunte: «Quais são as suas normas de codificação 4D?» e ele deverá responder com base no conteúdo dos seus ficheiros de instruções

Se isso acontecer, está tudo pronto. As instruções abrangem tópicos como:

• Preferência pelo uso de classes em vez de métodos procedurais
• Convenções de classes de formulários
• Referências de esquemas JSON para formulários e catálogos
• Convenções de nomenclatura e estrutura do código

Dica: Estes ficheiros são um ponto de partida. Os melhores resultados surgem quando os adapta aos seus próprios hábitos de codificação e convenções do projeto. Adicione as suas próprias regras, remova o que não se aplica e vá aperfeiçoando ao longo do tempo.

Juntando tudo: dois exemplos

Exemplo 1: Construir uma estrutura de base de dados com prompts

Quando trabalha com o editor de Estrutura, as alterações são refletidas no ficheiro 4DCatalog. Com os ficheiros de instruções do repositório GitHub, o Copilot pode editar com segurança este mesmo ficheiro por si (o contexto do esquema está incluído nessas instruções). Continua a ser orientado por prompts e, após o reinício, as alterações na estrutura ficam imediatamente visíveis no 4D. Aqui está uma sequência realista:

Você: «Crie uma tabela no catálogo que liste os funcionários com o seu apelido e nome próprio.»

O Copilot edita a sua estrutura. Reinicie o 4D e obterá uma tabela Employee com uma chave primária UUID e os campos solicitados.

Você: «Crie uma nova tabela que liste os departamentos da empresa.»

Aparece outra tabela.

Você: «Adicione uma relação entre funcionários e departamentos, com cada funcionário a pertencer a um departamento.»

O Copilot adiciona uma chave estrangeira e a definição de relação adequada. Você constrói um modelo relacional completo desta forma, passo a passo, apenas conversando com a IA.

A ideia principal: descreves a intenção em linguagem simples e a IA trata dos detalhes do catálogo. Os ficheiros de instruções mantêm o resultado alinhado com as tuas convenções esperadas (chaves UUID, tipos de atributos adequados, sintaxe de relação correta).

Exemplo 2: Criar um formulário e a sua classe

É nos formulários que as coisas ficam realmente interessantes. Pode descrever um layout numa única solicitação:

Você: «Cria um formulário 4D que liste tarefas. Quero uma caixa de lista no lado esquerdo com resumo, apelido do responsável, departamento, data de vencimento e estado. No lado direito, mostra uma vista detalhada com toda essa informação, além da descrição da tarefa e do gestor do departamento. Associa o formulário a uma classe de formulário.»

O Copilot gera:

• O JSON do formulário (form.4DForm) com a caixa de lista, campos de entrada e layout
• A classe do formulário (.4dm) com tratamento de eventos e lógica de ligação de dados

O resultado é um formulário funcional que pode abrir no 4D e começar a utilizar. Será perfeito ao primeiro tentativa? Provavelmente não. Mas dá-lhe uma base sólida para aperfeiçoar através de sugestões de acompanhamento ou ajustes manuais.

Aperfeiçoar o Design

O primeiro formulário gerado é uma base funcional, não um produto acabado. Existem várias formas de orientar o Copilot para um resultado melhor:

• Cole uma captura de ecrã para inspiração. Encontre uma interface de utilizador de que goste, cole-a no Copilot Chat e diga: «Redesenhe o formulário usando isto como referência visual.» O Copilot irá extrair padrões de layout, tons de cor e espaçamento da imagem.
• Dê um briefing de design preciso. Descreva a intenção, o tom e as restrições: «Redesenhe este formulário para um agente de viagens que precisa de processar e-mails rapidamente. Dê prioridade à densidade de informação, indicadores de estado de alto contraste e navegação fácil de usar com o teclado.»
• Especifique tokens de design explicitamente. Se tiver um sistema de design, introduza-o diretamente: «Use espaçamento base de 8px, fundos cinzentos neutros (#F5F5F5), azul (#1A73E8) para ações principais e vermelho/laranja/verde semânticos para o estado das tarefas.»
• Peça consistência com os formulários existentes. Em vez de começar do zero todas as vezes: «Torne este formulário visualmente consistente com o formulário de Funcionário existente: mesmo estilo de cabeçalho, hierarquia de botões e densidade das linhas da lista.»
• Codifique o seu estilo nos ficheiros de instruções. A abordagem mais duradoura. Defina a sua paleta de cores, regras de espaçamento e convenções de componentes da IU uma vez em .github/instructions/, e todos os formulários que o Copilot gerar seguirão essas regras automaticamente, sem necessidade de solicitação.

Modos de chat do Copilot: Perguntar, Planear e Agente

O Copilot Chat no VS Code tem três modos, selecionáveis a partir do seletor de agente na parte inferior do painel de chat:

• Perguntar: Apenas perguntas e respostas. Responde a perguntas sobre a sua base de código, conceitos de programação ou o VS Code sem tocar em nenhum ficheiro. Útil para compreender como algo funciona ou explorar ideias.
• Plan: Produz um plano de implementação estruturado e passo a passo utilizando uma análise da base de código apenas de leitura, antes de escrever uma única linha de código. Revela questões em aberto sobre requisitos ambíguos, para que possa esclarecer a intenção antecipadamente. Quando estiver satisfeito, um botão «Iniciar Implementação» transfere o plano diretamente para o modo Agente para execução.
• Agente: O cavalo de batalha da codificação. Edita ficheiros de forma autónoma em todo o seu projeto, executa comandos de terminal, invoca ferramentas e itera para corrigir erros até que a tarefa esteja concluída.

Todos os exemplos anteriores nesta publicação foram executados no modo Agente, que é a predefinição adequada para qualquer tarefa que modifique efetivamente o seu projeto.

Quando o Modo Plano Vale a Pena

Até agora, temos trabalhado de forma incremental: um prompt, uma alteração, revisão, repetição. Para trabalho exploratório ou adições rápidas, isso é perfeitamente eficiente. Mas para funcionalidades maiores que afetam vários componentes de uma só vez, vale a pena dar o passo extra do modo Plano.

O modo Plan lê a sua base de código antes de produzir qualquer coisa. O resultado é um resumo de alto nível dividido em etapas exequíveis, incluindo quaisquer questões que tenha sobre os seus requisitos. Itera sobre o plano numa conversa simples até que este reflita com precisão o que pretende e, em seguida, entrega-o ao Agent.

Isto é especialmente valioso em projetos 4D, onde uma única funcionalidade pode afetar o catálogo, um ou mais métodos ou classes, um formulário JSON, uma classe de formulário e ficheiros de recursos, tudo ao mesmo tempo. Detetar uma suposição errada na fase de planeamento é muito mais barato do que desfazer uma execução com vários ficheiros que seguiu na direção errada.

Como isto se traduz na prática

Em vez desta sequência incremental:

• “Adicionar uma tabela de e-mails”
• “Criar um formulário para e-mails”
• «Adicionar um botão para processar e-mails»
• «Escrever o método de processamento de IA»
• “Adicionar dados de amostra”

Pode escrever um único prompt bem estruturado que descreva a funcionalidade completa, executá-lo no Plan para validar a abordagem e, em seguida, deixar que o Agent o execute numa única passagem coordenada. Foi exatamente isso que fizemos no webinar ao criar a funcionalidade de IA de «e-mail para tarefa»: um grande prompt, abrangendo a tabela, o formulário, o botão, a lógica de processamento, a configuração da chave API e os dados de amostra, tudo de uma só vez.

Dicas para um fluxo de trabalho de IA eficiente

1. Adapte a sua abordagem à dimensão da tarefa. Prompts passo a passo funcionam bem quando está a explorar ou quando o âmbito não é claro, facilitando a revisão e a correção do rumo. Para funcionalidades bem definidas, um único prompt maior com o modo Plan é mais eficiente. A documentação do VS Code recomenda dividir tarefas complexas, mas também observa que incluir resultados esperados (quais ficheiros, qual comportamento) ajuda o agente a verificar o seu próprio trabalho.
2. Nomeie o que espera, não como fazê-lo. Para prompts maiores, listar os ficheiros, tabelas ou formulários que espera que sejam criados ajuda a reduzir as suposições. Evite especificar em excesso os detalhes de implementação: essa é a função do agente. O objetivo é definir limites claros, não escrever uma especificação.
3. Mantenha regras permanentes nos ficheiros de instruções e o contexto pontual no prompt. Convenções, regras de nomenclatura e preferências arquitetónicas pertencem a .github/instructions/, não devem ser repetidas em cada prompt. De acordo com a documentação do VS Code, os ficheiros de instruções são carregados em cada interação, por isso mantenha-os focados no que a IA não consegue inferir apenas a partir do seu código.
4. Envie os erros de volta, com contexto para os que não forem óbvios. Colar um erro de tempo de execução diretamente no Copilot costuma ser suficiente para erros isolados. Para problemas de lógica ou arquitetura, indique também o ficheiro relevante ou explique o comportamento esperado; a mensagem de erro por si só não dará sinalização suficiente.
5. Use capturas de ecrã para diagnóstico visual. Anexar uma captura de ecrã é mais rápido do que descrever um problema de layout com palavras, e a documentação do VS Code lista-a como uma técnica de contexto recomendada. Nota: o suporte a imagens pode precisar de ser ativado, dependendo do seu plano do Copilot e das definições da organização.
6. Analise o resultado da IA: a barra varia de acordo com o que está em jogo. Para protótipos, basta uma leitura rápida. Para produção, trate-o como qualquer código contribuído: verifique a lógica, casos extremos, validação de entradas e tudo o que envolva serviços externos ou credenciais.
7. Mantenha os ficheiros de instruções concisos e atualizados. Instruções mais específicas produzem melhores resultados, mas os ficheiros de instruções são carregados em cada pedido. A documentação do VS Code aconselha a concentrar-se em aspetos que a IA não consegue inferir a partir do código: convenções não padrão, decisões arquitetónicas, especificidades do ambiente. Um ficheiro abrangente e sobrecarregado começa a diluir o sinal.

Aprofundando: Agentes e Competências Personalizadas

Tudo o que abordámos até agora utiliza os agentes integrados com ficheiros de instruções partilhados. Mas o VS Code permite-lhe agora ir mais longe, definindo os seus próprios agentes e competências personalizados, armazenados no seu projeto em .github/agents/.

Um agente personalizado é um ficheiro Markdown (.agent.md) que atribui à IA uma personalidade específica, restringe as ferramentas que esta pode utilizar e, opcionalmente, associa-a a um modelo específico. Por exemplo, pode criar um agente 4D-reviewer dedicado que se concentra exclusivamente na qualidade do código, exposição de segurança e convenções de nomenclatura para projetos 4D, utilizando ferramentas de leitura apenas para que nunca modifique nada, a menos que o solicite explicitamente. Ou um agente 4D-scaffolder pré-carregado com os seus modelos de formulários e classes, pronto para criar novos ecrãs a pedido.

As competências (ficheiros.skill.md ) vão um passo além: são capacidades reutilizáveis e portáteis que podem incluir scripts e aceder a recursos externos. Enquanto um ficheiro de instruções contém regras passivas, uma competência contém lógica ativa que o agente pode invocar. Um exemplo prático em 4D: uma competência que sabe consultar o site de documentação do 4D e recuperar exemplos de código relevantes diretamente para o chat.

A documentação do VS Code também descreve transferências: fluxos de trabalho encadeados em que um agente passa o contexto para o seguinte com um simples clique. Um agente de planeamento gera uma especificação de funcionalidade, depois transfere-a para um agente de implementação, que a transfere para um agente de revisão. Cada etapa é aprovada por um humano antes de ser executada.

Pode gerar tudo isto com IA diretamente no chat: digite /create-agent ou /create-skill e descreva o que pretende. Podem ser armazenados ao nível do espaço de trabalho (partilhados com a equipa através do controlo de código-fonte) ou no seu perfil de utilizador (pessoal, disponível em todos os projetos).

Para além da geração de código: outros fluxos de trabalho úteis da IA

A criação de funcionalidades é apenas uma das coisas que um agente de IA faz bem num fluxo de trabalho de desenvolvimento. Aqui estão outras situações em que o Copilot pode assumir uma carga significativa:

• Documentação. Peça ao agente para escrever ou atualizar documentação técnica a partir do código-fonte, gerar docstrings para métodos e classes, ou traduzir documentação existente para outro idioma. Especificamente para o 4D, isto pode significar gerar conteúdo de ajuda voltado para o utilizador a partir da lógica da classe de formulário, ou produzir uma referência de API estruturada a partir de um conjunto de métodos.
• Revisão de segurança. Peça ao agente para analisar um método, uma classe de formulário ou uma funcionalidade inteira em busca de vulnerabilidades comuns: entradas não validadas, falta de controlo de acesso, exposição a injeções SQL, credenciais codificadas. Um agente de segurança dedicado e de leitura apenas (ver acima) é a escolha natural aqui. Isto não substituirá uma auditoria de segurança adequada, mas é uma primeira verificação rápida.
• Refactoração. Os agentes de IA lidam bem com tarefas mecânicas de refactoração: renomear símbolos de forma consistente, extrair lógica repetida para métodos ou classes partilhadas, converter código procedural para padrões ORDA ou modernizar código 4D legado de acordo com as melhores práticas atuais.
• Explicação de código e integração. Use o modo Ask para compreender código desconhecido, rastrear o que um método faz ou obter um resumo em linguagem simples de uma parte complexa da lógica. Isto é especialmente útil ao assumir um projeto existente ou ao integrar novos membros da equipa.
• Geração de testes. Peça ao agente para escrever testes unitários para um determinado método ou classe, incluindo casos extremos e condições de erro. O Copilot também pode executar os testes após gerá-los e iterar se eles falharem.
• Mensagens de commit e descrições de PR. O VS Code inclui ações inteligentes integradas para gerar mensagens de commit a partir de alterações preparadas e resumos de pull requests. Pequenas poupanças de tempo que se somam.

O que se segue?

O fluxo de trabalho descrito nesta publicação já está disponível para si. Crie a sua primeira tabela e formulário através de prompts, utilize o modo Plan para abordar uma funcionalidade completa, refatore código legado, gere documentação, execute uma revisão de segurança, crie um agente personalizado para a sua equipa. A única coisa que falta é experimentá-lo.

Aqui está tudo o que precisa para começar:

1. Descarregue o 4D 21
2. Instale o VS Code com o GitHub Copilot ativado
3. Adicione a extensão 4D Analyzer
4. Copie os ficheiros de instruções para o seu projeto

Abra o modo Agent, descreva o que pretende construir e veja até onde consegue chegar.

Gostaríamos muito de saber a sua opinião. Partilhe os seus resultados, fluxos de trabalho e perguntas no Fórum 4D, a comunidade está à sua espera!