Delphi AI Skills: código Delphi correto gerado por IA

Escrever código ficou barato. O que custa caro, agora, é fazer com que ele nasça bem escrito: o delphi-ai-skills ensina aos agentes de IA (Claude Code, Codex, Cursor, Gemini) a API de verdade do DelphiMVCFramework, com diretrizes, estilo, segurança e testes embutidos.

A partir de hoje está público o delphi-ai-skills: um conjunto de skills open source (Apache-2.0) que ensinam aos agentes de IA de codificação a escrever código DelphiMVCFramework que compila, que segue as convenções certas e que já nasce seguro. Funciona com Claude Code, Codex, Cursor, Gemini CLI, Windsurf, Continue e com qualquer outra ferramenta capaz de ler instruções em Markdown.

Em resumo

• O que é: sete skills open source (Apache-2.0) que ensinam a um agente de IA a API real do DelphiMVCFramework 3.5.0, em vez de deixá-lo adivinhar.
• Para quem: quem escreve REST APIs, Minimal APIs ou aplicações web em Delphi com a ajuda de um agente de IA.
• Agentes suportados: Claude Code, Codex, Cursor, Gemini CLI, Windsurf, Continue, e qualquer agente que leia Markdown.
• Instalação: git clone, depois install_in_claude.bat (ou _codex, _cursor, _gemini).
• O que muda: nada de MapGroup no lugar de Prefix, nada de ToFree liberando duas vezes o objeto retornado, endpoints filtrados pelo usuário autenticado e testes de integração DUnitX de verdade.
• Repositório: github.com/danieleteti/delphi-ai-skills

O código ficou barato. A direção, não.

Por trinta anos a parte cara da profissão foi digitar. O projeto você já tinha na cabeça, e o gargalo era transformá-lo em linhas: escrever o controller, o DTO, os testes, o boilerplate, o CRUD. Quem produzia mais linhas corretas por hora valia mais.

Essa escassez acabou. Hoje um agente de IA escreve para mim, em trinta segundos, um controller CRUD completo com testes. Não é mais novidade de palestra: é o dia normal de quem programa em 2026. E quando algo se torna abundante, o valor se desloca para outro lugar.

Ele se desloca para a direção. Se o código custa pouco para produzir, então a pergunta interessante não é mais “quanto tempo você leva para escrevê-lo”, mas:

• ele segue as nossas convenções, ou inventa novas a cada sessão?
• ele usa a API que o framework realmente tem, ou aquela que o agente imagina que o framework tenha?
• o endpoint que ele acabou de gerar é filtrado pelo usuário autenticado, ou lê o pedido de qualquer um que passe um ID na URL?
• o código que acabei de aceitar com um toque de Tab, quem vai mantê-lo daqui a dois anos?

O risco do código barato é exatamente esse: produzir depressa muito código medíocre, plausível na leitura e errado nos detalhes, cada trecho com seu pequeno estilo pessoal. Um agente solto é rapidíssimo para construir dívida técnica.

A resposta não é frear o agente. É guiá-lo: dar a ele diretrizes, modos operacionais, um estilo da casa e regras de segurança embutidas, para que o caminho certo seja também o caminho padrão. É exatamente o trabalho que as skills fazem.

O que é uma skill para um agente de IA

Uma skill é um arquivo Markdown que o agente carrega sob demanda, apenas quando o seu pedido corresponde à descrição dela. No contexto do agente ficam sempre apenas o nome e uma linha de descrição, para cada skill instalada. Quando você pede “crie um controller DMVCFramework”, o agente reconhece a correspondência e nesse momento abre o arquivo, que lhe explica a API real do framework: os nomes exatos das units, os atributos, as regras de ownership dos objetos, os idiomas, as armadilhas já conhecidas.

Carregamento sob demanda: a documentação pesada entra em cena somente quando a tarefa exige.

