clanker25/ai

Habilidad ADR

Filosofía

Los ADR creados con esta habilidad son especificaciones ejecutables para agentes de codificación. Un humano aprueba la decisión; un agente la implementa. El ADR debe contener todo lo que el agente necesita para escribir el código correcto sin hacer preguntas de seguimiento.

Esto significa:

• Las restricciones deben ser explícitas y medibles, no sensaciones
• Las decisiones deben ser lo suficientemente específicas para actuar ("usar PostgreSQL 16 con pgvector", no "usar una base de datos")
• Las consecuencias deben asignarse a tareas de seguimiento concretas
• Los no objetivos deben establecerse para evitar la ampliación del alcance
• El ADR debe ser autónomo, sin suposiciones de conocimiento tribal
• El ADR debe incluir un plan de implementación: qué archivos tocar, qué patrones seguir, qué pruebas escribir y cómo verificar que la decisión se implementó correctamente

Cuándo Escribir un ADR

Escriba un ADR cuando una decisión:

• Cambia la forma en que se construye o opera el sistema (nueva dependencia, patrón de arquitectura, elección de infraestructura, diseño de API)
• Es difícil de revertir una vez que se ha escrito código en su contra
• Afecta a otras personas o agentes que trabajarán en este código base más adelante
• Tiene alternativas reales que fueron consideradas y rechazadas

NO escriba un ADR para:

• Elecciones de implementación rutinarias dentro de un patrón establecido
• Correcciones de errores o correcciones tipográficas
• Decisiones ya capturadas en un ADR existente (actualícelo en su lugar)
• Preferencias de estilo ya cubiertas por linters o formateadores

En caso de duda: si un agente futuro que trabaje en este código base se beneficiaría al saber por qué se tomó esta elección, escriba el ADR.

Disparadores Proactivos de ADR (Para Agentes)

Si usted es un agente que codifica en un repositorio y se encuentra con alguna de estas situaciones, deténgase y proponga un ADR antes de continuar:

• Está a punto de introducir una nueva dependencia que aún no existe en el proyecto
• Está a punto de crear un nuevo patrón arquitectónico (nueva forma de manejar errores, nueva capa de acceso a datos, nueva convención de API) que otro código deberá seguir
• Está a punto de elegir entre dos o más alternativas reales y las compensaciones no son obvias
• Está a punto de cambiar algo que contradice un ADR aceptado existente
• Se da cuenta de que está escribiendo un comentario de código largo explicando "por qué" — ese razonamiento pertenece a un ADR

Cómo proponer: Dígale al humano qué decisión ha encontrado, por qué es importante y pregúntele si quiere capturarla como un ADR. Si es así, ejecute el flujo de trabajo completo de cuatro fases. Si no, anote la decisión en un comentario de código y continúe.

Creación de un ADR: Flujo de Trabajo de Cuatro Fases

Cada ADR pasa por cuatro fases. No omita fases.

Fase 0: Escanear el Código Base

Antes de hacer cualquier pregunta, recopile contexto del repositorio:

1. Encuentre ADR existentes. Verifique contributing/decisions/, docs/decisions/, adr/, docs/adr/, decisions/ en busca de registros existentes. Léalos. Tome nota de:

   • Convenciones existentes (directorio, nomenclatura, estilo de plantilla)
   • Decisiones que se relacionan o restringen la actual
   • Cualquier ADR que esta nueva decisión pueda reemplazar

2. Verifique la pila tecnológica. Lea package.json, go.mod, requirements.txt, Cargo.toml o equivalente. Tome nota de las dependencias y versiones relevantes.

3. Encuentre patrones de código relacionados. Si la decisión involucra un área específica (por ejemplo, "cómo manejamos la autenticación"), busque implementaciones existentes. Identifique los archivos, directorios y patrones específicos que se verán afectados por la decisión.

4. Verifique referencias de ADR en el código. Busque referencias de ADR en comentarios y documentos (consulte "Vinculación entre Código ↔ ADR" a continuación). Esto revela qué decisiones existentes rigen qué partes del código base.

5. Tome nota de lo que encontró. Lleve este contexto a la Fase 1; agudizará sus preguntas y evitará que el ADR contradiga decisiones existentes.

Fase 1: Capturar la Intención (Socrática)

