RamonRuan

XLDent · base Delphi de grande porteXLDent · large Delphi codebase

Agentes genéricos editavam arquivos, mas não conheciam o domínio, as convenções nem o build. Codifiquei o domínio em skills para Claude Code e Codex, gerei documentação técnica como contexto recuperável e liguei o build automatizado como verificação determinística. O resultado é um ciclo repetível em que agentes concluem tarefas reais numa base que o ferramental padrão não lê.

Generic agents could edit files but knew neither the domain, the conventions nor the build. I encoded the domain as skills for Claude Code and Codex, generated technical documentation as retrievable context, and wired the automated build in as deterministic verification. The result is a repeatable loop in which agents complete real tasks on a codebase standard tooling cannot read.

• skills de domínio
• domain skills
• documentação como contexto
• docs as context
• build como verificação
• build as verification

Projeto pessoal sobre harnesses para trabalho com agentesPersonal project on harnesses for agent work

A ideia: transformar uma boa sessão de trabalho com agentes em procedimento. Cada fase do desenvolvimento deixa um artefato que uma checagem determinística confere, a especificação passa por revisão adversarial de outro modelo antes de virar código, e o modelo nunca aprova nada. Foi daqui que saíram as ideias do fluxo de desenvolvimento com agentes verificáveis, escrito do zero para a empresa.

The idea: turn a good working session with agents into a procedure. Every development phase leaves an artifact a deterministic check verifies, the specification gets an adversarial review from a different model before it becomes code, and the model never approves anything. This is where the ideas behind the verifiable agent development workflow came from, written from scratch for the company.

App completo construído por um pipeline de agentesA complete app built by an agent pipeline

Código, testes, especificação e documentação produzidos por agentes Claude a partir de uma especificação aprovada por mim. Cinco papéis: analista de regras de negócio, redator de spec, implementador em TDD estrito, revisor adversarial e release. Cada fase passa por um gate humano antes do merge.

Code, tests, specification and documentation produced by Claude agents from a specification I approved. Five roles: business-rules analyst, spec writer, strict-TDD implementer, adversarial reviewer and release. Every phase passes a human gate before merge.

Regra de negócio, requisito, tarefa e teste são ligados por ID, e o build falha se a cadeia quebrar. Depois de três tentativas sem sucesso, a falha escala para a especificação. Até a fase 10, 25 incidentes ficaram registrados com causa raiz e resolução.

Business rules, requirements, tasks and tests are linked by ID, and the build fails if the chain breaks. After three failed attempts, a failure escalates to the specification. Through phase 10, 25 incidents were logged with root cause and resolution.

• Abrir o appOpen the app ↗
• RepositórioRepository ↗
• Como foi construídoHow it was built ↗

Fluxo de desenvolvimento com agentes de IA e a ferramenta de linha de comando que o operaAn AI-agent development workflow and the command-line tool that runs it

Agentes de IA já escrevem código, mas raramente com previsibilidade. Partem de buscas soltas em arquivos em vez do conhecimento confirmado do produto, aprovam o próprio trabalho e deixam pouca evidência que um humano consiga auditar.

AI agents already write code, but rarely predictably. They start from loose file searches instead of the product's confirmed knowledge, approve their own work, and leave little evidence a human can audit.

Neste fluxo, toda mudança nasce de conhecimento confirmado por pessoas, e cada fase deixa evidência que uma checagem determinística verifica. A ferramenta de linha de comando monta o contexto dos agentes, registra cada fase e recusa o que quebra uma regra, sempre dizendo qual regra, em qual campo e como corrigir.

In this workflow, every change starts from knowledge people have confirmed, and every phase leaves evidence a deterministic check can verify. The command-line tool builds the agents' context, records each phase and refuses whatever breaks a rule, always naming the rule, the field and the fix.

O ciclo de uma mudançaThe life of a change

1. DEFINE

   O definidor monta o contexto a partir da base de conhecimento, entrevista o humano e escreve uma spec executável com requisitos, tarefas, arquivos exatos e testes. Um adversário ataca a spec antes da aprovação humana.

   The definer builds context from the knowledge base, interviews the human and writes an executable spec with requirements, tasks, exact files and tests. An adversary attacks the spec before human approval.

2. IMPLEMENT

   Um implementador de modelo mais barato executa a spec. O teste falha primeiro e depois passa.

   An implementer on a cheaper model executes the spec. The test fails first, then passes.

3. VERIFY

   Um verificador independente reexecuta os critérios de aceite e confirma, em ambiente isolado, que cada teste falhava antes do código existir.

   An independent verifier reruns the acceptance criteria and confirms, in isolation, that each test failed before the code existed.

4. GATE

   Na CI, predicados determinísticos julgam o pull request. As regras vêm sempre da branch base, então um PR não muda como é julgado.

   In CI, deterministic predicates judge the pull request. Rules always come from the base branch, so a PR cannot change how it is judged.