É um mecanismo simples, mas com uma propriedade valiosa: a janela de contexto continua livre. A skill principal, dmvcframework, mantém no seu SKILL.md o núcleo operacional (bootstrap, controller, respostas, ownership, middleware, erros típicos) e move o material pesado para arquivos reference/ que o agente só abre se a tarefa exigir: o ORM ActiveRecord, a validação, o container de dependency injection, os servidores backend, dotEnv, os SSE.

O problema concreto: código Delphi plausível que não compila

Peça a um agente sem skills uma Minimal API com DelphiMVCFramework. Você vai receber um código bem escrito, bem indentado, bem comentado, e que não compila.

Mesmo pedido, mesmo modelo. À esquerda os nomes que o framework teria se fosse ASP.NET, à direita os que ele realmente tem.

Os nomes errados não são aleatórios: são aqueles que o framework teria se fosse ASP.NET Core, porque de ASP.NET Core o modelo leu milhões de linhas e de DelphiMVCFramework bem menos. Assim sai MapGroup no lugar de Prefix, OkResponse no lugar de Ok, classes de middleware que não existem, e um ToFree em volta do objeto retornado que o libera duas vezes, porque de liberá-lo já cuida o framework.

Existe uma pergunta que desmascara um agente não instruído em dez segundos:

Em uma functional action do DelphiMVCFramework, devo usar ToFree no objeto que retorno?

A resposta certa é não: o framework libera o objeto retornado, e o ToFree o liberaria uma segunda vez. Um agente sem skills normalmente responde que sim, e o seu código faz um double free.

Cada skill do projeto nasceu justamente reproduzindo antes o erro: faz-se o agente falhar, documenta-se a API que o framework realmente tem, relança-se a mesma tarefa e verifica-se que agora ele acerta. Nenhum nome de API escrito de memória: tudo verificado nos fontes e nos samples do DelphiMVCFramework 3.5.0 (silicon).

As sete skills para DelphiMVCFramework

Elas são complementares: as skills de Minimal API e de aplicação web dão o núcleo como certo para entidades, validação e DI, e a skill de aplicação web delega a marcação para dmvcframework-ui e a sintaxe htmx para htmx-skill em vez de duplicá-las. Instale todas: é o agente que escolhe as certas.

Se você não conhece os assuntos que as skills ensinam ao agente, aqui está o ponto de partida humano: as Minimal APIs do DMVCFramework, as aplicações web Delphi com TemplatePro e, no lado da IA, o servidor MCP para DMVCFramework com o seu agente. As skills são a peça que faltava: não dão ao agente novas ferramentas, dão a ele o conhecimento para usar bem as que já tem.

Segurança: não um controle final, mas uma pré-condição do código gerado

Esta é a parte que mais me importa, e o motivo pelo qual a dmvcframework-security não é uma skill que se invoca no fim do trabalho, mas uma dependência obrigatória das outras skills de servidor: qualquer endpoint que receba entrada de um cliente a puxa junto.

O código gerado às pressas erra sempre nos mesmos pontos. O mais comum, e o mais grave, é o IDOR: o endpoint que confia no ID da URL.

// ERRADO: qualquer usuário autenticado pode ler os pedidos de qualquer um
function TOrdersController.GetOrder(const ID: Integer): IMVCResponse;
begin
  Result := OKResponse(TMVCActiveRecord.GetByPK<TOrder>(ID));
end;

O ID chega pela URL. Nada o vincula a quem está chamando. A regra que a skill impõe ao agente é que o controle de propriedade seja a própria query, e não um if colocado depois:

function TOrdersController.GetOrder(const ID: Integer): IMVCResponse;
var
  lOrder: TOrder;
begin
  // a verificação de propriedade É a própria query
  lOrder := TMVCActiveRecord.GetOneByWhere<TOrder>(
    'id = ? and customer_id = ?', [ID, CurrentUserID], False);
  if lOrder = nil then
    Exit(NotFoundResponse);      // mesma resposta de "não é seu": não vazar a existência
  Result := OKResponse(lOrder);
end;

