Trazabilidad
Cada regla apunta a un ADR por identidad estable y ruta relativa, preservando el origen de la restricción.
Estudio de caso arquitectónico · proyecto de código abierto
De la decisión arquitectónica a la verificación continua
Un ADR puede explicar por qué El dominio no debe depender de la infraestructura. El próximo desafío es detectar, con evidencia verificable, cuando la implementación no respeta esta decisión.
Este es un escenario de repositorio reproducible, no un reclamo de adopción de producción o certificación de arquitectura completa.
Problema
La documentación preserva el razonamiento; no preserva por sí sola la dependencia.
A medida que el software evoluciona, una referencia agregada por conveniencia puede alterar un límite planificado. El ADR sigue siendo aceptado y legible, mientras que el gráfico del código real cuenta otra historia.
Las consecuencias aparecen después: las reglas de dominio comienzan a conocer la persistencia, las pruebas requieren infraestructura y un cambio técnico atraviesa capas que deberían evolucionar por separado. El problema no es la falta de documentación, sino la distancia entre la decisión, la evidencia y el feedback.
Restricciones y atributos de calidad
La verificación debe ser útil sin afirmar más de lo que permite la evidencia.
Determinismo
La misma entrada debe producir una clasificación, huella digital, resultado e informe estables.
Falla segura
La evidencia ausente, dinámica o ambigua produce unknown, nunca una aprobación implícita.
Compatibilidad
Deriva, impacto y validación tienen sus propios contratos sin cambiar los formatos ya publicados.
AuditabilidadSeguridadReproducibilidadOperabilidadCapacidad de evoluciónCompatibilidad
Decisiones arquitectónicas
Cuatro responsabilidades, cuatro preguntas diferentes.
Validación estructural de ADR
adr-guard check verifica metadatos, secciones, referencias, ciclo de vida y otros contratos documentales. Un ADR válido todavía no prueba que el código lo cumpla.
Análisis de impacto
adr-guard impact correlaciona los archivos modificados con asignaciones locales explícitas. El resultado indica decisiones potencialmente afectadas para su revisión; no declara cumplimiento o violación.
Detección de drift
adr-guard drift evalúa reglas opt-in asociadas con ADR vigentes. La v1 solo comprueba referencias estáticas exactas entre proyectos y consume pruebas externas reportadas.
Núcleo compartido, interno
AdrGuard.Core se centra en el análisis, la validación, el inventario de Git, el impacto y la deriva para CLI y MCP. No es un paquete público independiente; La interfaz de usuario y el transporte permanecen en los ejecutables.
El vocabulario de resultados preserva la incertidumbre
pass
La evidencia determinista completa prueba la condición declarada.
violation
La evidencia determinista completa demuestra que la condición es falsa.
unknown
La evidencia es insuficiente, ausente, dinámica, condicional, inválida o contradictoria.
not-applicable
El ADR referenciado no está vigente según la política de ciclo de vida configurada.
Componentes y contratos
Una regla compartida, diferentes superficies.
- CLIComandos, códigos de salida, texto, JSON/SARIF y escritura explícita.
- AdrGuard.CoreReglas deterministas internas y límites de entrada.
- Acción de GitHubEjecuta la CLI y publica informes dentro del contrato de acción.
- VS CodeExploración, edición, diagnósticos y ejecución de la CLI como proceso.
- Servidor MCPSiete herramientas de solo lectura, transporte stdio y límite del workspace.
- HumanoAprueba ADR, selecciona reglas y revisa los cambios de referencia.
MCP no aprueba decisiones; la revisión mediante IA es opcional y advisory. La acción compuesta existente no incorpora implícitamente un modo de drift: la guía instala la herramienta e invoca el comando en un paso explícito.
Implementación reproducible
Dominio sin referencia a Infraestructura, hasta el cambio que introduce la deriva.
1. Registre la decisión
El ADR aceptado establece: "El proyecto de Dominio no debe hacer referencia al proyecto de Infraestructura". La consecuencia reconoce que las referencias condicionales o expandidas dinámicamente requieren revisión humana.
2. Configurar la regla
{
"schemaVersion": "1.0",
"rules": [{
"id": "domain-no-infrastructure",
"decision": {
"stableId": "ADR-1",
"path": "docs/adr/0001-protect-domain-boundary.md"
},
"scope": { "projects": [
"src/Domain/Domain.csproj",
"src/Infrastructure/Infrastructure.csproj"
]},
"check": {
"type": "forbid-project-reference",
"from": "src/Domain/Domain.csproj",
"to": "src/Infrastructure/Infrastructure.csproj"
},
"evidence": { "source": "dotnet-project-reference" },
"failure": { "severity": "error", "onInconclusive": "unknown" },
"gate": true
}]
}3. Verificar la implementación inicialmente conforme
(
cd docs/examples/architectural-drift
adr-guard drift . --rules .adrguard-fitness.json --format json
)
# Resultado documentado por el fixture: passEl Domain.csproj versionado contiene únicamente el SDK y el target framework. El conjunto estático completo no contiene la dependencia prohibida.
4. Introducir la referencia prohibida
<ItemGroup>
<ProjectReference Include="../Infrastructure/Infrastructure.csproj" />
</ItemGroup>Cuando reemplaza el proyecto con el accesorio infractor y repite el comando, el informe identifica la referencia y la línea como violation.
(
cd docs/examples/architectural-drift
adr-guard drift . --rules .adrguard-fitness.json \
--write-baseline drift-baseline.json
)
# Revise la línea base antes de confirmarla5. Aplicar la política sin borrar matices
| Ejecución | Comportamiento documentado | lo que no significa |
|---|---|---|
--policy advisory | Política estándar; registra la infracción sin utilizar la regla como bloqueo de aplicación. | No convierte la violación en éxito. |
--policy enforce | Una violación nueva, gate: true, local y determinista devuelve el código de salida 4. | No bloquea toda falla externa ni toda violación ya registrada en la línea base. |
Resultado unknown | Devuelve la salida 3 en ambas políticas y no puede aparecer como una marca de verificación verde. | No se convierte en violation. |
| evidencia externa | Mantiene la procedencia como observación reportada. | No es una atestación y nunca autoriza el bloqueo automático. |
6. Arreglar y revalidar
(
cd docs/examples/architectural-drift
adr-guard drift . --rules .adrguard-fitness.json \
--baseline drift-baseline.json
)
# Violación anterior: resolved
# Regla actual: passLa línea base solo se crea o reemplaza mediante un comando explícito y debe revisarse como código. Al eliminar la referencia prohibida se restablece pass; al compararla con una línea base que contenía el finding, el historial aparece como resolved.
Alternativas y compensaciones
El diseño elige pruebas limitadas en lugar de inferencias amplias.
Revisión manual
Es indispensable para interpretar decisiones y excepciones, pero puede no detectar drift repetitivo en cada pull request.
Cuándo usarla: reglas sin representación determinista o decisiones contextuales.
Pruebas arquitectónicas específicas
Pueden analizar código con mayor profundidad, pero requieren implementación y mantenimiento por pila. ADR Guard sólo puede consumir el resultado como evidencia externa informada.
Cuando usar: invariantes más allá del contrato estático v1.
Evaluar MSBuild
Resolvería más referencias condicionales, pero ejecutaría una superficie compleja y potencialmente poco confiable. v1 deliberadamente no invoca MSBuild.
Elección: las condiciones y propiedades permanecen unknown.
Línea base automática
Reduciría la fricción inmediata, pero podría normalizar una regresión. La creación y actualización son acciones explícitas del responsable.
Elección: historia auditable en lugar de aceptación silenciosa.
Limitaciones y riesgos
El informe verifica una regla declarada, no toda la arquitectura.
v1 solo inspecciona ProjectReference estático y exacto en archivos .csproj incluido explícitamente en el alcance. Las importaciones, los comodines, las propiedades, las condiciones, los archivos faltantes, el XML inseguro y los límites excedidos no son concluyentes. No hay descubrimiento de red ni ejecución arbitraria.
Una regla mal formulada puede ser determinista y aun así tergiversar la ADR. La cobertura parcial, las excepciones legítimas y los cambios en el ciclo de vida siguen requiriendo una gobernanza humana. pass significa que esa condición ha sido probada bajo ese contrato, no que la solución haya recibido una certificación amplia.
Aprendizajes y evolución
Hacer que las decisiones sean ejecutables comienza con hacer explícitos los límites.
La separación entre control, impacto y deriva impide que “documento válido”, “cambio relacionado” y “restricción violada” sean tratados como sinónimos. El vocabulario de los cuatro estados evita que la falta de pruebas se convierta en cumplimiento.
La extracción del Core reduce la divergencia entre CLI y MCP sin crear una nueva API pública. La evolución puede agregar nuevas comprobaciones versionadas, siempre que preserve la procedencia, la incertidumbre, la compatibilidad y la autoridad humana sobre la decisión y la línea de base.
Evidencias y referencias
Documentos auditables, fixtures e implementación disponibles en el repositorio.
Ejemplo reproducibleADR, manifiestos, proyectos conformes, infractores y no concluyentes.
Contrato de reglas de fitness v1Esquema, resultados, políticas, línea base y límites de seguridad.
Comprobador de referencia del proyectoImplementación de resultados deterministas y no concluyentes.
Acción de GitHubContrato real, entradas, permisos y ejemplos de CI.
Servidor MCPHerramientas, esquemas y límites de solo lectura del workspace.
Extensión de VS CodeIntegración editorial y diagnósticos respaldados por la CLI.
Código fuenteCLI, Core, pruebas, documentación e historial del proyecto.