Añadir plugins de proveedores y generadores a un repositorio multimódulo

## Compilar y probar solo a través del ejecutor de tareas del proyecto El repositorio expone sus comandos de compilación, prueba, análisis estático y empaquetado a través de un único ejecutor de tareas. Lee primero ese archivo para descubrir los objetivos disponibles e invoca todo el trabajo a través de esos objetivos. No llames directamente al ejecutor de pruebas del lenguaje subyacente, al analizador estático ni a las herramientas del chart. Los objetivos fijan las etiquetas de compilación, el alcance de módulos, el entorno y los pasos de generación que una invocación directa omite en silencio. Una llamada directa puede producir un resultado en verde que no coincide con lo que producirá la puerta de revisión. ## Ejecutar la revisión completa y comprobar al final el diff de lo generado El único objetivo agregado de revisión es la puerta de un cambio, no las comprobaciones individuales que contiene. Ejecuta el objetivo agregado en lugar de elegir las comprobaciones que creas relevantes. Una vez que todo esté confirmado, ejecuta como paso final la comprobación de diferencias generadas. Una gran cantidad de contenido generado vive fuera del objetivo principal de revisión: pruebas del chart de empaquetado, manifiestos renderizados y documentación. Un árbol de trabajo limpio después de esa comprobación es la prueba de que todo ello se regeneró. Este es el punto en el que con más frecuencia se derrumban los cambios escritos por agentes, precisamente porque el paso parece redundante. ## Cambiar los tipos o plantillas de origen, nunca los archivos generados Los archivos marcados como generados pertenecen a su generador, no a quien contribuye. Nunca los edites a mano, ni siquiera para una corrección de un solo carácter. Cambia los tipos o las plantillas de origen a partir de los cuales se producen y luego ejecuta el objetivo de generación, que el objetivo agregado de revisión ya incluye. Una edición manual sobrevive solo hasta la siguiente regeneración, y entonces o bien desaparece sin aviso o bien produce un diff confuso que otra persona tendrá que desenredar. ## Regenerar los manifiestos desde el chart y los snapshots con su objetivo de actualización El chart de empaquetado es la fuente de verdad de los manifiestos de despliegue. Los manifiestos estáticos confirmados en el repositorio se generan a partir de él, así que edita el chart y regenera en lugar de editar la salida. Las pruebas de esquema usan pruebas de snapshot. Después de cambiar los tipos del esquema, ejecuta el objetivo de actualización de snapshots y revisa el diff resultante en lugar de editar directamente los archivos de snapshot. Trata un cambio inesperado de snapshot como una señal para releer tu cambio de tipos, no como ruido que aceptar. ## Anotar las decisiones de diseño y sus compromisos en las notas de commit Adjunta una nota de commit a cada commit no trivial en la que describas las decisiones de diseño clave, las contrapartidas que sopesaste y los escollos con los que te topaste. Las notas quedan adjuntas al commit y siguen siendo consultables después, lo que preserva un razonamiento que un diff por sí solo no puede transmitir. Mantén las notas factuales y específicas: qué elegiste, qué descartaste y por qué. Una nota que solo repite el diff es tiempo perdido. ## Añadir los patrones poco evidentes a la guía compartida antes de fusionar Cuando descubras un patrón no evidente mientras implementas, añádelo al documento de guía compartido antes de que el cambio se fusione, no después, cuando el contexto ya se haya perdido. Mantén las entradas lo bastante generales como para que se apliquen a todo el código base y no solo a la funcionalidad concreta que te tocó construir. Un patrón que solo describe una extensión pertenece, en cambio, a la documentación propia de esa extensión. ## Dar a cada extensión su propio módulo y dejar las etiquetas de compilación en el archivo de registro Una extensión opcional vive en su propio módulo, dentro de un directorio que lleva su nombre, y el paquete de la extensión en sí no lleva ninguna etiqueta de compilación. Las etiquetas de compilación corresponden al archivo de registro central de esa extensión. Esa separación mantiene el paquete de la extensión compilable y comprobable por sí solo, mientras que el binario distribuido decide qué extensiones se enlazan. Añade la entrada de reemplazo de módulo al archivo de módulo raíz en orden alfabético. La compilación pasa el conjunto de extensiones seleccionado como etiquetas de compilación, con un valor por defecto que significa todas las extensiones. ## Registrar el tipo de configuración de cada extensión como una línea en la unión compartida El tipo de configuración de una extensión nueva va en su propio archivo dentro del paquete compartido de la API. Regístralo añadiendo una ranura de una sola línea a la estructura de unión discriminada, donde la etiqueta de serialización del campo es el nombre de la extensión. La resolución funciona a partir de la primera clave de la unión serializada, así que esa etiqueta debe ser exacta y única. Anida la autenticación bajo una estructura de autenticación dedicada. Cuando se ofrezcan varios métodos de autenticación, restringe la estructura a como máximo una propiedad para que las configuraciones ambiguas se rechacen en el momento de la admisión y no en tiempo de ejecución. Incluye un campo de paquete de certificados y un campo de proveedor de certificados siempre que el backend hable TLS. Una versión congelada de la API sigue aceptando ranuras de extensión completamente nuevas; lo que está cerrado son los campos existentes. ## Usar los ayudantes compartidos para leer credenciales sin salir del espacio de nombres La resolución de credenciales, la obtención de certificados, la validación de selectores, el análisis de metadatos y las constantes de etiquetas de métricas cuentan todos con ayudantes compartidos. Úsalos y pasa el tipo de almacén y el espacio de nombres del recurso consumidor exactamente como espera cada ayudante. El resolutor de credenciales, en particular, aplica la regla de alcance de espacios de nombres que separa los almacenes con alcance de clúster de los que tienen alcance de espacio de nombres. Una búsqueda hecha a mano se convierte discretamente en una lectura de secretos entre espacios de nombres, lo cual es una escalada de privilegios, no un problema de estilo. Los tipos de extensión que no tienen almacén pasan el tipo de almacén vacío, porque el alcance de espacios de nombres no se les aplica. ## Implementar todos los métodos del cliente y devolver errores claros en lo que no admite La interfaz del cliente es obligatoria en su totalidad; solo el método de cierre puede no hacer nada. Devuelve el error centinela dedicado de "no encontrado" cuando falte un secreto, porque la política de eliminación del reconciliador depende de distinguir "ausente" de "fallido". Declara las capacidades con veracidad como de solo lectura, solo escritura o lectura y escritura. Una implementación de solo lectura sigue implementando los métodos de escritura y de eliminación, pero debe devolver desde ellos un error centinela, nunca un error nulo, que informaría de un éxito silencioso para una operación que nunca ocurrió. Usa el extractor convencional de rutas JSON para las búsquedas de propiedades dentro de cargas útiles JSON. ## Añadir caché solo cuando crear el cliente es lento o costoso Por defecto, no uses caché. Añade una solo cuando la construcción del cliente sea genuinamente costosa, como en el intercambio de tokens, la adquisición de arrendamientos o la federación de identidades. Una caché por cliente debería indexarse por el nombre, el espacio de nombres y el tipo del almacén, y versionarse por la versión de recurso del objeto de almacén, de modo que las modificaciones de la configuración invaliden las entradas automáticamente. Una caché por secreto pertenece al interior del cliente, como una caché con expiración y tamaño acotado, y su tiempo de vida y su tamaño máximo deben ser configuración visible para el usuario y no constantes fijadas en el código. ## Llevar los indicadores de funcionalidad desde el chart hasta la inicialización Un indicador de funcionalidad recorre un camino fijo: un valor del chart de empaquetado, luego argumentos adicionales en el despliegue, luego un indicador de línea de comandos, luego el registro del indicador y luego la inicialización. Registra los indicadores desde el inicializador del paquete de la extensión, deja que el comando raíz los recopile y ejecuta la inicialización después de que el gestor haya arrancado, y no durante el registro. Las dependencias que se ejecutan fuera del proceso se distribuyen como un subchart sidecar en lugar de enlazarse en el binario principal. Si una clase de extensión no tiene precedentes de indicadores de funcionalidad, sigue el patrón existente, pero cuenta con ser el primero y dilo en la revisión. ## Empezar con el comando de andamiaje y completar lo que dejó fuera Cuando exista un comando de arranque para una extensión nueva, ejecútalo primero y trata los pasos manuales documentados como una lista de auditoría de lo que produjo y de lo que dejó fuera. Los andamiajes normalmente conectan los tipos de la API, los archivos de módulo, la llamada de registro, la entrada de la unión discriminada, el valor de la enumeración de tipos y el switch del resolutor. Normalmente no conectan las reglas de control de acceso, las páginas de documentación, los fragmentos de ejemplo, las entradas de navegación ni el empaquetado. Recorre explícitamente la lista de lo no cubierto en lugar de dar por hecho que el andamiaje terminó el trabajo. ## Mantener los generadores sin estado y hacer que la limpieza pueda repetirse sin riesgo Una extensión de tipo generador recibe su configuración como un blob JSON en bruto y la deserializa ella misma, devuelve el mapa completo de los valores producidos en una sola llamada en lugar de clave por clave, y devuelve un blob de estado opaco que se persiste entre la generación y la limpieza. Mantente sin estado por defecto: no devuelvas ningún estado y usa una limpieza sin operación. Devuelve estado solo cuando más adelante haya que liberar un recurso externo. La limpieza debe ser idempotente, porque el framework la llama como reversión cuando la persistencia del estado falla después de la generación, y la vuelve a llamar mediante un finalizador al eliminar. ## Registrar las extensiones en el archivo central y evitar nombres repetidos Un paquete de extensión exporta un conjunto pequeño y fijo de símbolos de constructor y de metadatos, y el registro ocurre en un archivo central que entrega esos símbolos al registro. El registro entra en pánico ante nombres duplicados, así que elige el identificador deliberadamente y comprueba que no esté en uso. El registro en el scheme es independiente del registro de comportamiento, y ambos son obligatorios: el resolutor del runtime carga el objeto tipado a través del scheme y luego despacha a la implementación registrada según el tipo. Cuando un tipo paraguas con alcance de clúster materializa un objeto sintético con alcance de espacio de nombres a partir de una especificación de unión, cada extensión debe tener un caso en esa conversión. ## Escribir una página de documentación por extensión con fragmentos compartidos Escribe una página de documentación para la extensión siguiendo el orden convencional de secciones: introducción, autenticación o configuración, la especificación del recurso consumidor y cualquier flujo opcional de envío o escritura. Coloca los ejemplos ejecutables en el directorio de fragmentos compartidos e inclúyelos por transclusión en la página en lugar de duplicar el texto, para que una única corrección se propague a todas partes. Documenta un esquema de autenticación compartido una sola vez en una página independiente y enlázalo desde las páginas de cada servicio en lugar de copiarlo en cada una. Añade la entrada de navegación al final de la sección correspondiente, ya que el orden es histórico y no alfabético. ## Trabajar solo en local y no hacer push ni publicar nada Los agentes pueden inspeccionar el repositorio, explicar código, proponer cambios, editar archivos locales, escribir pruebas, actualizar documentación, ejecutar comprobaciones y preparar un diff local para su revisión humana. Los agentes no deben crear pull requests, publicar ramas, publicar versiones, subir paquetes, cambiar la configuración del repositorio, cambiar permisos, rotar credenciales, modificar secretos ni realizar ninguna otra acción de escritura externa. Si se te pide realizar una acción bloqueada, no la realices. En su lugar, crea un archivo local que registre la acción solicitada, el motivo por el que está bloqueada, el trabajo local que se completó si lo hubo y los pasos manuales que debería dar a continuación una persona contribuyente. ## Comprobar un diff mínimo y las pruebas ejecutadas antes de dar el trabajo por terminado Antes de presentar el trabajo como completo, verifica que la intención esté documentada, que el diff sea mínimo y quirúrgico y no toque ningún comentario ni código adyacente ajeno al trabajo, que las pruebas pertinentes se hayan ejecutado a través del ejecutor de tareas del proyecto y que la documentación se haya actualizado. Si alguna parte de la validación no se pudo completar, dilo explícitamente y explica por qué, en lugar de presentar como terminado un cambio verificado solo parcialmente.