Si no puede leer su código PHP, tampoco su LLM

Hay muchos conceptos erróneos, opiniones y discursos de personas influyentes en torno a la IA. Todo el mundo se pregunta si está preparado para la IA, una pregunta muy válida.

La IA no lo hará todo por ti. Lo hará intentará de hacerlo todo por ti si se lo permites, pero dependiendo de la pila que estés utilizando, los resultados serán probablemente mixtos. La forma más importante de tratar la IA es como un conjunto adicional de herramientas en tu arsenal. Esto, como resultado, es sólo otra iteración de tener un conjunto decente de herramientas como el análisis estático, linters de código, y pruebas bien escritas.

Para preparar tu código base para el uso de IA, vamos a ver cómo usar Readalizer de PHPde PHP, porque las herramientas de IA son tan buenas como el código que leen.

¿Qué es Readalizer?

Readalizer es una biblioteca PHP que ofrece a los desarrolladores una API compuesta por un conjunto de reglas que aplicará en su código base. En tiempo de ejecución, ingiere cada archivo PHP definido en su configuración, y tokeniza su código utilizando el Árbol de sintaxis abstracta. Un ejemplo de regla sería NoTodoWithoutTicketRule. En tiempo de ejecución, tu código:

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

Esto fallará. La regla establece que algún tipo de referencia de billete debe dentro del comentario en línea. Así que, para solucionarlo, tenemos que modificar nuestro comentario:

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

Hay muchas reglas, así que no podemos repasarlas todas. Lo que haremos, sin embargo, es mostrar una implementación y por qué es importante en una base de código en vivo.

Espera, ¿en qué se diferencia esto del análisis estático?

Ah, me alegro de que lo preguntes. Porque, en esencia, un conjunto de reglas y una herramienta de pasa o no pasa se parece a los analizadores estáticos como PHPStan o PsalmPHP (ambos también usan el AST para analizar el código PHP en tokens). Sin embargo, hay una diferencia muy clara entre los dos. El análisis estático asegura que su código funciona. Readalizer no se preocupa de si su código funciona o no, sólo que siga las reglas que le has dado. Por lo tanto, podemos concluir que un analizador estático forma parte de su cadena de herramientas de calidad del código, pero el mayor caso de uso de Readalizer es asegurarse de que tanto los humanos como los Large Language Models puedan leer su código y tomar decisiones mejoradas debido a los conjuntos de reglas que ha implementado.

Readalizer en palabras del autor

Algo que me gusta hacer ahora en los artículos es preguntar a los creadores de un proyecto cómo surgió y cuál es el objetivo del proyecto. del proyecto. Así que aquí van unas palabras sobre lo que es Readalizer, en Christopher Millerde Christopher Miller:

"Readalizer fue diseñado desde cero para ayudarle tanto a usted como a sus Agentes de Inteligencia Artificial a entender su Código PHP. La inspiración para comenzar este paquete fue una cita de Ondrej Mirtes, quien dijo que PHPStan no se preocupa por el aspecto de su código; ese es el trabajo de otra persona. Así que lo hice mío. Habiendo pasado la mayor parte de mi carrera hablando de código legible, pensé que ya era hora de hacer algo al respecto. Ahí es donde entra Readalizer. Le permite personalizar las reglas con configuraciones, reglas personalizadas y conjuntos de reglas personalizadas, mientras se pone en marcha en unos 30 segundos."

Ejecutar Readalizer en el SDK PHP de Vonage

Para ver cómo funciona esto en la práctica, vamos a ejecutar Readalizer en una base de código del mundo real: el Vonage PHP SDK.

El objetivo aquí es simple: identificar dónde la mejora de la coherencia del código puede hacer que el proyecto sea más fácil de entender tanto para los humanos como para los LLM.

Para empezar, sólo hay que seguir dos pasos:

composer require readalizer/readalizer

vendor/bin/readalizer --init

Esto le dará una readalizer.php config en la raíz de su proyecto. Excelente. He modificado el boilerplate para que busque en el directorio src por defecto, y deshabilité temporalmente todas las reglas para que podamos habilitarlas de una en una y ver su 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(),
   ],
];

. A continuación, me puse a añadir reglas, una por una. En primer lugar, añadí la regla ClassNamePascalCaseRule()que se asegura de que todas las clases del código fuente estén en PascalCase (así que los desarrolladores de WordPress deberían mirar hacia otro lado). Ejecuté Readalizer y obtuve los resultados:

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

[OK] No readability violations found.

Time: 1.06s

Aquí no hay infracciones. Buen trabajo, autores del SDK¡! Supongo que será mejor que elija otro. Por lo tanto, me fui con el ExceptionSuffixRule(). Esta regla dice que todas sus /Excepción's deben ser identificables por tener Excepción en el nombre de la clase. Para un LLM, esto es importante porque la estructura del archivo y las convenciones de nomenclatura le dan previsibilidad. ¿Qué ocurre entonces cuando ejecutamos esto?

[##############################] 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

Ahora estamos llegando a alguna parte. No es una mala decisión tener las excepciones escritas de esta manera - están, después de todo, definidas dentro de la estructura del espacio de nombres como Excepciones. Pero para reiterar: quieres que tu LLM tenga el menor trabajo posible para tomar la siguiente decisión. Una vez más, previsibilidad en tu código base es la clave aquí.

Con sólo seis violaciones, y la solución de cambiar el nombre de seis clases, esto parece un trabajo bastante trivial para Claude para arreglar. Así que abro mi prompt en Cursorpego las violaciones, y le digo que las refactorice. Subo el código, creo un PR, y listo:

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

En parece un pequeño ejemplo, pero sólo para comprobar la cordura, incluso le pedí a Glean que me dijera con sus propias palabras qué mejoras puedo introducir en un SDK para mejorar la experiencia del agente. Su resultado confirmó lo que yo suponía:

• Añada campos de razonamiento estructurado a sus respuestas API

• Utilizar convenciones de nomenclatura coherentes - Los LLM necesitan previsibilidad para tomar decisiones

• Incluya acciones de resolución en las respuestas de error para que los agentes sepan cómo solucionar los 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 {}

Ahí lo tienes, desde el propio agente con un aviso de una sola frase.

Conclusión

Aunque este sencillo ejemplo sirve para ofrecer un esquema muy suave sobre cómo estar preparado para la IA, también merece la pena mencionar que la experiencia del agente es un enfoque polifacético. Para tener éxito con la IA, yo no escucharía, por ejemplo, a los muchos, muchos influenciadores en los feeds de LinkedIn que afirman "X es malo, usa Y". Eso es demasiado simplista. El enfoque de Vonage es muy parecido al de otros líderes del sector, ya que se trata de un esfuerzo multiplataforma:

• En este artículo se esbozaban herramientas para mejorar sus SDKs para Agentes que se ejecutan sólo como un LLM, tales como OpenClaw

• Además de esto, un Agente debería poder tener la opción de utilizar un servidor MCP como opción alternativa (Vonage, por ejemplo ha lanzado el nuestro), que a su vez debería estar conectado:

• Una interfaz de línea de comandos (CLI) refactorizada y reforzada, Vonage tiene una desde hace mucho tiempo) y una estructura de comandos pública para que los agentes tengan la opción de utilizar la CLI por sí mismos.

Tres enfoques, permitiendo que las herramientas de IA decidan qué es lo que mejor cumple la tarea que se le ha encomendado. Así es como te preparas para la IA.