ai-agent-rules

AI Rules es una herramienta de línea de comandos para mantener la configuración de varios agentes de codificación de IA en una única ubicación rastreada por git y enlazarla al directorio de configuración esperado de cada agente mediante enlaces simbólicos. El objetivo declarado es "editar una vez, aplicar en todas partes", permitiendo aún la personalización por agente y por máquina. Agentes compatibles y sus directorios de configuración: - Amp: ~/.config/amp/ (habilidades en ~/.config/agents/skills/) - Claude Code: ~/.claude/ (habilidades en ~/.claude/skills/) - Codex CLI: ~/.codex/ (habilidades en ~/.agents/skills/) - Gemini CLI: ~/.gemini/ (descubre habilidades a través de ~/.agents/skills/) - Goose: ~/.config/goose/ (habilidades en ~/.config/goose/skills/) - Material compartido como AGENTS.md y habilidades La instalación requiere Python 3.10+ y uv. La ruta recomendada es una configuración de un solo comando desde PyPI (uvx --from ai-agent-rules ai-agent-rules setup), que instala enlaces simbólicos, hace disponible el comando ai-agent-rules (y el alias ai-rules) en todo el sistema y opcionalmente instala herramientas auxiliares. Una bandera --github instala desde la rama principal en su lugar, y el desarrollo local usa uv run ai-agent-rules install. Un comando upgrade verifica e instala actualizaciones, con banderas para solo verificación, forzar, omitir la instalación posterior a la actualización o actualizar solo una herramienta específica. Los comandos principales cubren configuración, instalación/sincronización, estado e inspección, configuración, exclusiones y anulaciones, habilidades, herramientas y completado de shell. Comportamientos notables: - install admite seleccionar agentes específicos, vistas previas de prueba, confirmación automática, reconstrucciones de caché y selección de perfil. - status informa el estado de los enlaces simbólicos, herramientas opcionales y el perfil activo con símbolos de estado y diferencias; validate verifica que los archivos fuente existan; uninstall elimina enlaces simbólicos. - config init/show/edit expone configuraciones crudas o fusionadas, opcionalmente por agente. - exclude add/remove/list gestiona patrones glob para archivos que no deben enlazarse simbólicamente (por ejemplo, archivos gestionados por la empresa). - override set/unset/list edita configuraciones anidadas, incluida la notación de índice de matriz para estructuras como matrices de comandos de hooks, con validación de ruta que sugiere claves válidas en errores tipográficos. - skill list/show renderiza habilidades incluidas, puede imprimir una URL de GitHub versionada para compartir o emitir markdown crudo para canalizar. - tool list/show y tool source get/set gestionan herramientas opcionales y su fuente de instalación (pypi, github, ruta local, restablecer). - completions install/uninstall/update/status y salida de script bash/zsh crudo se proporcionan. La configuración está en capas. Un archivo a nivel de usuario en ~/.ai-agent-rules-config.yaml contiene exclusiones y anulaciones de configuración específicas de la máquina. El estado (perfil activo, marca de tiempo de última instalación) reside en ~/.ai-agent-rules/state.yaml, y las configuraciones fusionadas se almacenan en caché bajo ~/.ai-agent-rules/cache/. El pipeline de fusión documentado es: configuraciones base rastreadas por git, luego anulaciones de perfil, luego anulaciones de usuario, luego campos gestionados por el agente preservados fusionados desde la caché, luego almacenamiento en caché, luego enlace simbólico al directorio del agente. Los campos preservados incluyen enabledPlugins y hooks de Claude, extensions de Goose, projects de Codex e ide de Gemini. Cambiar anulaciones requiere ejecutar install --rebuild-cache. Los perfiles agrupan anulaciones en ajustes preestablecidos con nombre y admiten herencia; tres perfiles integrados se incluyen con la herramienta con la cadena default -> personal -> work, donde default se describe como genérico y personal/work como ajustes preestablecidos del autor en lugar de recomendaciones generales. Los perfiles pueden definir anulaciones de configuración, plugins, marketplaces, fuentes de instalación de herramientas gestionadas, fragmentos de AGENTS.md (agents_md_file, añadidos padre-primero a través de herencia, mutuamente excluyentes con agents_md en línea), exclusiones y anulaciones de MCP. La configuración local del usuario tiene prioridad sobre las anulaciones de perfil. Los archivos de perfil definidos por el usuario no se admiten actualmente; la personalización por máquina va en el archivo de configuración del usuario. Los servidores MCP se definen una vez en un mcps.json compartido y cada gestor de agente los traduce a formatos nativos (JSON para Amp, Claude, Gemini; TOML para Codex; extensiones YAML para Goose). Las entradas gestionadas llevan un marcador _managedBy para distinguirlas de los servidores añadidos por el usuario, y mcp_overrides permiten valores por máquina como claves API. Los plugins de Claude Code pueden declararse en perfiles o configuración de usuario; install añade marketplaces y plugins faltantes, desinstala automáticamente plugins gestionados previamente huérfanos y advierte sobre los instalados manualmente sin eliminarlos. El estado del plugin se rastrea en un archivo JSON gestionado. Las características de seguridad incluyen advertencias de primera ejecución, copias de seguridad con marca de tiempo, indicaciones interactivas, modo de prueba, una afirmación de que solo se gestionan enlaces simbólicos y los archivos reales nunca se eliminan, y mensajes de error contextuales. La guía de solución de problemas cubre objetivos incorrectos, restauración de copias de seguridad, desactivación de un enlace simbólico mediante exclusión, reconstrucción de la caché cuando las anulaciones no se aplican, visualización de configuraciones fusionadas y migración automática desde rutas de configuración anteriores a v0.35. El proyecto tiene licencia MIT.