Roles de agente para apps creadas por chat: flujo del Planificador al Revisor

Por qué la fiabilidad se rompe cuando construyes apps por chat

El chat te ayuda a moverte rápido, pero no es bueno para mantener todo un producto en la cabeza. La mayoría de los fallos no son “mal código”. Son huecos entre lo que querías, lo que el asistente asumió y lo que finalmente se entregó.

La primera grieta son los requisitos faltantes. Pides “un flujo de registro simple”, pero nadie documenta casos límite como restablecer contraseña, correo ya usado o qué ocurre si el usuario cierra la pestaña a mitad de proceso. El asistente rellena los huecos y esas suposiciones se convierten en tu producto.

La segunda grieta son las decisiones inconsistentes. Un mensaje elige un modelo de datos, el siguiente añade un atajo y un tercero cambia nombres o reglas de validación. Cada elección puede ser razonable por sí sola. Juntas, crean una app frágil que se rompe cuando añades la próxima función.

La tercera grieta es la falta de pruebas. Sin tests básicos y comprobaciones de aceptación claras, solo descubres problemas después de hacer clic por la interfaz. Ahí es cuando “funciona en mi pantalla” se convierte en noches largas, hotfixes y regresiones aleatorias.

Una solución simple es usar personas reutilizables: un Planificador que concretes el trabajo, un Arquitecto que le dé forma, un Implementador que construya en pasos pequeños, un Probador que intente romperlo y un Revisor que atrape el último 10% que causa el 90% del dolor. Esto no es un proceso pesado. Es una manera repetible de mantener decisiones consistentes.

Este enfoque funciona para fundadores en solitario, equipos pequeños y creadores no técnicos que usan herramientas de chat como Koder.ai. Puedes seguir moviéndote rápido, pero dejas de depender de la suerte.

Estos roles no garantizan la calidad por sí solos. Aún necesitas entradas claras (qué significa el éxito, restricciones y prioridades) y todavía tienes que leer las salidas. Piensa en los roles como barreras de contención: reducen errores evitables, pero tú sigues siendo el conductor.

La idea central: separar responsabilidades y luego transferir de forma limpia

La fiabilidad cae cuando un mismo chat intenta hacerlo todo a la vez: decidir qué construir, diseñarlo, codificarlo, probarlo y juzgarlo. Mezclar esos trabajos facilita perder casos límite, cambiar requisitos a mitad de construcción o “arreglar” bugs añadiendo más confusión.

Una forma práctica de evitar eso es mantener los roles consistentes y acotados. Cada rol se ocupa de un trabajo, y no se le permite “ayudar” fuera de él. Eso mantiene las decisiones trazables y hace más fácil detectar errores.

Usa esta secuencia para casi cualquier feature:

• Planificador: define el objetivo, los usuarios, las comprobaciones de aceptación y qué está fuera de alcance
• Arquitecto: propone el diseño más simple que soporte el objetivo
• Implementador: construye exactamente lo planeado, en pasos pequeños
• Probador: intenta romperlo y reporta fallos claramente
• Revisor: revisa los detalles finales (nombres, seguridad básica, huecos de UX, atajos peligrosos)

Los handoffs limpios importan tanto como los roles. Cada traspaso debe incluir qué se decidió, qué suposiciones se hicieron y qué significa “terminado”. Si usas Koder.ai, trata cada rol como una intervención de chat separada o un snapshot para poder revertir cuando una decisión salga mal.

Vuelve en bucle con propósito, no por accidente. Si las pruebas fallan, regresa al Implementador con un informe de bug mínimo. Si el diseño no soporta un nuevo requisito, vuelve al Arquitecto. Si el requisito es poco claro o cambia constantemente, pausa y vuelve al Planificador.

Mantén los mismos roles y orden a través de las features. Tras algunas iteraciones, desarrollas memoria muscular: haces mejores preguntas temprano y dejas de rehacer trabajo tarde.

Persona 1: Planificador (deja el trabajo claro antes de que alguien construya)

El trabajo del Planificador es convertir una idea difusa en algo que se pueda construir y verificar. Esto no es “escribir documentación”. Es acordar qué significa “hecho” antes de que exista la primera pantalla o endpoint.

