Independiente de herramienta. Empieza antes de la SPEC: de una idea vaga + material de referencia, el asistente propone la forma del sistema, vos decidís, y recién ahí se especifica, se construye y se avanza solo con evidencia.
Una forma ordenada de construir software con una IA en la que vos solo traés la idea y las restricciones. El método se encarga de convertirla en algo verificable, construirlo con control de calidad, y decir con evidencia cuándo está terminado de verdad.
La entrevista clásica (precisión adversarial) sirve cuando ya sabés el qué y falta pulir. Pero un sistema nuevo arranca antes: solo sabés qué querés lograr, no el cómo, ni las entidades, ni los endpoints. Ahí hace falta otro modo.
Greenfield / sistema nuevo. Traés idea + restricciones + material de referencia. El asistente propone dominio, superficie de API y opciones de arquitectura; vos reaccionás y decidís. Divergente y después convergente.
Feature dentro de un sistema existente. La entrevista adversarial pinta los bordes: casos sucios, errores, idempotencia, out-of-scope. La forma ya se conoce.
Discovery termina cuando hay una forma de sistema compartida: entidades, operaciones, decisiones grandes tomadas y las incógnitas marcadas. Suficiente para escribir SPECs — no más.
No implementa, no cierra cada detalle, no reemplaza tu criterio de negocio. Es para bajar la idea a algo especificable.
Vos nunca escribiste entidades ni endpoints — solo reaccionaste a propuestas y tomaste 3 decisiones. Ese es el cambio.
No es solo una conversación: es un skill invocable (/discovery) cuyo input inicial es solo la idea + material de referencia, y que escribe los .md directo en el repo.
# una pregunta del grill (propone)
Recomiendo idempotencia por clave natural
cuit+pv+nro (no hash de payload), por
compat con integradores legacy. ¿Lo tomo?
CONTEXT.md
SPEC.md
docs/adr/*.md
ACCEPTANCE.md
RISKS.md
HANDOFF.md
Para un feature ya conocido (no hace falta proponer la forma), el frente es /adr-refine. Mismo paquete de salida.
Qué entidades, qué operaciones, qué decisiones grandes. El "mapa".
Sobre esa forma, ahora sí: errores, idempotencia, seguridad, out-of-scope.
SPEC verificable + ADRs durables + acceptance — listo para construir.
Comportamiento observable, reglas, entradas/salidas/errores, criterios de aceptación, tests, operación. Es el contrato de construcción y verificación. Casi todo cambio no trivial necesita una.
Registra una decisión técnica, las alternativas descartadas y las consecuencias. Memoria arquitectónica, no lista de tareas. Solo decisiones con impacto durable.
# SPEC-001: gateway de CAE
## Objetivo / Valor
## Riesgo (A..E)
## Scope / Out of scope
## Comportamiento (reglas observables)
## Entradas / salidas / errores
## Acceptance criteria (verificable)
## Test plan (unit/integration/contract)
## Operación (logs, métricas, flags)
## Rollback
# ADR-001: cache del TicketAcceso
## Estado: Aceptado
## Contexto / Fuerzas
## Alternativas: A) memoria B) MSSQL C) Redis
## Decisión: B) MSSQL
## Consecuencias (+ / -)
## Relación con SPECs: SPEC-001
La SPEC suma Objetivo/Valor y Riesgo arriba: si no se justifica el valor ni se clasifica el riesgo, no debería entrar al loop.
| Perfil | Ejemplo | Documentos | Gates mínimos |
|---|---|---|---|
| A · Bajo | UI menor, config no crítica | SPEC mini | build + test relevante |
| B · Normal | feature local, bugfix | SPEC + acceptance | tests + static + review |
| C · Crítico | pagos, facturación, seguridad | SPEC formal + ADR | unit+integration+security+rollback |
| D · Multi-sistema | API pública, eventos | SPEC + contratos + ADR | contract tests + versionado |
| E · Legacy grande | refactor, migración | SPEC incremental + baseline | characterization + no regression |
Pregunta inicial: ¿qué puede romper esto y cuánto cuesta si se rompe? El riesgo escala el aparato — el perfil A no arrastra toda la maquinaria.
## Definition of Ready - [ ] Objetivo y valor / por qué ahora - [ ] Scope + out-of-scope explícito - [ ] Entradas / salidas / errores - [ ] Reglas de negocio escritas - [ ] Riesgo clasificado (A..E) - [ ] ADR requerido: sí/no - [ ] Rollback esperado: sí/no - [ ] Ambiente de prueba disponible
Agregué valor / por qué ahora al DoR: el riesgo mide el downside; el valor evita construir bien algo que no valía.
Si durante Build la realidad obliga a cambiar la SPEC, se versiona y vuelve a Ready. Y ese evento es señal de un DoR flojo → retroalimenta el DoR. La implementación nunca cambia la SPEC a escondidas para parecer correcta.
¿Cumple la SPEC y los acceptance criteria?
¿Compila, tiene tests, respeta estándares, sin bugs obvios?
¿No rompió lo existente, especialmente legacy?
¿No rompió APIs, schemas, eventos, clientes?
¿Sin findings HIGH/CRITICAL nuevos? ¿Secretos fuera de logs? (capa propia para perfil C+).
¿Se puede desplegar, observar, apagar o revertir?
Antes había dos taxonomías que no cerraban. Ahora cada capa es una dimensión del readiness — la evidencia rolea limpio hacia el estado. Coverage alto no prueba operación; CI verde no prueba contrato.
Una sola máquina de estados: DRAFT → READY TO BUILD → DEV DONE → MERGE READY → RELEASE READY. Se acabaron los dos vocabularios que se pisaban.
El estado lo definen los blockers, no el promedio. Si mostrás un número, sale de las 6 capas con pesos y caps definidos — nunca un número suelto. Sin fórmula, no hay número: eso sería la numerología que el método dice evitar.
Mostrar siempre: estado + blockers + evidencia + riesgo residual. El score es auxiliar y derivado.
# Evidence entry (la emite la ejecución)
change_id: SPEC-001
commit: a1b2c3d
command: mvn test
exit_code: 0
tests: 42 passed / 0 failed
coverage: 71%
security: 0 HIGH/CRITICAL new
artifacts:
- target/surefire-reports
- target/site/jacoco/jacoco.xml
Si el mismo agente que hace el cambio escribe el ledger, puede poner exit_code: 0 sin correr nada. La garantía solo vale si la evidencia la produce la ejecución (CI o un script que parsea artefactos reales), no si la transcribe el autor.
Ausente = sin evidencia, nunca "OK". Una herramienta que no corrió no se inventa en verde.
## Legacy baseline
- No new HIGH/CRITICAL findings
- No regression in existing tests
- Touched files: no new warnings
- Deuda fuera de scope → backlog
- Refactor solo con characterization
Exigir "cero findings" en legacy es no entregar nunca. Se congela la deuda vieja y se bloquea la nueva.
## Change budget (blast radius)
Máx: 3 iteraciones · 12 archivos
0 cambios de schema sin ADR
0 dependencias nuevas sin aprobación
Escalar si:
- un fix revierte otro
- aparece un test rojo nuevo
- cambia un contrato público
Escalar no es fallar: es que apareció una decisión humana. El proceso detectó que no debía seguir solo.
## Rollback
- Código: revert del PR
- DB: sin migration destructiva
- Config: feature flag off
- API: backward compatible
- Smoke post-rollback: /health + flujo base
Si hay schema forward-only o transformación de datos, el rollback es una decisión explícita, no se asume.
Cuando el cambio toca producción, logs/métricas/alertas/flags/runbook son parte de la capa operacional.
Código descartable para aprender. No SPEC; sí una nota de qué se aprendió. Lo que sobreviva, se especifica después.
Demo que no va a producción. Marcado como tal, aislado, con fecha de muerte.
Incidente en producción: arreglás primero. Pero la evidencia mínima (qué se cambió, cómo se revierte) y la SPEC/ADR retroactivos son obligatorios dentro de 24h.
SPEC.md — comportamiento, reglas, errores, tests, operación.docs/adr/*.md — solo decisiones durables.ACCEPTANCE.md — checklist verificable contra evidencia.RISKS.md — riesgos residuales y supuestos.HANDOFF.md — instrucciones para quien implemente.El método define qué evidencia se exige (las 6 capas). Cada stack provee el cómo: en Java/Maven es JaCoCo+Surefire+SpotBugs; en Node es jest+coverage+eslint; en un pipeline de datos son otros. Mismo contrato de evidencia, distinto adapter.
Por eso es agnóstico de verdad: la metodología gobierna, el adapter ejecuta. Sirve para backend, frontend o data.
No es un handoff entre herramientas — es entre fases. El modelado termina escribiendo el paquete en el repo; el build (/dev-loop) lo lee de los archivos, no del chat. Aunque sea todo en una sesión de Claude Code.
/clear o una compactación) no tiene el chat — lee el repo.# lo que el build lee antes de tocar código
SPEC.md · ACCEPTANCE.md · docs/adr/*.md
1. Resumí el comportamiento esperado.
2. Marcá ambigüedades o contradicciones.
3. Proponé plan de archivos + tests.
4. Implementá SOLO el scope de la SPEC.
5. Corré build/tests/gates disponibles.
6. Entregá evidence summary + blockers.
No cambies contratos fuera de SPEC ni
edites la SPEC para que tu implementación
parezca correcta.
Layout: CLAUDE.md/AGENTS.md (reglas estables) · SPEC.md · ACCEPTANCE.md · docs/adr/
| Fase (agnóstica) | En Claude Code |
|---|---|
| Discovery / entrevista | /discovery — grilla y escribe CONTEXT/SPEC/ADR/ACCEPTANCE |
| SPEC + ADR | archivos versionados en el repo (los escribe el skill) |
| Build + QA loop | /dev-loop + qa_ledger.py + sub-agentes |
| Evidence | qa_ledger parsea artefactos reales → ledger |
| Readiness | qa_ledger readiness — estado + blockers |
| Human gate | vos aprobás el PR (no se automatiza) |
| Docs del sistema | /sys-doc |
Protocolo estable del repo: comandos, no-go zones, DoD, cómo registrar evidencia. Lo permanente vive acá; lo puntual en SPEC/ADR.
discovery, dev-loop, sys-doc en .claude/skills/. Invocables, versionables, compartibles con el equipo.
Paralelizan las tools de QA (review, security, mejoras) sin ensuciar el contexto principal.
Corren gates solos: tests post-edit, lint pre-commit. La evidencia se captura por ejecución, no se narra.
Montás varios repos en una sesión para QA de integración/contratos (tu caso TipreSuite).
Seguís y manejás la sesión desde el celular mientras corre el loop.
+ plan mode para planificar · settings.local.json para permisos · ccusage para monitorear uso.
El ADR no solo justifica: incluye archivos a tocar, patrones a seguir, tests y verificación. Claude Code lo lee y ejecuta sin volver a preguntar.
Si Claude Code, codeando, está por meter una dependencia nueva, crear un patrón nuevo, elegir entre alternativas o contradecir un ADR aceptado → para y propone un ADR.
El ADR nombra los affected paths; el código lleva // ADR: … ver docs/adr/…. Cuando un ADR se supersede, encontrás todo lo que hay que tocar.
Antes de trabajar en un área gobernada por un ADR, el agente lo lee y respeta — o marca el conflicto. No lo resuelve a escondidas.
Tomado del adr-skill de Vercel y ya integrado al dev-loop (triggers + consultar/linkear) y al template de ADR (implementation plan + verificación).
qa_ledger.py (stdlib, sin deps).~/.claude/skills/.# Claude Code (native, sin Node) curl -fsSL https://claude.ai/install.sh | bash # Windows: irm https://claude.ai/install.ps1 | iex claude # login OAuth # Skills del kit (global) cp -r dev-loop-kit/.claude/skills/* ~/.claude/skills/ # Verificar claude --version && claude doctor
Lo específico del stack (Java/Maven, MSSQL, linters) es el adapter por repo — va en el CLAUDE.md, no en el workbench.
Traés el qué; el método propone el cómo.
Comportamiento que puede fallar, no deseos.
Hechos de la ejecución, no narrados.
El merge y el release no se automatizan.