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

Porción de torta con cuatro capas rotuladas: formulario, endpoint, handler y tabla

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.

Cuatro capas técnicas por cuatro funcionalidades; la porción "inscribir alumno" atraviesa las cuatro capas Crear alumno Inscribir alumno Listar cursos Editar curso Frontend Backend / API Controlador Base de datos formulario endpoint handler tabla 1 issue · 1 PR Capa = corte horizontal Porción = corte vertical, pantalla → base
Cada fila es una capa técnica; cada columna, una funcionalidad. Una porción toma un poco de cada capa, pero solo lo que esa funcionalidad necesita.

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:

Estructura por capas contra estructura por porciones: el caso de uso "inscribir alumno" repartido en cuatro carpetas o reunido en una Por capas 4 carpetas para leer Por porciones (VSA) 1 carpeta para leer Controllers/ AlumnosController InscripcionesController Services/ AlumnoService InscripcionService Repositories/ AlumnoRepository InscripcionRepository DTOs/ AlumnoDto InscripcionRequest Shared/ dominio · autenticación · conexión a la base Features/ Alumnos/CrearAlumno/ request · handler · test_crear_alumno referencia Inscripciones/InscribirAlumno/ request response handler test_inscribir todo el caso de uso en una carpeta Shared/ dominio · autenticación · conexión a la base
Lo resaltado es todo el código del caso de uso "inscribir alumno": repartido en cuatro carpetas a la izquierda, en una sola a la derecha. Para un agente, la derecha significa leer una carpeta en vez de cuatro.

Tres reglas que el agente debe respetar y que conviene dejar escritas en el repositorio:

  1. 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).
  2. 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/.
  3. 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.md en 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.

NivelEjemploQué hace la IAQué valida el orquestador
Historia de usuarioComo docente, quiero inscribir un alumno a un curso para que acceda al aula.La redacta desde notas, pedidos o el sistema actualQue refleje la necesidad real; la prioridad
Issue#42 Inscribir alumno a cursoLa deriva de la historia, con criterios, carpeta y porción de referenciaQue sea una porción vertical y no una capa
TestsUn test por criterio de aceptaciónLos escribe antes del código; un segundo agente verifica que cubran los criteriosSolo lo que marque el agente revisor
PorciónFeatures/Inscripciones/InscribirAlumno/La implementa copiando la porción de referenciaLo hace el CI con tests de arquitectura
PRfeature/42-inscribir-alumno, una sola carpetaLo abre y corrige según comentariosLa revisión final y el merge
La misma unidad de trabajo pasa por historia, issue, tests, porción y PR; en cada paso la IA produce y el orquestador valida LA IA PRODUCE la redacta la deriva los escribe antes la implementa lo abre y corrige Historia necesidad del usuario Issue #42 Inscribir alumno Tests uno por criterio Porción una sola carpeta PR feature/42-… refleja la necesidad y la prioridad ¿es una porción vertical? solo lo que marque el agente revisor CI con tests de arquitectura revisión final y merge EL ORQUESTADOR VALIDA
Una sola unidad de trabajo atraviesa los cinco niveles. Arriba, lo que la IA produce en cada uno; abajo, lo que el orquestador valida antes de dejarla pasar al siguiente.

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:

  1. 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.”

  2. El orquestador prioriza y aprueba las historias.
  3. 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.”

  4. 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 + issuesSolo issues
Mejor paraProductos con usuarios de negocio y priorizaciónEquipos chicos, sistemas internos, migraciones
Prompts de planificaciónDos: historias, luego issuesUno: la issue directa
Validaciones del orquestadorHistorias y corte en issuesSolo el corte en issues
Unidad que recibe el agenteUna issue = una porciónUna 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, pantallaVariante de la regla: inscripción simple → con lista de espera
Componente: backend, frontendCamino 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 adelantadoSolo 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 en Shared/.
  • 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.

  1. Asignar la issue. El prompt es corto porque la issue ya tiene todo: “Implementá la issue #42 siguiendo AGENTS.md.”
  2. 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.
  3. Implementación. El agente copia la estructura de la porción de referencia y escribe el código hasta que los tests pasen.
  4. CI. Corren los tests y los tests de arquitectura. Si fallan, el agente corrige y vuelve a intentar.
  5. 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.
  6. 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.

Flujo de una issue: criterios a tests, el agente implementa, CI y revisión del orquestador devuelven el trabajo al agente hasta aprobar el merge Issue aprobada Criterios → tests Agente implementa ¿CI pasa? falla: vuelve al agente pasa Orquestador revisa pide cambios aprueba Merge, cierra #42 ciclos de corrección: el trabajo vuelve al agente
Dos ciclos de vuelta al agente: el CI cuando los tests fallan y el orquestador cuando pide cambios. El agente no decide cuándo terminó.

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.

AgenteComando
Claude Codeclaude plugin install mattpocock-skills@claude-plugins-official
Codexcodex 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 CLIgemini 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:

  1. Lee la especificación y explora el código; si conviene, propone un refactor previo para facilitar el trabajo.
  2. 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.
  3. Marca las dependencias: qué ticket bloquea a cuál.
  4. 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.
  5. 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

  • /implement toma 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-spec trabaja 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ículoSkill
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 cortePreguntas de /to-tickets + prompt de control
Tests primero/tdd
Implementar la porción/implement
Agente revisor/code-review
Varias porciones en paralelo/implement-spec