Un buen output del Planificador es pequeño y comprobable: una declaración clara del problema, algunas historias de usuario, criterios de aceptación simples y una lista corta de casos límite. También indica lo que aún no vas a hacer, para que el Implementador no construya accidentalmente una funcionalidad más grande de la que se quería.

Plantilla de prompt del Planificador (plan pequeño y priorizado)

Úsala cuando tengas una idea de feature y quieras un plan ajustado que el resto de roles pueda seguir.

You are the Planner. Turn the feature idea below into a buildable plan.

Feature idea:
<PASTE IDEA>

Context:
- App type:
- Target users:
- Current behavior (if any):
- Constraints (time, data, compliance, devices):

Output (keep it short):
1) Problem statement (1-2 sentences)
2) Assumptions (3-6 bullets)
3) Questions to confirm (max 6, prioritized)
4) User stories (2-5)
5) Acceptance criteria (5-10, testable, specific)
6) Edge cases & failure modes (3-8)
7) Out of scope (3-6 bullets)
8) Small milestone plan (2-4 steps, highest value first)

Handoff del Planificador al Arquitecto (estructurado y corto)

Envía este mensaje tal cual (completado) para reducir idas y vueltas.

PLANNER HANDOFF
Feature: <name>
Problem: <1-2 sentences>
Users: <who>
Must-haves (AC): <5-10 acceptance criteria>
Key edge cases: <3-6>
Out of scope: <3-6>
Open questions (need Architect input): <1-4>
Constraints: <tech, data, privacy, deadlines>
Success signal: <how we’ll know it worked>

Si solo haces una cosa como Planificador, haz que los criterios de aceptación sean medibles. Por ejemplo: “El usuario puede restablecer la contraseña y recibe un correo en 60 segundos” vence a “El restablecimiento de contraseña funciona.”

Persona 2: Arquitecto (elige una forma que la app pueda sostener)

El Arquitecto convierte un buen plan en una forma construible. El trabajo no es inventar patrones sofisticados. Es escoger la estructura más simple que siga funcionando cuando usuarios reales interactúan, los datos crecen y ocurren errores.

Aquí la fiabilidad empieza a sentirse real: límites claros, datos claros y rutas de fallo claras.

Un output práctico del Arquitecto suele cubrir:

• Pantallas (React o Flutter) o endpoints API (Go)
• Un pequeño modelo de datos (tablas PostgreSQL y campos clave)
• Uno o dos flujos principales (ruta feliz más qué puede fallar)
• Fundamentos no funcionales que importan ahora (auth, privacidad, rendimiento, logging)
• Compensaciones (lo que no estás construyendo todavía)

Manténlo concreto. En lugar de “sistema de notificaciones”, di “POST /api/alerts, tabla alerts(user_id, type, status), mostrar contador de no leídos en el header.” En vez de “seguro”, di “sesión JWT, cheques de rol en endpoints admin, proteger campos PII.”

Plantilla de prompt: Handoff del Arquitecto (obliga a tomar decisiones)

Úsala cuando el Planificador entregue trabajo al Arquitecto, o cuando quieras resetear una feature que se siente desordenada.

You are the Architect.
Goal: design the simplest buildable structure for this feature.
Context:
- App type: [web/mobile/both]
- Stack: React UI, Go API, PostgreSQL DB (Flutter screens if mobile)
- Existing constraints: [auth method, existing tables, deadlines]

Input (from Planner):
- User story:
- Acceptance criteria:
- Out of scope:

Deliverables (keep it short and specific):
1) UI map: list screens/components with 1-line purpose each.
2) API map: list endpoints with method, path, request/response fields.
3) Data model: tables + key columns + relationships.
4) Key flows: happy path + 2 failure cases and how UI should respond.
5) Non-functional needs: security, performance, audit/logging (only what matters now).
6) Tradeoffs: 3 decisions you made (and what you avoided) to prevent over-design.

Rules:
- Prefer the smallest option that meets acceptance criteria.
- If something is unclear, ask up to 3 questions, otherwise make a reasonable assumption and write it down.

