desarrollar-con-adr

Desarrollar con ADRs

Primer paso obligatorio: verificación de conflictos

Antes de preguntar por el dominio, crear agentes, investigar el código o hacer cambios, ejecuta el script de solo lectura incluido:

python3 <directorio-absoluto-de-la-habilidad>/scripts/check_conflicting_skills.py --project <ruta-del-repositorio>

Reemplaza los marcadores de posición con rutas reales y entrecomilla las rutas según sea necesario. Pasa cada nombre del catálogo de habilidades disponibles de la sesión con un argumento --available-skill repetido, incluyendo nombres exclusivos de la nube y calificados por plugin. Añade directorios de habilidades no estándar con --root; agrega explícitamente los destinos de los enlaces simbólicos de subdirectorios relevantes. El script descubre archivos de habilidades locales y entradas del catálogo sin cargar sus instrucciones ni cambiar instalaciones.

• Trata grill-me y spec-first como habilidades conflictivas, incluyendo variantes de mayúsculas, minúsculas, espacios, guiones bajos y guiones, como Grill Me o spec_first.
• Salida 0 significa que no se encontraron conflictos en el alcance inspeccionado. Salida 1 significa que se encontraron conflictos, no un fallo del script. Salida 2 significa que el descubrimiento fue incompleto: reporta los errores y la limitación de cobertura, resuélvelos cuando sea posible y vuelve a ejecutar. Nunca afirmes que se verificaron todas las habilidades cuando la cobertura es incompleta.
• Ante cualquier coincidencia, deshabilita su uso dentro de este flujo de trabajo y advierte al usuario en su idioma antes de continuar: nombra las habilidades detectadas y explica que están deshabilitadas solo para el flujo de trabajo actual. No impliques desinstalación global ni cambios en la configuración de la cuenta. No se requiere aprobación adicional para estas exclusiones del flujo de trabajo.
• No invoques las habilidades excluidas, sigas sus instrucciones ni delegues trabajo en ellas. Aplica la exclusión al coordinador, al arquitecto y al implementador; pasa la lista de exclusión en cada traspaso de agente. Utiliza los propios pasos de aclaración y aprobación de este flujo de trabajo.
• El script detecta conflictos; el agente coordinador aplica las exclusiones. Excluye también cualquiera de las habilidades si el catálogo de la sesión la revela incluso cuando sus archivos no son accesibles. Si el script no puede ejecutarse, reporta esa limitación y aplica las exclusiones conocidas sin afirmar un escaneo exitoso.
• Vuelve a ejecutar después de reanudar una sesión o de cambios en las habilidades disponibles. Nunca borres, renombres ni deshabilites globalmente habilidades instaladas como parte de esta verificación.

Entrada y roles

1. Antes de comenzar el flujo de trabajo, pregunta por el dominio en el que el arquitecto debe enfocarse. Acepta dominios empresariales o técnicos. Reutiliza un dominio proporcionado explícitamente sin preguntar de nuevo.
2. Crea un agente arquitecto separado para el dominio seleccionado durante toda la sesión. Proporciónale estas reglas, el dominio, la ruta del repositorio y el contexto conocido. El arquitecto debe preguntar al usuario qué problema resolver; el agente principal puede retransmitir la pregunta y la respuesta. Si el problema ya está proporcionado, pregunta solo por la información faltante.
3. El agente principal coordina el diálogo, los documentos y las transferencias de contexto. El arquitecto investiga, diseña, mantiene los ADR y verifica los resultados de forma independiente. Un agente implementador separado implementa las decisiones aprobadas y prepara la evidencia. No combines los roles de arquitecto e implementador.
4. Utiliza las capacidades nativas de agentes separados del entorno: subagentes en Codex y capacidades de agente/tarea disponibles en Claude Code. No inventes APIs ni presentes un solo agente cambiando de rol como una verificación independiente. Si los agentes separados no están disponibles, explica la limitación y pide al usuario que elija un entorno adecuado. La investigación puede continuar, pero la implementación bajo este flujo de trabajo no debe comenzar.
5. Después de una pérdida de contexto, restaura el estado a partir de documentos y código. Si es necesario crear un nuevo arquitecto, no afirmes que el agente original sobrevivió; restaura su dominio y responsabilidades.

Investigación y decisión

• El arquitecto debe leer las instrucciones del proyecto, el código, los ADR relacionados y la evidencia, y aclarar el problema y las restricciones. No crees un ADR antes de investigar el código y aclarar el problema. Si aún no existe código, registra ese hecho e investiga los materiales disponibles.
• Identifica conflictos con decisiones actuales. Primero presenta el conflicto al usuario y solicita una decisión; solo después de la respuesta prepara un nuevo ADR. El permiso para preparar un reemplazo no es una aprobación para implementarlo.
• Escribe un ADR en docs/adr/ utilizando las plantillas. Incluye una breve declaración del problema, la solución propuesta, la justificación y criterios de aceptación verificables con identificadores estables. Establece el estado inicial como accepted-for-discussion.
• Separa decisiones independientes en ADR distintos y registra explícitamente las dependencias. No introduzcas ciclos de dependencia o reemplazo.
• Presenta el ADR específico o un conjunto enumerado de ADR para la aprobación explícita del usuario de implementación. No infieras aprobación a partir del silencio, una solicitud general de construir algo o un permiso para investigar.
• Registra la respuesta del usuario, la fecha y la versión del documento aprobado. Establece accepted-for-work solo después de la aprobación explícita. Permite la aprobación explícita de un conjunto enumerado de ADR.