Entreviste al humano para comprender el espacio de la decisión. Haga preguntas una a la vez, basándose en respuestas anteriores. No descargue una lista de preguntas.

Preguntas principales (haga aproximadamente en este orden, omita lo que ya esté claro por el contexto o la Fase 0):

1. ¿Qué está decidiendo? — Obtenga un título corto y específico. Insista en una frase verbal ("Elegir X", "Adoptar Y", "Reemplazar Z con W").
2. ¿Por qué ahora? — ¿Qué se rompió, qué está cambiando o qué se romperá si no hace nada? Este es el desencadenante.
3. ¿Qué restricciones existen? — Pila tecnológica, cronograma, presupuesto, tamaño del equipo, código existente, cumplimiento normativo. Sea concreto. Haga referencia a lo que encontró en la Fase 0 ("Veo que ya está usando X, ¿eso limita esto?").
4. ¿Cómo se ve el éxito? — Resultados medibles. Vaya más allá de "funciona" hacia aspectos específicos (latencia, rendimiento, experiencia del desarrollador, carga de mantenimiento).
5. ¿Qué opciones ha considerado? — Al menos dos. Para cada una: ¿cuál es la compensación principal? Si solo tienen una opción, ayúdelos a articular por qué se rechazaron las alternativas.
6. ¿Cuál es su inclinación actual? — Capture la intuición visceral temprano. A menudo revela prioridades no declaradas.
7. ¿Quién necesita saber o aprobar? — Tomadores de decisiones, expertos consultados, partes interesadas informadas.
8. ¿Qué necesitaría un agente para implementar esto? — ¿Qué archivos/directorios se ven afectados? ¿Qué patrones existentes debe seguir? ¿Qué debe evitar? ¿Qué pruebas demostrarían que funciona? Esto alimenta directamente el Plan de Implementación.

Preguntas de seguimiento adaptativas: Según las respuestas, profundice donde la decisión sea confusa. Preguntas de seguimiento comunes:

• "¿Cuál es el peor resultado posible si esta decisión es incorrecta?"
• "¿Qué le haría reconsiderar esto en 6 meses?"
• "¿Hay algo que esté explícitamente eligiendo NO hacer?"
• "¿A qué arte anterior o patrones existentes en el código base se relaciona esto?"
• "Encontré [ADR/patrón existente] — ¿esta nueva decisión interactúa con él?"

Cuándo detenerse: Tiene suficiente cuando puede completar cada sección del ADR, incluido el Plan de Implementación, sin inventar nada. Si está adivinando alguna sección, haga otra pregunta.

Puerta de Resumen de Intención: Antes de pasar a la Fase 2, presente un resumen estructurado de lo que capturó y pida al humano que lo confirme o corrija:

Esto es lo que estoy capturando para el ADR:

• Título: {título}
• Desencadenante: {por qué ahora}
• Restricciones: {lista}
• Opciones: {opción 1} vs {opción 2} [vs ...]
• Inclinación: {qué opción y por qué}
• No objetivos: {qué está explícitamente fuera del alcance}
• ADR/código relacionados: {qué existe con lo que esto interactúa}
• Archivos/áreas afectados: {dónde aterriza esto en el código base}
• Verificación: {cómo sabremos que se implementó correctamente}

¿Captura esto su intención? ¿Algo que añadir o corregir?

NO pase a la Fase 2 hasta que el humano confirme el resumen.

Fase 2: Redactar el ADR

1. Elija el directorio de ADR.

   • Si existe uno (encontrado en la Fase 0), utilícelo.
   • Si no existe ninguno, cree contributing/decisions/ (si existe contributing/), docs/decisions/ (valor predeterminado de MADR) o adr/ (repositorios más simples).

2. Elija una estrategia de nombre de archivo.

   • Si los ADR existentes usan prefijos de fecha (YYYY-MM-DD-...), continúe con eso.
   • De lo contrario, use nombres de archivo solo con slug (choose-database.md).

3. Elija una plantilla.

   • Use assets/templates/adr-simple.md para decisiones sencillas (un ganador claro, compensaciones mínimas).
   • Use assets/templates/adr-madr.md cuando necesite documentar múltiples opciones con pros/contra/impulsores estructurados.
   • Consulte references/template-variants.md para obtener orientación.