Si construyes en Koder.ai, este tipo de handoff hace que la implementación sea más rápida porque el Implementador puede seguir un mapa claro en lugar de adivinar la forma a mitad de construcción.

Persona 3: Implementador (construye en pasos pequeños, mantén el alcance)

El Implementador convierte un plan claro en código que funcione, sin cambiar el plan. Aquí se gana o pierde la mayor parte de la fiabilidad. El objetivo es directo: construir exactamente lo acordado, en rebanadas finas que puedas deshacer.

Trata cada cambio como si pudiera revertirse. Trabaja en slices delgadas y para cuando los criterios de aceptación se cumplan. Si algo no está claro, pregunta. Adivinar es como pequeñas features se convierten en reescrituras sorpresa.

Un buen Implementador deja un rastro corto de evidencia: el orden de construcción, qué cambió, qué no cambió (para evitar creep oculto) y cómo verificarlo.

Aquí tienes una plantilla de prompt que puedes pegar al pasar trabajo al Implementador:

You are the Implementer.

Context:
- Feature: <name>
- Current behavior: <what happens today>
- Desired behavior: <what should happen>
- Acceptance criteria: <bullets>
- Constraints: <tech choices, performance, security, no schema change, etc.>

Before writing code:
1) Ask up to 5 questions if anything is unclear.
2) Propose a step-by-step build plan (max 6 steps). Each step must be reversible.
3) For each step, list the exact files/modules you expect to touch.

Then implement:
- Execute steps one by one.
- After each step, summarize what changed and how to verify.
- Do not add extras. If you notice a better idea, stop and ask first.

Ejemplo: si el Planificador pidió “Añadir flujo de restablecer contraseña por email”, el Implementador no debería rediseñar la pantalla de login. Construye el endpoint de solicitud de email, luego el manejo del token y después la UI, con una nota corta de verificación tras cada paso. Si tu herramienta soporta snapshots y rollback (Koder.ai lo hace), los pasos pequeños son mucho más seguros.

Persona 4: Probador (demuestra que funciona y muestra cómo falla)

El trabajo del Probador es romper la feature antes de que lo hagan los usuarios. No confían en la ruta feliz. Buscan estados poco claros, validaciones faltantes y casos límite que aparecen desde el día uno.

Un buen output del Probador es utilizable por otra persona: una matriz de pruebas ligada a los criterios de aceptación, un script manual corto y reportes de bugs con pasos exactos (esperado vs actual).

Qué probar (UI, API y datos)

Apunta a cobertura, no volumen. Concéntrate en donde las fallas son más caras: validación, permisos y estados de error.

• UI: estados vacíos, mensajes de error, estados de carga, botones deshabilitados, flujo con teclado solamente
• API: campos faltantes, tipos incorrectos, fallos de auth, comportamiento ante límites/tiempos de espera
• Validación de datos: duplicados, longitudes máximas, formatos inválidos, cheques server-side (no solo UI)
• Permisos: qué puede hacer un usuario normal vs un admin
• Regresión: una o dos comprobaciones de “¿rompimos comportamiento existente?”

Ejemplo: si añadiste “Crear factura”, prueba un importe negativo, una nota de 10 000 caracteres, un cliente faltante y enviar dos veces.

Plantilla de prompt: generar una matriz de pruebas desde criterios de aceptación

Úsala cuando pases de Implementador a Probador. Pega los criterios de aceptación y notas UI/API relevantes.

ROLE: Tester
GOAL: Produce a test matrix tied to acceptance criteria, including negative tests.
CONTEXT:
- Feature: <name>
- Acceptance criteria:
  1) <AC1>
  2) <AC2>
- Surfaces: UI screens: <list>; API endpoints: <list>; DB changes: <notes>
OUTPUT FORMAT:
1) Test matrix table with columns: AC, Test case, Steps, Expected result, Notes
2) Negative tests (at least 5) that try to break validation and permissions
3) Manual test script (10 minutes max) for a non-technical person
4) Bug ticket template entries for any failures you predict (Title, Steps, Expected, Actual, Severity)
CONSTRAINTS:
- Keep steps precise and reproducible.
- Include at least one test for loading/error states.