A diferença entre as duas versões são três linhas. Mas a primeira é um vazamento de dados esperando para acontecer, e num mundo em que o código é aceito com toques de Tab, é a versão que vai parar em produção. Uma regra escrita em uma skill vale muito mais do que uma regra escrita em um checklist que ninguém relê: a skill é aplicada enquanto o código nasce, e não depois.

O mesmo vale para o estilo e para as diretrizes do projeto. As skills não ensinam só “como se chama esta função”: ensinam como se trabalha aqui. Por exemplo, elas obrigam a partir de um projeto criado com o wizard da IDE, em vez de inventar um bootstrap meio correto do zero, e a respeitar o backend server que o projeto já tem: se você está rodando em WebBroker sob ISAPI ou Apache, as skills reconhecem isso, mantêm e nunca propõem uma migração.

Os testes: o contrapeso do código barato (DUnitX e IMVCRESTClient)

Se há uma coisa que a era do código abundante torna mais importante, e não menos, são os testes.

O raciocínio é simples. Antes, o código quem escrevia era você: você o tinha na cabeça linha por linha, e podia se dar ao luxo (erradamente, mas podia) de confiar nessa compreensão. Hoje o código vem de um agente, em quantidade, e você o lê na diagonal. A única coisa que lhe diz se aquele código faz mesmo o que você acredita não é mais a sua leitura: é um teste que falha. O teste virou o lugar onde vive a sua intenção, e o código é apenas o meio, agora barato, de satisfazê-la.

E há um segundo motivo, ainda mais prático: o teste é a única linguagem em que o agente pode se verificar sozinho. Um agente que tem uma suíte para rodar fecha o ciclo (escrevo, compilo, executo os testes, corrijo) sem que você tenha de bancar o compilador humano a cada volta. Sem testes, o agente tem uma única fonte de verdade: você.

Por isso a dmvcframework-testing não é uma skill acessória. Ela ensina ao agente a stack de testes de verdade do DelphiMVCFramework: DUnitX como runner, um IMVCServer in-process (Indy Direct) e o IMVCRESTClient como cliente HTTP fluente. Nenhum servidor externo para iniciar, nenhum WebModule: o servidor nasce e morre dentro do teste.

function StartTestServer(APort: Integer; out AEngine: TMVCEngine): IMVCServer;
begin
  AEngine := TMVCEngine.Create(
    procedure(Config: TMVCConfig)
    begin
      Config[TMVCConfigKey.DefaultContentType] := TMVCMediaType.APPLICATION_JSON;
    end);
  AEngine.AddController(TCustomersController);

  Result := TMVCServerFactory.CreateIndyDirect(AEngine);
  Result.Listen(APort);
end;

Repare em um detalhe que sozinho já justifica a instalação da skill: isto funciona mesmo se a aplicação em produção rodar como ISAPI sob IIS ou como módulo Apache. O host não é o que você está testando: o que você testa são a engine, os controllers e os middlewares. Um agente não instruído, para quem pede testes em um projeto WebBroker, responde tentando iniciar o IIS.

Os testes de integração são HTTP de verdade contra o servidor in-process, e a skill obriga a asserir sobre o status code e o body, e não sobre o fato de a chamada não ter explodido:

procedure TCustomersTests.Create_Returns201_And_Location;
var
  lResp: IMVCRESTResponse;
begin
  lResp := FClient.Post('/api/customers',
    '{"firstName":"Daniele","lastName":"Teti","email":"d.teti@example.com"}');

  Assert.AreEqual(HTTP_STATUS.Created, lResp.StatusCode);
  Assert.IsNotEmpty(lResp.HeaderValue('Location'));
end;

procedure TCustomersTests.Post_Invalid_Email_Returns422;
var
  lResp: IMVCRESTResponse;
begin
  lResp := FClient.Post('/api/customers',
    '{"firstName":"Bob","lastName":"X","email":"not-an-email"}');
  // validação falhou => 422, e a action nunca chegou a rodar
  Assert.AreEqual(HTTP_STATUS.UnprocessableEntity, lResp.StatusCode);
