Una metodología independiente de herramienta: primero se transforma una idea bruta en una SPEC verificable, se registran decisiones con ADR cuando corresponde, se implementa con límites claros y se avanza solo con evidencia.
Define qué debe hacer el sistema, bajo qué reglas, con qué entradas, salidas, errores, criterios de aceptación, tests esperados y límites operativos. Es el contrato de construcción y verificación.
Registra por qué se tomó una decisión técnica, qué alternativas se descartaron y cuáles son sus consecuencias. Es memoria arquitectónica, no una lista de tareas.
En un sistema nuevo, normalmente no sabés entidades, endpoints, tablas ni arquitectura. Sabés qué querés lograr. La metodología no debe pedirte una SPEC; debe ayudarte a descubrirla.
Qué problema resuelve, para quién, qué duele hoy, qué significa éxito y qué queda fuera.
Quién llama al sistema, desde dónde, con qué protocolo, credenciales, frecuencia y criticidad.
Happy path, errores, reintentos, duplicados, estados intermedios, vencimientos y consultas.
Entidades tentativas, invariantes, reglas de negocio, estados y relaciones. Se valida, no se impone.
Solo cuando hay alternativa real: sync vs async, REST vs SOAP, persistencia, seguridad, idempotencia.
Tests esperados, contratos, datos de prueba, smoke test, rollback y criterios de aceptación.
La primera sesión no apunta a crear archivos de proyecto. Apunta a convertir una intención vaga en un sistema pensable, verificable y ejecutable.
Solo se pasa a SPEC cuando están claros: objetivo, actores, canales, flujos principales, errores críticos, datos persistidos, riesgos, decisión de MVP y criterios de aceptación.
# Anti-patrón Usuario: quiero un gateway fiscal. Asistente: perfecto, acá va el pom.xml. # Patrón correcto Usuario: quiero un gateway fiscal. Asistente: primero cierro alcance, actores, protocolos, idempotencia, CAE/CAEA, certificados, numeración y operación.
“Necesito armar un server que atienda muchos POS vía SOAP/REST para gestionar la obtención de CAE de ARCA mediante los WS de factura electrónica. Revisá el manual ARCA COMPG. Quiero Java 21, Spring Boot 4.0.3, UI React y base MSSQL. Necesito SPEC, ADR y un prompt inicial para el agente de código.”
CAE solamente o también CAEA, tenant por CUIT, manejo de certificados, numeración, idempotencia, auditoría, reintentos, SLA, seguridad POS.
Dominio fiscal, integración externa SOAP, alto riesgo de duplicados, necesidad de persistencia fuerte y trazabilidad operativa.
Convertir esa idea en mapa de actores, flujos, entidades candidatas, APIs, riesgos, MVP y decisiones ADR.
| Archivo | Contenido |
|---|---|
| SPEC.md | Objetivo, alcance, actores, flujos, entidades candidatas, APIs, errores, tests, operación. |
| docs/adr/*.md | Decisiones: REST/SOAP, idempotencia, numeración, persistencia, certificados, cliente ARCA. |
| ACCEPTANCE.md | Checklist verificable: emisión CAE, reintento, rechazo, consulta, auditoría, seguridad. |
| RISKS.md | Riesgos fiscales, duplicados, certificados, indisponibilidad ARCA, concurrencia, seguridad. |
| HANDOFF.md | Prompt final para el agente de código, ya armado desde la conversación. |
El prompt de ejecución no lo redacta el usuario. Se genera al final, cuando el sistema ya fue modelado y tiene suficiente contexto.
# HANDOFF.md
Leé SPEC.md, ADRs y ACCEPTANCE.md.
No implementes todo el sistema.
Primero creá esqueleto backend + modelo
de dominio + endpoints MVP + tests base.
Antes de tocar código, resumí plan de archivos,
riesgos y primer test.
El humano no debería tener que saber entidades, endpoints, tablas ni prompts finales. Su trabajo es explicar la intención inicial y validar/corregir las conclusiones de la entrevista.
Un arranque mínimo: Use spec-discovery. Tengo esta idea.... Desde ahí, el skill conduce la entrevista y genera el handoff técnico.
Esto no es todavía diseño final. Es el primer modelo coherente para discutir. Si el usuario corrige algo —por ejemplo “la numeración la trae el POS”— cambian SPEC, ADRs y tests.
| Aspecto | SPEC | ADR |
|---|---|---|
| Pregunta | ¿Qué debe pasar? | ¿Por qué decidimos hacerlo así? |
| Uso | Construcción, testing, aceptación, handoff | Memoria técnica, trade-offs, restricciones |
| Formato | Checklist + reglas + casos + contratos | Contexto + alternativas + decisión + consecuencias |
| Frecuencia | Casi todo cambio no trivial | Solo decisiones con impacto técnico duradero |
| Bloquea avance | Sí: si no hay SPEC verificable, no se construye | A veces: si falta decisión arquitectónica o de riesgo |
| Ejemplo | “POST /tickets valida importes y devuelve 422 si no cierra IVA.” | “Se valida en service, no en controller, para compartir regla con batch.” |
# SPEC-014: recepción de ticket fiscal ## Objetivo Aceptar tickets de terceros y persistirlos sin duplicar. ## Scope - POST /api/tickets - Validación de API key y punto de venta - Idempotencia por cuit + pv + nrocomprobante ## Out of scope - Conciliación ERP - Reproceso masivo ## Reglas - importetotal debe cerrar contra neto + IVA + percepciones - fecha futura mayor a 24h → 422 - API key inválida → 401
Cada regla importante debe tener un caso de prueba o verificación manual explícita. Si no se puede testear, probablemente está escrita como deseo, no como especificación.
Una buena SPEC dice qué entra y qué queda afuera. El out-of-scope protege contra el “ya que estamos”.
La SPEC define comportamiento. Si hay que elegir arquitectura, persistencia, protocolo o estrategia de idempotencia, ahí aparece el ADR.
# ADR-014: idempotencia de tickets ## Estado Aceptado ## Contexto El cliente puede reenviar el mismo ticket por timeout. Necesitamos evitar duplicados sin perder trazabilidad. ## Alternativas A) Idempotency-Key externa B) Hash del JSON completo C) Clave natural: cuit + pv + nrocomprobante ## Decisión C) Clave natural + log de request. ## Consecuencias + Simple para integradores legacy - Cambios de numeración requieren coordinación
Cuando la decisión cambia cómo se mantiene, opera o evoluciona el sistema: persistencia, idempotencia, seguridad, contratos, colas, migraciones, costos, tolerancia a fallos.
No uses ADR para cada campo, rename o validación menor. Eso genera burocracia y después nadie lee los ADR importantes.
Una buena decisión técnica no solo dice “elegimos X”. Debe dejar explícito qué restricciones gobiernan el código, qué alternativas se descartaron, qué archivos o patrones quedan afectados y cómo se verifica que la decisión fue respetada.
Debe entenderse sin depender de memoria tribal: problema, disparador, restricciones, alternativas, opción elegida y consecuencias.
Incluye rutas afectadas, patrones a seguir, tests esperados, migraciones, flags, datos y límites de scope.
Los criterios se escriben como checks verificables: tests, contratos, linters, smoke test, rollback o revisión manual explícita.
## Implementation Plan - Affected paths: src/fiscal/, src/api/, tests/integration/ - Pattern: toda llamada fiscal pasa por FiscalGatewayPort - Tests: idempotencia, timeout, error ARCA, replay - No tocar: UI operativa fuera del MVP ## Verification - [ ] Reintento no duplica comprobante - [ ] Timeout queda auditable - [ ] No se loguea certificado ni clave privada - [ ] Contract tests REST/SOAP verdes
Si un agente o dev no puede implementar sin volver a preguntar “¿cómo era la decisión?”, el ADR todavía está incompleto.
Durante discovery o implementación, el proceso debe detectar decisiones que no pueden resolverse “de paso”. Si aparece una de estas señales, se pausa el build-loop y se abre una decisión.
Se introduce una librería, framework, cliente externo, motor de cola o componente que condiciona el mantenimiento futuro.
Se crea una forma nueva de manejar errores, persistencia, seguridad, integración, logging, validación o contratos.
Hay más de una alternativa razonable y la elección impacta costo, performance, operación, seguridad o reversibilidad.
El cambio propuesto contradice un ADR aceptado o un patrón dominante del repo. No se pisa: se supersede.
Si el código necesita un comentario extenso para justificar la decisión, probablemente ese razonamiento pertenece a un ADR.
Si después de escribir código será caro cambiarlo —schema, protocolo, auth, persistencia— la decisión merece registro formal.
Leer ADRs existentes, README, build files, dependencias, patrones de código y referencias ADR↔código.
Entrevista socrática: qué se decide, por qué ahora, restricciones, opciones, lean, non-goals y éxito medible.
Escribir ADR autocontenido con alternativas, decisión, consecuencias, implementation plan y verificación.
Revisar contra checklist de agent-readiness. Si hay gaps, no finalizar salvo aceptación explícita del humano.
Antes del draft, el asistente muestra un resumen: título, trigger, restricciones, opciones, lean, non-goals, áreas afectadas y verificación. Si el humano corrige, se actualiza el intento.
En un sistema ya iniciado, no se entrevista ignorando lo que existe. Primero se detectan convenciones reales para no generar ADRs incompatibles con el código.
Un ADR aceptado no se contradice silenciosamente. Si la decisión cambió, se crea uno nuevo que supersede al anterior y se enlazan ambos.
El implementation plan lista paths, patrones y tests gobernados por la decisión.
Comentarios livianos en puntos de entrada permiten que un agente futuro encuentre la razón de una decisión.
// ADR-0003: idempotencia CAE por POS + comprobante // See: docs/adr/fiscal/ADR-0003-idempotencia-cae.md public CaeResponse solicitarCae(CaeRequest request) { ... }
docs/adr/README.md lista estado, fecha, categoría y ADR superseded.
backend, fiscal, integration, security, operations, data. Facilita búsqueda y revisión.
Cada consecuencia relevante se convierte en tarea, test, verificación o riesgo registrado.
Documento vivo del cambio. Debería estar cerca del ticket o PR.
Documento durable. No se reescribe por cada ajuste; se supersede si cambia la decisión.
Documento factual. Registra qué se ejecutó y con qué resultado.
| Perfil | Ejemplo | Documentos | Gates mínimos |
|---|---|---|---|
| A · Bajo | Texto, UI menor, config no crítica | SPEC mini / ticket claro | Build + test relevante |
| B · Normal | Feature local, bugfix de dominio | SPEC + acceptance | Tests + static gate + review |
| C · Crítico | Pagos, facturación, seguridad, datos | SPEC formal + ADR si hay decisión | Unit + integration + security + rollback |
| D · Multi-sistema | API pública, eventos, multi-repo | SPEC formal + contratos + ADR | Contract tests + integración + versionado |
| E · Legacy grande | Refactor, migración, módulos viejos | SPEC incremental + baseline | Characterization + no regression + no new debt |
## Definition of Ready
- [ ] Objetivo claro
- [ ] Scope definido
- [ ] Out-of-scope explícito
- [ ] Entradas y salidas conocidas
- [ ] Errores esperados definidos
- [ ] Reglas de negocio escritas
- [ ] Ambiente de prueba disponible
- [ ] Riesgo clasificado
- [ ] ADR requerido: sí/no
- [ ] Rollback esperado: sí/no
La etapa correcta no es implementar “algo” y corregir después. Es volver a SPEC hasta que el cambio sea construible.
Reduce retrabajo, discusiones tardías y decisiones improvisadas dentro del código.
AMOUNT_MISMATCH.Implementar solo lo que la SPEC permite. Cambios fuera de scope vuelven a refinamiento.
Tests, static analysis, security, contratos, operación, rollback. Separar señales.
El resultado final no dice “listo”. Dice por qué está listo o qué lo bloquea.
¿Cumple la SPEC y los acceptance criteria?
¿Compila, tiene tests, respeta estándares y no introduce bugs obvios?
¿No rompió comportamiento existente, especialmente legacy?
¿No rompió APIs, schemas, eventos, clientes o integraciones?
¿Se puede desplegar, observar, apagar o revertir?
Coverage alto no prueba operación. CI verde no prueba contrato externo. Smoke OK no prueba seguridad.
En sistemas legacy, exigir “cero findings” es una receta para no entregar nunca. La estrategia correcta es congelar la deuda conocida y bloquear deuda nueva.
## Legacy policy
- No new HIGH / CRITICAL findings
- No regression in existing tests
- Touched files cannot introduce new warnings
- Existing debt outside scope goes to deferred backlog
- Refactor only when protected by characterization tests
Permite avanzar sin convertir cada feature en una limpieza global.
El cambio nuevo no puede empeorar el sistema. La deuda vieja se tolera, la deuda nueva se bloquea.
El número es auxiliar. El estado real lo definen los blockers. Un cambio no es READY si falta evidencia crítica, aunque el promedio dé alto.
Mostrar siempre: estado, score entero, blockers, evidencia y riesgos residuales. Nunca score solo.
NOT READY · IN PROGRESS · MERGE READY · RELEASE CANDIDATE · READY
## Evidence entry
- timestamp: 2026-06-28T22:40:00-03:00
- change_id: SPEC-014
- commit: a1b2c3d
- command: mvn test
- exit_code: 0
- tests: 42 passed / 0 failed
- coverage: 71%
- static_gate: 0 HIGH/CRITICAL new
- artifacts:
- target/surefire-reports
- target/site/jacoco/jacoco.xml
El ledger registra hechos verificables. No interpreta negocio ni reemplaza criterio humano.
Si una herramienta no corrió, no se inventa verde. Ausente significa “sin evidencia”, no “OK”.
## Change budget
Máximo:
- 3 iteraciones automáticas
- 12 archivos modificados
- 0 cambios de schema sin ADR
- 0 dependencias nuevas sin aprobación
- No tocar módulos fuera de scope
Escalar si:
- Un fix revierte otro fix anterior
- Aparece un test rojo nuevo
- Cambia contrato público
- Se supera el scope previsto
Un agente, un dev o un equipo bajo presión tienden a resolver “un poco más”. Esa expansión es donde nacen regresiones y deuda accidental.
Escalar significa que apareció una decisión humana o arquitectónica. El proceso funcionó: detectó que no debía seguir solo.
Para cambios no triviales, la SPEC debe decir cómo se neutraliza el cambio si falla en ambiente real.
## Rollback
- Código: revert del PR
- DB: sin migration destructiva
- Config: feature flag `new_flow_enabled=false`
- API: backward compatible
- Smoke test post-rollback: GET /health + flujo base
Si hay cambio de schema forward-only o transformación de datos, el rollback debe ser decisión explícita. No se asume.
Logs, métricas, alertas, feature flags y runbook son parte del readiness cuando el cambio toca producción.
Implementado localmente, tests relevantes verdes, evidencia inicial.
CI verde, review cerrada, acceptance cumplida, sin blockers de merge.
Deploy, rollback, smoke, monitoreo y comunicación listos.
# SPEC-000: título del cambio
## Objetivo
Qué problema resuelve y para quién.
## Riesgo
Bajo / Normal / Crítico / Multi-sistema / Legacy grande.
## Scope
Qué entra.
## Out of scope
Qué NO entra.
## Comportamiento esperado
Reglas observables del sistema.
## Entradas / salidas / errores
Payloads, códigos, mensajes, validaciones.
## Acceptance criteria
Checklist verificable.
## Test plan
Unit / integration / contract / manual smoke.
## Operación
Logs, métricas, config, permisos, monitoreo.
## Rollback
Cómo se revierte o neutraliza.
# ADR-000: título de la decisión
## Estado
Propuesto / Aceptado / Superseded
## Contexto
Qué problema técnico fuerza una decisión.
## Fuerzas / restricciones
Performance, operación, seguridad, legacy, costo, plazos.
## Alternativas consideradas
A) ...
B) ...
C) ...
## Decisión
Qué se eligió.
## Consecuencias
Positivas, negativas y riesgos residuales.
## Relación con SPECs
- SPEC-014
- SPEC-021
POST /api/tickets recibe comprobante, valida API key, valida importes, evita duplicados, persiste y responde con estado. Define 401, 422, 409, payloads y test matrix.
La idempotencia se resuelve con clave natural cuit + punto de venta + nrocomprobante, no con hash de payload ni Idempotency-Key externa, por compatibilidad con integradores legacy.
Usar SPEC para cambios medianos: objetivo, scope, acceptance y test plan.
Registrar solo decisiones durables: seguridad, datos, contratos, operación.
Guardar build, tests, coverage y static gate en un resumen estándar.
Estados + blockers explícitos. Score opcional, nunca solo.
La conversación sirve como una entrevista técnica: el asistente pregunta, contradice, detecta huecos y destila una SPEC verificable. El código recién empieza cuando la SPEC está lista para ejecutarse.
El humano describe objetivo, sistema actual, restricciones, datos disponibles, actores y dolores. No hace falta que venga perfecto.
El asistente fuerza precisión: casos borde, errores, idempotencia, seguridad, operación, rollback, compatibilidad y out-of-scope.
La salida es un paquete versionable: SPEC.md, ADRs necesarios, acceptance, riesgos, preguntas abiertas y handoff técnico.
En chat libre podés escribir este contrato una vez. Si existe el skill, no hace falta repetirlo: basta invocar spec-discovery y dar la idea bruta.
En esta fase la productividad es eliminar dudas. Cada ambigüedad resuelta en chat evita código equivocado, tests falsos y retrabajo.
| Archivo | Contenido |
|---|---|
SPEC.md | Comportamiento, reglas, errores, tests, operación y evidencia esperada. |
docs/adr/*.md | Solo decisiones relevantes: alternativas, decisión, consecuencias. |
ACCEPTANCE.md | Checklist verificable que luego se tilda contra evidencia. |
RISKS.md | Riesgos residuales, supuestos y puntos que requieren aprobación humana. |
HANDOFF.md | Instrucciones para quien implemente: humano, agente, CI o equipo. |
Se usa para conversación larga, modelado conceptual, preguntas adversariales, SPEC y ADR.
La verdad queda en archivos versionados. Nada importante vive solo en el chat.
Se usa para leer el repo, modificar código, correr comandos, iterar y producir evidencia.
En ChatGPT: entrevista SPEC/ADR hasta converger. No pedir código todavía.
Crear en el repo SPEC.md, ACCEPTANCE.md y ADRs necesarios.
Codex lee esos archivos y propone plan de archivos + estrategia de tests antes de editar.
Implementa, corre build/tests/gates, registra evidencia y deja PR/diff listo.
AGENTS.mdReglas estables del repo: comandos, convenciones, no-go zones, definition of done y cómo registrar evidencia.
SPEC.md cambia por tareaNo mezclar reglas permanentes con requerimientos puntuales. Lo permanente vive en AGENTS/guías; lo puntual vive en SPEC/ADR/Acceptance.
La metodología puede cubrir el ciclo completo desde una idea bruta hasta dejar un cambio listo para revisión humana: SPEC/ADR generados, código implementado, tests/gates ejecutados, evidencia registrada y PR/diff preparado.
Chat de modelado para discovery, SPEC, ADR, acceptance y riesgos. Luego agente de repo para implementar, correr comandos y producir evidencia.
Un mismo agente puede entrevistar, escribir SPEC/ADR, confirmar con el humano, implementar, testear y dejar evidencia final.
“Final del desarrollo” no significa merge o release automático. El agente puede dejar el cambio listo para revisión; el smoke test, aprobación de riesgos, merge y release siguen siendo decisión humana.
El skill toma una intención inicial —incompleta, ambigua, incluso mal nombrada— y conduce una entrevista estructurada hasta producir SPEC, ADRs, modelo de dominio, acceptance, riesgos y handoff.
Pregunta comportamiento, actores, reglas, fallos, volumen, seguridad, operación y límites. Luego deriva interfaces.
Su salida no es código. Su salida es claridad ejecutable para un agente de código o un dev humano.
Todo queda marcado como confirmado, asumido, abierto o diferido. Las dudas no desaparecen: se administran.
Una frase de objetivo más restricciones conocidas. No hacen falta entidades, tablas, endpoints, pantallas, contratos ni arquitectura.
# Ejemplo de input válido
Necesito un server que atienda muchos POS vía SOAP/REST
para gestionar CAE contra ARCA. Quiero Java, Spring,
React y MSSQL. No sé todavía entidades ni endpoints.
Pregunta de a 3 a 7 cosas por ronda. Prioriza los huecos de mayor riesgo. Si el usuario no sabe, propone default y lo marca como supuesto.
| Archivo | Propósito |
|---|---|
| docs/spec/00-discovery-notes.md | Notas, supuestos, preguntas abiertas, decisiones preliminares. |
| docs/spec/SPEC.md | Comportamiento verificable del sistema. |
| docs/spec/DOMAIN-MODEL.md | Conceptos, estados, invariantes, source of truth. |
| docs/spec/ACCEPTANCE.md | Criterios testeables de aceptación. |
| docs/spec/RISKS.md | Riesgos, mitigaciones, rollout, rollback. |
| docs/adr/ADR-0001-*.md | Decisiones técnicas relevantes. |
| docs/spec/HANDOFF-CODE-AGENT.md | Prompt inicial para implementación. |
Objetivo, usuarios, restricciones, documentos externos, integraciones existentes.
Éxito, MVP, fuera de scope, volumen, SLA, compliance, operación manual/automática.
Clientes máquina, usuarios humanos, soporte, sistemas externos, jobs, canales.
Entidades candidatas, lifecycle, invariantes, idempotencia, auditoría.
Happy path, retry, validación, no autorizado, falla externa, reproceso.
REST/SOAP/UI/jobs/eventos con contratos y modelo de error.
Solo para decisiones de largo impacto: persistencia, seguridad, idempotencia, integración.
Primer slice implementable, tests iniciales, comandos, límites y stop conditions.
.agents/
└─ skills/
└─ spec-discovery/
├─ SKILL.md
├─ templates/
│ ├─ SPEC.template.md
│ ├─ DOMAIN-MODEL.template.md
│ ├─ ACCEPTANCE.template.md
│ ├─ RISKS.template.md
│ ├─ ADR.template.md
│ └─ HANDOFF-CODE-AGENT.template.md
└─ scripts/
└─ init_spec_docs.py
El formato puede vivir en cualquier agente que soporte instrucciones reutilizables. Si no hay filesystem, el skill emite markdown copiable.
Antes de pisar un archivo existente, se lee. Los supuestos confirmados se preservan. Las preguntas abiertas no se borran. Un ADR no se reescribe silenciosamente: se crea uno nuevo si la decisión cambió.
init_spec_docs.py crea la estructura inicial. No decide nada: solo prepara carpetas y templates para que la entrevista escriba sobre archivos reales.
$ python .agents/skills/spec-discovery/scripts/init_spec_docs.py --name "arca-gateway"
El cambio se construye contra comportamiento verificable, no contra una idea ambigua.
Las decisiones importantes quedan justificadas sin burocratizar cada tarea.
La salida se sostiene con hechos: tests, gates, contratos, rollback y blockers.