Persona 5: Revisor (atrapa el último 10% que causa el 90% del dolor)

El Revisor hace la pasada final de calidad. No para reescribirlo todo, sino para detectar los pequeños problemas que luego se convierten en bugs largos: nombres confusos, casos límite faltantes, mensajes de error débiles y atajos peligrosos que dificultan el próximo cambio.

Una buena revisión produce salidas claras: qué se revisó, qué debe cambiar, qué es riesgoso pero aceptable y qué decisión se tomó (para no reabrirla la semana siguiente).

En qué se fija el Revisor

Mantén la pasada corta y repetible. Enfócate en lo que más suele romper la fiabilidad:

• Consistencia: nombres, patrones, estructura de carpetas y comportamiento UI que coincidan con la app existente
• Fundamentos de seguridad: validación de entrada, cheques de auth, no dejar datos sensibles en logs
• Errores: mensajes para el usuario claros; errores del servidor accionables; sin fallos silenciosos
• Mantenibilidad: funciones pequeñas, intención obvia, sin lógica duplicada sin motivo
• Cambios futuros: qué será difícil de modificar después y cómo reducir ese coste ahora

Prompt de revisión estructurada (aprobar o solicitar cambios)

Úsalo cuando el Implementador diga que la feature está lista:

You are the Reviewer. Do a final review for correctness, clarity, and maintainability.

Context
- Feature goal:
- User flows:
- Key files changed:
- Data model/migrations:

Review checklist
1) Correctness: does it meet the goal and handle edge cases?
2) Security basics: auth, validation, safe logging.
3) Errors: clear messages, consistent status codes.
4) Consistency: naming, patterns, UI text.
5) Maintainability: complexity, duplication, TODOs.

Output format
- Findings (bulleted): include file/function references and severity (high/medium/low)
- Requested changes (must-fix before merge)
- Risk notes (acceptable with reason)
- Decision log updates (what we decided and why)

Finish with exactly one:
APPROVE
CHANGES REQUESTED

Si el Revisor solicita cambios, deben ser pequeños y específicos. El objetivo es menos sorpresas en producción, no un segundo ciclo de desarrollo.

Plantillas de handoff que previenen rehacer trabajo

La mayoría del trabajo repetido ocurre porque la siguiente persona empieza con un objetivo borroso, entradas faltantes o restricciones ocultas. Una plantilla de handoff simple arregla eso haciendo cada transferencia predecible.

Usa un encabezado compartido cada vez, incluso para tareas pequeñas:

• Contexto + Objetivo: qué construyes y por qué, en un párrafo.
• Entradas: pantallas, notas de API, campos de datos, registros de ejemplo, áreas de código relacionadas.
• Restricciones: elecciones tecnológicas, fechas límite, rendimiento, seguridad, comportamientos que se deben mantener.
• Definición de Hecho: comprobaciones medibles (qué debe pasar, qué debe existir).
• Suposiciones / Preguntas abiertas / Decisiones tomadas: lo que asumiste, lo que es desconocido y lo que quedó cerrado.

Aquí hay un ejemplo de handoff (Arquitecto -> Implementador):

ROLE HANDOFF: Architect -> Implementer
Context: Add “Invite team member” to the admin area.
Goal: Admin can send an invite email; invited user can accept and set a password.
Inputs: Existing Users table; auth uses JWT; email provider already configured.
Constraints: Go backend + PostgreSQL; React UI; audit log required; no breaking auth changes.
Definition of Done:
- UI: invite modal + success state
- API: POST /invites, POST /invites/accept
- DB: invites table with expiry; audit event on create/accept
- Tests: happy path + expired invite + reused token
Assumptions: Email templates can reuse “reset password” styling.
Open questions: Should invites be single-use per email?
Decisions made: 72h expiry; tokens stored hashed.

Si quieres que esto se mantenga, guarda tus plantillas en un lugar donde todos puedan copiarlas. Si usas Koder.ai, puedes mantener estos prompts en Planning Mode y tomar un snapshot antes de implementar para que el rollback sea indoloro si el alcance cambia.

Flujo paso a paso que puedes seguir para cada feature