end;

Mas a parte que realmente me interessa é outra, e é o ponto em que a skill de testes e a de segurança se dão as mãos. Teste a fechadura, não só a chave. Para cada recurso protegido, o teste que conta não é aquele que verifica que o dono recebe 200: é aquele que verifica que qualquer outra pessoa não chega lá.

procedure TSecureTests.NoToken_Returns401;
begin
  // o teste que pega o [MVCRequiresAuthentication] que você esqueceu
  Assert.AreEqual(HTTP_STATUS.Unauthorized, FClient.Get('/api/admin/stats').StatusCode);
end;

procedure TOrdersTests.User_Cannot_Read_Another_Users_Order;
begin
  // o pedido 1 pertence a user1
  FClient.SetBearerAuthorization(TokenFor('user2'));
  // 404, não 403: um 403 confirmaria que o pedido existe
  Assert.AreEqual(HTTP_STATUS.NotFound, FClient.Get('/api/orders/1').StatusCode);
end;

Este é o teste de IDOR, ou seja, exatamente a falha do parágrafo anterior, capturada em três linhas. É também o teste que quase ninguém escreve, porque um 200 para o dono dá a sensação tranquilizadora de que o endpoint “funciona”. A regra que a skill impõe ao agente é clara: para cada verbo de cada recurso que tem um dono, é preciso o teste que demonstra que outro usuário é rejeitado. Um GET bem filtrado e um DELETE deixado aberto continuam sendo um vazamento de dados.

O sentido está todo aqui: ao pedir “escreva os testes de integração para os endpoints Customers, incluindo os casos de autorização”, o agente não produz apenas testes, produz os testes que você não teria tido vontade de escrever. E é o tipo de trabalho em que o código barato é uma bênção de verdade, em vez de um jeito elegante de acumular dívida. A skill traz junto também o scripts/run-tests.bat, para que o agente compile e execute a suíte sozinho, e veja o vermelho antes de lhe dizer que terminou.

Como instalar as skills Delphi no Claude Code, Codex, Cursor e Gemini

Clone o repositório e rode o script do seu agente (Windows):

git clone https://github.com/danieleteti/delphi-ai-skills.git
cd delphi-ai-skills
install_in_claude.bat

