En mi último artículo, te mostré por qué la verificación es la base de todo lo que hago con agentes y cómo empezar a crear tus propias habilidades de verificación. La lección clave fue que si un agente no puede verificar su propio trabajo, nada más importa. Sigues siendo el cuello de botella y pasarás todo el día supervisando a tus agentes.
https://x.com/poteto/status/2094457600259842065
Pero una vez que tienes la verificación funcionando, la siguiente pregunta es: ¿cómo averiguas realmente qué construir?
https://x.ai/bot/plugin/9717366
En este artículo, te guiaré a través de cómo hago investigación, planificación, prototipado y arquitectura con pstack. Este es el flujo de trabajo exacto que me permite enviar miles de PRs a producción cada mes mientras mantengo una calidad de código extraordinariamente alta.
Finalizando el mes de agosto con 2,462 PRs en producción
El arte de supervisar a alguien más inteligente que tú
Allá por los viejos tiempos de 2024, para hacer cualquier cambio en un sistema, primero necesitabas leer lo suficiente para construir un modelo mental de lo que estaba pasando. Dependiendo del tamaño y la complejidad del código base, esto podía llevarte desde horas hasta días e incluso meses. Con un cambio pequeño, podías arreglártelas con solo una comprensión local de un subsistema pequeño. Sin embargo, si estabas refactorizando el núcleo, probablemente necesitabas tener un modelo mental de cómo funciona todo para hacer la refactorización correcta y efectivamente.
Los agentes obviamente eliminan esta barrera. Puedes hacer cambios en los sistemas muy fácilmente con solo darle una instrucción a tu agente y él lo hará, sin importar cuánto o poco sepas sobre el código. Pero mantener la calidad del código y la experiencia de usuario sigue siendo difícil, especialmente si no eres ya un experto en el dominio que sepa qué buscar y qué preguntar.
Aunque los modelos frontera se han vuelto muy capaces, todavía hay 2 modos de fallo que observo constantemente:
- No logran entender completamente tu intención porque están subespecificados o mal especificados.
- No tienen suficiente contexto sobre cómo hacer el trabajo correctamente.
Ambos problemas están relacionados. Usar bien los agentes se reduce a qué tan bien eres capaz de preparar la ventana de contexto del agente con contexto de alta calidad. Ciertamente puedes escribir código que funcione sin hacer esto, pero encuentro que los resultados y la calidad son mucho mejores cuando he hecho el trabajo de proporcionar a mis agentes todo lo que necesitan para hacer un trabajo de alta calidad.
En tus propias palabras
Los modelos frontera son codificadores muy capaces. Mientras que con modelos más antiguos podría haber indicado muy específicamente lo que quería que hiciera, casi microgestionándolos, los últimos modelos son capaces de escribir código mejor que tú o yo. Así que hay un equilibrio fino que quiero lograr al decirle al agente lo que quiero que logre, mientras le doy la libertad de resolverlo de maneras que quizás no se me hubieran ocurrido.
Este es el arte de supervisar a alguien más inteligente que tú, en un código base que no has escrito tú mismo, y donde los humanos ya no pueden contener el modelo mental completo del código base en su cabeza.
Una técnica que me gusta usar es la instrucción indirecta. En lugar de decirle al agente exactamente lo que quiero, intento sacarlo del agente en su lugar, en sus propias palabras.
Por ejemplo, cuando alguien reporta un problema en Slack, a menudo le pido al agente que lea el hilo y reformule el problema en sus propias palabras antes de hacer cualquier otra cosa.
Por ejemplo, podría decir:
/poteto-mode lee este hilo de slack. reformula en tus propias palabras y en lenguaje sencillo cuál crees que es el problema subyacente
Esto logra tres cosas:
Primero, obliga al agente a comprimir una conversación ruidosa en una declaración de problema estructurada. Segundo, me permite detectar malentendidos de inmediato. Si el agente se fija en una pista falsa en el hilo, puedo corregirlo rápidamente antes de que empiece a escribir código.
Y tercero, no lo he llevado potencialmente por el camino equivocado al expresar mis propias suposiciones e hipótesis que podrían ser incorrectas o limitar lo que el agente podría lograr de otra manera.
Construyendo un modelo mental
Pedirle al agente que se reformule a sí mismo de una manera que puedas entender es una parte importante de trabajar con alguien que es más inteligente que tú. Esa fue la inspiración para /teach, una habilidad que ayuda a tu agente a explicarte las cosas de una manera intuitiva. La uso cada vez que necesito asegurarme de que mi agente está haciendo algo que tenga sentido para mí.
Internamente, /teach llama a /how y /why.
/how rastrea la mecánica en tiempo de ejecución. Cuando preguntas /how, el agente evalúa la complejidad del subsistema. Si el subsistema abarca múltiples directorios o servicios, genera agentes exploradores paralelos en modelos rápidos y eficientes como Grok.
/how está implementada la virtualización?
/why investiga la motivación y la intención. El código te dice qué sucede. Rara vez te dice por qué alguien lo escribió de esa manera. Cuando ejecutas /why, pstack consulta evidencia histórica a través de múltiples fuentes en paralelo: historial de Git y comentarios de revisión de PRs, tickets de Linear, documentos de diseño de Notion, conversaciones de Slack, monitores de Datadog, errores de Sentry, linaje de código y eventos del almacén de análisis.
/why todavía estamos atascados con una versión antigua de node.js?
Uso /teach cada vez que quiero que el agente reformule algo para poder entender mejor y confiar en su trabajo.
/teach me por qué lo implementaste de esta manera y no de <otra manera>. ¿cuáles fueron las compensaciones que hiciste y por qué?
En la práctica, también he descubierto que la investigación realizada por la habilidad /teach no solo es útil para los humanos, sino también para los agentes. Incluso con los últimos modelos frontera (esto también depende de la calidad del arnés), en general encuentro que todavía a menudo afirman cosas con confianza sin respaldarlas con datos o leer realmente el código necesario para construir un modelo mental de cómo funciona. Así que este acto de enseñarte lo que va a hacer y por qué termina ayudando también al agente.
Aprendiendo de la historia
Muchos de mis proyectos abarcan múltiples conversaciones. Por ejemplo, hace unos meses estaba trabajando en corregir errores de virtualización y problemas de rendimiento que la gente reportaba en Cursor. Me di cuenta de que cada vez que iniciaba un nuevo chat, básicamente tenía que empezar de nuevo construyendo el contexto rico que mi agente tenía antes cuando estaba resolviendo un problema similar.
Lo que me di cuenta es que tus transcripciones pasadas son a menudo una mina de oro para obtener contexto rico. pstack incluye la habilidad /recall para extraer tu contexto reciente del historial de chat, para que incluso los agentes nuevos tengan el contexto correcto que necesitan para volver a un buen estado.
/recall el trabajo que hice ayer sobre virtualización y luego lee este reporte de error en slack
Usar /teach, /recall, /how y /why es cómo mantengo actualizados mis propios modelos mentales del código base, comprimidos en una forma que puedo entender y recordar fácilmente. ¡Y también ayuda a los agentes!
Trabajando hacia atrás
Una vez que entiendes el problema, ¿cómo especificas la solución?
En mi opinión, la mayoría de los arneses que tienen modos de plan tienden a sobrespecificar los detalles de implementación y subespecificar todo lo demás. Es por eso que en pstack, dije con picardía que "no creo en la planificación". La verdad es que sí planifico, pero lo hago a través del código.
Para ciertos tipos de trabajo, como crear código compartido o paquetes que otros usarán, soy un gran creyente del desarrollo impulsado por el README. Si no estás familiarizado con ello, es una técnica de desarrollo que fue popular en su día, donde empiezas por redactar tu README primero. Esto te obligaba a ponerte el sombrero de experiencia de desarrollador, donde empiezas describiendo las APIs a un usuario hipotético, y trabajas hacia atrás hasta la implementación y la arquitectura.
Por ejemplo, cuando estaba construyendo Dune, nuestro framework cliente interno para aplicaciones de escritorio, empecé escribiendo primero un tutorial para ello, para poder entender cómo sería construir una aplicación con él. O al menos lo intenté. Fue una verdadera lucha conseguir que el agente produjera algo bueno o legible. Así que tuve que primero pasar un tiempo afilando mi cuchillo, creando la habilidad /technical-writing.
La primera versión del README sin la habilidad /technical-writing era dolorosa de leer porque mezclaba diferentes objetivos. Intentaba ser un tutorial, una guía práctica, una explicación arquitectónica y una referencia de API todo en el mismo documento, escrito con la habitual basura de IA y prosa amanerada.
/technical-writing utiliza el marco Diátaxis para separar la documentación en cuatro modos distintos:
- Tutorial: Aprender haciendo. Una lección que guía a un recién llegado a través de una serie de pasos para construir algo visible.
- Guía práctica: Pasos para resolver un problema específico del mundo real para un usuario experimentado.
- Referencia: Descripciones técnicas secas, completas y autorizadas de maquinaria, APIs y banderas de configuración.
- Explicación: Discusión de alto nivel que aclara e ilumina los antecedentes, las decisiones de diseño y las compensaciones.
También usa /unslop, por lo que produce documentación muy legible.
Escribir un plan de esta manera es muy útil porque también les da a tus agentes un objetivo y una meta concretos contra los cuales pueden verificar su propio trabajo. Y, por supuesto, también es mucho más fácil entender exactamente qué va a construir el agente.
Muchas de las habilidades de pstack se combinan aquí en la fase de diseño. Por ejemplo:
(1) /recall mi trabajo corrigiendo errores de virtualización y problemas de rendimiento de los últimos 7 días. usa /how y /why para entender cómo funciona nuestra implementación de virtualización actual.
(2) luego usa /poteto-mode planning y /technical-writing para crear un nuevo motor de virtualización que elimine categóricamente el parpadeo y la vibración. empecemos escribiendo un tutorial sobre cómo usaría este nuevo paquete para virtualizar una aplicación React
(3) después de escribir el plan, /teach me y pruébame por qué este nuevo enfoque es superior a nuestro motor actual
La técnica aquí se trata realmente de extraer un contexto interesante y rico que les dé a tus agentes la capacidad de ver el problema de la misma manera que tú, no solo como una pequeña porción:
- La primera parte de la instrucción recuerda el contexto pasado y presente relevante sobre cómo se implementa la virtualización en mi aplicación.
- La segunda parte guía al agente para que use ese contexto, como errores que ha corregido antes, para crear un nuevo diseño que elimine esos problemas por completo.
- La pieza final es pedirle a tu agente que te demuestre que este nuevo paquete es superior. Aquí es donde es importante tener herramientas de alta calidad como habilidades de verificación.
Mide cien veces, corta una
Al planificar, dos de los errores más comunes que veo son:
- Aceptar el primer diseño del agente.
- Sobrecocinar el plan sin evidencia empírica.
Cuando los humanos escribían código, a menudo colaborábamos entre nosotros a través de documentos de diseño. Estos eran documentos que hablaban sobre la arquitectura de alto nivel, alternativas consideradas, compensaciones y cualquier nota de implementación inusual. Era muy común pasar por múltiples iteraciones de estos documentos antes de llegar a un diseño establecido.
Con los agentes, aunque podemos saltarnos la ceremonia del documento de diseño, a menudo veo el error de aceptar lo primero que el agente te devuelve. Con pstack, podemos llevar el enfoque de "mide dos veces, corta una" al límite, utilizando agentes paralelos.
Hacemos esto usando el libro de jugadas de prototipado.
En pstack, los libros de jugadas no son habilidades, sino archivos de referencia dentro de /poteto-mode. Estos libros de jugadas se cargan condicionalmente (para eficiencia de tokens) dependiendo del tipo de tarea en la que estés trabajando. Estos 23 libros de jugadas (a partir de la versión 0.15.0) contienen cada uno un flujo de trabajo que uso cuando estoy haciendo una tarea.
A diferencia de las habilidades, los libros de jugadas son utilizados automáticamente por el agente como parte de /poteto-mode. Por ejemplo:
/poteto-mode prototipa algunas opciones para el nuevo menú desplegable /poteto-mode corrige este error /poteto-mode evalúa este cambio de habilidad
El prototipado es uno de mis libros de jugadas favoritos de pstack. Te da muchos intentos para lograr un objetivo y ayuda al agente a razonar sobre la mejor opción. Esto es útil no solo para el prototipado visual, sino también para prototipar diferentes soluciones para funciones, correcciones de errores, etc.
/poteto-mode prototipa algunas opciones para <solicitud de función>. usa /control-app* y toma videos/capturas de pantalla para que las revise y elija
\ nota: /control-app es la habilidad de verificación que creamos en [Parte 1*](https://x.com/poteto/status/2094457600259842065
Al prototipar cambios visuales, el agente construye bocetos desechables en tu aplicación o en un directorio de pruebas. Si está probando una interacción de UI, coloca dos o tres variaciones detrás de un conmutador simple. Luego impulsa la interacción con la habilidad /control-app, toma capturas de pantalla de cada variante y mide el tiempo real o el diseño.
El prototipado es planificación, pero con código. Permite a los agentes la libertad de explorar el espacio del problema y les da la oportunidad de sorprenderte con algo que no se te habría ocurrido a ti mismo. Los prototipos permiten a los agentes responder sus propias preguntas con evidencia empírica en lugar de esperar mi opinión.
Arquitectando cambios más grandes
Como ingeniero en la era de los agentes, es más importante dedicar mi tiempo a la arquitectura, elegir las estructuras de datos correctas y pensar en cómo los sistemas que construyo funcionarán juntos. Mis agentes llenan los detalles de implementación.
Otra habilidad útil que incluye pstack es /architect. Estructura el diseño en fases distintas y disciplinadas:
- Fundamenta el problema. El agente ejecuta /how y /why sobre los sistemas afectados para construir un modelo mental preciso de la propiedad y las restricciones existentes.
- Boceto. El agente entra en una arena de arquitectura. Genera ejecutores de candidatos independientes en paralelo, a menudo a través de diferentes familias de modelos. Cada ejecutor recibe el resumen de fundamentación y redacta un paquete de diseño completo: el boceto de uso del llamador, las definiciones de tipos centrales, las firmas de funciones públicas y una justificación concisa. Estos generalmente se hacen dibujando solo las firmas de tipo, que se derivan de cómo queremos que se vean los sitios de llamada. Cada ejecutor debe evaluar la profundidad de la interfaz, examinar los modos de fallo en modelos débiles y filtrar contra nuestro catálogo de banderas rojas de diseño.
- Evaluación cruzada y síntesis. Un agente de evaluación cruzada que utiliza un modelo diferente al del agente principal evalúa a los candidatos contra una rúbrica estricta.
- Implementar contra el boceto. El agente reemplaza los cuerpos de marcador de posición del boceto con lógica real. Si el agente descubre durante la implementación que una función necesita parámetros inesperados o estado adicional, expone la discrepancia.
- Desechar cuando el diseño es incorrecto. Si durante la implementación encontramos que los bocetos eran incorrectos, el agente lo tira todo y empieza de nuevo.
El punto aquí es darle al agente un mini-bucle autocontenido donde pueda sintetizar múltiples diseños competidores de diferentes familias de modelos en un enfoque óptimo, y tener cuidado de ser riguroso y no tener miedo de desechar su diseño si resulta que la arquitectura que concibió es incorrecta basándose en pruebas empíricas. Si la misma solución alternativa aparece en sitios de llamada no relacionados, o si los tipos requieren escapes como 𝚊𝚗𝚢 o conversiones forzadas, esa es una prueba empírica de que la arquitectura es incorrecta.
/architect esta nueva <solicitud de función>
La gran lección aquí es que es mucho más efectivo planificar con código usando el prototipado de /poteto-mode y /architect.
También es por eso que nunca me molesto en revisar planes abstractos de manera adversarial. Los agentes empiezan a alucinar riesgos teóricos e inventar casos extremos complejos para protegerse contra problemas que nunca sucederán. No sobrecocines tus planes cuando todavía son abstractos: deja que el agente responda preguntas abiertas por sí mismo mediante el prototipado y la verificación de su propio trabajo.
Vale, pero realmente quiero un documento de planificación
Aunque pstack no viene con una habilidad de planificación, sí incluye un libro de jugadas de planificación multifásica. Normalmente lo uso después de que el agente haya creado un diseño con el que estoy satisfecho, como una forma de crear un plan de ejecución táctico.
/poteto-mode convierte este diseño en un plan
Cada tarea en el plan está estructurada en torno a la prueba y la verificación. El libro de jugadas les dice a los agentes que las pruebas por sí solas no son una verificación suficiente. Se verifica solo cuando realmente ha ejecutado el código y verificado que funciona.
Cada plan es verificado por un script automatizado que valida su estructura y formato. Una vez aprobado, el plan se ejecuta elemento por elemento. Cada PR es pequeño, autocontenido y fácil de revisar.
Para proyectos realmente grandes (como uno que podría llevarme una semana entera), a veces puedo decidir comprometer los planes temporalmente en el código base para que otros agentes estén al tanto del trabajo en curso. Pero normalmente los elimino cuando termino para no dejar el código base en un estado de confusión. No encuentro valioso mantener los planes permanentemente.
El flujo de trabajo en la práctica
Para ver cómo encajan todas estas piezas, repasemos tres ejemplos concretos de cómo indico estos flujos de trabajo.
Ejemplo 1: Investigar un error ambiguo
Cuando aparece un problema en producción y la causa raíz no está clara:
/poteto-mode investiga por qué los trabajadores en segundo plano fallan periódicamente con errores de tiempo de espera. dame un desglose de lo que sabemos, qué datos usaste y tus mejores hipótesis.
El agente explora el código, verifica métricas y confirmaciones históricas en paralelo, y te da sus mejores conjeturas fundamentadas sobre dónde podría estar el problema.
Ejemplo 2: Diseñar un nuevo límite de servicio
Al introducir un nuevo subsistema del que dependerán otros módulos:
/poteto-mode necesitamos agregar limitación de velocidad para webhooks externos. /architect esto primero y responde cualquier pregunta abierta con prototipos. déjame revisar antes de continuar.
El agente fundamenta la arquitectura de webhook existente, inicia ejecutores de diseño competidores en múltiples modelos, compara con prototipos desechables y produce una interfaz limpia y verificada.
Ejemplo 3: Ejecutar una migración de múltiples PRs
Al ejecutar una refactorización compleja a través de muchos archivos:
/poteto-mode crea un plan para migrar toda nuestra biblioteca de UI a StyleX. divide la migración en PRs pequeños y verificables. cada PR debe tener sus pruebas de regresión visual y pasos de verificación en vivo. quiero que el resultado final sea 100% idéntico en comparación con el original, errores incluidos
El agente divide el trabajo en pasos independientes, escribe una lista de verificación auditable y prepara cada unidad para que pueda construirse, verificarse y publicarse de forma segura.
Ejemplo 4: Arreglar cosas que la gente reporta en Slack
Si alguna vez me has visto en Slack en uno de nuestros canales de problemas o comentarios, probablemente hayas visto estos clásicos:
# el hilo ya tiene suficiente contexto
/poteto-mode hazlo
/poteto-mode reproduce esto con /control-app. si se reproduce en main, arréglalo y muéstrame un video como prueba
Muchas de las habilidades de las que he hablado aquí ya son utilizadas automáticamente por /poteto-mode, por lo que la gran mayoría de las veces puedes simplemente usar /poteto-mode y ¡seguir con tu vida!
El arte de la planificación
El modo de planificación se usa a menudo como una forma de convencerte a ti mismo de que el agente va a hacer lo correcto. Pero la realidad es que los planes abstractos solo te dan la ilusión de progreso. Un plan largo y extenso hace que parezca que tú y tu agente fueron muy productivos, pero probablemente carece de sustancia.
pstack te proporciona herramientas para combinar una investigación exhaustiva, evidencia empírica y verificación rigurosa. Cuando planificas de esta manera, la ingeniería con agentes deja de sentirse como una apuesta. Se vuelve predecible y repetible.
https://x.ai/bot/plugin/9717366
Gracias por leer, ¡y estad atentos a la Parte 3!
