La sesión en vivo: tu primer agente de IA en la terminal

Esta es la guía completa de la sesión en vivo, en una sola página. Vamos en cinco partes, en este orden. Síguelas de arriba abajo: cada una usa lo que dejaste listo en la anterior.

Parte 1: Qué es un agente de IA, qué es OpenCode y en qué se diferencia de un chat

Antes de instalar nada, vamos a entender qué es lo que vas a instalar. Esta es la parte de teoría del taller: sin fórmulas y sin palabras raras, pero con el porqué de cada cosa. Si te quedas con las ideas de esta página, todo lo que hagas después con las manos va a tener sentido.

En esta parte vas a entender:

1. Qué es un modelo de lenguaje (LLM) y qué puede y no puede hacer.
2. Qué es un chat y qué es un agente.
3. Qué son las "herramientas" de un agente y cómo funciona su ciclo de trabajo.
4. Qué es OpenCode, qué parte corre en tu laptop y qué parte en la nube.
5. Por qué un agente necesita reglas de permiso.

1. Qué es un modelo de lenguaje (LLM)

Un modelo de lenguaje, o LLM (de Large Language Model), es un programa que hace una sola cosa: recibe un texto y predice cómo sigue. Palabra por palabra, calcula cuál es la continuación más probable.

Piensa en el autocompletado del teclado de tu celular: escribes "nos vemos" y te sugiere "mañana". Un LLM es esa misma idea, pero entrenado con una cantidad enorme de texto, así que la continuación que predice puede ser una explicación, un correo, una receta o un programa completo.

                    +----------------------+
  "Explícame qué  ->|   Modelo de lenguaje |->  "Un CSV es un archivo
   es un CSV"       |   (predice cómo      |     de texto donde cada
                    |    sigue el texto)   |     línea es una fila..."
                    +----------------------+
       texto que entra                          texto que sale

Tres cosas importantes que se siguen de esto:

• Solo sabe dos cosas: lo que aprendió durante su entrenamiento y lo que tú le das en el momento. No ve tu computadora, no ve tus archivos, no sabe qué hora es. Si no está en su entrenamiento ni en lo que le mandas, no lo sabe.
• Puede equivocarse con toda seguridad. Como predice texto que suena correcto, a veces produce algo que suena perfecto y es falso. No miente a propósito: simplemente no tiene forma de saber que se equivocó. Por eso, a lo largo del taller, vas a comprobar lo que te diga.
• Solo produce texto. Por sí solo, un modelo no puede abrir un archivo ni ejecutar nada. Todo lo que "hace" es escribir.

Al texto que le mandas al modelo en cada petición se le llama contexto. Guarda esa palabra: aparece más abajo.

2. Qué es un chat

Un chat de IA es una página o una app que pone una caja de texto delante de un modelo. Tú escribes, el chat le manda tu mensaje al modelo, el modelo predice una respuesta y el chat te la muestra.

El trato es este: el modelo contesta con texto, y tú haces algo con ese texto. Copias el código, lo pegas en un archivo, lo corres, vuelves al chat con el error. El modelo nunca toca tu computadora.

  +-------+   1. escribes    +-------+   2. predice    +--------+
  |  Tú   | ---------------> | Chat  | --------------> | Modelo |
  |       | <--------------- |       | <-------------- |        |
  +-------+   3. lees texto  +-------+    respuesta    +--------+
      |
      |  4. TÚ copias, pegas, ejecutas y vuelves con el error
      v
  +------------------+
  | Tu computadora   |
  +------------------+

Analogía: un chat es como llamar por teléfono a un experto. Te dice qué hacer, pero las manos las pones tú.

3. Qué es un agente

Un agente usa el mismo tipo de modelo, pero le agrega dos cosas: herramientas y un ciclo.

Agente = modelo + herramientas + ciclo

Analogía: si el chat es el experto al teléfono, el agente es el experto sentado en tu escritorio, con permiso para abrir tus carpetas y usar tu computadora. Ya no te dicta los pasos: los hace él, y tú supervisas.

Qué son las herramientas

Una herramienta es una acción concreta que el programa del agente sabe hacer en tu computadora, y que el modelo puede pedir que se haga. Las más comunes:

Fíjate en un detalle importante: el modelo no ejecuta nada. El modelo sigue produciendo solo texto, pero ahora ese texto puede ser una petición del tipo "quiero leer el archivo expenses.csv". El programa del agente, que sí corre en tu computadora, recibe esa petición, hace la acción y le devuelve el resultado al modelo.

El ciclo del agente

Cuando le das un encargo, el agente repite un ciclo hasta terminar:

          +-------------------------+
          |  Tu encargo             |
          |  "¿Cuánto gasté?"       |
          +-----------+-------------+
                      |
                      v
          +-------------------------+
     +--> | 1. PIENSA               |
     |    |    ¿Qué necesito hacer? |
     |    +-----------+-------------+
     |                |
     |                v
     |    +-------------------------+
     |    | 2. USA UNA HERRAMIENTA  |
     |    |    leer, buscar,        |
     |    |    escribir, ejecutar   |
     |    +-----------+-------------+
     |                |
     |                v
     |    +-------------------------+
     |    | 3. MIRA EL RESULTADO    |
     |    |    ¿Qué encontré?       |
     |    +-----------+-------------+
     |                |
     |       ¿Ya terminé?
     |        |            |
     +--- no -+            +- sí --+
                                   v
                       +-------------------------+
                       | 4. TE RESPONDE          |
                       |    "Gastaste 385.15"    |
                       +-------------------------+

Un ejemplo real con la carpeta del taller. Le preguntas "¿cuánto gasté en septiembre?":

1. Piensa: "Necesito ver qué archivos hay."
2. Herramienta: lista la carpeta. Resultado: hay expenses.csv, notes.md y opencode.json.
3. Piensa: "Los gastos deben estar en expenses.csv."
4. Herramienta: lee expenses.csv. Resultado: 12 filas con montos.
5. Piensa: "Ya tengo los datos, sumo." Responde: te da el total.

Cada vuelta del ciclo es una petición al modelo. Por eso un solo encargo tuyo se convierte en varias peticiones, y por eso el plan gratuito de tu proveedor se mide en peticiones y no en mensajes.

Chat contra agente

La diferencia no es el modelo. Es que el agente tiene herramientas para leer y escribir en tu computadora, y un ciclo para usarlas solo.

4. Qué es OpenCode

OpenCode es un agente de programación de código abierto que corre en tu terminal, en tu laptop. "Código abierto" quiere decir que su código es público: cualquiera puede leerlo, revisarlo y usarlo gratis.

Aquí está la confusión más común, así que vale la pena decirlo claro: OpenCode no es el modelo. OpenCode no "piensa". OpenCode es el programa que:

• te da la interfaz para escribirle,
• tiene las herramientas (leer, escribir, buscar, ejecutar) sobre tu carpeta,
• corre el ciclo del agente,
• y habla con un modelo que tú eliges, a través de un proveedor.

Un proveedor es la empresa que tiene los modelos corriendo en sus servidores y te da acceso a ellos por internet, a través de una API (una puerta para que un programa le hable a otro). Para entrar por esa puerta usas tu llave (API key), la que conseguiste en la preparación. En el taller el proveedor es OpenRouter, OpenCode Zen o Groq.

