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 cuidando a tus agentes.
https://x.com/poteto/status/2094457600259842065
Pero una vez que la verificación funciona, 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 al mes a producción mientras mantengo la calidad del código extraordinariamente alta.
Terminando 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 tomarte desde horas hasta días y meses. Con un cambio pequeño, podías arreglártelas con solo un entendimiento local de un subsistema pequeño. Sin embargo, si estabas refactorizando el núcleo, probablemente necesitabas tener un modelo mental de cómo funcionaba 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 instrucciones 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 del usuario alta sigue siendo difícil, especialmente si no eres ya un experto en el dominio que sepa qué buscar y preguntar.
Aunque los modelos de frontera se han vuelto muy capaces, todavía hay 2 modos de falla que observo constantemente:
- No pueden entender completamente tu intención porque están mal o pobremente especificados.
- No tienen suficiente contexto sobre cómo hacer el trabajo correctamente.
Ambos problemas están relacionados. Usar agentes bien 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 de frontera son codificadores muy capaces. Mientras que con modelos más antiguos podía dar instrucciones muy específicas sobre lo que quería que hiciera, casi microgestionándolos, los modelos más recientes pueden 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 había pensado.
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 caber todo el modelo mental 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 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 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é pasa. 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 en una versión antigua de node.js?
Uso /teach cada vez que quiero que el agente reformule algo para que pueda entender y confiar mejor en su trabajo.
/teach 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 encontrado 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 modelos de frontera más recientes (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 contexto rico. pstack incluye la habilidad /recall para extraer tu contexto reciente del historial de chat, así que incluso los agentes nuevos tienen 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 mis propios modelos mentales del código base actualizados, 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 especificar en exceso los detalles de implementación y a especificar de menos todo lo demás. Por eso en pstack, dije en broma 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 readme. Si no estás familiarizado, es una técnica de desarrollo que fue popular en su momento, donde empiezas creando tu readme primero. Esto te obligaba a ponerte el sombrero de experiencia de desarrollador, donde empiezas describiendo las API 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 él, para poder entender cómo sería construir una aplicación con él. O al menos lo intenté. Fue una verdadera lucha lograr que el agente produjera algo bueno o legible. Así que tuve que primero pasar algo de 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 y del mundo real para un usuario experimentado.
- Referencia: Descripciones técnicas secas, completas y autorizadas de maquinaria, API y banderas de configuración.
- Explicación: Discusión de alto nivel que aclara e ilumina antecedentes, decisiones de diseño y 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 que escribas el plan, /teach y pruébame por qué este nuevo enfoque es superior a nuestro motor actual
La técnica aquí se trata realmente de extraer 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 relevante pasado y presente sobre cómo está implementada la virtualización en mi aplicación.
- La segunda parte guía al agente a usar 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 herramientas de alta calidad como las habilidades de verificación son importantes de tener.
Mide cien veces, corta una
Al planificar, dos de los errores más comunes que veo son:
- Aceptar el primer diseño del agente.
- Cocinar demasiado 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 en su lugar llevar el enfoque de "mide dos veces, corta una" al límite, usando agentes paralelos.
Hacemos esto usando el playbook de prototipado.
En pstack, los playbooks no son habilidades, sino archivos de referencia dentro de /poteto-mode. Estos playbooks se cargan condicionalmente (para eficiencia de tokens) dependiendo del tipo de tarea en la que estés trabajando. Estos 23 playbooks (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 playbooks 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 playbooks favoritos de pstack. Te da múltiples intentos para un objetivo y ayuda al agente a razonar sobre la mejor opción. Esto es útil no solo para 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 prueba. 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 habrías pensado tú mismo. Los prototipos permiten a los agentes responder sus propias preguntas con evidencia empírica en lugar de esperar mi opinión.
Arquitecturando cambios más grandes
Como ingeniero en la era de los agentes, es más importante pasar mi tiempo en la arquitectura, eligiendo las estructuras de datos correctas y pensando en cómo los sistemas que construyo trabajarán juntos. Mis agentes llenan los detalles de implementación.
Otra habilidad útil que pstack incluye 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 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 tipos, 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 falla 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 usa un modelo diferente al del agente principal evalúa a los candidatos contra una rúbrica estricta.
- Implementa 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, saca a la luz la discrepancia.
- Descarta 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 descartar su diseño si resulta que la arquitectura que creó es incorrecta basada 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 /poteto-mode prototyping 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 ocurrirán. No cocines demasiado tus planes cuando todavía son abstractos: deja que el agente responda preguntas abiertas por sí mismo a través del prototipado y la verificación de su propio trabajo.
Está bien, pero realmente quiero un documento de planificación
Si bien pstack no viene con una habilidad de planificación, sí incluye un playbook de planificación multifásica. Normalmente lo uso después de que el agente ha 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 playbook 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 tomarme una semana completa), a veces puedo decidir comprometer los planes temporalmente en el código base para que otros agentes estén al tanto del trabajo en progreso. 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 todas estas piezas encajan, repasemos tres ejemplos concretos de cómo uso estas instrucciones para 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 commits históricos 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 webhooks existente, genera ejecutores de diseño competidores a través de 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 lanzarse de manera 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 habrás 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, así que la gran mayoría de las veces puedes simplemente usar /poteto-mode y seguir con tu vida!
El arte de planificar
El Modo Plan a menudo se usa 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 da herramientas para combinar 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 mantente atento a la Parte 3!
