¿Qué hace Flujo de Trabajo de Desarrollo de Proyecto?
Una disciplina operativa aplicada a lo largo de un proyecto de desarrollo. Aborda estos fallos: una IA comienza a codificar basándose en una solicitud malinterpretada; termina de escribir y luego declara que su propio trabajo está bien; defiende un diseño desde un único punto de vista; hace solo lo que se le dijo; y repite un obstáculo que ya encontró la vez anterior.
El peso de la disciplina debe coincidir con la importancia de la tarea: las tareas pequeñas toman el nivel ligero — no ejecutes un proceso por el mero hecho de hacerlo.
El flujo de trabajo completo:
Entrada: enrutamiento de sección única / decisión de nivel (ligero · estándar) / si se debe trabajar de forma autónoma
0. Pre-vuelo — leer el registro de obstáculos y las reglas del proyecto, confirmar el estado del espacio de trabajo
1. Comprender — replantear la solicitud; actuar solo después de que el usuario confirme
2. Planificar — dividir en capas, cada una con criterios de finalización verificables
3. Ejecutar y verificar — verificar cada capa según los criterios, por sí mismo o mediante un verificador; sin aprobación, no se pasa a la siguiente capa
4. Informar — evidencia, elementos no verificados, críticas aceptadas/rechazadas, sugerencias, nuevos obstáculos
Durante todo el proceso: revisión adversaria (§5), ejecución proactiva (§6), registro de obstáculos en tiempo real (§7)
Entrada: decidir cómo usarlo
Invocación de sección única
Cuando el usuario nombra solo una etapa, ejecuta esa sección únicamente; no ejecutes el flujo de trabajo completo:
| El usuario dice | Ejecutar |
|---|---|
| critica / revisa este plan / ¿este enfoque está bien? | Solo §5 |
| verifica esto / comprueba si es correcto | Solo verificación §3. El objeto es lo que el usuario especificó; si los criterios de finalización no están claros, alinéalos con el usuario antes de verificar |
| registra este obstáculo / actualiza los obstáculos | Solo §7 |
| sigue el flujo de trabajo / ejecuta esto correctamente | El flujo de trabajo completo (nivel estándar) |
Niveles ligero y estándar
Decide el nivel antes de comenzar e indica cuál elegiste en una línea en tu primera respuesta.
Nivel ligero — se cumplen las tres condiciones:
- la solicitud es inequívoca, con solo una lectura razonable;
- se puede revertir fácilmente, sin eliminación de datos, interfaces públicas o impacto externo;
- el cambio está concentrado (un punto de funcionalidad, pocos archivos) y un solo paso de verificación decide el resultado.
El nivel ligero omite el replanteamiento, la estratificación y los subagentes, pero aún respeta la sección §0 de pre-vuelo, las reglas de evidencia de §3 y el registro de obstáculos de §7, y cierra con el informe corto de §4.
Nivel estándar: todo lo demás. Cuando no estés seguro, usa el nivel estándar.
Si una tarea de nivel ligero resulta ser más compleja de lo estimado (involucra otros módulos, aparece ambigüedad, se necesita una operación irreversible): actualiza al nivel estándar inmediatamente y haz el replanteamiento y la confirmación de forma retroactiva.
Modo autónomo
Cuando el usuario dice explícitamente "solo hazlo / no me preguntes / tú decides", o la tarea es una ejecución prolongada sin supervisión en un entorno no interactivo:
- §1 aún escribe "mi entendimiento", pero no espera confirmación. Cada elemento bajo "decisiones que necesito de ti" se decide tomando la opción recomendada, se registra como una suposición propia, y el trabajo continúa;
- las operaciones que son irreversibles o tienen impacto externo (eliminar datos, desplegar, hacer push, migración de datos, llamadas a APIs de pago) aún no se realizan; omítelas, enuméralas en el informe y déjalas para el usuario;
- el informe final enumera todas las suposiciones propias juntas, para que el usuario pueda corregirlas después.
0. Pre-vuelo
- Registro de obstáculos: si la raíz del proyecto tiene
PITFALLS.md, léelo antes de planificar; si el archivo mantiene un índice en la parte superior, lee primero el índice, luego las entradas relevantes para la tarea actual. Si existe un registro a nivel de máquina en~/.agents/PITFALLS.local.md, léelo también (consulta §7 para el ámbito). Menciona las entradas relevantes para la tarea por su nombre en el replanteamiento o el plan. - Reglas del proyecto: si el proyecto tiene
AGENTS.md,CLAUDE.md,CONTRIBUTING.mdo archivos de reglas similares, síguelos también. - Estado del espacio de trabajo: si el proyecto es un repositorio git, comprueba primero
git status. Los cambios no confirmados que ya existen pertenecen al usuario: recuérdalos, no los sobrescribas y no los mezcles con tus propios cambios. Si no es un repositorio git y el cambio es arriesgado, advierte primero al usuario, o haz una copia de seguridad de los archivos que estás a punto de modificar.
1. Comprender y confirmar
La redacción del usuario generalmente omite el contexto, mezcla objetivos con medios y deja las limitaciones sin expresar. Codificar según la redacción literal y equivocarse cuesta mucho más que una ronda adicional de preguntas.
Cuándo el replanteamiento y la confirmación son obligatorios
Cualquiera de estos hace que el replanteamiento y la confirmación sean obligatorios (excepto en modo autónomo):
- la solicitud tiene dos o más lecturas razonables, y las lecturas conducen a resultados materialmente diferentes;
- el usuario dio un objetivo en lugar de una instrucción ("haz que el inicio de sesión sea más bonito");
- el trabajo implica operaciones irreversibles, impacto externo, eliminación de datos, o cambios en interfaces públicas o en el modelo de datos;
- el cambio abarca múltiples módulos, o es lo suficientemente grande como para que ir en la dirección incorrecta sea costoso de deshacer.
Las tareas de nivel ligero pueden realizarse directamente, con una explicación posterior. Cuando no estés seguro, trátalo como "confirmación requerida".
Qué puedes hacer antes de la confirmación
Puedes hacer trabajo de preparación: leer código y documentación, ejecutar comandos de solo lectura (inspeccionar el estado, ejecutar pruebas existentes, comprobar versiones). No puedes: modificar archivos, instalar dependencias, cambiar la configuración, ni ejecutar ningún comando con efectos secundarios.
Formato del replanteamiento
Haz el trabajo de preparación antes de replantear. Un replanteamiento reconstruye el requisito con tus propias palabras; no es una recitación de la frase del usuario. Expón tus suposiciones para que el usuario pueda ver de un vistazo dónde te equivocas.
**Mi entendimiento**
- Objetivo: <el problema a resolver / el efecto a lograr, una o dos oraciones>
- Entregables: <lo que existirá al final: archivos, funcionalidades, documentos…>
- Dentro del alcance: <lo que harás>
- Fuera del alcance: <lo que explícitamente no harás, para evitar la expansión del alcance>
- Limitaciones: <stack, estilo, áreas que no tocar, límites de tiempo/recursos>
- Criterios de aceptación: <cómo decidirá el usuario que está hecho, tan observable como sea posible>
- Mis suposiciones: <puntos no declarados que inferiste por tu cuenta>
**Decisiones que necesito de ti**
1. <pregunta>? Opción A: … / Opción B: … (me inclino por X porque …)
Si el entorno proporciona una herramienta de preguntas de opción múltiple, prefierela para la parte de "decisiones que necesito", con una opción recomendada.
Después de la confirmación
- Trata la versión confirmada como la línea base de requisitos. Regístrala en el plan o en la lista de tareas pendientes; cada verificación posterior se juzgará en función de ella.
- Si la línea base resulta ser incorrecta, o el alcance debe expandirse: detente, explica el cambio y su impacto, vuelve a confirmar y continúa. No amplíes ni reduzcas el alcance en silencio.
- Después de que el usuario confirme, procede a través del plan sin volver a preguntar "¿debo continuar?" en cada paso. Detente solo por un cambio de objetivo, una operación irreversible o una compensación que el usuario debe decidir.
- Cuando uses una herramienta de preguntas, un tiempo de espera o una pregunta sin respuesta no es consentimiento: deja ese elemento pendiente, procede solo con las partes que no dependen de él, y enumera los elementos pendientes nuevamente en el siguiente informe. No procedas silenciosamente con la opción recomendada.
2. Plan en capas
Divide la tarea en capas (etapas); cada capa es un incremento que se puede verificar por sí mismo. Cada capa establece tres cosas:
| Elemento | Requisito |
|---|---|
| Salida | Qué existe específicamente al final de esta capa |
| Criterios de finalización | Condiciones verificables, p. ej., "npm test está en verde", "la interfaz X devuelve Z para la entrada Y", "sin desplazamiento horizontal a 375px de ancho", "el archivo A ya no hace referencia a B". Descripciones que no pueden verificarse — "buena calidad del código", "básicamente funciona" — están prohibidas |
| Método de verificación | Autocomprobación, o un verificador independiente (consulta los criterios en §3) |
- Si el plan implica compensaciones significativas (elección de tecnología, arquitectura, modelo de datos), realiza una ronda de revisión adversaria §5 antes de finalizarlo.
- Muestra el plan al usuario de forma resumida. Para un plan pequeño ya confirmado durante el replanteamiento, comienza directamente después de mostrarlo.
- Para tareas largas, escribe el plan y el progreso en una lista de tareas pendientes o archivo de tarea y mantenlo actualizado, para que el trabajo pueda reanudarse desde el punto de interrupción si la sesión se interrumpe.
- Puntos de control: cada capa verificada es un punto de control. No hagas
git commitogit pushsin el consentimiento del usuario. Si el usuario acepta confirmar por capa, confirma una vez después de que cada capa pase, siguiendo el estilo de mensaje de confirmación existente del proyecto.
3. Ejecución y verificación capa por capa
Verifica cada capa antes de comenzar la siguiente. Si la verificación falla, corrígela y verifica nuevamente. Si el mismo criterio falla dos veces seguidas, detente y analiza primero la causa raíz (y considera registrar un obstáculo) en lugar de parchear in situ.
Autocomprobación o un verificador independiente
Cualquiera de estos significa que debes pasar la verificación a un verificador independiente:
- la capa está orientada al usuario, la superficie de cambio es grande o el riesgo es alto;
- los criterios de finalización requieren ejecutar, operar o comparar cosas para juzgar, y no un solo comando;
- es la entrega final de una tarea de nivel estándar;
- estás profundamente involucrado en tu propia implementación y es probable que veas todo como correcto.
La autocomprobación es aceptable para: tareas de nivel ligero; o cambios pequeños cuyos criterios decide un solo comando, con un resultado obvio.
Uso del verificador
El valor del verificador radica en su independencia: no debe heredar el razonamiento o la autojustificación del implementador.
- Proporciónale: la línea base de requisitos, los criterios de finalización de esta capa, las rutas de archivo relevantes, cómo ejecutar las cosas y el rango de cambios (
git diffo un rango de confirmaciones). El rango de cambios es un hecho, no una línea de razonamiento, y ayuda al verificador a encontrar lugares que deberían haber cambiado pero no lo hicieron. - No le proporciones: tu razonamiento de implementación, tus justificaciones de compensaciones, ni nada como "creo que ahora está bien".
- Permisos: no puede modificar el código fuente, la configuración ni la documentación. Puede ejecutar comandos de verificación locales (pruebas, compilaciones, linters), y los artefactos de compilación resultantes están bien. Los comandos con efectos secundarios externos están prohibidos — desplegar, migración de datos,
git commit/git push, eliminar datos, llamar a APIs de producción o de pago. - Exígele que verifique cada criterio de verdad (ejecuta el comando, lee el código, inspecciona la salida) y que informe aprobado / fallido / no se puede verificar por elemento con evidencia, además de cualquier problema que encuentre fuera de los criterios, ordenado por gravedad.
- Las correcciones son tuyas, para que el verificador y el implementador no vuelvan a ser la misma persona.
- Si la implementación fue realizada por un agente de codificación CLI (omp / codex / claude-code), verifica de acuerdo con la sección de Verificación de la habilidad
omp: lee el diff que produjo, busca específicamente ramas condicionales que solo cubran el camino feliz, ejecuta el subconjunto más pequeño de forma independiente con--filter, y envía el retrabajo como "archivo:línea + criterio aprobado/fallido + aserción esperada". - Las plantillas de indicaciones están en la sección "Subagente verificador" de references/subagent-prompts.md.
Si el entorno actual no tiene capacidad de subagente, o las reglas del usuario o anfitrión prohíben subagentes: cambia tú mismo al rol de verificador, comprueba cada criterio contra la misma plantilla y escribe la evidencia, en lugar de marcar casillas de memoria.
Manejo de los resultados de verificación
- Criterios fallidos: corrige, luego verifica nuevamente (continúa con el mismo verificador o envía uno nuevo).
- Crees que el verificador está equivocado: debes producir contraevidencia (un comando y su salida, un archivo:línea) para anular el veredicto, y declarar en el informe qué veredicto anulaste y sobre qué base. No te convenzas de lo contrario solo con argumentos.
- Problemas encontrados fuera de los criterios: solo los "graves" — que incumplen la línea base de requisitos, datos incorrectos, fallos, problemas de seguridad — bloquean la siguiente capa. Registra el resto y enuméralos en el informe, o muévelos a sugerencias fuera del alcance.
Reglas de evidencia
- Cualquier cosa que no se haya ejecutado o inspeccionado realmente no puede llamarse "hecho" o "aprobado". La única redacción permitida es "implementado, no verificado".
- Que las pruebas locales pasen no es aceptación del usuario. Que las pruebas unitarias pasen no es una funcionalidad en funcionamiento. Indica qué nivel verificaste realmente.
4. Informe final
Nivel estándar, un informe después de que todas las capas estén completas:
**Finalización**: <cada elemento de la línea base de requisitos, abordado por turno>
**Evidencia de verificación**: <lo que se ejecutó y lo que devolvió; qué elementos verificó un verificador; qué veredictos de verificación anulaste y sobre qué base>
**No verificado / limitaciones conocidas**: <rutas no ejercitadas, lagunas conocidas>
**Suposiciones propias**: <solo modo autónomo: lo que decidiste por tu cuenta, qué operaciones irreversibles omitiste>
**Resultado de la crítica**: <qué críticas recibieron las decisiones clave, cuáles se aceptaron y cuáles se rechazaron, y por qué>
**Sugerencias fuera del alcance**: <propuestas de §6 que necesitan la decisión del usuario, con valor y costo>
**Obstáculos nuevos / actualizados**: <títulos de las entradas escritas>
La línea "No verificado / limitaciones conocidas" es obligatoria; cuando realmente no hay ninguna, escribe "ninguna" y explica por qué estás seguro. Las otras líneas pueden omitirse cuando están vacías.
Nivel ligero, el formulario corto:
**Lo que se hizo**: <una o dos oraciones>
**Cómo se verificó**: <comando + resultado>
**Limitaciones conocidas**: <solo si las hay>
El informe declara solo hechos y evidencia. Sin autoevaluaciones como "perfectamente implementado", "muy elegante", "mejora masiva".
De lo que los usuarios se quejan más en proyectos largos es del progreso como una caja negra: informar solo este incremento les impide juzgar dónde se encuentra todo el proyecto. Periódicamente — o siempre que se solicite — entrega un panorama desde cero hasta ahora: cronograma de etapas y cada estado actual. Esto evita que el usuario tenga que reconstruir el historial de la sesión. Para una sesión nueva, el panorama se limita a lo que ha sucedido en esta sesión.
5. Revisión adversaria de decisiones clave
Aplicar por decisión importante antes de comprometerse: arquitectura, modelo de datos, elección de librería, estructura de API, herramientas, dependencias, cambios de configuración. Cada decisión recibe el mismo tratamiento:
¿Es necesaria la revisión adversaria?
La revisión adversaria es necesaria cuando la decisión satisface cualquiera de estos:
- irreversible, o costosa de deshacer (migración de datos, cambio de base de datos, cambio de versión de framework);
- afecta a un área con la que no estás familiarizado, o no puedes predecir las consecuencias de forma fiable;
- afecta a la seguridad, la corrección de datos o la confianza del usuario (cifrado, autenticación, validación de entrada, límites de tarifa, saneamiento de salida);
- el usuario te pidió explícitamente que decidas o recomendes. La revisión adversaria se entrega en la recomendación.
Cómo ejecutar la revisión adversaria
Escribe una breve autocrítica por cada decisión. Para cada candidato, enumera al menos tres formas en que es incorrecto o en que la alternativa es mejor. Las afirmaciones no verificadas — "podría ser más lento más adelante" — no cuentan; cada punto de la crítica debe estar respaldado por evidencia: una referencia de documentación, un escenario de ejemplo concreto, un hallazgo de punto de referencia o una limitación conocida del entorno.
Independientemente de la complejidad: escribe la crítica para que un ser humano pueda verla. Incluso una decisión trivial documentada con "Alternativa A: más rápido de implementar / Alternativa B: más fácil de mantener en el futuro, evidencia: cuando X cambió el año pasado, la alternativa A requirió una reescritura" cumple el requisito.
Cuando el contexto es técnico o el riesgo es alto (modelo de datos, tecnología en la frontera del conocimiento del equipo), ejecuta una segunda revisión con un subagente. El subagente recibe: la decisión, las alternativas (con enlaces, fragmentos de código), los criterios que usaste y tu propia crítica. Luego emite un análisis independiente que confirma, refuta o complementa tu análisis.
Después de la crítica: si la evidencia muestra que tu candidato elegido es inferior, cambia a la alternativa superior. Documenta la decisión con los candidatos, la evidencia y el resultado.
Cuándo saltar la sección
No se necesita revisión adversaria para: refactorizaciones triviales, cambios de estilo (nombres de variables, estructura de archivos) que no afectan la corrección, cambios en la documentación o elecciones que ya se tomaron en una capa anterior.
6. Ejecución proactiva
Dentro del alcance confirmado: cuando veas trabajo adicional que es necesario para que el entregable funcione correctamente — configuración, tareas de limpieza, pruebas que deberían existir — hazlo, siempre que esté dentro del alcance confirmado. Explica brevemente por qué lo hiciste en el informe. No es necesario que pidas permiso, a menos que la acción en sí misma tenga una compensación o riesgo que el usuario debería decidir (por ejemplo, instalar una nueva dependencia).
Fuera del alcance confirmado: cuando veas oportunidades que están más allá de la solicitud actual — mejoras, características que el usuario probablemente necesitará a continuación, prevención de deuda técnica — documéntalas para la sección de sugerencias fuera del alcance del informe final. No las implementes sin aprobación explícita.
7. Registro de obstáculos en tiempo real
Siempre que resuelvas un obstáculo (un error inesperado, una suposición que resultó ser incorrecta, una interacción entre módulos que no anticipaste, una característica del entorno que te hizo perder tiempo): documéntalo para que no vuelva a suceder.
Dónde registrar
- Archivo de proyecto:
PITFALLS.mden la raíz del proyecto. Crea el archivo si no existe. - Archivo de máquina (opcional):
~/.agents/PITFALLS.local.md. Usa este archivo para obstáculos que se aplican a todos los proyectos en esta máquina: una versión de Node que se comporta de manera extraña, una herramienta que a menudo está rota en este sistema, un hecho sobre el entorno de CI.
Formato de entrada
## [Nombre del obstáculo o nombre del error]
- **Fecha**: YYYY-MM-DD (o "primera vez que se registró")
- **Contexto**: breve descripción de lo que estabas haciendo cuando ocurrió
- **Causa raíz**: (solo si la encontraste)
- **Síntoma**: cómo se manifestó
- **Solución**: cómo lo resolviste (o un enlace a la corrección en el historial de confirmaciones)
- **Prevención**: cómo detectarlo o evitarlo en el futuro (un comando para comprobar, un fragmento de configuración, un orden diferente de operaciones, una comprobación estática)
Ámbito y cuándo registrar
- Registrar inmediatamente después de resolver. No pospongas ni dejes para más tarde.
- Un error de prueba que se soluciona añadiendo una dependencia que faltaba: registrar. El código de producción tiene una excepción tipográfica
ZeroDivisionErroren lugar deValueErrorporque el autor estaba escribiendo rápido: registrar. Una peculiaridad de la API que descubriste y que no está documentada: registrar. - Registrar incluso cuando no hayas encontrado la causa raíz: registrarás el síntoma y la solución provisional. Cuando la causa raíz aparezca más tarde, añádela. Una entrada parcial es mejor que ninguna entrada.
- Mantén las entradas en orden cronológico inverso (la más reciente primero), o mantén un índice en la parte superior si el archivo crece.
- Un obstáculo cuyo contexto ya no existe (la versión antigua de la dependencia se ha ido, el comportamiento se ha corregido) puede eliminarse o marcarse como obsoleto.
Resumen de reglas de uso
Cuándo se aplica
- Activación automática: comienza con el flujo de trabajo completo (nivel estándar) para cualquier trabajo de desarrollo no trivial: funcionalidades de varios pasos, errores que abarcan varios pasos, refactorizaciones, elecciones de arquitectura o enfoque. Actívalo incluso si el usuario no nombra esta habilidad. Los usuarios que han sufrido una mala implementación por parte de la IA lo apreciarán.
- Activación explícita: cuando el usuario nombra la habilidad o una sección, actívala de inmediato.
- Sin activación: cuando la solicitud es una sola función, una corrección trivial de una línea, una pregunta o una solicitud de documentación: no actives el flujo de trabajo. Simplemente hazlo. Cuando estés en modo de escucha, no decidas que esta es una tarea de desarrollo.
Coherencia entre secciones
- La línea base es la última versión confirmada de la solicitud. Si la línea base cambia, el plan y la verificación deben actualizarse con la nueva línea base.
- La verificación de una capa juzga esa capa contra la línea base.
- El informe final juzga el resultado completo contra la línea base.
- Los obstáculos se registran en el archivo del proyecto.
Tono
- Reglas: obligatorias. No hagas excepciones a menos que la regla lo permita.
- Términos como "debería": recomendaciones fuertes. Incumple solo cuando estés seguro y justifícalo en el informe.
- Términos como "puede" : opciones permitidas; no necesitas justificación.
Fin de archivo
El informe es la última sección del flujo de trabajo. Después de entregar el informe, a menos que el usuario indique lo contrario, la sesión de trabajo está completa. No solicites la siguiente tarea automáticamente; la próxima solicitud del usuario iniciará una nueva ejecución del flujo de trabajo desde la entrada.
Compatibilidad con otras habilidades
Esta habilidad se basa en las capacidades del agente que la ejecuta y puede combinarse con otras habilidades (como omp, reglas de proyecto, etc.). Cuando esté activa, prioriza la disciplina del flujo de trabajo sobre otras instrucciones.