La fiabilidad mejora cuando tratas cada feature como un mini release, con handoffs limpios entre roles. Empieza con una historia de usuario, no con un montón de ideas. Escríbela en lenguaje llano y añade criterios de aceptación que alguien pueda verificar sin adivinar.

Diseña solo la mínima forma necesaria para soportar esa historia. El objetivo no es un sistema perfecto sino un plan simple que no colapse cuando añadas la siguiente feature.

Un flujo práctico se ve así:

1. Planificador: Confirma la historia, casos límite y criterios de aceptación (éxito, fallo y “qué pasa si el usuario hace X”).
2. Arquitecto: Propone el modelo de datos y la superficie API más pequeños (tablas/campos, endpoints, reglas de auth), más una nota corta sobre lo que no construirás.
3. Implementador: Construye una rebanada delgada end-to-end (UI a API a DB) que cumpla los criterios, aunque la UI sea sencilla.
4. Probador: Ejecuta un script de prueba repetible, registra fallos con pasos para reproducir y anota comportamientos poco claros.
5. Revisor: Hace la pasada final por seguridad básica y pulido de producto, luego registra decisiones.

Mantén la salida de cada paso pequeña y explícita. Un mensaje de handoff por rol suele ser suficiente: entradas, decisiones tomadas y qué necesitas a continuación.

Termina escribiendo una nota de cambio de un párrafo: qué se añadió, qué se eliminó y qué vigilar en el próximo release. Esta “memoria” evita que los mismos debates y bugs vuelvan.

Un ejemplo realista: una feature desde la idea hasta el release revisado

Feature: una pantalla CRM simple donde usuarios pueden añadir contactos, aplicar etiquetas (como “Lead” o “Vendor”) y buscar por nombre o etiqueta. Restricción: tienes 90 minutos y debes reutilizar la tabla contacts existente (sin migraciones que rompan). Mobile necesita una sola pantalla “Añadir contacto” que quepa en una página.

Aquí está el handoff cuando usas esta cadena de personas. Cada rol produce un artefacto pequeño en el que la siguiente persona puede confiar.

Planner output (definition + acceptance)
- Goal: Add contacts with tags and fast search.
- Must: Create, edit, list contacts; add/remove tags.
- Search: matches name OR any tag; results update in under 300ms.
- Constraint: keep existing contacts table; tags can be new table.
- Done when: 5 test cases pass; mobile screen has no scroll on common devices.

Architect output (shape + data)
- Tables: contacts (existing), tags (id, name), contact_tags (contact_id, tag_id).
- API: POST /contacts, PATCH /contacts/:id, GET /contacts?query=.
- Search: SQL ILIKE on contact name + join on tags.
- UI: Contact list with search bar; contact form with tag picker.
- Risk: duplicate tags (“lead” vs “Lead”) - enforce lowercase unique.

Implementer output (small steps)
- Step 1: Add tags + join table migrations.
- Step 2: Update backend handlers and query.
- Step 3: Build React UI list + form; wire to API.
- Step 4: Add basic validation (name required, tag length).
- Step 5: Add loading/error states; keep UI responsive.

Tester output (proof + failure)
- Case: search “lea” returns contacts tagged “lead”. FAIL: returns none.
- Case: adding tag “Lead” then “lead” should not create two tags. PASS.
- Case: empty name rejected. PASS.
- Bug note: backend search only checks contact name, not tags.

Loop-back (Planner update)
- Update acceptance: search must match tags via join; include a test for it.
- Add edge case: searching by tag should return even if name doesn’t match.

Reviewer output (last 10%)
- Check: query uses indexes; add index on tags.name and contact_tags.tag_id.
- Check: error messages are clear; avoid raw SQL errors.
- Check: mobile form spacing and tap targets.
- Confirm: snapshots/rollback point created before release.

Esa única prueba fallida fuerza un loop-back limpio: el plan se afina, el Implementador cambia una consulta y el Revisor valida rendimiento y pulido antes del release.

Trampas comunes (y soluciones simples)

La manera más rápida de perder la confianza en el software generado por chat es dejar que todo el mundo haga todo. Roles claros y handoffs limpios mantienen el trabajo predecible, incluso cuando vas rápido.

