.projectstore / método / 2
La industria lo inventó hace tiempo.
Los agentes lo abarataron.
ADR, revisiones, un backlog, criterios de aceptación, vínculos del objetivo al código. Los equipos de ingeniería maduros llevan veinte años trabajando así. ProjectStore no inventa nada de esto.
De dónde viene cada pieza
- 1969RFC: decisiones escritas y numeradas, y después discutidas en abierto.
- 1992DO-178B: en aviónica, cada requisito debe rastrearse hasta el código y hasta un test.
- 1995Scrum: el trabajo como un backlog, ordenado y visible.
- 1999XP: historias de usuario y criterios de aceptación que dicen cuándo una está hecha.
- 2007Kanban para software: un tablero que muestra lo que está en curso.
- 2011ADR, Michael Nygard: un archivo corto por cada decisión de arquitectura.
- ahoraAgentes de programación: cada paso lleva minutos. Sin los artefactos, cada sesión empieza vacía.
Un proyecto, muchas manos. La misma base para todas.
Un ADR dice qué se decidió y qué se descartó. Una spec dice cómo debe funcionar. Una épica y sus historias dicen qué se está construyendo y cuándo está hecha cada parte. El tablero muestra lo que está en marcha.
Con ellos, un ingeniero que se incorpora mañana, un revisor de otro equipo y un agente en una sesión nueva parten todos de lo que sabía la primera persona. Por eso los equipos que construyen sistemas grandes llevan décadas manteniendo estos documentos.
El proceso siempre fue valioso. Lo caro era que cada paso lo hicieran personas.
El proceso funciona. Sus documentos son lo más valioso que conserva una empresa después de un proyecto: por qué el sistema está hecho así, qué contaba como terminado, dónde vive cada funcionalidad en el código. Pero cuando las personas lo hacen todo a mano, es lento. Escribir un ADR lleva una tarde, y conseguir que lo revisen, una semana. Los documentos se quedan por detrás del código. El tablero deja de reflejar la realidad. Así que los equipos toman atajos, y «ágil» se convierte en la excusa para no escribir nada.
Donde faltan los artefactos, pasa lo mismo con personas y con agentes: vuelven cuestiones ya resueltas, nadie sabe decir por qué el código es como es y cada recién llegado empieza adivinando.
Con los agentes pasa lo contrario. Escribir un ADR, dividir una épica en historias o contrastar un diff con los criterios le lleva a un agente minutos, no días. Lo que le falta a un agente es lo que las personas tienen gratis: memoria entre sesiones, contexto compartido con los compañeros, el vínculo entre un objetivo y el código. Cada sesión nueva empieza vacía y vuelve a decidir lo que ya estaba resuelto.
el proceso de las personas+la velocidad de los agentes=ProjectStore
ProjectStore une las dos cosas. La velocidad de los agentes abarata por primera vez el viejo proceso. Los documentos de ese proceso, guardados en archivos junto al código, dan a los agentes lo que nunca tuvieron: el contexto del proyecto, vinculado hacia arriba con los objetivos y hacia abajo con el código. Cada paso lo revisa, por norma, un segundo agente que no escribió el borrador. La velocidad gana memoria, y la memoria, verificación.
Seis etapas, a mano y en ProjectStore.
| Etapa | La práctica y su antigüedad | Hecha por personas | En ProjectStore |
|---|---|---|---|
| Decisiónpor qué | ADR, Michael Nygard, 2011. Antes, comités de arquitectura y revisiones de diseño. | Una tarde para escribirlo, una semana en la cola de revisión. Las alternativas descartadas se quedan en la cabeza de alguien. | El agente lo redacta en un minuto. El critic, otro agente, busca los puntos débiles. Tú lo apruebas. El resultado es un archivo con fecha que también recoge lo que se descartó. |
| Contratocómo | Spec, documento de diseño, RFC. Los RFC se numeran desde 1969; los documentos de diseño son la norma en las grandes empresas. | Lleva una semana escribirla y para el release ya está desfasada. Nadie comprueba que el código siga ajustándose a ella. | Una spec describe el comportamiento esperado en reglas numeradas. Sus comprobaciones se aplican a cada historia que cubre. Una historia no puede cerrarse mientras su spec siga siendo un borrador. |
| Backlogqué | Product backlog de Scrum, 1995. Historias de usuario de XP, 1999. Kanban para software, 2007. | Reuniones de refinamiento. El tablero se aleja de la realidad en una semana porque se mantiene a mano. | Cada archivo de historia guarda su propio estado. El tablero, los índices y el mapa de enlaces se construyen a partir de esos archivos. Si se desajustan, un comando los reconstruye. |
| Plandónde | Diseño técnico, análisis de impacto. El tech lead mira dónde encaja esto en el código existente. | Cómo llegaron al código las funcionalidades anteriores solo lo sabe el tech lead. Y está de vacaciones. | El planner mira dónde quedaron en el código las épicas anteriores. Dice dónde va el cambio y qué reutilizar. El plan queda en la historia. |
| Aceptaciónprueba | Criterios de aceptación, Definition of Done. XP y Scrum, principios de los años 2000. | Un ciclo de QA al final del sprint. «Hecho» por declaración; los criterios, comprobados por muestreo. | El reviewer contrasta el diff con cada criterio y pide evidencia: un test, un comando ejecutado, una línea de código. Sin evidencia, no se cierra. |
| Trazabilidadvínculos | Trazabilidad de requisitos. Obligatoria en aviónica desde DO-178B (1992) y en el software médico. | Una matriz de Excel «requisito → código → test» que nadie actualiza después del segundo release. | Cada historia enlaza hacia arriba con su épica, sus ADR y sus specs, y hacia abajo con su código. La evidencia va bajo cada criterio de aceptación. El mapa de enlaces y el mapa de código se generan solos, así que nadie los mantiene a mano. |
Los vínculos que un agente obtiene gratis: del objetivo a la prueba
- objetivoÉpicaCHECKOUT · por qué hacemos estoepic:
- por quéADRla decisión y las opciones descartadasadr: [ ]
- cómoSpecel comportamiento esperadospecs: [ ]
- quéHistoriaplan y criterios de aceptacióncode_refs:
- dóndeCódigosrc/billing/cards/ · donde ya viven las épicas anteriores— evidencia:
- pruebaEvidenciatests/cards.test.ts:58 · por criterio
Los vínculos están en la cabecera de cada archivo, y la evidencia es una línea bajo cada criterio de aceptación. El agente lo rellena todo mientras trabaja. El mapa de enlaces muestra con qué se conecta cada documento. El mapa de código muestra dónde vive el código de cada épica. Una sesión nueva, un modelo nuevo o un compañero nuevo parten de esta cadena, no de cero.
Install the projectstore plugin from https://github.com/SmartAndPoint/ProjectStore and set it up for this project.