4. Complete cada sección a partir del resumen de intención confirmado. No deje texto de marcador de posición. Cada sección debe contener contenido real o eliminarse (solo secciones opcionales).

5. Escriba el Plan de Implementación. Esta es la sección más importante para los ADR centrados en el agente. Le dice al siguiente agente exactamente qué hacer. Consulte la plantilla para la estructura.

6. Escriba los criterios de Verificación como casillas de verificación. Estos deben ser lo suficientemente específicos para que un agente pueda verificar cada uno programáticamente o manualmente.

7. Genere el archivo.

   • Preferido: ejecute scripts/new_adr.js (maneja el directorio, el nombre y las actualizaciones opcionales del índice).
   • Si no puede ejecutar scripts, copie una plantilla de assets/templates/ y complétela manualmente.

Fase 3: Revisar Según la Lista de Verificación

Después de redactar, revise el ADR con la lista de verificación de preparación para el agente en references/review-checklist.md.

Presente la revisión como un resumen, no como un volcado de lista de verificación sin procesar. Formato:

Revisión de ADR

✅ Aprobado: {liste lo que es sólido — por ejemplo, "el contexto es autónomo, el plan de implementación cubre los archivos afectados, los criterios de verificación son comprobables"}

⚠️ Brechas encontradas:

• {brecha específica 1 — por ejemplo, "El Plan de Implementación no menciona los archivos de prueba: ¿qué conjunto de pruebas debería cubrir esto?"}
• {brecha específica 2}

Recomendación: {Enviarlo / Arreglar las brechas primero / Necesita más trabajo en la Fase 1}

Solo muestre fallas y fortalezas notables; no recite cada casilla de verificación aprobada.

Si hay brechas, proponga correcciones específicas. No solo señale problemas, ofrezca soluciones y pida al humano que las apruebe.

No finalice hasta que el ADR pase la lista de verificación o el humano acepte explícitamente las brechas.

Consultar ADR (Flujo de Trabajo de Lectura)

Los agentes deben leer los ADR existentes antes de implementar cambios en un código base que los tenga. Esto no es parte del flujo de trabajo de creación de un ADR; es una operación independiente que cualquier agente debe realizar.

Cuándo Consultar ADR

• Antes de comenzar a trabajar en una función que toque la arquitectura (autenticación, capa de datos, diseño de API, infraestructura)
• Cuando se encuentre con un patrón en el código y se pregunte "¿por qué se hace así?"
• Antes de proponer un cambio que pueda contradecir una decisión existente
• Cuando un humano diga "consulta los ADR" o "hay una decisión sobre esto"
• Cuando encuentre una referencia de ADR en un comentario de código

Cómo Consultar ADR

1. Encuentre el directorio de ADR. Verifique contributing/decisions/, docs/decisions/, adr/, docs/adr/, decisions/. También verifique si hay un archivo de índice (README.md o index.md).

2. Analice los títulos y estados. Lea el índice o enumere los nombres de archivo. Concéntrese en los ADR accepted — estas son decisiones activas.

3. Lea los ADR relevantes por completo. No solo lea el título, lea el contexto, la decisión, las consecuencias, los no objetivos Y el Plan de Implementación. El Plan de Implementación le dice qué patrones seguir y qué archivos rige esta decisión.

4. Respete las decisiones. Si un ADR aceptado dice "use PostgreSQL", no proponga cambiar a MongoDB sin crear un nuevo ADR que lo reemplace. Si encuentra un conflicto entre lo que hace el código y lo que dice el ADR, notifíquelo al humano.

5. Siga el Plan de Implementación. Al implementar código en un área regida por un ADR, siga los patrones especificados en su Plan de Implementación. Si el plan dice "todas las nuevas consultas pasan por la capa de acceso a datos en src/db/", hágalo.

6. Haga referencia a los ADR en su trabajo. Agregue referencias de ADR en los comentarios de código y las descripciones de PR (consulte "Vinculación entre Código ↔ ADR" a continuación).

Vinculación entre Código ↔ ADR

Los ADR deben estar vinculados bidireccionalmente al código que rigen.

ADR → Código (en el Plan de Implementación)

La sección del Plan de Implementación nombra archivos, directorios y patrones específicos:

## Plan de Implementación

