Introducción
La IA redacta las historias de usuario, las convierte en issues e implementa cada issue como una porción de código. El desarrollador deja de escribir cada línea y pasa a ser orquestador: define qué se construye, valida lo que produce la IA en cada paso y decide qué se integra. La clave es que una historia, una issue, una porción y un PR son la misma unidad de trabajo, del tamaño justo para que un agente la resuelva bien.
La mayoría de los proyectos se organizan por capas técnicas: Controllers/, Services/, Repositories/, DTOs/ (un DTO, Data Transfer Object, es un objeto que solo transporta datos entre partes del sistema, sin lógica). Con esa estructura, cualquier cambio obliga al agente a leer y tocar cuatro o cinco carpetas llenas de código ajeno a la tarea.
VSA organiza el código por caso de uso. El agente recibe una tarea acotada, trabaja en una sola carpeta y entrega un cambio que el orquestador revisa en minutos.
Qué es VSA

De ahí el nombre: si el sistema es una torta de capas, una funcionalidad no es una capa entera sino una porción vertical que lleva un poco de cada una.
Una porción vertical (slice) es un caso de uso completo con todo lo que necesita: endpoint, validación, lógica de negocio, acceso a datos, DTOs y tests. Jimmy Bogard, quien popularizó el enfoque, lo resume en un principio: minimizar el acoplamiento entre porciones y maximizarlo dentro de cada porción (fuente).
La diferencia se ve en la estructura de carpetas:
Tres reglas que el agente debe respetar y que conviene dejar escritas en el repositorio:
- Una porción = un caso de uso. Un comando (“inscribir alumno”) o una consulta (“listar alumnos”), al estilo CQRS (Command Query Responsibility Segregation: separar las operaciones que modifican datos, los comandos, de las que solo los leen, las consultas).
- Las porciones no se importan entre sí. Lo que de verdad se comparte (entidades del dominio, autenticación, conexión a la base) va a
Shared/. - La duplicación es aceptable. Dos porciones pueden tener DTOs parecidos. Es preferible a un DTO compartido que, al cambiar para un caso, rompe otro.
Preparar el repositorio para trabajar con IA
Antes de asignar la primera issue a un agente, el repositorio tiene que dejar escritas las reglas que el agente no puede adivinar. Con VSA el código se ordena solo por convención, así que esa convención tiene que estar escrita y verificada automáticamente.
- Un archivo
AGENTS.mden la raíz con las convenciones de porciones (o el archivo de instrucciones que lea el agente). - Una porción de referencia completa, que el agente copie.
- La plantilla de issue en el repo (por ejemplo,
.github/ISSUE_TEMPLATE/porcion.md), para que la IA la complete. - Tests de arquitectura, generados por la IA, que fallen si una porción importa otra.
- CI que corra los tests y los tests de arquitectura en cada PR.
- Revisión de tests por IA: un segundo agente verifica que los tests cubran todos los criterios de la issue antes de la implementación; el orquestador resuelve solo lo que ese agente marque.
- Revisión periódica de
Shared/: cuando la IA repite lo mismo en varias porciones, se extrae.
Ejemplo de AGENTS.md:
# Convenciones
- Cada caso de uso vive en Features/<Módulo>/<Verbo><Sustantivo>/
- Archivos de una porción: request, response, handler y tests, con la
extensión del lenguaje del proyecto
- Las porciones no se importan entre sí. Lo compartido va en Shared/.
- Porción de referencia: Features/Alumnos/CrearAlumno/
- Un PR = una issue = una porción.
- Escribí los tests antes del código, uno por criterio de aceptación.
- Los títulos de issue son verbos de caso de uso, nunca capas.
Historias, issues y porciones: la misma unidad
Una buena historia de usuario ya es vertical: describe un resultado que el usuario obtiene, no una capa técnica. Con VSA, esa unidad pasa intacta por todo el proceso, y en cada nivel la IA produce el artefacto y el orquestador lo valida.
| Nivel | Ejemplo | Qué hace la IA | Qué valida el orquestador |
|---|---|---|---|
| Historia de usuario | Como docente, quiero inscribir un alumno a un curso para que acceda al aula. | La redacta desde notas, pedidos o el sistema actual | Que refleje la necesidad real; la prioridad |
| Issue | #42 Inscribir alumno a curso | La deriva de la historia, con criterios, carpeta y porción de referencia | Que sea una porción vertical y no una capa |
| Tests | Un test por criterio de aceptación | Los escribe antes del código; un segundo agente verifica que cubran los criterios | Solo lo que marque el agente revisor |
| Porción | Features/Inscripciones/InscribirAlumno/ | La implementa copiando la porción de referencia | Lo hace el CI con tests de arquitectura |
| PR | feature/42-inscribir-alumno, una sola carpeta | Lo abre y corrige según comentarios | La revisión final y el merge |
El error más común de la IA al generar issues es cortar por capas: “crear tabla inscripciones”, “crear endpoint”, “crear pantalla”. Ninguna entrega valor por sí sola y no se pueden probar de punta a punta. Si pasa, se rechaza el corte y se le pide que lo rehaga por caso de uso: una issue cerrada tiene que ser una funcionalidad que anda.
Opción A: historias de usuario + issues
Conviene cuando hay usuarios de negocio y un producto con varias funcionalidades que priorizar. La historia vive en un nivel superior (épica, milestone o etiqueta) y cada issue es una porción de esa historia.
Flujo con IA:
- La IA redacta las historias a partir de la necesidad, notas de reunión o la descripción del sistema actual.
Prompt: “A partir de estas notas, proponé historias de usuario para el módulo de inscripciones, en formato Como / quiero / para.”
- El orquestador prioriza y aprueba las historias.
- La IA convierte cada historia en issues, una por porción, completando la plantilla del repositorio.
Prompt: “Convertí la historia #12 en issues. Cada issue debe ser una porción vertical, con criterios de aceptación, carpeta en Features/ y porción de referencia. Usá la plantilla de AGENTS.md.”
- El orquestador revisa el corte (ver Cómo validar el corte) y recién entonces asigna las issues al agente.
Plantilla de issue que la IA completa:
## #42 Inscribir alumno a curso
Historia: #12 Gestión de inscripciones
Como docente, quiero inscribir un alumno a un curso para que acceda al aula.
### Criterios de aceptación
- [ ] Alumno ya inscripto → error 409
- [ ] Curso sin cupo → error 422
- [ ] Inscripción exitosa → 201 y aparece en el listado del curso
### Porción
Features/Inscripciones/InscribirAlumno/
### Referencia
Features/Alumnos/CrearAlumno/
### No tocar
Otras porciones. Cambios a Shared/ requieren aviso en el PR.
Opción B: solo issues
Conviene en equipos chicos, sistemas internos o migraciones, donde el formato de historia agrega ceremonia sin agregar claridad. La IA redacta la issue directamente desde un pedido breve.
Prompt: “Escribí una issue para ‘inscribir alumno a curso’ con la plantilla de AGENTS.md. El objetivo es que el alumno acceda al aula del curso.”
Resultado esperado:
## Inscribir alumno a curso
Para: que el alumno acceda al aula del curso.
- [ ] Ya inscripto → 409
- [ ] Sin cupo → 422
- [ ] OK → 201
Porción: Features/Inscripciones/InscribirAlumno/
Referencia: Features/Alumnos/CrearAlumno/
En las dos opciones hay una regla que conviene incluir en el prompt: el título de la issue es un verbo que un usuario o sistema ejecuta (“Inscribir alumno”, “Listar cursos activos”), nunca una capa (“Crear repositorio de cursos”).
| Historias + issues | Solo issues | |
|---|---|---|
| Mejor para | Productos con usuarios de negocio y priorización | Equipos chicos, sistemas internos, migraciones |
| Prompts de planificación | Dos: historias, luego issues | Uno: la issue directa |
| Validaciones del orquestador | Historias y corte en issues | Solo el corte en issues |
| Unidad que recibe el agente | Una issue = una porción | Una issue = una porción |
Cómo validar el corte que propone la IA
La IA propone cómo dividir las historias; el orquestador decide. Cuando una historia es grande, el corte correcto genera historias más finas que siguen siendo verticales. Esta tabla sirve para corregir a la IA cuando corta mal:
| En vez de cortar por… | Cortar por… |
|---|---|
| Capa: tabla, endpoint, pantalla | Variante de la regla: inscripción simple → con lista de espera |
| Componente: backend, frontend | Camino feliz primero, casos de error después |
| ”Todo el ABM de cursos” | Cada operación: crear, editar, dar de baja, listar |
| Infraestructura genérica por adelantado | Solo la infraestructura que la primera porción necesita |
Criterios para aceptar una issue generada por la IA (INVEST):
- Se puede probar de punta a punta, sola.
- Toca una sola carpeta de
Features/, más cambios menores enShared/. - El PR se revisa en una sentada.
- Tiene entre dos y seis criterios de aceptación. Más que eso suele indicar que son dos porciones.
Una excepción razonable: la base técnica del proyecto (autenticación, conexión a la base, CI) se arma una vez de forma horizontal, antes de la primera porción.
La misma IA puede hacer una primera revisión del corte antes que el orquestador:
Prompt: “Revisá estas issues. Marcá cualquiera que toque más de una carpeta de Features/, que esté nombrada por capa o que tenga más de seis criterios, y proponé cómo dividirla en porciones verticales.”
Implementar cada issue con un agente
Con la issue aprobada, el agente la implementa. La issue es el prompt: dice qué hacer, dónde hacerlo, qué no tocar y cuándo está terminado.
- Asignar la issue. El prompt es corto porque la issue ya tiene todo: “Implementá la issue #42 siguiendo AGENTS.md.”
- Tests primero. El agente convierte cada criterio de aceptación en un test dentro de la carpeta de la porción. Un segundo agente revisa que los tests cubran lo que pide la issue antes de seguir; el orquestador resuelve lo que ese agente marque.
- Implementación. El agente copia la estructura de la porción de referencia y escribe el código hasta que los tests pasen.
- CI. Corren los tests y los tests de arquitectura. Si fallan, el agente corrige y vuelve a intentar.
- Revisión del orquestador. El PR toca una sola carpeta y se revisa rápido. Los cambios se piden con un comentario en el PR y el agente los aplica.
- Merge y cierre. El PR cierra la issue (
Closes #42).
Como las porciones son independientes, varias issues pueden asignarse a varios agentes en paralelo sin conflictos de merge.
Los dos ciclos de vuelta al agente (CI y revisión) son los que mantienen la calidad: el agente no decide cuándo terminó.
Cómo implementarlo: mattpocock/skills
Para no armar todo desde cero, el proceso se puede montar sobre mattpocock/skills, una colección abierta (licencia MIT) que funciona con Claude Code, Codex, Copilot, Gemini CLI, Cursor y otros agentes.
1. Instalar
Un solo método por agente: instalar el plugin y además los archivos duplica los skills.
| Agente | Comando |
|---|---|
| Claude Code | claude plugin install mattpocock-skills@claude-plugins-official |
| Codex | codex plugin marketplace add mattpocock/skills y luego codex plugin add mattpocock-skills@mattpocock |
| GitHub Copilot (CLI y VS Code) | copilot plugin marketplace add mattpocock/skills y luego copilot plugin install mattpocock-skills@mattpocock |
| Gemini CLI | gemini skills install https://github.com/mattpocock/skills.git --path skills/engineering |
| Otros (Cursor, OpenCode, Windsurf…) | npx skills@latest add mattpocock/skills -a <agente>, incluyendo setup-matt-pocock-skills cuando pregunte qué skills instalar |
2. Configurar el repositorio (una vez)
Ejecutar /setup-matt-pocock-skills. Pregunta qué gestor de issues usar (GitHub, GitLab, archivos locales u otro), qué etiquetas se usan para clasificar issues y dónde guardar la documentación. Después se agrega el AGENTS.md con las convenciones de porciones de la sección Preparar el repositorio.
3. Alinear con la IA: /grill-with-docs
La IA entrevista al orquestador, una pregunta por vez, hasta que todas las decisiones quedan explícitas. Mientras tanto mantiene un glosario del dominio (GLOSSARY.md) y registra decisiones de arquitectura (ADR). Es la etapa donde nacen las historias de usuario.
4. Escribir la especificación: /to-spec
Convierte lo conversado en una especificación y la publica en el gestor de issues. Cumple el rol de la historia de usuario o la épica.
5. Dividir en issues verticales: /to-tickets
Es el paso central. Se ejecuta sobre la especificación, por ejemplo /to-tickets #12, y:
- Lee la especificación y explora el código; si conviene, propone un refactor previo para facilitar el trabajo.
- Divide el trabajo en tickets tipo tracer bullet: cada uno atraviesa todas las capas, se puede verificar por sí solo y entra en una ventana de contexto nueva.
- Marca las dependencias: qué ticket bloquea a cuál.
- Muestra la lista al orquestador y pregunta si la granularidad es correcta, si las dependencias son reales y si hay que unir o dividir tickets. Itera hasta que el orquestador aprueba.
- Publica una issue por ticket, con criterios de aceptación y la etiqueta
ready-for-agent(o un archivo por ticket en.scratch/<funcionalidad>/issues/si se eligieron archivos locales).
El paso 4 es la validación del corte. Para reforzarla, antes de aprobar se puede correr sobre la lista el prompt de control de Cómo validar el corte. Un detalle: /to-tickets evita poner rutas de archivos en las issues porque se vuelven obsoletas, así que la carpeta de cada porción la define la convención de AGENTS.md, no la issue.
6. Implementar: /implement o /implement-spec
/implementtoma los tickets, trabaja con/tdd(primero un test que falla, después el código que lo hace pasar), corre los tests y cierra con/code-review. Ese review usa subagentes en paralelo que revisan dos cosas por separado: si el código respeta los estándares del repo y si implementa fielmente la issue. Es el agente revisor que describe este artículo./implement-spectrabaja una especificación completa: lanza varios subagentes en paralelo sobre los tickets que no tienen bloqueos.
Cada pocos días conviene correr /improve-codebase-architecture, que busca dónde se está degradando la estructura y propone mejoras.
Correspondencia con el proceso
| Etapa del artículo | Skill |
|---|---|
| Preparar el repositorio | /setup-matt-pocock-skills + AGENTS.md propio |
| Redactar historias | /grill-with-docs + /to-spec |
| Convertir historias en issues verticales | /to-tickets |
| Validar el corte | Preguntas de /to-tickets + prompt de control |
| Tests primero | /tdd |
| Implementar la porción | /implement |
| Agente revisor | /code-review |
| Varias porciones en paralelo | /implement-spec |