Se você não consegue ler seu código PHP, seu LLM também não consegue

Existem muitos equívocos, opiniões e discursos de influenciadores sobre a IA. Todo mundo está perguntando: “Você está pronto para a IA?”, uma pergunta muito pertinente.

A IA não vai fazer tudo por você. Ela vai tentará fazer tudo por você, se você permitir, mas, dependendo da pilha de tecnologias que você estiver usando, os resultados provavelmente serão variados. A maneira mais importante de lidar com a IA é considerá-la um conjunto extra de ferramentas em seu arsenal. Isso, no fim das contas, é apenas mais uma versão do conceito de ter um conjunto decente de ferramentas, como análise estática, linters de código e testes bem escritos.

Para preparar seu código para o uso de IA, vamos abordar como usar o Readalizer do PHP, já que a qualidade das ferramentas de IA depende diretamente da qualidade do código que elas estão lendo.

O que é o Readalizer?

O Readalizer é uma biblioteca PHP que oferece aos desenvolvedores uma API composta por um conjunto de regras que ela aplicará em sua base de código. Em tempo de execução, ela processa cada arquivo PHP definido em sua configuração e divide em tokens seu código usando a Árvore de Sintaxe Abstrata. Um exemplo de regra seria NoTodoWithoutTicketRule. Durante a execução, seu código:

public function(stdObj $myExample) {
	// TODO add some logic
	return stdObject->valid === true; 
}

Isso não vai funcionar. A regra determina que deve haver algum tipo de referência ao ticket deve ser fornecida no comentário embutido. Portanto, para corrigir isso, precisamos modificar nosso comentário:

public function(stdObj $myExample) {
	// TODO add some logic (DEVEX-2541)
	return stdObject->valid === true; 
}

Há muitas de regras, por isso não podemos abordar todas elas. O que faremos, porém, é mostrar uma implementação e explicar por que isso é importante em uma base de código ativa.

Espere aí, em que isso difere da análise estática?

Ah, que bom que você perguntou isso. Porque, basicamente, um conjunto de regras e uma ferramenta do tipo “aprovado ou reprovado” se assemelham a analisadores estáticos como o PHPStan ou PsalmPHP (ambos também usam a AST para analisar o código PHP em tokens). No entanto, há uma diferença bem clara entre os dois. A análise estática garante que seu código funcione. O Readalizer não se importa se seu código é executado ou não, apenas que ele siga os conjuntos de regras que você definiu. Portanto, podemos concluir que um analisador estático faz parte da sua cadeia de ferramentas de qualidade de código, mas o principal uso do Readalizer é garantir que tanto pessoas quanto Grandes Modelos de Linguagem possam ler seu código e tomar decisões mais acertadas com base nos conjuntos de regras que você implementou.

O Readalizer nas próprias palavras do autor

Algo que tenho gostado bastante de fazer nos artigos atualmente é perguntar aos criadores de um projeto como ele surgiu e qual é o . Então, aqui estão algumas palavras sobre o que é o Readalizer, em nas palavras de Christopher Miller:

“O Readalizer foi projetado desde o início para ajudar tanto você quanto seus agentes de IA a entender seu código PHP. A inspiração para criar esse pacote veio de uma citação de Ondrej Mirtes, que disse que o PHPStan não se preocupa com a aparência do seu código; isso é tarefa de outra pessoa. Então, assumi essa tarefa como minha. Tendo passado a maior parte da minha carreira falando sobre código legível, achei que já era hora de fazer algo a respeito. É aí que entra o Readalizer. Ele permite que você personalize as regras com configurações, regras personalizadas e conjuntos de regras personalizados, e ainda comece a usá-lo em cerca de 30 segundos."

Executando o Readalizer no SDK PHP da Vonage

Para ver como isso funciona na prática, vamos executar o Readalizer em uma base de código real: o SDK PHP da Vonage.

O objetivo aqui é simples: identificar em que pontos a melhoria da consistência do código pode tornar o projeto mais fácil de ser compreendido tanto por pessoas quanto por modelos de linguagem de grande escala (LLMs).