Analogía: OpenCode es como un control remoto universal. El control está en tu mano (tu laptop), pero la tele (el modelo) puede ser de la marca que tú escojas. Cambias de modelo sin cambiar de control.

La arquitectura completa

  TU LAPTOP                                  |  INTERNET (la nube)
                                             |
  +-------------+      +------------------+  |  +-------------------+
  |     Tú      | <--> |     OpenCode     |  |  |  Proveedor (API)  |
  | (terminal)  |      | - interfaz       | <-->|  OpenRouter, Zen, |
  +-------------+      | - herramientas   |  |  |  Groq             |
                       | - ciclo          |  |  +---------+---------+
                       +--------+---------+  |            |
                                |            |   viaja con tu llave
                         lee y escribe       |            |
                                |            |            v
                                v            |  +-------------------+
                       +------------------+  |  |  Modelo (LLM)     |
                       | ~/agent-workshop |  |  |  predice el texto |
                       |  expenses.csv    |  |  +-------------------+
                       |  notes.md        |  |
                       +------------------+  |

Qué se queda en tu laptop y qué se va a la nube

La fila que más importa es la de en medio. Recuerda que el modelo solo sabe lo que le das en el contexto. Para que pueda contestar sobre expenses.csv, OpenCode tiene que mandarle el contenido de ese archivo. Es decir: todo archivo que el agente lee, sale de tu laptop y llega al proveedor.

Por eso la regla de privacidad del taller es tan concreta: con modelos gratuitos, trabaja solo con datos de ejemplo. Varios modelos gratuitos usan lo que reciben para mejorar sus modelos. No abras OpenCode en una carpeta con datos personales o de tu trabajo.

Lo que aprendas hoy con OpenCode se traslada a cualquier otro agente de terminal: todos siguen esta misma arquitectura.

5. Por qué un agente necesita reglas de permiso

Un agente que puede escribir archivos y ejecutar comandos puede hacer cosas buenas muy rápido. También puede hacer cosas malas muy rápido: sobrescribir un archivo, borrar algo, correr un comando que no entendías. Y recuerda que el modelo puede equivocarse con total seguridad.

Por defecto, OpenCode edita archivos sin preguntarte. Para una primera vez eso es demasiada confianza. Por eso la carpeta de práctica trae un opencode.json con estas reglas:

{
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

• "edit": "ask": antes de crear o modificar un archivo, el agente se detiene y te pide permiso.
• "bash": "ask": antes de ejecutar un comando en la terminal, también te pide permiso.

  El modelo pide:             OpenCode revisa        Tú decides
  "escribir summary.md"  -->  opencode.json:    -->  [ Aceptar ] -> se escribe
                              edit = "ask"           [ Rechazar ] -> no pasa nada

Analogía: es como darle a alguien las llaves de tu casa, pero pidiéndole que te llame antes de mover cualquier mueble. Confías, pero verificas.

Por qué esto importa para ti

Si el agente puede escribir archivos, tu trabajo cambia de "escribir" a "pedir bien y revisar". Ese es el músculo que entrenamos hoy:

• Pedir bien: describir el qué (lo que quieres lograr), no el cómo, y decir qué no debe tocar.
• Revisar: mirar lo que el agente cambió antes de aceptarlo, y comprobar al menos un dato por tu cuenta, porque el modelo puede equivocarse con seguridad.

Para comprobar que entendiste

1. Le preguntas a un agente por un archivo de tu carpeta y te contesta correctamente. ¿El modelo "vio" tu computadora?

2. ¿Qué es OpenCode: el modelo, el proveedor o otra cosa?

3. Le haces una sola pregunta al agente y en tu cuenta del proveedor aparecen cinco peticiones. ¿Por qué?

Resumen

• Un LLM predice texto. Solo sabe lo que aprendió y lo que le das en el contexto, y puede equivocarse con seguridad.
• Un chat te da texto y tú ejecutas. Un agente es modelo + herramientas + ciclo: lee, escribe y ejecuta en tu máquina.
• OpenCode no es el modelo: es el agente que corre en tu laptop y habla con el modelo que eliges a través de un proveedor.
• Lo que el agente lee sale de tu laptop hacia el proveedor: usa datos de ejemplo.
• Las reglas de permiso ("ask") hacen que el agente te pregunte antes de escribir o ejecutar. Tu trabajo es pedir bien y revisar.

Parte 2: Instalar OpenCode y conectarlo a un modelo

Ahora sí, a la terminal. Al terminar esta parte vas a tener OpenCode instalado, conectado a un modelo y contestándote. Además vas a entender qué hace cada comando que escribes, para que no sea magia. Vamos todos al mismo paso: si algo falla, paramos aquí.

Recuerda la arquitectura de la parte anterior: OpenCode es el programa que corre en tu laptop, y el modelo vive en la nube, detrás de un proveedor. En esta parte haces tres cosas, una por cada pieza:

  Paso 1-2: instalar          Paso 3: abrir en          Paso 4-5: conectar
  el programa                 tu carpeta                con el modelo

  +-------------+            +------------------+       +-------------+
  |  OpenCode   |  ------->  | ~/agent-workshop |  ---> | Proveedor + |
  | en tu laptop|            | (dónde trabaja)  |       | modelo      |
  +-------------+            +------------------+       +-------------+

1. Instala OpenCode

Hay una forma recomendada por sistema. Usa solo la de tu sistema:

Mac y Linux (recomendado): el instalador oficial

curl -fsSL https://opencode.ai/install | bash

Por qué este: no necesita que tengas nada instalado antes. Ni Node.js, ni Homebrew. Solo la terminal.

Qué hace, pieza por pieza:

• curl es un programa que descarga cosas de internet desde la terminal. Aquí descarga un script (un archivo con una lista de comandos) desde opencode.ai/install.
• -fsSL son opciones de curl: que falle con claridad si hay un error, que no muestre la barra de progreso, y que siga redirecciones hasta el archivo real.
• | (se llama "pipe", tubería) toma lo que salió del comando de la izquierda y se lo pasa al de la derecha.
• bash es el programa que ejecuta scripts. Recibe el script descargado y lo corre: ese script descarga OpenCode y lo deja listo en tu computadora.

  +------+   descarga el script   +------+   lo ejecuta   +-------------------+
  | curl | ---------------------> |  |   | -------------> | bash              |
  +------+  desde opencode.ai     | pipe |                | instala OpenCode  |
                                  +------+                +-------------------+

Una costumbre sana: solo ejecuta curl ... | bash con direcciones oficiales en las que confíes, porque estás corriendo en tu máquina un script de internet.

Windows (recomendado): Node.js y npm

Son dos pasos:

1. Instala Node.js. Entra a nodejs.org, descarga la versión LTS e instálala con las opciones por defecto. Cuando termine, cierra la terminal y abre una nueva (más abajo explicamos por qué).
2. Instala OpenCode en PowerShell o Terminal:

npm install -g opencode-ai

Por qué este: Node.js es el programa que ejecuta aplicaciones escritas en JavaScript, y trae incluido npm, su gestor de paquetes. Con eso ya tienes todo. Por eso la página del taller pide Node 18 o superior: si no lo tienes, lo instalamos juntos en los primeros minutos.

Qué hace, pieza por pieza:

• npm (Node Package Manager) es como una tienda de aplicaciones para la terminal: descarga e instala programas publicados por sus autores.
• install le pide que instale algo.
• -g significa global: lo instala para toda tu computadora, no solo para una carpeta. Así el comando opencode funciona desde cualquier lugar.
• opencode-ai es el nombre del paquete de OpenCode en npm.

Si en alguna guía ves un $ al inicio del comando, no lo escribas: solo indica que es una terminal.

2. Verifica la instalación

Cierra la terminal, ábrela de nuevo y escribe:

opencode --version

Si ves un número de versión, funcionó.

Qué significa "command not found"

Si ves command not found (o en Windows "no se reconoce como un comando"), no es que la instalación falló. Casi siempre es esto:

Cuando escribes un comando, la terminal no busca en toda tu computadora. Busca solo en una lista de carpetas llamada PATH. Si el programa no está en alguna de esas carpetas, la terminal dice que no existe.

La terminal lee esa lista una sola vez, cuando se abre. Si instalaste OpenCode con la terminal abierta, esa terminal sigue con la lista vieja. Una terminal nueva lee la lista actualizada.

  Escribes: opencode

  La terminal busca en el PATH:
    carpeta 1  ->  ¿opencode aquí?  no
    carpeta 2  ->  ¿opencode aquí?  no
    carpeta 3  ->  ¿opencode aquí?  no
    ...
    -> "command not found"

  Terminal NUEVA (lee el PATH actualizado):
    carpeta 1  ->  no
    carpeta 2  ->  no
    carpeta de OpenCode  ->  sí  ->  lo ejecuta

Analogía: el PATH es la agenda de contactos de la terminal. Si agregaste un contacto en otro teléfono, este no lo ve hasta que se sincroniza. Abrir una terminal nueva es sincronizar.

3. Abre OpenCode dentro de tu carpeta de práctica

OpenCode trabaja sobre la carpeta donde lo abres: esa carpeta es todo lo que el agente puede ver y tocar. Por eso primero entras a agent-workshop (la creaste en tu carpeta personal) y lo abres ahí. Este comando sirve igual en Mac, Linux y PowerShell:

cd ~/agent-workshop
opencode

• cd (change directory) te mueve a una carpeta.
• ~ es un atajo para tu carpeta personal.
• opencode abre el programa en la carpeta actual.

Anatomía de la pantalla de OpenCode

Se abre una interfaz dentro de la misma terminal. Tiene tres zonas:

+----------------------------------------------------------------+
|                                                                |
|   ZONA DE CONVERSACIÓN                                         |
|                                                                |
|   Tú:     ¿Qué hay en esta carpeta?                            |
|   Agente: (lee expenses.csv)                                   |
|           Hay un registro de gastos de septiembre...           |
|                                                                |
|   Aquí ves tus mensajes, las respuestas y las herramientas     |
|   que el agente va usando.                                     |
|                                                                |
+----------------------------------------------------------------+
|  > Escribe aquí tu mensaje o un comando con /                  |  <- CAJA DE TEXTO
+----------------------------------------------------------------+
|  Build                                    modelo elegido       |  <- BARRA INFERIOR
+----------------------------------------------------------------+
     ^ modo actual (Plan o Build)              ^ qué modelo usa

• Zona de conversación: tus mensajes, las respuestas y cada herramienta que usa el agente (verás cuando lee un archivo).
• Caja de texto: donde escribes.
• Barra inferior: el modo en el que estás (Plan o Build) y el modelo que estás usando.

Mensajes contra comandos con /

En la caja puedes escribir dos cosas muy distintas:

Analogía: los comandos con / son los botones del control remoto (cambiar de canal, subir volumen). Los mensajes son lo que le dices al experto.

4. Conéctalo a tu proveedor con /connect

¿Usas LM Studio (camino C de la preparación)? Sáltate este paso: no hay llave que conectar. Revisa que LM Studio esté abierto con el servidor encendido y pasa directo a /models, donde eliges Qwen3 8B (local).

Escribe en la caja:

/connect

Paso a paso:

1. Aparece una lista de proveedores. Escribe para buscar el tuyo: OpenRouter (o OpenCode Zen, o Groq).
2. Selecciónalo con las flechas y presiona Enter.
3. Te pide la llave. Pégala y presiona Enter.

Nunca pegues la llave en la caja de mensajes. Solo va en el campo que abre /connect. Si la pegas como mensaje, OpenCode la trata como un encargo y la manda al modelo en texto: tu llave ya salió de tu computadora. Si te pasa, entra a OpenRouter, borra esa llave, crea otra y conéctala con /connect.

Dónde queda guardada tu llave: OpenCode la guarda en tu carpeta de usuario, en su propio archivo de configuración, no en la carpeta del proyecto. Eso tiene dos ventajas: la conexión se hace una sola vez y sirve para cualquier carpeta en la que abras OpenCode, y la llave no termina por accidente dentro de agent-workshop ni en nada que compartas.

  Tu carpeta de usuario                 ~/agent-workshop
  +---------------------------+         +--------------------+
  | configuración de OpenCode |         | expenses.csv       |
  |  - tu llave (guardada     |         | notes.md           |
  |    una sola vez)          |         | opencode.json      |
  +---------------------------+         |  (permisos, sin    |
         sirve para todas               |   ninguna llave)   |
         las carpetas                   +--------------------+

5. Elige un modelo con /models

Tener proveedor no basta: cada proveedor tiene muchos modelos, y tú eliges cuál usa el agente. Este paso no es opcional. OpenCode arranca con un modelo ya elegido de su propio servicio (en la barra inferior dice OpenCode), y ese modelo puede ser de pago. Si le escribes sin cambiarlo, verás Insufficient account funds: no es tu llave de OpenRouter, es que ese modelo pide saldo en OpenCode Zen.

Qué modelo elegir

No todos los modelos gratuitos sirven para un agente. Un agente necesita un modelo que sepa usar herramientas (pedir "lee este archivo", "lista esta carpeta"), y con un contexto grande para que le quepan tus archivos. Estos cumplen las dos cosas. Usa el primero; si falla, pasa al siguiente:

Evita los modelos muy pequeños (los que dicen 2.6b o menos en el nombre) y los que dicen preview o safety: se equivocan al usar herramientas o no sirven para esto.

Lista revisada el 30 de septiembre de 2026. Los modelos gratuitos cambian seguido: si uno ya no aparece, usa el siguiente de la tabla.

Paso a paso

1. En la caja de mensajes escribe /models y presiona Enter.

   Copiar

   /models
   

2. Se abre una lista con buscador. Escribe qwen3.8. La lista se reduce.

3. Con las flechas, baja hasta el que dice OpenRouter y termina en free (en la lista puede aparecer como Qwen3.8 27B (free)). Presiona Enter.

4. Puede abrirse una segunda ventana, Select variant, con opciones como Default, none, low, medium y xhigh. Es el nivel de razonamiento: cuánto piensa el modelo antes de contestar. Deja Default y presiona Enter. Con menos (none, low) contesta más rápido pero se equivoca más al usar herramientas; con más (medium, xhigh) tarda más y gasta más de tu cuota gratis.

5. Comprueba la barra inferior. Tiene que decir el nombre de ese modelo y OpenRouter. Si todavía dice OpenCode, no quedó elegido: repite desde el paso 1.

  Mal (modelo por defecto, de pago)      Bien (modelo gratuito de OpenRouter)
  +-------------------------------+      +--------------------------------------+
  | Build · GPT-6.1 Sol  OpenCode |      | Build · Qwen3.8 27B (free) OpenRouter |
  +-------------------------------+      +--------------------------------------+

Si más adelante un modelo empieza a fallar (no contesta, contesta a medias, dice "rate limit"), no es tu culpa: está saturado. Repite estos pasos y elige el siguiente de la tabla. Recuerda el límite gratis de OpenRouter: 20 peticiones por minuto y 50 al día.

6. Tu primera respuesta

1. Haz clic en la caja de mensajes (o solo empieza a escribir).

2. Escribe este mensaje, normal, sin / al inicio, y presiona Enter:

   Copiar

   Hola. En una frase: ¿qué puedes hacer en esta carpeta?
   

3. Espera. La primera respuesta puede tardar de 5 a 30 segundos con un modelo gratuito.

Qué puedes ver:

Qué acabas de ver

Esa respuesta tan corta es el ciclo completo de un agente. Tu pantalla se ve más o menos así:

  Hola. En una frase: ¿qué puedes hacer en esta carpeta?   <- tu encargo

  + Thought · 6.4s                  <- 1. el modelo piensa qué necesita
  $ ls /Users/tu-usuario/agent-workshop
    expenses.csv                    <- 2. pide una herramienta (listar la carpeta),
    notes.md                           OpenCode te pide permiso, la corre
    opencode.json                      y le devuelve el resultado
  + Thought · 13.6s                 <- 3. el modelo piensa con lo que vio

  Puedo leer, editar y crear archivos en esta carpeta   <- 4. contesta
  (como expenses.csv, notes.md y opencode.json)...

  Build · Qwen3.8 27B (free) · 30.6s          | Context
                                              | 8,948 tokens
                                              | 3% used
                                              | $0.00 spent

1. Thought: el modelo razona antes de actuar. Puedes hacer clic en el + para leer qué pensó.
2. $ ls ...: el modelo no puede ver tu disco, así que pidió una herramienta: listar la carpeta. OpenCode te preguntó antes de correrla porque tu opencode.json dice bash: "ask". Aprobaste, OpenCode corrió el comando y le mandó la lista al modelo.
3. El segundo Thought: el modelo vuelve a pensar, ahora con la lista de archivos.
4. La respuesta: nombra tus tres archivos reales porque los vio, no porque los adivinó.

En el panel de la derecha:

Y 30.6s es lo que tardó todo. Con modelos gratuitos es normal: fueron dos idas y vueltas al modelo, más tu aprobación.

Ese mensaje viajó de tu laptop al proveedor, el modelo predijo la respuesta y OpenCode te la mostró.

7. Plan y Build: los dos modos

OpenCode tiene dos modos de trabajo, y cambias entre ellos con la tecla Tab. La barra inferior te dice en cuál estás.

Analogía: en Plan, el arquitecto te enseña el plano. En Build, entra la cuadrilla a construir. Primero revisas el plano, luego construyes.

         Tab                    Tab
  +--------------+  ------>  +--------------+
  |    PLAN      |           |    BUILD     |
  | lee, propone |  <------  | lee, escribe,|
  | no cambia    |           | ejecuta      |
  +--------------+           +--------------+

Aun en Build, gracias al opencode.json de la carpeta, el agente te pide permiso antes de escribir un archivo o ejecutar un comando.

8. Mencionar archivos con @

Si escribes @ en tu mensaje, OpenCode te deja elegir un archivo de la carpeta: @expenses.csv. Así te aseguras de que el agente lea ese archivo sí o sí y lo incluya en el contexto, en vez de adivinar cuál buscar. Recuerda: ese archivo se le envía al modelo.

9. Otros comandos útiles

Opción B: OpenCode dentro de Visual Studio Code

Si prefieres algo más visual que la terminal sola, puedes usar OpenCode dentro de Visual Studio Code (VS Code), un editor de código gratuito. El agente es exactamente el mismo; lo que cambia es que lo ves junto a tus archivos.

La ventaja: ves el Explorador con los archivos de tu carpeta mientras el agente trabaja. Cuando crea summary.md, aparece en la lista, y puedes abrirlo de inmediato para revisar el cambio.

+-------------------+-------------------------------------------+
| EXPLORADOR        | EDITOR                                    |
|                   |                                           |
| AGENT-WORKSHOP    |  summary.md                               |
|  expenses.csv     |  # Gastos de septiembre                   |
|  notes.md         |  food ........ 192.65                     |
|  opencode.json    |  home ........  77.10                     |
|  summary.md  (*)  |                                           |
|                   +-------------------------------------------+
|                   | TERMINAL: opencode                        |
|                   |  Tú: crea summary.md                      |
|                   |  Agente: ¿Puedo escribir summary.md?      |
|                   |  > _                                      |
+-------------------+-------------------------------------------+
  (*) archivo nuevo: lo creó el agente y aparece en el Explorador sin que hagas nada

Paso a paso

1. Instala OpenCode como en el paso 1. VS Code no lo trae incluido.

2. Abre la carpeta en VS Code: menú File > Open Folder (Archivo > Abrir carpeta) y elige agent-workshop, dentro de tu carpeta personal. A la izquierda, en el Explorador, verás tus tres archivos.

3. Abre la terminal integrada: menú Terminal > New Terminal, o el atajo **Ctrl + ** (la tecla del acento grave, arriba del Tab). Se abre una terminal abajo, **ya ubicada en tu carpeta**: no necesitas cd`.

4. Corre OpenCode ahí:

   Copiar

   opencode

   La primera vez que corres opencode en la terminal integrada, la extensión de OpenCode para VS Code se instala sola. Si no pasa, búscala a mano: ícono de Extensions (Extensiones) en la barra izquierda, escribe "OpenCode" e instálala.

5. Conecta y elige modelo igual que arriba: /connect y /models. Si ya lo hiciste en la terminal normal, no hace falta: la llave está en tu carpeta de usuario y sirve aquí también.

Atajos de la extensión

El segundo atajo es muy útil: seleccionas unas líneas en el editor, presionas el atajo y OpenCode recibe una referencia a ese archivo y esas líneas exactas (#L37-42 quiere decir "líneas 37 a 42").

Si la extensión no funciona: el comando code

La extensión necesita que el comando code (el que abre VS Code desde la terminal) esté instalado.

• Mac: abre la paleta de comandos con Cmd + Shift + P, escribe Shell Command: Install 'code' command in PATH y presiona Enter. Luego cierra y abre VS Code.
• Windows y Linux: normalmente el instalador de VS Code ya lo agrega. Si no, reinstala VS Code con la opción de agregarlo al PATH.

Fíjate que es el mismo concepto del PATH de arriba: la terminal solo encuentra code si está en su lista de carpetas.

Trampas comunes

• command not found: abre una terminal nueva para que lea el PATH actualizado. Si sigue, reinstala con la opción recomendada de tu sistema.
• Insufficient account funds: sigues en el modelo por defecto de OpenCode, que es de pago. Escribe /models y elige uno de OpenRouter que termine en :free.
• Pegaste la llave como mensaje: bórrala en OpenRouter, crea otra y conéctala con /connect. La llave va solo en el campo que abre /connect.
• Error de autenticación: casi siempre es la llave mal pegada, con un espacio o incompleta. Vuelve a /connect y pégala de nuevo.
• "Rate limit" o el modelo no contesta: el modelo gratuito está saturado o llegaste al tope del día. Cambia de modelo con /models.
• El agente dice que no ve archivos: lo abriste en otra carpeta. Sal con /exit, entra con cd ~/agent-workshop y vuelve a abrirlo. En VS Code, revisa que abriste la carpeta agent-workshop con Open Folder.

Para comprobar que entendiste

1. Instalaste OpenCode, escribes opencode --version y la terminal dice command not found. ¿Qué pasó y qué haces?

2. ¿Qué diferencia hay entre escribir /models y escribir Hola en la caja?

3. Quieres que el agente te explique cómo sumaría los gastos, sin tocar ningún archivo todavía. ¿En qué modo lo pides?

Resumen

• Instalaste OpenCode con la opción recomendada de tu sistema (curl ... | bash en Mac y Linux, Node.js y npm install -g opencode-ai en Windows) y verificaste con opencode --version.
• command not found casi siempre se arregla con una terminal nueva, porque así se relee el PATH.
• Abriste OpenCode en ~/agent-workshop, lo conectaste con /connect (la llave queda en tu carpeta de usuario) y elegiste modelo con /models.
• Los mensajes van al modelo; los comandos con / los resuelve OpenCode. Tab cambia entre Plan (mira y propone) y Build (actúa). @ mete un archivo al contexto.
• Opción B: el mismo OpenCode dentro de VS Code, con el Explorador a la vista para ver aparecer los cambios del agente.

Parte 3: Tu primer encargo: que lea la carpeta y te la explique

El primer encargo no cambia nada. Le pedimos al agente que lea la carpeta y nos cuente qué hay. Es la forma más segura de empezar y te deja tres ideas que vas a usar el resto de tu vida con agentes:

1. Cómo "lee" un agente (spoiler: no ve tu computadora, usa herramientas).
2. Qué es el contexto: el modelo solo sabe lo que se le dio en esta conversación.
3. Por qué lo que dice el agente se comprueba, aunque suene muy seguro.

Antes de empezar: cómo lee un agente

Cuando le pides "lee esta carpeta", el modelo no abre tu disco duro. El modelo vive en la nube, en los servidores de tu proveedor (OpenRouter, por ejemplo), y lo único que sabe hacer es recibir texto y producir texto.

OpenCode es el intermediario. Corre en tu laptop y le ofrece al modelo un menú de herramientas: "listar una carpeta", "leer un archivo", "escribir un archivo", "correr un comando". El modelo no las ejecuta: pide usarlas, OpenCode las ejecuta en tu máquina y le devuelve el resultado como texto.

Piensa en un asistente por teléfono que no puede entrar a tu oficina. Te dice: "léeme qué dice el primer cajón". Tú lo lees en voz alta. Con eso, el asistente decide qué pedir después. El asistente es el modelo; tú, leyendo en voz alta, eres OpenCode.

  Tú              OpenCode (tu laptop)          Modelo (la nube)
  |                      |                             |
  |-- "Lee la carpeta" ->|                             |
  |                      |-- tu mensaje + menú ------->|
  |                      |   de herramientas           |
  |                      |<-- "usa: listar carpeta" ---|
  |                      |                             |
  |                (lista la carpeta)                  |
  |                      |-- "hay 3 archivos: ..." --->|
  |                      |<-- "usa: leer expenses.csv"-|
  |                      |                             |
  |                (lee el archivo)                    |
  |                      |-- contenido del archivo --->|
  |                      |          ... (repite) ...   |
  |                      |<-- respuesta final ---------|
  |<-- "Hay un registro  |                             |
  |     de gastos..."    |                             |

Cada flecha hacia la derecha es una petición al modelo. Por eso un solo encargo gasta varias peticiones de tu plan gratuito.

Qué es el contexto

Todo lo que viaja hacia el modelo en esa conversación (tu mensaje, lo que respondió antes, el contenido de los archivos que leyó) forma su contexto. Es su memoria de trabajo, y es la única que tiene.

• Si un archivo no se leyó, el modelo no sabe qué dice. Puede adivinar, pero no lo sabe.
• El contexto tiene un tamaño máximo (la "ventana de contexto"). Una carpeta pequeña cabe de sobra; una carpeta con miles de archivos, no.

Es como una mesa de trabajo: el modelo solo puede usar las hojas que están sobre la mesa. Lo que se quedó en el archivero no existe para él.

  +----------------- Ventana de contexto -----------------+
  |                                                        |
  |  [tu mensaje]  [contenido de expenses.csv]             |
  |  [contenido de notes.md]  [respuestas anteriores]      |
  |                                                        |
  +--------------------------------------------------------+
         ^
         |  El modelo SOLO razona con lo que está aquí dentro.
         |
     Archivos que no se leyeron: invisibles para él.

Por eso existe el @: cuando escribes @expenses.csv, garantizas que ese archivo entre al contexto.

1. Pasa a modo Plan

Presiona Tab hasta que abajo diga Plan.

Por qué Plan es seguro: en este modo OpenCode le quita al agente las herramientas que cambian cosas. Puede listar y leer, pero no escribir archivos (y si quisiera correr un comando, te lo tiene que pedir). Aunque el modelo se confunda y "quiera" editar algo, la herramienta no está disponible. Es como dejar que alguien vea tu cocina pero sin darle las llaves de la alacena.

  Modo Plan                      Modo Build
  +----------------------+       +----------------------+
  | listar carpeta   SI  |       | listar carpeta   SI  |
  | leer archivo     SI  |       | leer archivo     SI  |
  | escribir archivo NO  |       | escribir archivo SI* |
  | correr comando   ?   |       | correr comando   SI* |
  +----------------------+       +----------------------+
  ? = solo si tú lo apruebas     * con tu permiso, gracias
                                    a opencode.json

2. Pídele que te explique la carpeta

Copia este mensaje:

Lee los archivos de esta carpeta y explícame en pocas líneas qué hay en cada uno y para qué parece servir la carpeta.

Mira cómo trabaja: vas a ver que lista la carpeta y abre los archivos uno por uno antes de contestar. Son las flechas del diagrama de arriba, en vivo.

Debería decirte algo parecido a esto: que hay un registro de gastos de septiembre en expenses.csv, unas notas con una meta de presupuesto en notes.md, y un archivo de configuración de OpenCode.

Si usas VS Code: mientras el agente trabaja en la terminal integrada, abre expenses.csv y notes.md desde el Explorador (la barra de la izquierda). Así ves con tus propios ojos lo mismo que el agente está leyendo.

3. Hazle una pregunta con respuesta comprobable

Según @expenses.csv, ¿cuánto gasté en total en septiembre y en qué categoría gasté más?

Ahora viene lo importante. No le creas todavía. Comprueba al menos un número por tu cuenta. Estos son los valores reales:

food ya incluye la fila Food de 6.50, y transport incluye la fila Transport de 12.40.

Si usas VS Code: abre expenses.csv en el editor y suma a mano las filas de comida: 54.20 + 6.50 + 61.75 + 11.90 + 58.30 = 192.65. Tardas menos de un minuto.

¿Coincide? Si el agente te dio otro número para comida o transporte, ya encontraste lo raro del archivo.

4. Lo raro del archivo, y por qué confunde

Mira con atención la columna category. Hay filas con food y una con Food; filas con transport y una con Transport. Para una persona es la misma categoría. Para una computadora, no.

Por qué: un programa compara texto letra por letra, y para él una f minúscula y una F mayúscula son caracteres distintos (tienen códigos distintos). Así que food y Food son dos textos diferentes, igual que food y fool. Así ve la computadora las categorías si nadie le dice lo contrario:

  Como lo ves tú           Como lo ve la computadora
  +-----------+--------+   +-------------+--------+
  | food      | 192.65 |   | "food"      | 186.15 |
  | home      |  77.10 |   | "Food"      |   6.50 |
  | fun       |  63.00 |   | "home"      |  77.10 |
  | transport |  52.40 |   | "fun"       |  63.00 |
  +-----------+--------+   | "transport" |  40.00 |
                           | "Transport" |  12.40 |
                           +-------------+--------+
         4 categorías              6 categorías

Según cómo lo haya sumado, el agente pudo:

• Darse cuenta y unirlas (bien).
• Separarlas en dos categorías, o dejar fuera una fila (mal, y sin avisarte).

Si no lo mencionó, pregúntale:

¿Hay algo inconsistente en la columna category? ¿Afecta a los totales que me diste?

Por qué un agente puede equivocarse con tanta seguridad

Un modelo de lenguaje no "calcula" como una calculadora. Produce el texto que le parece más probable dado su contexto. Casi siempre ese texto es correcto, pero cuando hay un detalle raro (una mayúscula, una fila fuera de lugar) puede producir una respuesta que suena perfecta y está mal. El tono seguro no es una prueba: el modelo escribe con la misma confianza cuando acierta y cuando se equivoca.

No es mala fe ni un error raro: es lo normal. Por eso la regla de hoy es:

El agente propone. Tú compruebas al menos una cosa antes de creerle.

  +-----------+     +----------------+     +--------------+
  |  Agente   | --> | Tú compruebas  | --> | ¿Coincide?   |
  |  responde |     | UN dato rápido |     +--------------+
  +-----------+     +----------------+       |          |
                                            SI          NO
                                             |          |
                                     confías más    le preguntas
                                     y sigues       qué pasó

No hace falta comprobarlo todo. Basta con un dato que puedas verificar rápido: un total, un nombre de archivo, una línea concreta.

Para comprobar que entendiste

1. Cuando el agente "lee" expenses.csv, ¿quién abre realmente el archivo: el modelo o OpenCode?

2. Si el agente nunca leyó notes.md y le preguntas cuál es tu meta de presupuesto, ¿qué puede pasar?

3. ¿Por qué Food y food pueden dar totales distintos?

Resumen

• El modelo no ve tu computadora: pide herramientas y OpenCode las ejecuta. Cada ida y vuelta es una petición.
• El contexto es todo lo que el modelo recibió en esta conversación. Lo que no leyó, no lo sabe.
• En modo Plan el agente no tiene herramientas para escribir: ideal para empezar.
• Para una computadora, food y Food son textos distintos. Por eso comprobaste un número y encontraste la inconsistencia.
• Regla: el agente propone, tú compruebas al menos una cosa.

Parte 4: Tu primer cambio: el agente escribe, tú revisas

Ahora sí le dejamos escribir. Esta es la parte más importante del taller, y no por el archivo que va a crear: lo que importa es cómo revisas lo que propone antes de aceptarlo.

En esta parte vas a entender cuatro cosas:

1. Por qué conviene pedir un plan antes de un cambio.
2. Cómo funciona el permiso: quién decide si un archivo cambia.
3. Qué es un diff y cómo leerlo.
4. Qué hacer si aceptaste un cambio que no querías.

Por qué primero un plan

Un cambio pasa por dos momentos: la idea ("voy a sumar así, voy a ordenar así") y el archivo ya escrito. Corregir la idea es barato: le escribes una frase y listo. Corregir el archivo es caro: tienes que leerlo entero, encontrar el error, pedir otro cambio y volver a revisar.

Es como un carpintero que te enseña el dibujo del mueble antes de cortar la madera. Si el dibujo está mal, borras. Si la madera ya está cortada, compras otra.

  Detectar el error en...     Costo de corregirlo
  +---------------------+
  | la idea (plan)      |  ->  una frase
  +---------------------+
  | el archivo escrito  |  ->  leer, rechazar, pedir otra vez
  +---------------------+
  | algo que ya usaste  |  ->  descubrir qué salió mal y dónde
  +---------------------+

1. Primero, que proponga (modo Plan)

Sigue en modo Plan y pídele un plan antes de tocar nada:

Quiero un archivo summary.md con el gasto de septiembre por categoría, ordenado de mayor a menor, el total del mes y si cumplí la meta de @notes.md. Antes de hacerlo, dime cómo vas a tratar las categorías que solo cambian en mayúsculas. No escribas nada todavía.

Lee su plan. Si dice que va a unir food con Food y transport con Transport, vas bien. Si no, díselo tú:

Trata las categorías sin distinguir mayúsculas: food y Food son la misma.

Fíjate que en el mensaje ya le dijiste de antemano el problema que encontraste en la parte anterior. Eso es pedir bien: le pones sobre la mesa (en su contexto) lo que tú ya sabes.

Cómo funciona el permiso

Por defecto, OpenCode edita archivos sin preguntarte: el agente decide y el archivo cambia. Para alguien con experiencia eso ahorra tiempo. Para una primera vez es arriesgado, porque no ves nada hasta que ya pasó.

Por eso el archivo opencode.json de tu carpeta dice esto:

{
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

• "edit": "ask": antes de crear o modificar un archivo, te pregunta.
• "bash": "ask": antes de correr un comando en tu terminal, te pregunta.

Con eso, el flujo queda así:

  +-----------------+
  | Agente propone  |   "quiero escribir summary.md con esto"
  | un cambio       |
  +--------+--------+
           |
           v
  +-----------------+
  | OpenCode te     |   te muestra el cambio y espera
  | pregunta        |
  +--------+--------+
           |
     +-----+------+
     |            |
  Aceptas      Rechazas
     |            |
     v            v
  +--------+   +----------------------+
  | El     |   | El archivo NO cambia |
  | archivo|   | y sigues conversando |
  | cambia |   | ("corrige esto...")  |
  +--------+   +----------------------+

Es como un contador que prepara tu declaración pero no la envía hasta que tú la firmas. Él hace el trabajo; la firma es tuya.

2. Ahora, que lo haga (modo Build)

Presiona Tab hasta que diga Build y escribe:

Adelante, crea summary.md como acordamos.

Como en opencode.json pusimos "edit": "ask", el agente se detiene y te pide permiso antes de escribir. Te muestra lo que quiere hacer, en verde lo que agrega. Eso que te muestra se llama diff.

Qué es un diff y cómo leerlo

Un diff (de difference, diferencia) es la lista de líneas que cambian entre la versión de antes y la de después. No te muestra el archivo entero: solo lo que cambia, para que revises rápido.

• Una línea que empieza con - (a veces en rojo) se quita.
• Una línea que empieza con + (a veces en verde) se agrega.
• Las líneas sin signo están ahí solo para que te ubiques; no cambian.

Cuando se modifica una línea, el diff la muestra como "se quita la vieja, se agrega la nueva". Así se vería el cambio que vas a pedir en el paso 4:

   date,description,category,amount
   2026-09-02,Bus card top-up,transport,20.00
-  2026-09-03,Coffee with a friend,Food,6.50
+  2026-09-03,Coffee with a friend,food,6.50
   2026-09-05,Internet bill,home,35.00
   ...
-  2026-09-12,Taxi home,Transport,12.40
+  2026-09-12,Taxi home,transport,12.40
   2026-09-14,Electricity bill,home,42.10

Léelo así: "en la fila del café, Food pasa a food; en la del taxi, Transport pasa a transport; nada más". Cuando el archivo es nuevo, como summary.md, todas las líneas salen con +, porque antes no existía nada.

3. Revisa antes de aceptar

Antes de aceptar summary.md, mira tres cosas:

1. ¿Es el archivo que pediste? Nombre y ubicación: summary.md, en esta carpeta.
2. ¿Un número cuadra? Compara con la tabla de la parte anterior. Comida debería dar 192.65 y el total 385.15.
3. ¿La conclusión es correcta? La meta en notes.md era gastar menos de 350. La cuenta es simple:

  Gasto real de septiembre     385.15
  Meta                       - 350.00
                             --------
  Te pasaste por                35.15   ->  la meta NO se cumplió

Si el agente escribió "cumpliste la meta", o puso otra diferencia, ya tienes algo que corregir.

Si todo está bien, acepta. Si algo está mal, recházalo y dile qué corregir. Rechazar es tan válido como aceptar: el archivo no se escribe y sigues conversando.

Si usas VS Code: en cuanto aceptes, vas a ver aparecer summary.md en el Explorador de la izquierda. Ábrelo y léelo completo en el editor: es la versión final, ya en tu disco.

4. Un segundo cambio, sobre un archivo que ya existe

Crear un archivo nuevo es fácil de revisar: todo es nuevo. Modificar uno existente es donde de verdad importa revisar, porque un cambio de más puede quedar escondido entre líneas que ya estaban bien:

Corrige expenses.csv para que todas las categorías estén en minúsculas. No cambies nada más.

Cuando te pida permiso, mira el diff con atención: deberían cambiar exactamente dos líneas, la de Food y la de Transport, como en el ejemplo de arriba. Si ves que tocó otras líneas, reordenó filas o cambió algún monto, recházalo.

"No cambies nada más" es de las frases más útiles que le puedes decir a un agente. Un modelo tiende a "mejorar" cosas que no le pediste (reordenar, formatear, redondear). Esa frase le pone un límite claro y, además, te da un criterio de revisión: todo lo que no sean esas dos líneas sobra.

Si usas VS Code: después de aceptar, abre expenses.csv en el editor y confirma que las demás filas siguen igual y que ahora solo ves categorías en minúsculas.

5. Si aceptaste algo que no querías

Tu mejor protección ya la tienes: el permiso. Mientras opencode.json diga "edit": "ask", ningún archivo cambia sin que tú lo apruebes. Si el diff no te convence, recházalo y ya: el archivo queda como estaba.

  El agente propone un cambio
            |
            v
     ¿El diff está bien?
       |            |
       sí           no
       |            |
       v            v
    aceptar      rechazar  -->  el archivo queda igual

Si ya lo aceptaste y te arrepientes, pídeselo al agente con palabras claras:

Deshaz el último cambio que hiciste en expenses.csv y déjalo exactamente como estaba antes.

Te va a proponer otro cambio, con su diff y su permiso. Revísalo igual que el primero: aquí depende de que el agente recuerde bien cómo estaba el archivo. Por eso vale más revisar antes de aceptar que deshacer después.

Lo que te llevas de este encargo

• Pide un plan antes de un cambio que te importe: corregir una idea cuesta menos que corregir un archivo.
• Revisa el diff antes de aceptar: el archivo correcto, un número que cuadre, nada fuera de lo pedido.
• Rechazar está bien. Es parte del trabajo, no un fracaso.

Para comprobar que entendiste

1. En un diff ves una línea con - y justo abajo otra casi igual con +. ¿Qué pasó?

2. Si borras opencode.json de la carpeta, ¿qué cambia cuando el agente quiera editar un archivo?

3. Aceptaste un cambio y luego ves que tocó una fila que no debía. ¿Qué haces?

Resumen

• Usaste Plan para acordar el cambio y Build para hacerlo.
• "edit": "ask" y "bash": "ask" hacen que el agente te pida permiso; sin eso, OpenCode edita sin preguntar.
• Un diff muestra solo lo que cambia: - se quita, + se agrega.
• Comprobaste la meta: 385.15 contra 350, te pasaste por 35.15.
• En el segundo cambio, solo debían cambiar dos líneas. "No cambies nada más" limita al agente y te dice qué revisar.
• Tu protección es el permiso: si el diff no te convence, recházalo. Si ya aceptaste, pide al agente que lo deshaga y revisa ese diff también.

Parte 5: Qué no pedirle todavía y por qué

Ya viste lo que un agente hace bien. Para no perder una tarde, conviene saber también dónde está el límite hoy, sobre todo con modelos gratuitos. Pero una lista de "no hagas esto" se olvida rápido. Lo que no se olvida es por qué existe cada límite. Con el porqué, puedes decidir tú solo en situaciones que esta lección no cubre.

Lo que le sale bien

• Leer y resumir una carpeta, un documento o un archivo de datos.
• Cambios pequeños y bien descritos: crear un archivo, corregir un formato, renombrar algo.
• Explicar qué hace un archivo o un comando que no entiendes.
• Proponer un plan antes de que tú decidas.

Lo que tienen en común: son encargos pequeños, claros y comprobables. Vas a ver que cada límite de abajo es lo contrario de alguna de esas tres palabras.

  +----------------------------+---------------------------------+
  | Buen encargo               | Mal encargo (por ahora)         |
  +----------------------------+---------------------------------+
  | Pequeño                    | Enorme                          |
  | "Crea summary.md con el    | "Hazme una app de finanzas      |
  |  total por categoría"      |  completa"                      |
  +----------------------------+---------------------------------+
  | Claro                      | Vago                            |
  | "Categorías en minúsculas, | "Mejora este archivo"           |
  |  no cambies nada más"      |                                 |
  +----------------------------+---------------------------------+
  | Comprobable                | Imposible de revisar            |
  | "El total debe dar 385.15" | "Dime si mis finanzas van bien" |
  +----------------------------+---------------------------------+
  | Carpeta de práctica        | Tu carpeta de trabajo real      |
  | Datos de ejemplo           | Datos personales o de tu empleo |
  +----------------------------+---------------------------------+

Lo que todavía no conviene pedirle, y por qué

1. Encargos enormes y vagos

Como "hazme una aplicación completa".

Por qué: una petición vaga tiene muchas respuestas válidas. Si le dices a un albañil "hazme una casa", puede hacer cien casas distintas y todas cumplen lo que pediste. El agente elige una, sin preguntarte, y tú descubres al final que no era la que imaginabas. Además, un encargo enorme produce un cambio enorme, y un diff de 500 líneas nadie lo revisa de verdad.

Qué hacer: parte el trabajo en pasos pequeños, cada uno con su revisión.

2. Cosas que no puedes comprobar

Por qué: un modelo de lenguaje funciona prediciendo el texto más probable, palabra por palabra. Casi siempre eso coincide con la verdad, pero no siempre. Cuando no sabe algo, no se queda callado: produce algo que suena correcto. A eso se le llama alucinar. Una alucinación no se distingue por el tono, solo al compararla con la realidad. Si no tienes forma de comprobar, no tienes forma de detectarla.

  Lo que tú crees que pasa         Lo que pasa en realidad
  +------------------------+       +---------------------------+
  | pregunta -> busca el   |       | pregunta -> predice el    |
  | dato -> responde       |       | texto más probable ->     |
  |                        |       | responde (acierte o no)   |
  +------------------------+       +---------------------------+

Qué hacer: antes de pedir algo, piensa cómo vas a saber si está bien. Si no se te ocurre, no lo aceptes a ciegas.

3. Esperar que recuerde lo de ayer

Por qué: el agente no tiene memoria entre sesiones. Recuerda la conversación actual porque todo está en su contexto, pero cuando empiezas una nueva (con /new o al volver a abrir opencode), arranca en blanco. Lo único que sobrevive son los archivos de tu carpeta, porque puede volver a leerlos.

Por eso existe AGENTS.md: un archivo donde se describe el proyecto (qué hay, cómo se trabaja, qué no tocar) y que el agente lee al empezar. El comando /init de OpenCode lo crea por ti: analiza la carpeta y escribe un AGENTS.md que la describe. Es como la nota que le dejas a quien te cubre en el trabajo: la persona no sabe lo que tú sabes, pero la nota sí.

  Sesión 1                         Sesión 2 (nueva)
  +------------------+             +------------------+
  | contexto:        |   se        | contexto:        |
  | "food = Food",   |  pierde     | (vacío)          |
  | "meta 350" ...   | ----X---->  |                  |
  +------------------+             +--------+---------+
          |                                 ^
          | se escribe en un archivo        | lo vuelve a leer
          v                                 |
  +--------------------------------------------------+
  | AGENTS.md, summary.md... (tu carpeta, en disco)  |
  +--------------------------------------------------+

4. Carpetas enormes o conversaciones interminables

Por qué: el contexto tiene un tamaño máximo. Una carpeta con miles de archivos no cabe, y el agente va a trabajar con una parte sin decírtelo. Y en una conversación muy larga, lo del principio se diluye o se recorta: el agente empieza a confundirse con lo que ya habían acordado.

Qué hacer: trabaja en carpetas pequeñas, menciona con @ lo que importa, y cuando la conversación se haga larga, empieza una nueva con /new.

5. Tocar carpetas importantes, o comandos que borran o instalan

Por ejemplo, abrirlo sobre tu carpeta de documentos personales, o aceptar un comando sin leerlo.

Por qué: cuando el agente corre un comando, lo corre con los permisos de tu usuario. Todo lo que tú puedes hacer en tu computadora (borrar archivos, instalar programas, mover carpetas), él también puede, si lo apruebas. No hay una capa extra de protección. Por eso dejamos "bash": "ask" en opencode.json: cada comando pasa por ti antes de ejecutarse.

Qué hacer: practica en carpetas de práctica, y lee cada comando antes de aceptarlo. Si no entiendes qué hace, recházalo y pregúntale: "¿Qué hace exactamente este comando?".

6. Datos personales o confidenciales con modelos gratuitos

Por qué: varios modelos gratuitos usan lo que les escribes para entrenar futuras versiones. Todo lo que el agente lee de tu carpeta viaja al proveedor como parte del contexto. Si ahí hay contraseñas, datos de clientes o información de tu trabajo, ya salió de tu computadora.

Qué hacer: con modelos gratuitos, solo datos de ejemplo o cosas que no te importaría ver publicadas.

7. Trabajar todo el día con el plan gratuito

Por qué: los planes gratuitos tienen límites de peticiones (en OpenRouter, 20 por minuto y 50 al día para los modelos gratis). Como viste, un solo encargo puede gastar varias peticiones. Si un día se te acaban, no es un error: es el límite del plan.

Qué hacer: usa las peticiones en encargos que valgan la pena, o cambia de modelo con /models si uno está saturado.

Tres reglas para llevarte

Cada una sale de los porqués de arriba:

1. Pide el qué, no el cómo, y di qué no debe tocar. (Porque lo vago tiene muchas respuestas válidas.)
2. Plan primero en cualquier cambio que te importe. (Porque corregir una idea es más barato que corregir un archivo.)
3. Comprueba al menos una cosa antes de aceptar. (Porque el modelo predice texto y puede alucinar con total seguridad.)

Si usas VS Code: tener el Explorador y el editor al lado de la terminal te ayuda con las tres reglas: ves qué archivos existen, abres el que cambió y compruebas con tus propios ojos.

Para comprobar que entendiste

1. ¿Por qué un modelo puede darte un dato falso con total seguridad?

2. Ayer le explicaste al agente que food y Food son lo mismo. Hoy abres una sesión nueva y vuelve a separarlas. ¿Qué pasó y cómo lo evitas?

3. ¿Por qué "bash": "ask" es importante aunque confíes en el agente?

Resumen

• Al agente le salen bien los encargos pequeños, claros y comprobables.
• Lo vago tiene muchas respuestas válidas; lo enorme no se puede revisar.
• El modelo predice texto, por eso puede alucinar: comprueba siempre algo.
• No hay memoria entre sesiones: lo que deba recordar va en un archivo como AGENTS.md (/init lo crea).
• El contexto tiene tamaño máximo, y el plan gratuito, límite de peticiones.
• Los comandos corren con tus permisos (por eso "bash": "ask"), y los modelos gratuitos pueden entrenar con lo que les mandas: nada de datos personales.
• Para seguir, ve al módulo Después: los ecosistemas de NIEVA a tu ritmo o los bootcamps si quieres algo guiado.

Recursos

• OpenCode: instalación
• OpenCode: la interfaz de terminal
• OpenCode: proveedores
• OpenRouter: modelos gratuitos
• Comparativa de modelos probados con OpenCode