Implementación

• Comienza a implementar un ADR solo después de que todos los ADR de los que depende estén completados, incluso si todo el conjunto ya está aprobado.
• Proporciona al implementador el ADR, los criterios, las dependencias y las restricciones. Exige que la implementación se realice dentro del alcance de la decisión aprobada.
• Si la implementación es imposible o la decisión o los criterios deben cambiar, detén el trabajo afectado y devuelve el problema al arquitecto. El trabajo aprobado independiente puede continuar.
• Nunca cambies la descripción de la solución ni los criterios de aceptación después de la aprobación. Registra los cambios en un nuevo ADR con aprobación separada.
• El implementador debe preparar evidencia en docs/evidence/: resultados para cada criterio, comandos e instrucciones de reproducción, y el commit verificado o la versión exacta del código. No sustituyas un commit futuro por la versión probada. Para cambios no confirmados, incluye un diff guardado y los identificadores o hashes de los archivos verificados.

Verificación independiente y finalización

• El arquitecto debe ejecutar personalmente las comprobaciones y comparar los resultados reales con cada criterio de aceptación. El informe del implementador y la inspección del código no sustituyen la ejecución.
• Conserva los comandos, el entorno, los resultados, los enlaces a los registros y la versión verificada en la evidencia. Marca honestamente las comprobaciones que no se ejecutaron, fueron bloqueadas o fallaron. No completes un ADR con criterios no verificados o no cumplidos.
• Si la implementación falla la verificación pero el ADR sigue siendo válido, primero presenta los resultados y el alcance concreto de la corrección al usuario y solicita permiso. No delegues ni realices correcciones antes de la respuesta. Después del permiso, el implementador corrige el problema y el arquitecto verifica de nuevo. Otra verificación fallida requiere un nuevo permiso para el siguiente ciclo de corrección.
• Si el fallo requiere una nueva decisión de arquitectura, vuelve a la investigación y al procedimiento de nuevo ADR.
• Solo el arquitecto puede establecer completed después de la verificación independiente exitosa de cada criterio. Se requiere un enlace al documento de evidencia. No se necesita aprobación adicional del usuario para completar el ADR.

Estados y preservación del historial

Usa exactamente cuatro valores canónicos de status. Las etiquetas en ruso a continuación identifican sus significados originales; preserva el historial del proyecto existente en lugar de reescribir documentos heredados en silencio.

Status	Etiqueta original	Condición
accepted-for-discussion	принято к обсуждению	Propuesta investigada pendiente de discusión o aprobación
accepted-for-work	принято к работе	El usuario aprobó explícitamente el ADR específico
completed	завершен	El arquitecto verificó de forma independiente todos los criterios; la evidencia está enlazada
rejected	отклонено	Existe un nuevo ADR aprobado y una justificación/evidencia de rechazo

• Nunca borres ADR ni documentos de evidencia ni reutilices sus identificadores. Antes de la aprobación, permite el refinamiento del borrador mientras se registran los cambios sustanciales.
• Después de la aprobación, mantén inmutables el cuerpo de la solución y los criterios. Permite actualizaciones de estado y enlaces con entradas de historial añadidas. Conserva las entradas anteriores, la evidencia y los resultados de verificación. No sobrescribas una comprobación fallida con un resultado exitoso.
• Rechaza el ADR antiguo en el momento en que el usuario aprueba explícitamente su reemplazo para trabajar, incluso si el ADR antiguo estaba completado. Enlaza inmediatamente el ADR antiguo con su reemplazo y un documento separado de justificación de rechazo. Esto demuestra por qué se rechazó la decisión anterior; no demuestra que la nueva implementación funcione.
• Conserva la finalización anterior, su fecha, versión y evidencia. Registra explícitamente que el reemplazo puede no haber sido implementado aún. Rechazar un documento no elimina el código funcional por sí mismo.
• No rechaces un ADR sin una nueva decisión. Si el usuario no ha elegido un reemplazo, conserva el estado actual y añade una entrada de discusión. No inventes un reemplazo solo para permitir una transición de estado.
• Si una dependencia es rechazada o reemplazada, detén el trabajo afectado y pide al arquitecto que evalúe el impacto. No reconectes en silencio decisiones aprobadas.

Grafo de documentos

• Lee las plantillas antes de crear documentos y la guía de portabilidad al usar un nuevo entorno.
• Almacena los ADR como docs/adr/ADR-0001-slug-corto.md y la evidencia como docs/evidence/EVID-0001-slug-corto.md. Elige el siguiente número no utilizado teniendo en cuenta el historial existente; no renumeres documentos antiguos.
• Usa enlaces relativos explícitos de Markdown y tipos de relación: replaces / replaced_by, depends_on / required_by, extends / extended_by, y evidence / proves. Mantén los enlaces de retroceso e identifica si la evidencia demuestra la implementación o la razón del rechazo.
• Trata los ADR y la evidencia como los documentos del grafo; no es necesaria una base de datos de grafos separada. En los traspasos, verifica los destinos de los enlaces, los enlaces de retroceso, la ausencia de ciclos de dependencia y las condiciones de estado.
• Al final de cada paso, reporta el estado del ADR, el resultado, los enlaces a los documentos y la decisión específica necesaria si se está esperando al usuario. No describas trabajo meramente aprobado o implementado pero no verificado como completado.