5. REVIEW · CLOSE

   Um humano revisa e aprova, e um registro de ciclo fecha o ticket.

   A human reviews and approves, and a cycle record closes the ticket.

recall da recuperação híbrida contra a busca lexical, em pares rotulados de tickets reaishybrid retrieval recall vs lexical search, on labeled pairs from real tickets

0,53 → 0,840.53 → 0.84

predicados no gate: dez sempre ativos e dois de disciplina (rastreabilidade e evidência de TDD)gate predicates: ten always on, two for discipline (traceability and TDD evidence)

12

testes automatizadosautomated tests

~1.000~1,000

start-up do binário para Windows, Linux e macOSbinary start-up on Windows, Linux and macOS

0,08–0,23 s0.08–0.23 s

Base de conhecimento e distribuiçãoKnowledge base and distribution

Um único Postgres com pgvector guarda texto, embeddings e um grafo de código (símbolos, imports, chamadas) reconstruível a partir do repositório. Os embeddings vêm de um modelo aberto, local e multilíngue, e nenhum dado sai da rede. A recuperação combina full-text, vetores e vizinhança no grafo dentro de um orçamento de tokens. Agentes acessam por um servidor MCP, e o que respondem em entrevistas vira proposta que um humano confirma.

A single Postgres with pgvector stores text, embeddings and a code graph (symbols, imports, calls) that can be rebuilt from the repository. Embeddings come from an open, local, multilingual model, and no data leaves the network. Retrieval combines full-text, vectors and graph neighborhood within a token budget. Agents connect through an MCP server, and interview answers become proposals a human confirms.

Um comando instala o processo inteiro num repositório (configuração com versão fixada, skills, permissões, workflow do gate e donos de código) e faz o commit de forma transacional: se algo falha, tudo volta como estava. Outro comando confere se o repositório segue o processo, e um terceiro migra de versão. A ferramenta foi construída com o próprio processo, e cada lição aprendida vira regra nas instruções dos papéis.

One command installs the whole process into a repository (pinned configuration, skills, permissions, gate workflow and code owners) and commits it transactionally: if anything fails, everything rolls back. Another command checks the repository still follows the process, and a third migrates it to a new version. The tool was built with its own process, and every lesson learned becomes a rule in the role instructions.

• Python
• Typer
• Pydantic
• Postgres + pgvector
• MCP
• GitHub Actions
• PyInstaller

Base de conhecimento, governança e esteira de documentação para uma equipe de software legado de grande porteKnowledge base, governance and documentation pipeline for a large legacy software team

O conhecimento de negócio estava espalhado em tickets, código e na cabeça das pessoas. Os agentes reaprendiam o mesmo contexto a cada tarefa, ninguém sabia se um texto era regra confirmada ou hipótese, e as propostas de documentação ficavam paradas sem ninguém aceitar.

Business knowledge was scattered across tickets, code and people's heads. Agents relearned the same context on every task, no one could tell a confirmed rule from a hypothesis, and documentation proposals sat waiting with no one to accept them.

Cada merge publica em produção via Docker com checagem de saúde, e cada troca levou menos de 20 segundos fora do ar. Agentes de planejamento, implementação e revisão trabalham em paralelo, coordenados por um canal de mensagens entre sessões e máquinas, com humanos nas decisões.

Every merge ships to production through Docker with a health check, and each swap took under 20 seconds of downtime. Planning, implementation and review agents work in parallel, coordinated by a message channel across sessions and machines, with humans on the decisions.

• Python
• Git
• SQLite
• Docker
• MCP
• OAuth
• D3 + Canvas
• GitHub Actions

Próximo passo: banco relacional com busca vetorial para RAG completo, convivendo com o modo Git por uma chave de configuração, e implantação em nuvem.

Next: a relational database with vector search for full RAG, coexisting with the Git mode behind a configuration switch, and cloud deployment.

SDR para WhatsApp com CRM e IA integrada para atendimentoWhatsApp SDR with CRM and built-in AI for customer service

Plataforma que qualifica leads e atende pelo WhatsApp com IA, com CRM, funil de vendas e agendamento integrados. Contribuí na construção da arquitetura. Não participo da operação do produto.

A platform that qualifies leads and serves customers over WhatsApp with AI, with CRM, a sales pipeline and scheduling built in. I contributed to building its architecture. I am not involved in operating the product.

• pexbot.pexhub.com.br ↗

Plataforma que permite a uma administração central acessar serviços que rodam dentro de redes de clínicas sem nenhuma porta de entrada aberta.A platform that lets a central administration reach services that run inside clinic networks with no inbound port open.