• Personas que se mezclan (construir antes de que los requisitos estén estables). Solución: bloquea la salida del Planificador antes de cualquier cambio de código. Ajuste de plantilla: “Implementador: no escribir código hasta que el Scope, Assumptions y Acceptance Criteria del Planificador estén presentes. Si faltan, pregunta máximo 3 cosas.”
• Sin definición de hecho, el trabajo nunca termina. Solución: cada handoff debe incluir una línea de Hecho. Ejemplo: “Hecho significa: criterios de aceptación cumplidos, no hay nuevos TODOs y cambios documentados en 5 viñetas.”
• Probador que solo verifica la ruta feliz. Solución: exige un caso de entrada inválida y un caso límite cada vez. Ajuste de plantilla: “Probador: provee (1) ruta feliz, (2) un caso de entrada inválida, (3) un caso límite. Si no puedes ejecutarlo, describe pasos exactos y resultado esperado.”
• Revisor que debate estilo en lugar de riesgos de producto. Solución: obliga al Revisor a enfocarse en riesgos primero. Ajuste de plantilla: “Revisor: lista los 3 riesgos principales (seguridad, pérdida de datos, UX roto, rendimiento). Menciona estilo solo si bloquea legibilidad o causa bugs.”
• Handoffs que pierden contexto, la siguiente persona adivina. Solución: exige un Bloque de Handoff corto cada vez: “Goal, What changed, How to verify, Known gaps.” Manténlo bajo 8 líneas.

Un hábito pequeño que ayuda: cuando el Implementador termina, pega otra vez los criterios de aceptación y márcalos uno por uno.

Checklist rápido para releases fiables construidos por chat

Ejecuta este checklist antes de construir, antes de mergear y justo después de lanzar.

Antes de construir (antes de que alguien escriba código)

• Escribe el objetivo en una frase y lista 2-3 comprobaciones de aceptación (qué significa “hecho”).
• Nombra qué está fuera de alcance (para que el Implementador no adivine).
• Lista los campos de datos exactos y reglas (tipos, obligatorio/opcional, valores por defecto).
• Anota los principales casos de error (input inválido, permisos faltantes, estados vacíos, timeouts).
• Decide cómo lo verificarás rápidamente (una pantalla, una respuesta API, una línea de log).

Un ejemplo pequeño: “Añadir invitación por email.” Incluye campos (email, rol), qué pasa si el email es inválido y si permites re-invites.

Pre-merge y post-release (reducir el miedo al cambio)

• Pre-merge: confirma que las pruebas corrieron (o al menos un script manual corto) y registra qué se comprobó.
• Pre-merge: cubre 2-3 casos límite explícitamente, no “debería funcionar”.
• Pre-merge: anota un plan de rollback y qué cambio lo activaría.
• Post-release: vigila 1-2 señales (errores, páginas lentas, jobs fallidos) la primera hora/día.
• Post-release: recoge feedback de usuarios y escribe límites conocidos para que soporte no adivine.

Si tu plataforma lo soporta (Koder.ai lo hace), toma un snapshot antes de ediciones riesgosas. Saber que puedes revertir hace más fácil lanzar cambios pequeños y seguros.

Próximos pasos: convierte esto en tu flujo por defecto

Elige una feature pequeña y ejecuta la cadena completa de personas una vez. Escoge algo real pero contenido, como “añadir restablecimiento de contraseña”, “crear una página solo para admins” o “exportar facturas a CSV”. El punto es ver qué cambia cuando fuerzas handoffs limpios de Planificador a Revisor.

Si usas Koder.ai (koder.ai), Planning Mode es un lugar práctico para fijar alcance y criterios de aceptación antes de construir. Luego, los snapshots y el rollback te dan una vía de escape segura cuando una decisión sale mal, sin convertir todo el proyecto en un debate.

Para hacer el flujo repetible, guarda tus prompts de persona como plantillas que el equipo pueda reutilizar. Mantenlos cortos, con formatos de salida consistentes, y pasarás menos tiempo volviendo a explicar el mismo contexto en cada feature.