Directrices para agentes de programación

El AGENTS.md en la raíz del repositorio es el contrato compacto, siempre cargado, para los asistentes de codificación con IA. Esta página proporciona detalles útiles para algunas tareas, pero no debería consumir el presupuesto de contexto de cada sesión.

Estas reglas se aplican independientemente del tamaño del modelo o de dónde se ejecute el modelo. Los perfiles de prompt compactos pueden cambiar cuánto contexto se carga de forma anticipada; no debilitan los requisitos de seguridad, privacidad, autorización o contribución.

Cómo usar esta página

Comienza con el mapa de arquitectura y contribuciones. Su tabla de rutas de cambios dirige cada tarea hacia la documentación actual de arquitectura, fundamentos, pruebas, seguridad y mantenimiento. Regresa aquí solo para los temas específicos de agentes que se indican a continuación.

Ejemplos de fuente única de verdad

Ninguna parte del estado debe residir en dos lugares mantenidos de forma independiente. Si un dato ya existe en la configuración, el esquema, el estado de ejecución o una definición generada, resuélvelo o derívalo de esa fuente en lugar de copiarlo en otro campo.

Antes de agregar un campo de struct, un campo de canal o de handle, un campo de esquema o una entrada de configuración, indica una de estas respuestas:

1. “Esta es la fuente de verdad, creada aquí.” Indica qué representa.
2. “La fuente de verdad es <path>; esto la duplicaría.” Resuélvela desde esa ubicación en el momento de usarla.

No difiera la limpieza del estado duplicado para un seguimiento posterior. Una instantánea de solo reinicio sigue siendo estado duplicado.

Ejemplos prohibidos:

• un manejador de canal que almacena en caché a los usuarios autorizados mientras la configuración en vivo los gestiona;
• una enumeración y una lista de variantes mantenida a mano por separado;
• una instantánea de configuración que clona campos que el runtime puede leer desde la configuración activa;
• copiar una credencial de proveedor en otro campo de tiempo de ejecución.

Ejemplos permitidos:

• resolver de cierres sobre Arc<RwLock<Config>>;
• Config prestado o parámetros de configuración tipados;
• vistas bajo demanda que no se almacenan más allá de la operación;
• macros o generadores que emiten varias superficies a partir de una sola entrada.

Arquitectura y propiedad

ZeroClaw es un runtime de agentes orientado a Rust y basado en traits. Los traits de extensión principales se encuentran en crates/zeroclaw-api/src/:

• model_provider.rs (ModelProvider)
• channel.rs (Channel)
• tool.rs (Tool)
• memory_traits.rs (Memory)
• observability_traits.rs (Observer)
• runtime_traits.rs (RuntimeAdapter)
• peripherals_traits.rs (Peripheral)

No mantengas aquí otro inventario de crates o repositorios. Usa Crates para consultar la propiedad y la dirección de las dependencias, los miembros del espacio de trabajo en el Cargo.toml raíz para la composición actual y el mapa de arquitectura para las rutas de cambio de proveedores, canales, herramientas, plugins, tiempo de ejecución y configuración.

Estabilidad y riesgo

Las definiciones de los niveles de estabilidad y la política de versiones se encuentran en FND-001. Los archivos AGENTS.md locales de cada componente y los manifiestos del registro de plugins son el modelo de propiedad objetivo. Hasta que cada componente tenga uno, la tabla a continuación es la fuente canónica para las asignaciones actuales; no la copie en otro agregado mantenido manualmente.

Asignaciones de estabilidad actuales

Los componentes estables siguen la política de cambios incompatibles. Los componentes beta pueden introducir cambios incompatibles en una versión MINOR con notas en el registro de cambios. Los componentes experimentales no ofrecen ninguna garantía de estabilidad. Los niveles se promueven, nunca se degradan, mediante una decisión deliberada del equipo.

El enrutamiento según el riesgo de cambio se basa en las consecuencias, no en las rutas. Usa la guía de etiquetas para mantenedores para consultar las definiciones canónicas: risk:low abarca la documentación, los fixtures y los metadatos mecánicos sin ningún efecto en producción, la compatibilidad, la compilación, las publicaciones o la gobernanza; risk:medium abarca los cambios de comportamiento ordinarios; y risk:high abarca límites concretos de confianza, credenciales, compatibilidad, gobernanza o autoridad de publicación. domain:security es independiente de risk:* e identifica un límite de seguridad efectivo.

Un PR que incluya risk:high o domain:security requiere una revisión exhaustiva y dos aprobaciones independientes del Core Team antes de fusionarse. Ante la incertidumbre, clasifica al alza. Las evidencias de validación y reversión deben corresponder al radio de impacto real, no solo al número de líneas modificadas. Usa Cómo contribuir para los aspectos operativos de los PR y Pruebas para la taxonomía de validación.

Descubrimiento de habilidades

Las habilidades del asistente de programación del repositorio se encuentran en .claude/skills/. Inspecciona los archivos */SKILL.md disponibles y carga únicamente la habilidad que corresponda a la operación solicitada. No mantengas un segundo catálogo de habilidades en esta página; el directorio es el inventario actual y cada archivo de habilidad define su propio flujo de trabajo.

Documentos operativos protegidos

Estos archivos son consumidos por skills o herramientas de desarrollo. No los muevas ni elimines sin actualizar sus consumidores y la guía del repositorio.

Localización y privacidad

El texto orientado al usuario y las reglas de registro exclusivo en inglés permanecen en el AGENTS.md raíz. La Wiki y la documentación interna para desarrolladores también son exclusivamente en inglés. Para consultar los contratos completos, usa Privacy and PII discipline y Docs and translations.

Lecturas adicionales

• Mapa de arquitectura y contribución
• Cómo contribuir
• Disciplina de privacidad y PII
• Pruebas
• Descripción general de la arquitectura
• Solicitudes de extracción que reemplazan
• Política de auditoría