Os dados das clínicas ficam em servidores locais, atrás de NAT e firewall, e a administração precisava de acesso controlado a eles sem abrir portas de entrada. Desenhei uma plataforma de túnel reverso: um agente na rede privada abre um WebSocket de saída para um gateway na nuvem, e as chamadas HTTP voltam por esse mesmo socket até serviços ligados ao loopback da máquina da clínica. Sessões TCP brutas, como SSH, usam um serviço de relay separado, para que tráfego TCP pesado não esgote o relay HTTP. O mesmo backend mantém um registro de versões imutáveis de schema de API, servidas no formato exato que o parser do motor da clínica lê.

Clinic data lives on local servers behind NAT and firewalls, and the administration needed governed access to it without opening inbound ports. I designed a reverse-tunnel platform: an agent on the private network opens an outbound WebSocket to a cloud gateway, and HTTP calls travel back down that same socket to services bound to loopback on the clinic machine. Raw TCP sessions, such as SSH, use a separate relay service, so heavy TCP traffic cannot exhaust the HTTP relay. The same backend keeps a registry of immutable API schema versions, served in the exact shape that the clinic engine's parser reads.

O gateway roda Spring MVC sobre virtual threads, faz o relay das requisições por um contrato de mensagens JSON congelado e classifica cada sessão como online, suspeita ou offline, com heartbeat e anti-flapping. O agente e o SDK Delphi gerado reconectam com backoff exponencial e, quando o servidor recusa um túnel, esperam o intervalo que a mensagem de recusa informa. Um reconciliador agendado consulta o serviço de identidade e licenciamento sobre a licença de cada clínica e fecha os túneis bloqueados; uma queda desse serviço não altera nenhum registro. A telemetria passa por uma fila limitada em memória que descarta e conta amostras sob pressão, e nenhuma thread do gateway acessa o banco.

The gateway runs Spring MVC on virtual threads, relays requests over a frozen JSON message contract, and classifies each session as online, suspect or offline, with heartbeats and anti-flapping. The agent and the generated Delphi SDK reconnect with exponential backoff and, when the server refuses a tunnel, wait the interval that the refusal message carries. A scheduled reconciler asks the identity and licensing service for each clinic's license state and closes blocked tunnels; an outage of that service changes no record. Telemetry passes through a bounded in-memory queue that drops and counts samples under pressure, and no gateway thread touches the database.

A especificação de UI como contratoThe UI spec as a contract

Escrevi a especificação de UI do painel como a autoridade única para decisões de tela, e ela usa só dados que o backend já produz. O mapa de fontes de dados liga cada campo da UI a um campo REST ou a uma métrica Prometheus, e lista os dados que o backend ainda não expõe, com uma regra de placeholder para essas telas. A escala de cores, a escala tipográfica (Inter e JetBrains Mono) e os raios de borda vieram de um design system administrativo compartilhado, então os apps administrativos têm a mesma linguagem visual.

I wrote the dashboard's UI spec as the single authority for screen decisions, and it uses only data the backend already produces. Its data source map ties every UI field to a REST field or a Prometheus metric, and it lists the data the backend does not expose yet, with a placeholder rule for those screens. The color ramp, the type ramp (Inter and JetBrains Mono) and the border radii came from a shared admin design system, so the admin apps share one visual language.

• Todo erro ou estado degradado diz o que significa, a causa provável e o que tentar.
• Every error or degraded state says what it means, its likely cause, and what to try.
• Um status tem um ícone, uma cor e um texto em todas as telas.
• One status has one icon, one color and one wording on every screen.
• Cor nunca é o único sinal: cada estado também tem forma de ícone e rótulo de texto.
• Color is never the only signal: each state also has an icon shape and a text label.
• Informação crítica nunca fica escondida atrás de hover.
• Critical information never sits behind hover.
• Dado ausente aparece como traço, e nenhum elemento mostra dado que o backend não tem.
• Missing data shows a dash, and no element shows data the backend does not have.

AgentesAgents

Construí funcionalidades com agentes de código num fluxo de spec, plano e registro de tarefas: cada tarefa sai com um briefing, volta com um relatório e recebe uma revisão do seu diff. Arquivos de guia para agentes guardam invariantes numeradas, um mapa de marcos e um guia de verificação que lista leituras falsas que aconteceram de fato no repositório. O trabalho é conferido por testes unitários herméticos, testes de integração com Docker contra PostgreSQL real, regras de camadas com ArchUnit e, em qualquer mudança no túnel, uma execução com o agente real e curl.

I built features with coding agents on a spec, plan and task-ledger flow: each task goes out with a brief, comes back with a report, and gets a review of its diff. Agent guide files hold numbered invariants, a milestone map, and a verification guide that lists false readings that actually happened in the repository. Work is checked by hermetic unit tests, Docker-backed integration tests against real PostgreSQL, ArchUnit layering rules, and, for any tunnel change, a run with the real agent and curl.