- **Rutas afectadas**: `src/db/`, `src/config/database.ts`, `tests/integration/`
- **Patrón**: todas las consultas de base de datos pasan por `src/db/client.ts`

Código → ADR (en comentarios)

Al implementar código guiado por un ADR, agregue un comentario que haga referencia a él:

// ADR: Usar better-sqlite3 para la base de datos de prueba
// Ver: docs/decisions/2025-06-15-use-sqlite-for-test-database.md
import Database from 'better-sqlite3';

Manténgalos livianos: un comentario en el punto de entrada, no en cada línea. El objetivo es la capacidad de descubrimiento: cuando un agente futuro lea este código, pueda encontrar el razonamiento.

Por Qué Esto Es Importante

• Un agente que trabaje en src/db/ puede encontrar qué ADR rigen esa área
• Un agente que lea un ADR puede encontrar el código que lo implementa
• Cuando un ADR es reemplazado, las referencias de código facilitan la búsqueda de todo el código que necesita actualización

Otras Operaciones

Actualizar un ADR Existente

1. Identifique la intención:

   • Aceptar / rechazar: cambie el estado, agregue cualquier contexto final.
   • Desaprobar: estado → deprecated, explique la ruta de reemplazo.
   • Reemplazar: cree un nuevo ADR, vincule ambos sentidos (antiguo → nuevo, nuevo → antiguo).
   • Agregar aprendizajes: añada a ## Más Información con una marca de fecha. No reescriba la historia.

2. Use scripts/set_adr_status.js para cambios de estado (admite front matter YAML, estado de viñeta y estado de sección).

Ciclo de Vida Posterior a la Aceptación

Después de que se acepte un ADR:

1. Cree tareas de implementación. Cada elemento en el Plan de Implementación y cada seguimiento en Consecuencias debe convertirse en una tarea rastreable (problema, ticket o TODO).
2. Haga referencia al ADR en los PR. Enlace al ADR en las descripciones de PR, por ejemplo, "Implementa contributing/decisions/2025-06-15-use-sqlite-for-test-database.md."
3. Agregue referencias de código. Agregue comentarios con la ruta del ADR en los puntos clave de implementación.
4. Verifique los criterios de verificación. Una vez que la implementación esté completa, revise las casillas de verificación de Verificación. Actualice el ADR con los resultados en ## Más Información.
5. Revisite cuando se activen los disparadores. Si el ADR especificó condiciones de revisión ("si ocurre X, reconsiderar"), supervise esas condiciones.

Índice

Si el repositorio tiene un archivo de índice/registro de ADR (a menudo README.md o index.md en el directorio de ADR), manténgalo actualizado.

Preferido: deje que scripts/new_adr.js --update-index lo haga. De lo contrario:

• Agregue una entrada de viñeta para el nuevo ADR.
• Mantenga el orden consistente (numérico si están numerados; por fecha o alfabético si son slugs).

Arranque

Al introducir ADR en un repositorio que no tiene ninguno:

node /path/to/adr-skill/scripts/bootstrap_adr.js

Esto crea el directorio, un archivo de índice y un primer ADR completo ("Adoptar registros de decisiones de arquitectura") con contenido real que explica por qué el equipo está usando ADR. Use --json para salida legible por máquina. Use --dir para anular el nombre del directorio.

Categorías (Proyectos Grandes)

Para repositorios con muchos ADR, organice por subdirectorio:

docs/decisions/
  backend/
    2025-06-15-use-postgres
  frontend/
    2025-06-14-use-nextjs
  infra/
    2025-06-13-use-aws

Actualice el índice de cada subdirectorio por separado. Cada subdirectorio debe tener su propio archivo index.md o README.md.

Referencias

• assets/templates/ — Plantillas de ADR (simple, MADR)
• assets/templates/adr-simple.md — Para decisiones sencillas con un ganador claro
• assets/templates/adr-madr.md — MADR con opciones estructuradas, pros/contra
• references/template-variants.md — Guía para elegir entre plantillas
• references/review-checklist.md — Lista de verificación de preparación para el agente
• scripts/new_adr.js — Script para crear nuevos ADR (gestión de directorios, nomenclatura, índice)
• scripts/set_adr_status.js — Script para cambiar el estado del ADR
• scripts/bootstrap_adr.js — Script para arrancar una práctica de ADR