Objetivo del tema
Aprender a expresarte de forma que el agente acierte a la primera: estructura de un buen pedido, uso del contexto en tiempo real (archivos, comandos, imágenes), división correcta entre lo persistente y lo puntual, y plantillas reutilizables.
El modelo solo ve lo que llega al contexto: tus palabras, los archivos referenciados y las salidas de comandos adjuntas. Un pedido vago produce resultados genéricos; un pedido preciso produce cambios quirúrgicos.
Describe qué quieres lograr y dónde. Evita ambigüedades y supuestos que el agente no pueda verificar por sí mismo.
Incluye estado actual, restricciones y ejemplos. La información que aportas decide cómo actúa el agente.
Indica cómo se comprueba el éxito: tests que deben pasar, comportamiento esperado, formato de la salida.
| Pedido débil | Pedido fuerte | ¿Qué cambió? |
|---|---|---|
| "Arregla el login" | "Los usuarios con email verificado reciben 401 en POST /api/login desde ayer. El endpoint está en @src/routes/auth.ts. Encuentra la causa, corrígela y agrega un test de regresió" | Síntoma + ubicación exacta + criterio de éxito |
| "Hazlo más rápido" | "Esta consulta tarda 2s con 50k filas: @src/db/reportes.sql. Propón una estrategia de índices y mide el antes/después" | Metrica observable + alcance acotado |
Estructura mental para cualquier tarea no trivial:
@ si puedes).Más allá de las palabras, OpenCode te da canales directos para adjuntar contexto justo cuando lo necesitas:
@archivo: búsqueda difusa y contenido completo del archivo en el mensaje; con la extensión del IDE puedes referenciar líneas exactas (@Archivo#L37-42).!comando: ejecuta shell y agrega su salida al hilo. "!npm test" antes de pedir un arreglo da al modelo el error literal.Regla práctica: cada pieza de contexto que agregues tú es una suposición menos que debe hacer el modelo. Un !git log --oneline -5 pegado en la conversación vale por tres preguntas de aclaración.
| Tipo de información | Dónde vive | Ejemplo |
|---|---|---|
| Convenciones permanentes del proyecto | AGENTS.md |
"Usamos TypeScript estricto; imports relativos prohibidos" |
| Comandos estándar | AGENTS.md |
Cómo instalar, correr tests, levantar el entorno |
| Preferencias personales | AGENTS.md global | "Responde en español; commits en modo imperativo" |
| Detalles de esta tarea | El prompt actual | "Solo el módulo de facturación, sin tocar esquemas" |
| Estado transitorio | !, imágenes, @ |
Salida del test roto, captura del diseño nuevo |
Si te descubres repitiendo la misma instrucción en varios prompts, es señal de que debe migrar al AGENTS.md o convertirse en comando personalizado.
Para tareas grandes, el mejor prompt es dos prompts: uno para acordar el plan (modo Plan) y otro para ejecutarlo (modo Build). Esta separación convierte la comunicación en un diálogo barato: corregir un plan cuesta segundos; deshacer una implementación equivocada cuesta minutos y confianza.
Cuando un tipo de pedido se repite (reporte de bug, nueva feature, revisión), conviértelo en un comando personalizado con argumentos (tema 14). Dos plantillas base:
.opencode/commands/bug.md — uso: /bug No carga el listado en producción
Investiga este bug: $ARGUMENTS
Pasos:
1. Reproduce el problema o identifica dónde fallaría según el código.
2. Identifica la causa raíz y explicala antes de cambiar nada.
3. Implementa la corrección mínima necesaria.
4. Agrega un test de regresión que falle sin el arreglo.
5. Corre la suite completa..opencode/commands/feature.md — uso: /feature exportar pedidos a CSV
Nueva funcionalidad: $ARGUMENTS
Antes de implementar, presenta un plan breve con archivos a crear o modificar,
decisiones abiertas si las hay, y cómo se probará. Espera mi confirmación.La comunicación con un agente es iterativa por naturaleza: /undo revierte el último intercambio con sus cambios y permite reformular; los planes se corrigen conversando. Aun así, estos errores aparecen una y otra vez:
@ ni pistas, el agente busca a ciegas en repositorios grandes.AGENTS.md.Conclusión: comunicarte bien con OpenCode combina tres hábitos: estructura clara en cada pedido (objetivo, alcance, validación), contexto fresco mediante @, ! e imágenes, y separación limpia entre lo persistente (AGENTS.md, comandos) y lo puntual (la conversación). En el próximo tema cubriremos la otra pata de la profesionalización: seguridad, privacidad y solución de problemas.