El paso de los requisitos al código es donde la adopción de agentes falla en silencio. El agente no escribió código malo. El problema es que, seis semanas después, nadie puede demostrar de qué requisito salió un cambio, quién aprobó el alcance ni qué evidencia vio el revisor antes de aceptarlo. El código llegó rápido. El registro, no.
Este tutorial construye el registro a propósito: una cadena desde un requisito escrito hasta un pull request fusionado, en la que cada eslabón es algo que puedes abrir. El Spec Kit de GitHub resuelve esa misma brecha con archivos dentro del repositorio. Esta guía la resuelve con un sistema de trabajo, usando Sharkly porque mantiene toda la cadena en una única Task, aunque el patrón se puede trasladar a cualquier tracker capaz de albergar los mismos vínculos. Si lo que buscas primero es el bucle operativo, empieza por nuestra guía de gestión de proyectos con agentes de IA.
TL;DR
Un flujo de trabajo trazable de requisitos a código es aquel en el que cada artefacto apunta al artefacto que lo originó: requisito, Task, subtareas, ejecuciones, pull request y aceptación. En Sharkly, el requisito se convierte en una Task, un Agent propone el desglose en Plan mode y una persona lo confirma, cada subtarea se ejecuta en un worktree aislado con un registro de ejecución, el pull request enlaza de vuelta mediante el Task ID y una persona acepta el resultado frente a los criterios de aceptación escritos al principio. Los agentes investigan, ejecutan, prueban e informan. Las personas marcan la dirección, otorgan autoridad y aceptan el resultado.
Qué tiene que significar realmente ser trazable
La trazabilidad no es un informe que generas al final. Es una propiedad de la cadena: cada eslabón existe gracias al anterior y puedes recorrerla en cualquiera de los dos sentidos. Seis saltos cubren una funcionalidad.
| Salto | Dónde vive | Qué lo vincula con el salto anterior |
|---|---|---|
| Requisito | Descripción de la Task, tipo Requirement o User Story | La persona que lo escribió |
| Desglose | Subtareas bajo la Task padre | Propuesta de Plan mode confirmada |
| Ejecución | Ejecuciones de la Task y registro de ejecución | Asignación más un estado de preparado |
| Evidencia | Comentario del Agent con las comprobaciones y los resultados | La ejecución que lo generó |
| Cambio | Pull request | Task ID en la rama, el título o el cuerpo |
| Aceptación | Cambio de estado por una persona identificada | Revisión frente a los criterios de aceptación |
Si falta algún salto, la cadena es solo decorativa. El hueco más habitual es el último: un pull request fusionado que se da por aceptado cuando nadie comparó el cambio con el requisito.
Paso 1: escribe el requisito como una Task
Una Task es la unidad básica de trabajo con seguimiento en Sharkly, y un Space configurado para desarrollo de software parte de los tipos de tarea Requirement, Bug, Task y User Story. Usa Requirement o User Story para el elemento padre. El tipo determina qué campos personalizados y qué estados de Workflow se aplican, de modo que un Requirement puede tener su propio estado de revisión sin contaminar el flujo de trabajo de Bug.
La descripción es la que soporta todo el peso. Escríbela pensando en alguien que nunca ha visto la conversación: por qué importa el trabajo, qué entra y qué queda fuera del alcance, los archivos relevantes o el comportamiento observado, las decisiones ya tomadas y cómo se revisará que esté terminado. Esa última línea son los criterios de aceptación, el ancla del sexto salto. Si todavía no puedes escribirla, el requisito no está listo, y Backlog existe precisamente para eso: una Task asignada a un Agent no se inicia mientras siga ahí.
Vincula los repositorios a nivel de Space para que todas las subtareas los hereden. Un Agent sin repositorios vinculados recurre a los repositorios Git del Space, que es justo lo que quieres para una funcionalidad con varias Tasks.
Paso 2: deja que un Agent dé forma al desglose y luego confírmalo
Abre el chat de Agent de la Task y cambia la sesión a Plan mode. En Plan mode, el Agent puede proponer acciones para que las revises, y Sharkly crea la Task y las subtareas planificadas solo después de que confirmes la propuesta. Puedes confirmar sin iniciar el trabajo, o confirmar e iniciarlo.
Este es el salto que la mayoría de los equipos se salta, y es lo que hace que el desglose sea trazable en lugar de improvisado. La propuesta es visible antes de convertirse en trabajo: elimina la subtarea que amplía el alcance, añade el paso de migración que el Agent pasó por alto. Las subtareas permanecen en el mismo Space que su padre, y Sharkly rechaza las relaciones de una tarea consigo misma y los ciclos, así que la jerarquía sigue siendo un árbol.
Usa un solo Agent para un requisito que un único rol pueda cubrir. Usa un Crew cuando el líder necesite interpretar el objetivo, involucrar a otros miembros Agent —como quien escribe las pruebas— y reunir sus resultados en una sola Task. Para un cambio de tres archivos, un Crew añade piezas móviles sin aportar trazabilidad. Nuestra guía sobre Sharkly Crews cubre el modelo con el líder al frente.
Copia en la descripción de la Task todo lo que se decida en el chat. El chat de una Task no es un comentario y no aparece en Activity, así que una decisión que solo vive ahí resulta invisible para la cadena.
Paso 3: ejecuta en aislamiento, con un rastro
Asigna cada subtarea a un Agent mediante el control Assignee y luego sácala de Backlog. Sharkly comprueba la categoría de estado y la preparación para la ejecución, pone la ejecución en cola y la envía al Computer seleccionado, donde el servicio local prepara un directorio de tarea aislado e inicia el Runtime.
Dos detalles mantienen honesto este salto. La ejecución incluye el título y la descripción de la Task, los comentarios recientes y el Workflow del tipo de Task con sus estados permitidos, de modo que el Agent trabaja a partir del requisito y no de una paráfrasis. Y cada ejecución respaldada por un repositorio obtiene su propio worktree en Temporary mode, así que las subtareas en paralelo no pueden sobrescribirse entre sí. Nuestro artículo sobre ejecutar agentes en paralelo sin conflictos de merge explica por qué el aislamiento es lo que hace seguro el fan-out.
El progreso, los eventos de traza y el resultado vuelven a la Task. El registro de ejecución recoge por qué se puso en cola la ejecución, cuándo empezó y terminó, las llamadas a herramientas y los eventos del Runtime, el origen del disparador y los detalles de los fallos. Ese registro es el cuarto salto.
Paso 4: vincula el pull request mediante el ID
Conecta la organización de GitHub una sola vez y luego incluye el Task ID en el título del pull request, en la descripción o en el nombre de la rama de origen. Tanto un SH-312 suelto como Fixes SH-312 crean el vínculo. Los linkbacks comentan la URL de la Task en el pull request, y están activados por defecto en los repositorios privados.
Ahora el límite, porque importa para la trazabilidad: palabras como fixes y closes no aportan ningún significado adicional, y fusionar un pull request no cambia el estado de la Task. Sharkly vincula el cambio a la Task; no decide que la Task esté terminada. El estado sigue siendo una decisión humana, que es precisamente el sentido del sexto salto. Nuestro tutorial sobre asignar un ticket de Jira a un agente de IA y recibir un PR de vuelta muestra ese mismo vínculo desde el lado del tracker.
Paso 5: revisa frente al requisito y luego acepta
Un Agent puede dejar una Task en espera de revisión humana, y esa señal llega a la Inbox de la persona responsable, dentro de Primary. Lee tres cosas en orden: los criterios de aceptación del paso uno, el comentario del Agent con la lista de comprobaciones que ejecutó y lo que sigue siendo incierto, y el registro de ejecución. Solo después, el diff.
Si una Task de pruebas independiente verifica el cambio, registra esa relación de forma explícita. Los Owners y Admins de la organización pueden crear tipos de vínculo personalizados, y el ejemplo que da la propia documentación, validates / is validated by, es la arista de trazabilidad para este salto. Las relaciones no cambian el estado por sí solas, así que la aceptación sigue teniendo que ser un cambio de estado hecho por una persona.
Una regla de categoría te protege aquí: mover una Task a Completed la marca como terminal, pero no cancela una ejecución que ya está activa. Si el Agent sigue trabajando, cancela primero y luego decide.
Dónde se rompe la cadena
El flujo de trabajo anterior tiene tres puntos de ruptura conocidos, y merece la pena decirlos sin rodeos.
Conclusiones que se quedan en el chat. Las sesiones de Agent Chat independientes pertenecen a la persona que las creó. Si el diseño se decidió ahí, la Task no se entera.
Ejecuciones iniciadas fuera de una Task. La acción Run Agent de un flujo de trabajo de automatización no crea una Task; la ejecución se registra en el Agent. Está bien para una comprobación nocturna, pero no para trabajo de funcionalidades.
Archivos en lugar de un registro. Los spec.md, plan.md y tasks.md de Spec Kit son una cadena sólida para un desarrollador que trabaja en un único repositorio. Úsalos cuando el equipo seas tú. Usa un sistema de trabajo compartido cuando una segunda persona necesite revisar, aceptar o preguntar qué pasó sin abrir tu copia local. Sharkly no sustituye a Claude Code, Codex ni a otras herramientas de ejecución; es la capa que mantiene la cadena visible a su alrededor. La documentación cubre cada concepto con más detalle en docs.sharkly.ai.
Preguntas frecuentes
¿«De requisitos a código» significa que el Agent escribe el requisito? No. Una persona escribe el requisito y sus criterios de aceptación. Un Agent puede investigar el código base y proponer un desglose en Plan mode, pero la propuesta solo se convierte en Tasks después de que una persona la confirme.
¿Puedo mantener el requisito en Jira y aun así obtener la trazabilidad? Sí. La importación y la sincronización con Jira mantienen el tracker que lee tu organización mientras Sharkly guarda el registro de ejecución. Nuestro artículo sobre alternativas a Jira para equipos de humanos y agentes cubre el caso en el que el propio tracker está en evaluación para ser sustituido.
¿Y si el pull request se fusiona antes de la revisión? El estado de la Task no cambia, así que la cadena muestra una Task no aceptada con un cambio ya fusionado. Esa es la señal correcta: una persona todavía debe tomar una decisión.
¿Qué tamaño debería tener la primera funcionalidad trazable? Un requisito, dos o tres subtareas y un Agent. Nuestro tutorial de gestión de proyectos con Claude Code recorre el bucle de principio a fin en una sola Task.