Para o Claude Code não é preciso mais nada: as skills são descobertas sozinhas. Para Codex, Cursor e Gemini CLI existem install_in_codex.bat, install_in_cursor.bat e install_in_gemini.bat, que copiam as skills e escrevem o ponteiro no arquivo de instruções do agente (AGENTS.md, .cursor/rules/*.mdc, GEMINI.md), porque esses agentes não as descobrem sozinhos.

Cada script aceita um caminho de projeto, se você preferir instalar as skills dentro do repositório e versioná-las para todo o time:

install_in_claude.bat C:\DEV\meu-projeto

Depois cria-se o projeto com o wizard da IDE (File → New → Other → Delphi Projects → DelphiMVCFramework), compila-se uma vez, roda-se o agente dentro daquela pasta e pede-se o que for preciso:

Adicione um controller Customers com CRUD completo, apoiado em uma entidade ActiveRecord na tabela customers

Um último conselho que faz uma diferença notável: se você tem os fontes do DelphiMVCFramework em disco, diga isso ao agente (“os fontes do DMVCFramework estão em C:\DEV\dmvcframework”). As skills sabem que podem estar incompletas ou desatualizadas, e nesse caso estão instruídas a verificar em vez de adivinhar: leem os fontes e os samples, e se ainda assim não tiverem certeza, dizem isso, em vez de inventar.

Uma sessão de verdade, do começo ao fim

Chega de teoria. Veja como é uma sessão real dentro de um projeto gerado pelo wizard, com o Claude Code. Você nunca “chama” uma skill: descreve a tarefa, e a skill se carrega sozinha.

$ cd C:\DEV\OrdersAPI
$ claude

> adicione um controller Customers com CRUD completo, apoiado em
  uma entidade ActiveRecord na tabela customers

● Skill(dmvcframework)
  ⎿  SKILL.md carregada
  ⎿  reference/activerecord.md aberta (entidade + mapeamento)
● Skill(dmvcframework-security)
  ⎿  SKILL.md carregada (o endpoint aceita entrada do cliente)

● Read(EngineConfigU.pas)    projeto do wizard detectado, backend Indy Direct
● Read(Controllers.Base.pas) estilo da casa: functional action, IMVCResponse

● Write(Entities.Customer.pas)
● Write(Controllers.Customers.pas)
● Edit(EngineConfigU.pas)     +1 linha: AddController(TCustomersController)

  Pronto. Notas:
  - GET /api/customers/($id) é filtrado pelo cliente autenticado, e não
    apenas pelo ID: um usuário não pode ler a linha de outro.
  - O objeto retornado por OKResponse é liberado pelo framework:
    nada de ToFree, seria um double free.
  - O campo "id" fica excluído da desserialização (mass assignment).

As três notas finais não são cortesia: são as regras das skills que trabalharam enquanto o código nascia. Um agente sem skills, com o mesmo prompt, teria lhe entregado um GetByPK(ID) sem filtro, um ToFree a mais e um DTO que deixa o cliente escrever o id.

Continua-se na mesma conversa, e a skill de testes entra em cena sozinha:

> agora escreva os testes de integração, incluindo os casos de autorização

● Skill(dmvcframework-testing)
  ⎿  SKILL.md carregada

● Write(Tests.Server.pas)      IMVCServer in-process, sem WebModule
● Write(Tests.Customers.pas)   9 testes: CRUD, 404, 422, 401, IDOR
● Bash(scripts\run-tests.bat)
  ⎿  Running... 9 tests, 8 passed, 1 FAILED
     [FAIL] User_Cannot_Read_Another_Users_Order
            expected 404, got 200

  O teste de IDOR falha: OrdersController.GetOrder ainda busca apenas
  pela PK. Vou corrigir (estava fora do escopo que você me deu,
  confirma?)

Este é o ponto em que o círculo se fecha: um teste escrito pelo agente encontrou uma falha em um código que o agente não tinha escrito. Só com a geração de código aquele bug ficaria ali. É por isso que, num mundo de código barato, as diretrizes e os testes valem mais do que a velocidade.

O mesmo trabalho com Codex, Cursor, Gemini ou qualquer outro agente

As skills são Markdown puro, sem sintaxe proprietária: o conteúdo é idêntico em todos os agentes, muda apenas o modo como o agente descobre que aqueles arquivos existem.

Com o Codex, a mesma sessão de antes tem a forma a seguir: o pedido é idêntico, e muda só o rastro com que o agente declara ter lido a skill.

$ codex
> adicione um controller Customers com CRUD completo (DMVCFramework)

  Lendo skills/dmvcframework/SKILL.md, conforme exigido pelo AGENTS.md.
  Este endpoint recebe entrada do cliente: leio também
  skills/dmvcframework-security/SKILL.md.
  ...

Atenção a um detalhe: nos agentes que não são o Claude Code o carregamento não é garantido, depende do quanto aquele agente respeita o próprio arquivo de instruções. Por isso, com Codex, Cursor ou Gemini, convém nomear o framework no prompt (“crie um controller DMVCFramework”, e não “crie um controller”): é o gatilho mais forte. E se você suspeitar que a skill não foi carregada, diga isso explicitamente:

Use a skill dmvcframework. Depois crie o controller para Orders.

Existe também um jeito, de dez segundos, de descobrir se o agente à sua frente está instruído ou não. Pergunte a ele:

Em uma functional action do DelphiMVCFramework, devo usar ToFree no objeto que retorno?

Se ele responder não, porque o framework já libera o objeto retornado e o ToFree o liberaria duas vezes, a skill está ativa. Se responder que sim, o código dele está fazendo um double free e você vai descobrir isso em produção.

Perguntas frequentes sobre o delphi-ai-skills

O que é o delphi-ai-skills? É um projeto open source (Apache-2.0) que reúne sete skills para agentes de IA de codificação, dedicadas ao DelphiMVCFramework. Uma skill é um arquivo Markdown que o agente carrega sob demanda e que lhe ensina a API real do framework: units, atributos, regras de ownership dos objetos, idiomas e armadilhas conhecidas.

Com quais agentes de IA elas funcionam? Claude Code, Codex, Cursor, Gemini CLI, Windsurf, Continue e qualquer agente capaz de ler instruções em Markdown. O repositório inclui os scripts de instalação para os quatro primeiros.

Por que um agente de IA sem skills escreve código Delphi que não compila? Porque escreve de memória, e recai nos padrões dos frameworks que viu muito mais, tipicamente ASP.NET Core. Gera assim nomes plausíveis mas inexistentes, por exemplo MapGroup em vez de Prefix ou OkResponse em vez de Ok, e um ToFree no objeto retornado que causa um double free, já que de liberá-lo cuida o framework.

As skills também cuidam da segurança? Sim, e é a parte mais importante. A dmvcframework-security é uma dependência obrigatória de todas as skills de servidor: aplica-se a qualquer endpoint que receba entrada de um cliente. Cobre access control e IDOR, mass assignment, SQL injection, XSS no TemplatePro, CSRF, path traversal, upload, SSRF e open redirect, cabeçalhos de segurança, hardening do JWT e gestão dos segredos.

As skills sabem escrever os testes? Sim, com a stack de testes real do framework: DUnitX como runner, um IMVCServer in-process com Indy Direct e o IMVCRESTClient como cliente HTTP, sem servidores externos e sem WebModule, mesmo quando em produção a aplicação roda como ISAPI ou como módulo Apache. Cobrem os testes CRUD, os de autenticação e os testes de autorização (IDOR).

As skills criam o projeto Delphi do zero? Não, e é uma escolha. O projeto deve ser criado com o wizard da IDE, compilado uma vez, e só então se roda o agente dentro daquela pasta. As skills reconhecem o layout do wizard e acrescentam funcionalidades dentro dele, em vez de inventar um bootstrap meio correto.

Elas funcionam em um projeto WebBroker ou ISAPI existente? Sim. O backend padrão para um projeto novo é o Indy Direct, mas um projeto WebBroker existente (ISAPI sob IIS, módulo Apache) é plenamente suportado: as skills reconhecem o host, mantêm-no e nunca propõem uma migração. Tudo o que fica acima do host, ou seja, controllers, roteamento, ActiveRecord, validação, DI e middleware, é idêntico em qualquer backend.

Versão 0.1.0 das Delphi AI Skills, e o caminho pela frente

É um primeiro release. As skills foram escritas e verificadas sobre o DelphiMVCFramework 3.5.0, mas ainda não atravessaram dezenas de projetos reais: espere algumas arestas, e por favor reporte-as. Enquanto estivermos em 0.x, a própria forma do conjunto deve ser considerada instável: as skills poderão ser divididas, unidas, renomeadas ou removidas à medida que o uso real mostrar o que serve de fato.

O critério para contribuir é um só, e não é negociável: cada afirmação deve ser verificável nos fontes ou em um sample do DelphiMVCFramework, citando o arquivo. Nenhum nome de API escrito de memória, nunca. É exatamente a disciplina que pedimos aos agentes, e seria curioso não aplicá-la a nós mesmos.

O projeto está aqui: github.com/danieleteti/delphi-ai-skills. Issues e pull requests são bem-vindas.

Escrever código, agora, é a parte fácil. Decidir que código se quer, e garantir que seja esse o que sai mesmo quando quem escreve é uma máquina, é a profissão que resta. As Delphi AI Skills servem para isso: dar a um agente de IA as diretrizes, o estilo, a segurança e os testes com os quais queremos que o código Delphi nasça.