Título: Gemini CLI con AGENTS.md: qué es, cómo funciona y cuándo conviene sobre Antigravity

Metadescripción: Gemini CLI con AGENTS.md automatiza tareas de código desde la terminal con contexto persistente. Descubre sus capacidades reales al 22/02/2026 y sus diferencias con Antigravity.

Resumillo: Gemini CLI con AGENTS.md convierte la terminal en un agente de código con contexto permanente del proyecto, ejecuta tareas en múltiples archivos y se integra en flujos de automatización sin intervención manual.

En 2025, Google presentó dos herramientas de desarrollo asistido por inteligencia artificial con propósitos distintos: Antigravity, un entorno de desarrollo integrado basado en VSCode con orquestación de agentes en paralelo, lanzado el 18 de noviembre de 2025; y Gemini CLI, un asistente de terminal de código abierto bajo licencia Apache 2.0. Confundir ambas es frecuente, pero la diferencia no es de calidad sino de arquitectura: operan en capas distintas del entorno de desarrollo y resuelven problemas distintos.

¿Qué es AGENTS.md y para qué sirve?

AGENTS.md es un formato abierto y estandarizado para instruir a agentes de código. Funciona como un archivo de instrucciones permanente que le indica al agente cómo comportarse dentro de un proyecto específico. Su diseño sigue la lógica de estándares como SemVer o EditorConfig: definir las reglas una sola vez y reutilizarlas en múltiples herramientas compatibles. La lista de herramientas verificadas con soporte a febrero de 2026 incluye Gemini CLI, Aider, OpenAI Codex, Cursor, GitHub Copilot, Google Jules, Factory, Kilo Code, opencode y Semgrep, entre otras (agents.md, 2026). Es importante precisar que Claude Code no integra AGENTS.md de forma nativa: su archivo de referencia es CLAUDE.md, aunque es posible referenciar AGENTS.md dentro de él mediante la sintaxis @AGENTS.md como solución manual (Anthropic, Issue #6235, 2025).

Para activar AGENTS.md en Gemini CLI, basta con crear el archivo .gemini/settings.json en la raíz del proyecto y agregar { “contextFileName”: “AGENTS.md” }. Desde ese momento, cada sesión de trabajo comienza con ese contexto cargado de forma automática, sin necesidad de repetir instrucciones manualmente.

Cómo luce un archivo AGENTS.md en la práctica

El archivo admite instrucciones tan específicas como las convenciones de código del equipo, las rutas críticas del proyecto o las herramientas permitidas. El siguiente es un ejemplo ilustrativo mínimo funcional:

# Proyecto: Mi-API (ejemplo ilustrativo)

## Convenciones
- Toda la lógica de negocio debe vivir en ViewModels.
- Usa únicamente Jetpack Compose para la interfaz gráfica; no sugieras XML.

## Restricciones
- No incluyas dependencias de pago sin aprobación previa.
- No modifiques archivos en /legacy sin aviso explícito.

Estas instrucciones también pueden referenciarse desde otros archivos del proyecto mediante la sintaxis @./ruta/archivo.md, lo que permite modularizar el conocimiento del agente de la misma forma en que se modulariza el código fuente. Para proyectos con múltiples módulos, es posible crear archivos AGENTS.md anidados en cada subdirectorio para aplicar instrucciones específicas por componente.

¿Cómo instalar y configurar Gemini CLI?

La instalación se realiza con un solo comando en la terminal. Consulta la documentación oficial de Gemini CLI para opciones adicionales de autenticación y configuración empresarial:

npm install -g @google/gemini-cli

Los pasos básicos para integrar AGENTS.md en cualquier proyecto existente son:

1. Instalar Gemini CLI y autenticarse con una cuenta de Google.
2. Crear el archivo AGENTS.md en la raíz del proyecto con las convenciones del equipo, la arquitectura del sistema y las restricciones del proyecto.
3. Agregar { “contextFileName”: “AGENTS.md” } en .gemini/settings.json.
4. Opcionalmente, crear habilidades especializadas en .gemini/skills/[nombre]/SKILL.md para flujos de trabajo complejos.
5. Registrar el archivo AGENTS.md en el sistema de control de versiones para que todo el equipo comparta el mismo contexto desde el primer día.

¿Qué trae la versión 0.29.0 de Gemini CLI?

La versión estable más reciente, lanzada el 17 de febrero de 2026, introdujo cambios sustanciales. El primero es que Gemini 3 es ahora el modelo predeterminado para todos los usuarios sin configuración adicional. El segundo es el Modo Plan en estado experimental: mediante el comando /plan, el agente entra en un entorno de solo lectura que bloquea cualquier modificación de archivos mientras el desarrollador explora el proyecto, valida supuestos y diseña la estrategia de implementación. Una vez construido el plan, puede editarse activamente con la herramienta replace antes de ejecutar los cambios, lo que lo diferencia funcionalmente de un simple modo de vista previa (geminicli.com, 2026). El tercero es la incorporación de burbujas de pensamiento en línea con modos de resumen y visualización completa, que permiten seguir el razonamiento interno del agente en tiempo real. El cuarto es la mejora de sub-agentes, transicionados a formato XML con definiciones más explícitas. Por último, el Modo Plan soporta habilidades de agente, lo que permite personalizar el enfoque de planificación por tipo de tarea.

Habilidades de agente: personalización modular

Más allá de AGENTS.md, Gemini CLI soporta habilidades de agente: conjuntos de instrucciones especializadas que se cargan únicamente cuando la tarea lo requiere. El agente solo conoce el nombre y la descripción de cada habilidad hasta que la tarea activa su contenido completo, lo que mantiene el contexto eficiente y evita sobrecargar el espacio de trabajo. La jerarquía de precedencia es clara: las habilidades del espacio de trabajo tienen prioridad sobre las del perfil de usuario, que a su vez superan a las de extensiones instaladas. Consulta la guía de inicio de habilidades de agente para configurar las primeras en menos de diez minutos.

En el Modo Plan, las habilidades de agente pueden activarse para guiar las fases de investigación, diseño y planificación según el tipo de proyecto, lo que convierte a Gemini CLI en una plataforma extensible con comportamiento predecible y adaptable al contexto de cada equipo.

Gemini CLI frente a Antigravity: herramientas para propósitos distintos

El blog oficial de Google Cloud documentó en febrero de 2026 la distinción central: elige Antigravity cuando se necesita gestión visual de agentes, orquestación de tareas en paralelo y un entorno de desarrollo integrado completo; elige Gemini CLI cuando se necesita automatización desde la terminal, integración con sistemas de entrega continua y flujos no interactivos. La elección no depende de cuál herramienta es superior, sino de qué problema necesita resolver el equipo.

Limitaciones documentadas que deben considerarse

Ninguna de las dos herramientas está exenta de problemas en producción a la fecha de esta publicación. Ambas siguen en etapas tempranas de madurez y la comunidad ha documentado fallas en canales oficiales.

• Gemini CLI: La extensión de VSCode solo admite espacios de trabajo de una sola carpeta (Issue #6209, sin resolver a 22/02/2026); el agente de terminal no tiene esta limitación documentada. El Modo Plan es experimental y puede evolucionar en próximas versiones. Requiere conectividad constante a internet.
• Google Antigravity: En vista previa pública desde su lanzamiento, con bloqueos de cuota reportados incluso por usuarios activos. Requiere migración completa del entorno de desarrollo. El precio gratuito actual corresponde a la fase de vista previa y Google ha señalado que la estructura de cobro cambiará al lanzamiento oficial.
• Ambas herramientas: El procesamiento ocurre en la infraestructura de Google en ambos casos. Los equipos con requisitos de seguridad estrictos deben evaluar las ediciones empresariales de Gemini Code Assist, que incluyen certificaciones de cumplimiento documentadas.

¿Cuándo conviene Gemini CLI sobre Antigravity?

Gemini CLI tiene ventajas claras en escenarios donde la automatización, la integración con sistemas externos y la portabilidad son prioritarias:

• Flujos de entrega continua: Se puede invocar directamente desde scripts y sistemas de automatización mediante la acción oficial de GitHub Actions, algo que Antigravity no documenta.
• Trabajo sin cambiar el entorno: La extensión de VSCode permite usar Gemini CLI sin abandonar el entorno de desarrollo actual ni migrar configuraciones.
• Contexto compartido entre herramientas compatibles: Un solo archivo AGENTS.md en el repositorio alimenta a todas las herramientas que lo soportan de forma nativa —entre ellas Gemini CLI, Aider, Codex, Cursor y GitHub Copilot— sin instrucciones duplicadas. Para Claude Code, es necesario referenciar el archivo manualmente desde CLAUDE.md.
• Ejecución no interactiva: Mediante los parámetros –yolo y –prompt, es posible invocar tareas de forma automática sin intervención del desarrollador, útil para revisiones masivas de código.
• Código auditado: Al ser código abierto bajo licencia Apache 2.0, cualquier equipo puede inspeccionar, modificar y distribuir la herramienta, lo que facilita la auditoría de seguridad interna. El repositorio oficial incluye la hoja de ruta pública del proyecto.