Para começar, bastam duas etapas:

composer require readalizer/readalizer

vendor/bin/readalizer --init

Isso vai gerar um readalizer.php configuração na raiz do seu projeto. Ótimo. Modifiquei o modelo padrão para instruí-lo a procurar no src diretório por padrão e desativei temporariamente todas as regras para que possamos ativá-las uma por uma e observar seu impacto.

<?php

declare(strict_types=1);

use Readalizer\Readalizer\Rules\ClassNamePascalCaseRule;

use Readalizer\Readalizer\Rules\NoStaticPropertyRule;

use Readalizer\Readalizer\Rules\RequireNamespaceRule;

use Readalizer\Readalizer\Rules\StrictTypesDeclarationRule;

use Readalizer\Readalizer\Rules\PropertyNameCamelCaseRule;

use Readalizer\Readalizer\Rules\ConstantUpperCaseRule;

use Readalizer\Readalizer\Rules\ExceptionSuffixRule;

/**

* Copy this to readalizer.php in your project root and configure your rules.

*

* Each rule is a class implementing RuleInterface (node-level) or

* FileRuleInterface (file-level). Rules can live anywhere.

*

* ── Suppressing violations ───────────────────────────────────────────────────

*

* PHP attribute on a class, method, property, or parameter:

*

*   use Readalizer\Readalizer\Attributes\Suppress;

*

*   #[Suppress]                                   // suppress ALL rules

*   #[Suppress(NoLongMethodsRule::class)]          // suppress one rule

*   #[Suppress(RuleA::class, RuleB::class)]        // suppress multiple

*

* Scope: a class-level attribute suppresses everything within the class;

* a method-level attribute suppresses everything within that method.

*

* Inline comment for line-level suppression (trailing or preceding line):

*

*   $x = something(); // @readalizer-suppress NoLongMethodsRule

*   // @readalizer-suppress                   (preceding line, suppress all)

*   // @readalizer-suppress RuleA, RuleB      (preceding line, suppress named)

*/

return [

   // Paths to scan when no paths are passed on the CLI.

   'paths' => [

       'src',

   ],

   // Memory limit for analysis (default: 2G).

   'memory_limit' => '2G',

   // Cache results between runs.

   'cache' => [

       'enabled' => true,

       'path' => '.readalizer-cache.json',

   ],

   // Optional baseline file to suppress known violations.

   // 'baseline' => '.readalizer-baseline.json',

   // Paths, directory prefixes, or glob patterns to exclude from scanning.

   'ignore' => [

       // 'rector.php',

       // 'src/',

       // '*.generated.php',

   ],

   // Choose one or more rulesets (packs).

   'ruleset' => [

       // new FileStructureRuleset(),

       // new TypeSafetyRuleset(),

       // new ClassDesignRuleset(),

       // new MethodDesignRuleset(),

       // new NamingRuleset(),

       // new ExpressionRuleset(),

   ],

   // Add or override rules on top of rulesets.

   'rules' => [

       // File structure

       // new LineLengthRule(maxLeng)th: 120),

       // new CustomFileRule(),

       // Type safety

       // new CustomTypeRule(),

       // Class design

       // new CustomClassRule(),

       // Method design

       // new CustomMethodRule(),

       // Naming conventions

       // new CustomNamingRule(),

       // Expressions & control flow

       // new CustomExpressionRule(),
   ],
];

. Em seguida, dei uma olhada em como adicionar regras, uma por uma. Primeiro, adicionei a ClassNamePascalCaseRule(), que garante que todas as classes no seu código-fonte estejam em PascalCase (portanto, desenvolvedores do WordPress talvez prefiram ignorar isso). Executei o Readalizer e obtive os resultados:

