Mapa de Arquitectura y Contribución
Usa esta página cuando un cambio sea más grande que un error tipográfico y no estés seguro de qué documentos de arquitectura, base, colaborador o mantenedor aplican.
Esta página es solo un mapa. Los archivos enlazados siguen siendo la fuente de verdad.
Empieza aquí
- Lee primero el archivo
AGENTS.mden la raíz del repositorio. Contiene el contrato compacto de seguridad y contribución que siempre debe cargarse. - Consulta Cómo contribuir para conocer la mecánica de los PR, las expectativas de validación y el proceso de revisión.
- Utiliza las tablas siguientes para elegir los documentos de arquitectura y fundamentos que coincidan con el cambio.
- Consulta las directrices para agentes de programación cuando una tarea de programación con IA requiera ejemplos detallados de fuente de verdad, políticas de riesgo y estabilidad, descubrimiento de habilidades o documentos operativos protegidos.
- Si el cambio cruza los límites de subsistema, configuración, seguridad, flujo de trabajo, gobernanza o publicación, consulta el proceso de RFC antes de implementarlo.
Rutas de cambio comunes
| Cambiar | Leer primero | Por qué |
|---|---|---|
| Nuevo proveedor | Descripción general de la arquitectura, Crates, Proveedores personalizados, Configuración del proveedor | Los proveedores son adaptadores de borde detrás del trait de proveedor, con la configuración y el cableado de la fábrica. |
| Selección de perfiles de proveedor, rutas de modelos, anulaciones de sesión, cambio de modelo en tiempo de ejecución, reintento, reserva o atribución del proveedor | Ciclo de vida del enrutamiento de proveedores, Enrutamiento, Configuración del proveedor | Mantén la selección de rutas, la política de intentos, la construcción de perfiles y la atribución de lo solicitado frente a lo servido en sus respectivas capas responsables. |
| Análisis de flujos del proveedor, terminación o reproducción a nivel de turno | Ciclo de vida del enrutamiento de proveedores, Streaming, Pruebas | Mantén la finalización a nivel de cable en el adaptador y la repetición de la llamada completa en el entorno de ejecución. Nunca repitas después de que la salida inmutable del evento sea visible. |
| Nuevo canal | Descripción general de la arquitectura, Crates, Ciclo de vida del runtime del canal, Descripción general de los canales, implementaciones existentes en crates/zeroclaw-channels/ | Los canales son límites de confianza visibles para el usuario; valide el comportamiento de entrada, salida, emparejamiento, autorización, despacho y ciclo de vida de respuesta. |
| Despacho de canales, entrada de webhook, intención de respuesta, borradores en streaming, ciclo de vida del listener o comportamiento de recarga del canal | Ciclo de vida del runtime del canal, Ciclo de vida de la solicitud, API HTTP de Gateway, Protocolo de plugins, Pruebas | Los cambios del ciclo de vida del canal necesitan un único envío y una ruta de ejecución, en lugar de mini-orquestadores puntuales del adaptador o la pasarela. |
| Nueva herramienta integrada o política de herramientas | Descripción general de herramientas, Inventario de herramientas integradas, Ciclo de vida de ejecución de herramientas, ADR-004: Propiedad del estado compartido de la herramienta, Protocolo de plugins, Descripción general de seguridad, Recibos de herramientas | Las herramientas ejecutan acciones para el agente. Primero comprueba si la capacidad pertenece al núcleo; luego valida el registro, la aprobación, el despacho, la auditoría, los recibos, la localización, la atribución y la propiedad del estado compartido. |
| Tiempo de ejecución, bucle de agente, estado, transmisión de tokens del proveedor o comportamiento del bucle de herramientas | Ciclo de vida de la solicitud, Estado de ejecución y persistencia, Ciclo de vida de ejecución de herramientas, Crates, FND-001, Pruebas | Los cambios en tiempo de ejecución suelen afectar a múltiples rutas de usuario y necesitan pruebas a nivel de límites. La transmisión de tokens del proveedor sigue siendo propiedad del tiempo de ejecución; la transmisión de borradores de canal o indicadores de escritura sigue la fila del ciclo de vida del canal. Los cambios en el bucle de herramientas deben indicar si afectan a la aprobación, la distribución, los acuses de recibo, los eventos del observador, el historial o la cancelación. |
| Comportamiento de cron, SOP, delegación, subagente, modo objetivo, espera, cancelación o recuperación por reinicio | Ciclo de vida del trabajo en segundo plano, Delegación y subagentes, Pruebas | La ejecución en segundo plano no es un único ciclo de vida. Identifica el propietario actual y las superficies de estado, distingue los registros duraderos del trabajo reanudable tras el reinicio, y verifica la cancelación y la recuperación en el límite modificado. |
| Memoria, historial de sesión, contexto del prompt, resultados de herramientas, cargas útiles de archivos/multimedia o recorte de contexto | Memoria y ciclo de vida de la carga útil, Estado en tiempo de ejecución y persistencia, Gestión del historial, Internos del runtime, Pruebas | Los cambios de payload necesitan un propietario, alcance, durabilidad, privacidad y límites de truncamiento claros. |
| Registro de eventos, observabilidad, persistencia de trazas en tiempo de ejecución, paginación de registros, retención o migración de esquemas | Arquitectura del registro, Registros y observabilidad, Estado del tiempo de ejecución y persistencia, API HTTP de Gateway, Descripción general de la seguridad, Pruebas | Un único evento canónico se ofrece de forma independiente a la transmisión en directo y al JSONL persistido; una proyección tipada opcional de Observer solo se ejecuta cuando está vinculada. Verifica los campos de la proyección, el ciclo de vida del cursor del archivo activo, el comportamiento de reescritura y retención, la compatibilidad de migración y la privacidad en el destino modificado. |
| Comportamiento de Gateway, API web o panel de control | API HTTP del Gateway, Creación del panel web, Ciclo de vida de la solicitud, Descripción general de seguridad, Guía del revisor | Los cambios de Gateway pueden afectar la autenticación, la exposición pública, los contratos de API generados, los consumidores del dashboard y el riesgo de revisión. Usa la fila del ciclo de vida del canal para el despacho de webhooks o el comportamiento de respuesta. |
| Comportamiento visible para el usuario o evidencia de validación para un comando, terminal, daemon, navegador, canal, proveedor, herramienta, trabajo en segundo plano o ruta de instalación | Prueba de límites de usuario, Pruebas y el documento de arquitectura o características de la superficie modificada | Relaciona cada afirmación sobre el comportamiento con la prueba creíble más pequeña que alcance el límite en el que el usuario lo observa. Añade evidencia manual o específica del entorno únicamente para una carencia explícitamente identificada en la cobertura automatizada. |
| Esquema de configuración, variables de entorno, valores predeterminados o comportamiento de recarga | Ciclo de vida de la configuración, Variables de entorno, Estado en tiempo de ejecución y persistencia, Configuración del proveedor, FND-001, Proceso RFC | Los cambios de configuración afectan las rutas de actualización, el comportamiento de recarga, los límites de la fuente de verdad y pueden requerir migración o discusión de RFC. |
| Referencias generadas, preprocesadores de mdBook, fragmentos de documentación o despliegue de documentación | Pipeline de documentación generada, Compilar la documentación localmente y Ciclo de vida de la configuración cuando cambian las referencias de configuración | Nombra la fuente canónica, el materializador, la salida versionada o exclusiva de la compilación, el consumidor y la comprobación de desviaciones. |
| Catálogos Fluent/gettext, registro de configuraciones regionales, respaldo de traducción o fijaciones de versión de catálogos | Ciclo de vida del catálogo de localización, Documentación y traducciones, Canalización de documentación generada | Que haya un catálogo en el repositorio no demuestra que un entorno de ejecución o la compilación del sitio lo consuma. Verifica la ruta de carga, materialización o fijación. |
| CI, release, GitHub Actions o acciones permitidas | CI y Actions, FND-004, PR workflow | Los cambios de infraestructura son de alto riesgo cuando alteran qué código se puede ejecutar o lanzar. |
| Estructura de la documentación, guía para colaboradores u organización del conocimiento | FND-002, Documentación y traducciones, esta página | Los cambios en la documentación deben reducir el costo de búsqueda y preservar el registro de decisiones. |
| Gobernanza, etiquetas, flujo de trabajo del tablero o proceso de contribución | FND-003, Proceso RFC, Etiquetas, Manual del revisor | Los cambios de proceso afectan a los mantenedores y colaboradores; manténgalos duraderos y explícitos. |
| Cultura de contribución, sustitución o revisión asistida por IA | FND-005, PR de sustitución, protocolo de revisión de PR | El trabajo asistido por IA es bienvenido, pero el patrocinador humano es responsable de la precisión, la atribución y la respuesta a las revisiones. |
| Estado del código de producción, gestión de errores o limpieza de código muerto | FND-006, Testing, AGENTS.md en la raíz del repositorio | La disciplina en el manejo de errores, el código sin usar y la preparación para producción son criterios de revisión, no preferencias de estilo. |
Documentos fundamentales en una sola pantalla
| Foundation | Leer cuando el cambio solicita… |
|---|---|
| FND-001: Arquitectura intencional | ¿Esto encaja con la dirección de microkernel/runtime? ¿Qué capa debería ser responsable de ello? |
| FND-002: Estándares de documentación | ¿Dónde debería residir el conocimiento? ¿Cómo deberían mantenerse los documentos navegables y duraderos? |
| FND-003: Gobernanza | ¿Quién decide? ¿Qué etiquetas, tablero de proyecto o proceso de RFC debe contener el estado? |
| FND-004: Infraestructura de ingeniería | ¿Cómo deberían comportarse CI, la automatización de versiones o GitHub Actions? |
| FND-005: Cultura de contribución | ¿Cómo deben comunicarse y revisar el trabajo los colaboradores, los mantenedores y el trabajo asistido por IA? |
| FND-006: Cero concesiones en la práctica | ¿Qué estándar de calidad se aplica al código de producción, los errores, el código muerto y la preparación para el lanzamiento? |
Puntos de entrada del agente de codificación
Los agentes de codificación deben usar la misma documentación pública que los humanos, además de los contratos de agente locales del repositorio.
- Sigue el
AGENTS.mdde la raíz del repositorio. Inspecciona.claude/skills/*/SKILL.mdy usa la habilidad correspondiente del repositorio cuando sea aplicable; el archivo de habilidades es la fuente de autoridad. - Trata los documentos fundacionales como contexto de decisión. Explican por qué una revisión puede solicitar una división, un RFC, una validación más sólida o un propietario diferente.
- Mantén los mecanismos internos del flujo de trabajo fuera de los cuerpos de PR públicos, los comentarios de issues y las revisiones. El texto público debe citar comportamiento concreto, rutas de origen, comandos, evidencia de validación, issues vinculados y riesgo visible para el usuario.
- Si un borrador generado o creado mediante una skill entra en conflicto con el código fuente, el
AGENTS.mdactual o un documento de fundamentación ratificado, deténgase y resuelva la discrepancia antes de publicarlo o implementarlo.
Puntos de Control de RFC y PR
Este mapa no reemplaza el proceso de RFC ni la plantilla de PR; solo te ayuda a encontrar el documento correcto. El proceso de RFC contiene la tabla canónica de “¿esto tiene forma de RFC?”, así que consúltala en lugar de adivinar a partir de una lista reformulada aquí. Después de que se promuevan los segmentos de política del RFC #6808, sigue FND-003, Labels, PR workflow y Reviewer playbook.
- Si un cambio es ambiguo pero no tiene claramente la forma de un RFC, consulta a un maintainer o acota el PR antes de implementarlo.
- Antes de abrir un PR, responde las preguntas de la plantilla de PR (
.github/pull_request_template.md). Si esas respuestas no están claras, escribe primero la nota de diseño o el RFC.