• Java 21
• Spring Boot 4
• Spring MVC (virtual threads)
• Netty
• WebSocket
• Server-Sent Events
• PostgreSQL 16
• Liquibase
• Prometheus
• React 19
• TypeScript
• Tailwind CSS 4
• ArchUnit
• Testcontainers
• Delphi (SDK cliente gerado)
• Delphi (generated client SDK)

Substituto em Java de um servidor Delphi legado que recebe arquivos de extrato de cobrança das clínicas e os envia por SFTP a uma clearinghouse de cobrança externa.Java replacement for a legacy Delphi server that receives billing statement files from clinics and uploads them over SFTP to an external billing clearinghouse.

O servidor legado recebia arquivos de extrato de um cliente desktop, reformatava e enviava a uma clearinghouse de cobrança, e um envio duplicado cobra o cliente duas vezes. Projetei o substituto para que o cliente desktop existente funcione sem mudança: reimplementei em Java o protocolo RPC binário legado atrás de um adaptador removível, e uma regra ArchUnit mantém o núcleo independente dele. Toda entrada chama uma única porta de ingestão, então a regra de negócio tem uma só implementação. Um teste de arquivo golden fixa a saída dos conversores nos bytes do legado, e a clearinghouse recebe o arquivo bruto sem alteração.

The legacy server received statement files from a desktop client, reformatted them and uploaded them to a billing clearinghouse, and a duplicate upload bills the customer twice. I designed the replacement so the existing desktop client works unchanged: I reimplemented the legacy binary RPC protocol in Java behind a removable adapter, and an ArchUnit rule keeps the core independent of it. Every ingress calls one ingest port, so the business logic has a single implementation. A golden-file test pins the converter output to the legacy bytes, and the clearinghouse receives the raw file unchanged.

Os bytes do payload nunca vão para disco nem para o banco: existem só em mensagens persistentes do RabbitMQ e em memória, e cada transferência entre filas espera a confirmação do broker antes de reconhecer a mensagem de origem. A entrega segue uma máquina de estados: o serviço grava uma intenção de entrega com lease antes do upload SFTP, renova a lease com heartbeat e marca qualquer falha durante ou depois do upload como resultado desconhecido, que exige decisão humana auditada.

Payload bytes never reach disk or the database: they exist only in persistent RabbitMQ messages and in memory, and each transfer between queues waits for a broker confirm before the source message is acknowledged. Delivery follows a state machine: the service commits a leased delivery intent before the SFTP upload, renews the lease with a heartbeat, and marks any failure during or after the upload as an unknown outcome that needs an audited human decision.

Filas duráveis separadas estacionam mensagens pausadas, em retentativa, de resultado desconhecido, sem registro correspondente ou com falha de processamento, e um gauge Prometheus mostra a profundidade de cada fila. Uma API HTTP privada recebe os bytes brutos com chave de idempotência obrigatória e lê a clínica só de um claim de um service token de vida curta; o chamador dessa API, o serviço de identidade e licenciamento, está planejado.

Separate durable queues park messages that are paused, retrying, of unknown outcome, unmatched to a record, or failing in processing, and a Prometheus gauge reports each queue's depth. A private HTTP API takes the raw bytes with a mandatory idempotency key and reads the clinic only from a claim in a short-lived service token; the caller of that API, the identity and licensing service, is planned.

AgentesAgents

Escrevi o guia de agentes que qualquer agente de código lê antes de escrever código; ele define invariantes numeradas, um mapa de marcos e regras de processo: mudança de arquitetura exige registro de decisão antes do merge, e código de broker só é aceito com testes de integração contra um broker real. A verificação tem três camadas: testes unitários e de slice offline, testes com Testcontainers contra RabbitMQ e PostgreSQL reais que cobrem crash, reentrega e duplicata, e um script de smoke que exercita a stack inteira com um cliente independente de socket bruto e compara o arquivo SFTP byte a byte. A CI roda os testes unitários, compila as fontes de integração e gera a imagem Docker a cada pull request.

I wrote the agent guide that any coding agent reads before it writes code; it sets numbered invariants, a milestone map and process rules: an architecture change needs a decision record before merge, and broker code is accepted only with integration tests against a real broker. Verification has three layers: offline unit and slice tests, Testcontainers tests against real RabbitMQ and PostgreSQL that cover crash, redelivery and duplicate cases, and a smoke script that drives the full stack with an independent raw-socket client and compares the SFTP file byte for byte. CI runs the unit tests, compiles the integration sources and builds the Docker image on each pull request.

• Java 21
• Spring Boot 4
• Spring Security
• RabbitMQ 4.1 (filas quorum)
• RabbitMQ 4.1 (quorum queues)
• PostgreSQL 18
• Liquibase
• SFTP
• HAProxy
• Prometheus
• React 18
• TypeScript
• ArchUnit
• Testcontainers
• GitHub Actions