[##############################] 100% (319/319) 1s

[OK] No readability violations found.

Time: 1.06s

Não há violações aqui. Bom trabalho, autores do SDK! Acho melhor escolher outra. Então, optei pela ExceptionSuffixRule(). Essa regra diz que todas as suas /Exception’s devem ser identificáveis por meio de Exception no nome da classe. Para um LLM, isso é importante porque a estrutura de arquivos e as convenções de nomenclatura proporcionam previsibilidade. O que acontece quando executamos isso, então?

[##############################] 100% (319/319) 1s

src/Client/Exception/Conflict.php

  line 7  [ExceptionSuffixRule]  Exception class "Conflict" should end with "Exception".

src/Client/Exception/Credentials.php

  line 7  [ExceptionSuffixRule]  Exception class "Credentials" should end with "Exception".

src/Client/Exception/NotFound.php

  line 7  [ExceptionSuffixRule]  Exception class "NotFound" should end with "Exception".

src/Client/Exception/Request.php

  line 10  [ExceptionSuffixRule]  Exception class "Request" should end with "Exception".

src/Client/Exception/Server.php

  line 10  [ExceptionSuffixRule]  Exception class "Server" should end with "Exception".

src/Client/Exception/Transport.php

  line 7  [ExceptionSuffixRule]  Exception class "Transport" should end with "Exception".

[FAIL] Found 6 violations.

Time: 1.10s

Aha! Agora estamos chegando a algum lugar. Não é uma má decisão escrever as exceções dessa forma — afinal, elas são definidas dentro da estrutura de namespace como Exceções. Mas, para reiterar: você quer que seu LLM tenha o mínimo de trabalho possível para tomar a próxima decisão. Mais uma vez, a previsibilidade na sua base de código é o ponto-chave aqui.

Com apenas seis violações, e a correção consistindo em renomear seis classes, isso parece ser uma tarefa bastante trivial para Claude . Então, abro meu prompt no Cursor, colo as violações e peço para ele refatorá-las. Envio o código, crio um PR e, pronto:

https://github.com/Vonage/vonage-php-sdk-core/pull/553

Parece parece um exemplo simples, mas só para ter certeza, cheguei a perguntar ao Glean para me dizer, com suas próprias palavras, quais melhorias eu poderia fazer em um SDK para aprimorar a experiência do agente. A resposta dele confirmou o que eu já imaginava:

• Adicione campos de raciocínio estruturado às respostas da sua API

• Utilize convenções de nomenclatura consistentes - Os LLMs precisam de previsibilidade para tomar decisões

• Incluir ações de resolução nas respostas de erro para que os agentes saibam como resolver os problemas

// Example: Exception naming for predictability

// BAD - LLM can't predict this is an exception

class Invalid {}

// GOOD - Clear suffix helps LLM identify exceptions

class InvalidRequestException {}

Aí está, vindo do próprio agente, com uma solicitação de apenas uma frase.

Conclusão

Embora um exemplo simples aqui sirva para dar uma visão geral bem básica sobre como se preparar para a IA, também vale a pena mencionar que a experiência do agente é uma abordagem multifacetada. Para ter sucesso com a IA, eu não daria ouvidos, por exemplo, aos muitos, muitos influenciadores nos feeds do LinkedIn que afirmam “X é ruim, use Y”. Isso é simplista demais. A abordagem da Vonage é muito semelhante à de outros líderes do setor, na medida em que se trata de um esforço multiplataforma:

• Este artigo apresentou ferramentas para aprimorar seus SDKs para agentes que funcionam apenas como um LLM, tais como OpenClaw

• Além disso, um agente deveria ter a opção de utilizar um servidor MCP como alternativa (a Vonage, por exemplo, já lançou o nosso próprio), que, por sua vez, deve estar conectado a:

• Uma Interface de Linha de Comando (CLI) refatorada e mais robusta (e sim, a Vonage já tem uma há muito tempo) e uma estrutura de comandos voltada para o público, de modo que os agentes tenham a opção de simplesmente acessar a CLI por conta própria.

Três abordagens que permitem que as ferramentas de IA decidam qual é a melhor forma de realizar a tarefa que lhes foi atribuída. É assim que você se prepara para a IA.