Radiografía Completa de Repositorios

Transcript

1. Radiografía Completa de Repositorios Un ecosistema de skills para documentar, diagnosticar y reconstruir sistemas existentes con evidencia documentar → diagnosticar → especificar → reconstruir Ernesto Crespo · Julio 2026
2. El problema: brownfield sin especificaciones El código es el único artefacto — y la IA “alucina con confianza” sobre lo que no puede anclar Documentación inexistente o muerta El README de 2022 y la arquitectura que vive en la cabeza de alguien. Reconstruir la v2 exige specs que hoy no existen. Specs generadas por IA ≠ specs confiables Una spec plausible que diverge del código es peor que ninguna: la v2 hereda sus errores. La solución no es prohibir la IA, es exigirle evidencia. El historial git se desperdicia Los commits saben qué se construyó, en qué orden y qué se rompió. Cada fix es un criterio de aceptación que la historia ya pagó. Regla de oro compartida: [VERIFY: archivo:línea] [COMMITS: hash] [METRIC: dato] — lo demás se marca [INFERIDO] Radiografía de Repositorios · Ecosistema de Skills 2
3. El ecosistema: cinco skills, un pipeline graph-first-context reverse-sdd code-audit arch-evaluator spec-driven-design CONTEXTO D O C U M E N TA R A U D I TA R DIAGNOSTICAR ESPECIFICAR Entender el código sin quemar tokens: estructura, semántica e intención pre-indexadas. Código + historial git → arquitectura, stack, evolución, HUs con Gherkin, pruebas y plan v2. Calidad + seguridad en 8 dimensiones (DRY, SOLID, tests, SAST, SCA, secretos, contenedores) y gate precommit por stack. Grafo de dependencias + señales git → debilidades con evidencia, ADRs y plan de migración. Los 5 artefactos SDD de cada nueva versión: PRD, API Spec, Tech Design, Data Model, Implementation Plan. Los cinco se distribuyen desde github.com/ecrespo/skills (MIT) — formato Agent Skills, CI que valida y publica releases, y orden canónico de encadenamiento: contexto → documentar → auditar → diagnosticar → especificar Radiografía de Repositorios · Ecosistema de Skills 3
4. Instalación: github.com/ ecrespo/ skills cuatro vías según el agente · CI valida, empaqueta y publica en cada release Claude Code — plugin (recomendado) Claude Code · Codex · Cursor · OpenCode Bundle gestionado que se actualiza con el marketplace. Copias editables dentro del proyecto vía skills.sh. /plugin marketplace add ecrespo/skills /plugin install ecrespo-skills@ecrespo-skills npx skills@latest add ecrespo/skills Cualquier agente — installer del repo Claude Desktop / claude.ai / Cowork Sin Node; targets y selección de skills; --dry-run y --ref. Bundle .skill por skill en cada tag v* → Settings → Skills, o soltarlo en Cowork. ./scripts/install.sh --target claude-project curl -fsSL .../install.sh | bash -s -- --list github.com/ecrespo/skills/releases CI (skills.yml): valida reglas Agent Skills + smoke-test de scripts → empaqueta dist/*.skill → release en cada tag v* · git tag v1.0.0 && git push origin v1.0.0 Radiografía de Repositorios · Ecosistema de Skills 4
5. graph-first-context: contexto sin quemar tokens 3 capas de conocimiento pre-construidas · consultar ANTES de grep o leer archivos 0 Detección de capas consultas típicas ls -d .codegraph graphify-out lat.md — usar las que existan y degradar con gracia; ofrecer indexar si falta una que ayudaría. 1 2 Intención — lat.md lat search / section / refs El porqué del código: decisiones de diseño, reglas de negocio, restricciones y specs de prueba. codegraph_search / callers Estructura — CodeGraph graphify query / path / codegraph_impact / context explain El qué/dónde: símbolos, llamadores, imports e impacto de un cambio (blast radius). 3 Significado — Graphify El cómo encaja: consultas semánticas sobre código + docs, esquemas y PDFs. Radiografía de Repositorios · Ecosistema de Skills Regla: lat.md = por qué · CodeGraph = qué/dónde · Graphify = cómo encaja. El descubrimiento se paga una sola vez. 5
6. reverse-sdd: del repositorio al kit de reconstrucción 8 fases · scripts stdlib de solo lectura + curación humana + generación con evidencia 0-1 Inventario y curación Scripts detectan stack y agrupan commits en clusters de features; el humano fusiona, parte y descarta ruido. 2-4 5-6 ├── 00-INVENTARIO.md Arquitectura · Stack · Evolución ├── 01-ARQUITECTURA.md Componentes y flujos con [VERIFY:], versiones desde lockfiles, narrativa por eras con lecciones para la v2. ├── 03-EVOLUCION.md HUs · Criterios · Pruebas ├── 02-STACK-TECNOLOGICO.md ├── HU/ │ ├── INDICE-HU.md │ └── HU-001…HU-NNN.md ├── 04-MATRIZ-PRUEBAS.md Una HU por cluster con Gherkin; cada bug corregido se vuelve un criterio; matriz consolidada con prioridades. 7 docs/reverse-sdd/ Plan de reconstrucción Fases por dependencia + mapeo directo hacia los 5 artefactos SDD. Radiografía de Repositorios · Ecosistema de Skills └── 05-PLAN-RECONSTRUCCION.md Criterios de aceptación — fuentes en orden: 1. tests existentes · 2. commits fix · 3. validaciones en el código 6
7. arch-evaluator: seis fases hacia el veredicto del hallazgo medido a la decisión accionable · ninguna debilidad sin evidencia 0-1 Evidencia y verificación docs/arch-eval/ Grafo de dependencias + señales git; cada hallazgo se confirma en el código o se descarta como falso positivo. 2-3 Scorecard y ranking ├── analysis/ │ ├── dep_graph.{json,md} 8 atributos verde/ámbar/rojo; debilidades P1–P3 por severidad × evidencia × radio de impacto (fan-in). │ └── arch_signals.{json,md} ├── 01-INFORME-EVALUACION.md ├── adr/ 4 ADRs │ └── ADR-001…ADR-NNN.md └── 02-PLAN-MIGRACION.md Una decisión por debilidad P1: 2+ alternativas honestas, costo, reversibilidad y guardas anti-sobreingeniería. 5 Plan de migración Fase 1 = guardas en CI; fases reversibles con “Done” medible (ciclos 3→0) y rollback. Radiografía de Repositorios · Ecosistema de Skills P1 exige evidencia determinista: un ciclo, un par de cocambio o un hotspot — no una opinión. 7
8. arch-evaluator: evidencia determinista primero Dos scripts miden lo que la lectura de código solo puede opinar dep_graph.py arch_signals.py • Grafo de módulos: imports Python (AST) y TS/JS • Ciclos de dependencia (Tarjan/SCC) — rojo directo • Fan-in / fan-out / inestabilidad por módulo • Candidatos a god-module y módulos huérfanos • Acoplamiento temporal: archivos que cambian juntos cruzando módulos → frontera ficticia • Hotspots ponderados: toques × (1 + fixes) • Archivos con fixes recurrentes → síntomas de diseño • Bus factor por módulo (autor dominante ≥ 90%) P1 8 5–12 exige evidencia determinista atributos en el scorecard debilidades: rango útil Radiografía de Repositorios · Ecosistema de Skills 8
9. Del hallazgo a la acción — sin sobreingeniería Hallazgo métrica de los scripts → Verificación ¿real o falso positivo? → Scorecard 8 atributos: verde/ámbar/rojo → ADR 2+ alternativas honestas → Plan fases reversibles Guardas anti-sobreingeniería (no negociables) • Un monolito que funciona vale más que módulos pequeños rotos — nunca partir sin mostrar la costura que el grafo soporta. • Sin microservicios sin justificar equipo y operación: la complejidad distribuida se paga todos los días. • Solo abstraer lo que demostrablemente varía (dos implementaciones reales) — nada “por flexibilidad”. • Preferir la solución aburrida: una regla de lint que enforce la frontera antes que el rewrite estructural. • Todo ADR defiende “no hacer nada” con seriedad; si sobrevive, se reclasifica. Radiografía de Repositorios · Ecosistema de Skills 9
10. code-audit: calidad y seguridad en 8 dimensiones DRY · SOLID · tests unit/integración · SAST · SCA · secretos · contenedores — herramientas reales, nunca simuladas 0 Stack + matriz de gaps docs/code-audit/ detect_stack.py identifica el stack (FastAPI/Nest/Next/Go…) y qué dimensiones ya tienen tooling configurado vs cuáles faltan. 1-2 Matriz de herramientas + DRY/SOLID/tests Correr la matriz real del stack y guardar salidas crudas; umbrales de duplicación, 15 señales SOLID grep-ables y smells de tests. 3 Informe y remediación ├── analysis/ │ ├── stack.json · gaps.md │ └── salidas de herramientas ├── 01-INFORME-AUDITORIA.md ├── 02-PLAN-REMEDIACION.md └── .pre-commit-config.yaml Scorecard de 8 dimensiones, hallazgos P1–P3 con [TOOL:]/[VERIFY:], y fixes con esfuerzo (S/M/L) y verificación re-ejecutable. 4 Gate pre-commit por stack Plantilla que replica el gate CuidaSalud: secretos, lint, tipos, SAST ligero en <30s — lo lento (Trivy, cobertura) va al CI. Radiografía de Repositorios · Ecosistema de Skills Severidad = riesgo, no ruido de lint: 400 warnings de estilo + 1 secreto expuesto = 1 hallazgo P1. Reusa docs/arch-eval/ si existe. 10
11. spec-driven-design: especificar la próxima versión los 5 artefactos para cada nueva versión — insumos de la radiografía listos · specs como código vivo que evoluciona con el repo 1 PRD — el qué specs/ Requisitos con criterios verificables y Out of Scope explícito; insumo: HUs + lecciones de evolución. 2 API Spec — el contrato ├── prd/feature.md Un frontend integra sin preguntar; todos los errores con código; insumo: flujos de 01-ARQUITECTURA. ├── technical/ ├── api/feature-api-v1.md │ └── feature-arch.md ├── data-model/ 3 Tech Design — el cómo │ └── feature-schema.md └── plans/feature-phase-1.md Decisiones con alternativas documentadas; incorpora los ADRs aceptados del diagnóstico. 4-5 Data Model + Plan Cada índice ligado a una query crítica (dinero en Decimal, nunca float); fases con “Done” verificable. Radiografía de Repositorios · Ecosistema de Skills Profundidad proporcional al riesgo: de “solo el ticket” (bugfix) a los 5 documentos (servicio nuevo). 11
12. Playbook: radiografía en 8 pasos Prompts secuenciales listos para pegar — con el humano en el loop donde importa 0 2 4 6 Preparación Indexar con graph-first-context (repos grandes) Curación de clusters HUMANO: fusionar / partir / descartar ruido Diagnóstico y auditoría arch-evaluator + code-audit: informes, ADRs, remediación Especificación de la nueva versión spec-driven-design: los 5 artefactos con insumos listos 1 3 5 7 Evidencia bruta reverse-sdd Fase 0: scripts, sin documentos aún HUs y pruebas Gherkin desde tests y fixes + matriz consolidada Revisión adversarial HUMANO: aceptar/rechazar ADRs, defender “no hacer nada” Cierre Resumen ejecutivo + volcado al vault de Obsidian La curación (2) y la revisión adversarial (5) son lo que separa una radiografía de una alucinación bien formateada. Radiografía de Repositorios · Ecosistema de Skills 12
13. Portafolio: radiografía de múltiples repositorios Pasos 0–5 por repo (una sesión por repo) + una consolidación final Scorecards comparados Tabla de atributos entre repos: dónde el portafolio es fuerte y dónde sistemáticamente débil. Acoplamiento entre repos Contratos duplicados y fixes correlacionados a ambos lados de una integración = frontera rota entre sistemas. Radiografía de Repositorios · Ecosistema de Skills Debilidades sistémicas Un patrón que se repite en 2+ repos no es un problema del repo: es una práctica del equipo. Plan maestro Qué repo se ataca primero (riesgo × valor), dependencias de orden y decisión por repo: evolucionar / reconstruir / congelar / fusionar. 13
14. De auditoría puntual a prevención continua Línea base versionada Los JSON de analysis/ se commitean: son la foto contra la que se mide el progreso de cada fase. Cadencia con umbrales Re-ejecutar los scripts por release o mensualmente. Alarma: ciclo nuevo, par de co-cambio cruzado ≥ 0.5, hotspot nuevo en top 5. Guardas en CI Fase 1 del plan de migración: import-linter / dependency-cruiser codifican las fronteras actuales — el CI falla antes de que la arquitectura se degrade. Documentos vivos Al cerrar cada fase: ADR → “implementado” y el informe se regenera con la métrica nueva como evidencia del avance. Radiografía de Repositorios · Ecosistema de Skills 14
15. Próximos pasos 1 Instalar desde el repo /plugin marketplace add ecrespo/skills en Claude Code; bundles .skill de Releases en Desktop/Cowork. 2 Primer objetivo real Backend de CuidaSalud: el acoplamiento temporal sobre el historial de fixes de pagos iluminará las fronteras rotas. 3 Iterar Falsos positivos sistemáticos (barrel files de NestJS) → ajustar heurísticas de los scripts con datos reales. 4 Prevenir Guardas de Fase 1 en el CI y cadencia mensual: que la radiografía no vuelva a hacer falta. Nota completa con prompts: Radiografia-Repositorios-Skills.md (vault Obsidian)