Claude Code y OpenCode: curso acelerado de 90 minutos

15 conceptos, 80% del uso real

Un curso acelerado práctico. Sin relleno, sin venta disfrazada. Al final sabrás qué usar, cuándo usarlo y dónde mirar cuando necesites más, en cualquiera de las dos herramientas.

La idea única que hace que todo lo demás encaje: el coding agéntico es un problema de gestión de contexto disfrazado de herramienta de programación. Casi toda «técnica avanzada» se reduce a lo mismo: llevar la información correcta al modelo en el momento correcto y mantener fuera la información equivocada. Lee cada sección con esa lente.

Prerrequisito: Prompting de IA en 2026. Esta página asume que ya tienes esos trece conceptos a mano. Informar como a un colega (concepto 1), el contexto como todo el juego (concepto 4), modo de pensamiento (concepto 5), encuadre neutral (concepto 6), el bucle de iteración (concepto 7), modelos revisando modelos (concepto 13): esa es la disciplina. Esta página muestra cómo se ve esa disciplina cuando el modelo puede tocar tu sistema de archivos.

Claude Code y OpenCode son dos implementaciones de la misma idea, con casi el mismo vocabulario y atajos ligeramente distintos.

Dos herramientas, no una. A propósito. La disciplina de esta página debe sobrevivir a cualquier herramienta individual. Los cambios de precio, las restricciones de acceso, las preferencias de modelos y los giros estratégicos no deberían dejar varadas las lecciones que aprendiste. Mostrar cada concepto en ambas herramientas también es la prueba más fuerte de si el concepto es real: si una técnica solo funciona en Claude Code, es un truco de Claude Code; si funciona en ambas (misma forma, atajos distintos), es una parte de cómo se comporta realmente el coding agéntico. Recurre a Claude Code cuando la restricción sea el rendimiento de modelos de frontera; recurre a OpenCode cuando importen la flexibilidad, el control de costos o la apertura. OpenCode también viene con un conjunto de modelos gratuitos que puedes usar sin crear una cuenta. Las habilidades que desarrollas de cualquier modo son las mismas. Ese es el punto, no una concesión.

Vigente a mayo de 2026. Ambas herramientas avanzan rápido: los esquemas de configuración, los nombres de comandos y los comandos de instalación cambian. Si todavía no tienes las herramientas, las instrucciones de instalación están en esas mismas páginas de documentación: Claude Code, OpenCode. Cuando tengas dudas sobre cualquier otra cosa, esas páginas también son el punto de partida.

Ambas herramientas se actualizan con frecuencia; por eso, antes de iniciar cualquier sesión, ejecuta los comandos claude update y opencode upgrade para usar la versión más reciente.

Conocimientos asumidos: te sientes cómodo en una línea de comandos, has usado git y has leído o escrito configuración JSON antes. No necesitas experiencia previa con agentes de coding basados en LLM. Para eso es esta página. Si MCP, hooks o la capa de protocolo entre los LLM y las herramientas externas son completamente nuevos para ti, los irás aprendiendo por contexto.

Elige tu herramienta, la página te sigue

A lo largo de esta página, las secciones que divergen entre Claude Code y OpenCode tienen un selector. Elige una opción y todos los selectores de la página se sincronizan con ella; tu elección persiste entre visitas.

¿Quieres la versión profunda de algún concepto de esta página?

Este es un curso acelerado: 80% del uso real en una sola lectura. Para el tratamiento completo de todos los temas de abajo (jerarquía de archivos de reglas, modo plan en profundidad, anatomía de skills, orquestación de subagentes, eventos de hooks, CI/CD, gestión de sesiones), consulta Capítulo 14: trabajar con agentes generales y de coding y Capítulo 17: Claude Code para equipos, CI/CD y configuración avanzada. El curso acelerado es el mapa; esos capítulos son el terreno.

Hay un ejemplo trabajado completo en la Parte 6: una tarea realista de principio a fin, ejecutada dos veces, una en cada herramienta. Si aprendes mejor viendo que leyendo definiciones, salta primero allí y luego vuelve.

---

Parte 1: Fundamentos

Estos tres primeros conceptos aplican igual en ambas herramientas. Cuando los comandos o atajos difieren, la diferencia se indica en el propio texto.

1. Qué son realmente estas herramientas

El modelo mental de la mayoría de la gente es «un chatbot que sabe código». Eso es incorrecto, y ese error es el problema.

Un chatbot responde preguntas. Claude Code y OpenCode ejecutan acciones. Leen tus archivos, los editan, ejecutan comandos en tu equipo, acceden a la red y encadenan todo eso hasta completar una tarea. Tú les das un brief, ellos trabajan, tú revisas.

El cambio de mentalidad: deja de escribir preguntas y empieza a escribir briefs. «¿Cómo agrego auth?» es una indicación de chatbot. «Agrega auth de email/contraseña a esta app Express usando bcrypt y JWT, guarda usuarios en la tabla Postgres users existente, escribe pruebas, no toques el código OAuth» es una indicación de coding agéntico. La segunda funcionará; la primera producirá un monólogo errante.

Esto es el concepto 1 de Prompting de IA (principiante frente a usuario avanzado) con archivos en lugar de PDF. Misma forma de brief; apuestas más altas, porque el modelo actúa sobre él.

Las dos herramientas difieren en sus valores predeterminados, pero no en sus fundamentos. Claude Code es de Anthropic, viene con modelos Claude y está pulido desde el primer uso. OpenCode es open source, agnóstico al modelo (Claude, GPT, Gemini, local) y configurable hasta el nivel de permisos por herramienta. Elige una según tus preferencias de modelo y cuánto control de configuración quieras; el resto de este curso acelerado funciona en ambas.

¿Todavía no tienes ninguna instalada? Toma el one-liner canónico antes de seguir leyendo; las secciones posteriores asumen que puedes presionar una tecla y ver que algo sucede. La autenticación, los plugins de IDE y la resolución de problemas viven en la documentación oficial.

# macOS / Linux / WSL — recommended (auto-updates)
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# macOS Homebrew (no auto-update — run `brew upgrade claude-code` periodically)
brew install --cask claude-code

# npm fallback
npm install -g @anthropic-ai/claude-code

Referencia completa: code.claude.com/docs.

Una vez instalada, abre una terminal en cualquier carpeta en la que quieras trabajar y escribe claude (o opencode). Eso te deja dentro de tu primera sesión. De aquí en adelante, cada concepto de esta página es algo que puedes probar en esa sesión.

2. Modo plan (la función más infrautilizada)

Las implementaciones difieren un poco, pero la idea es idéntica: antes de permitir que el modelo escriba algo, oblígalo a producir un plan escrito que puedas revisar.

Presiona Shift+Tab para recorrer los modos de permisos. La primera pulsación te pone en auto-accept; la segunda te pone en modo plan. En modo plan, el modelo puede leer pero no puede escribir: sin ediciones de archivos, sin comandos de shell.

En cualquiera de los dos casos, el movimiento te ralentiza por dos razones que en realidad aceleran:

1. Atrapa malentendidos antes de que te cuesten. El plan es un contrato. Si el modelo entendió mal el brief, lo ves en el plan, no en un diff de 200 líneas que tienes que revertir.
2. Produce mejor código en la segunda pasada. Un plan escrito de antemano comprime el contexto relevante (rutas de archivos, nombres de funciones, enfoque previsto) en un artefacto limpio en el que puede apoyarse la fase de implementación. Sin un plan, el modelo razona y escribe al mismo tiempo, y el razonamiento pierde.

Regla práctica: cualquier cambio de más de 10 minutos pasa primero por el modo plan. Para funciones más grandes, pide al modelo que guarde el plan en un archivo Markdown (docs/plans/feature-x.md) para poder reanudarlo más tarde o pasarlo a una sesión nueva.

El modo plan combina dos conceptos de prompting en un solo movimiento: piensa con profundidad (concepto 5) con un contrato adjunto, y esquematizar antes de redactar (concepto 7) con un sistema de archivos detrás. Edita el plan, no el diff.

3. Disciplina de permisos

Ambas herramientas piden aprobación antes de actuar. Ambas permiten omitir aprobaciones globalmente: Claude Code tiene --dangerously-skip-permissions, OpenCode permite definir "permission": "allow". No lo hagas, al menos no al principio.

El patrón que funciona: empieza manualmente durante algunas sesiones, observa qué acciones son lo bastante seguras como para aprobarlas automáticamente y luego escríbelo en la configuración.

.claude/settings.json:

{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Write",
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(npm run build)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)"
    ],
    "deny": ["Bash(rm -rf *)", "Bash(npm publish *)", "Bash(git push *)"]
  }
}

Luego instala un ayudante de notificaciones. El patrón que hace que el coding agéntico se sienta rápido no es una ejecución más veloz: es la capacidad de irte. Lanzas una tarea larga, cambias a otro trabajo y vuelves cuando recibes un aviso. Si ejecutas varias sesiones en paralelo (algo real y una mejora real de productividad), las notificaciones son la forma de saber cuál necesita tu atención.

Claude Code tiene ayudantes comunitarios como cc-notify. La app de escritorio de OpenCode envía notificaciones del sistema de forma nativa; para el TUI, escribe un plugin que se suscriba a session.idle y llame a osascript (macOS) o notify-send (Linux).

---

Parte 2: Gestión de contexto

Si solo interiorizas una sección de este curso acelerado, que sea esta. Todo lo que sigue aplica de forma idéntica en ambas herramientas; solo cambian ocasionalmente los nombres de comandos.

Esto es el concepto 4 de Prompting de IA (el contexto es todo el juego) con el volumen al máximo. Allí, un mal contexto te costaba una peor respuesta. Aquí te cuesta una peor respuesta y una peor base de código. Misma disciplina, consecuencias compuestas.

4. El deterioro del contexto es real

La ventana de contexto es la cantidad de texto que el modelo puede sostener a la vez. Los modelos modernos tienen ventanas enormes: cientos de miles de tokens, a veces un millón. Eso suena ilimitado. No lo es.

Dos cosas que debes entender:

El uso real llena la ventana más rápido de lo que crees. Unos cuantos archivos de código, una traza de pila, documentación pegada y una conversación de 30 turnos consumen decenas de miles de tokens antes de que te des cuenta. Tu portátil no muestra un indicador de combustible.

El recuerdo se degrada mucho antes de que la ventana se llene. Los estudios (y tu propia experiencia, si prestas atención) muestran que a medida que sube el conteo de tokens, el modelo empeora de forma visible al recordar detalles específicos de etapas anteriores del contexto. El modelo no olvida exactamente. Simplemente deja de ponderar esa información correctamente. Síntomas: ignora una restricción que declaraste hace 20 mensajes, repite trabajo que ya hizo, alucina una firma de función que antes tenía correcta.

También hay una dimensión financiera. Cada mensaje vuelve a facturar la ventana de contexto completa: una conversación de 50K tokens golpeada veinte veces durante una sesión de depuración equivale a un millón de tokens de entrada, cobrados en cada turno. En APIs por token (la mayoría de configuraciones de OpenCode, API cruda de Anthropic) eso daña la cartera; en niveles de suscripción (Claude Code Pro/Max) aparece como límites de uso. En ambos casos, el contexto inflado drena tu presupuesto justo cuando más necesitas seguir trabajando.

La conclusión no es romántica, pero es práctica: menos contexto, usado deliberadamente, vence a más contexto arrojado con esperanza.

5. /clear y /compact

Dos comandos, dos situaciones.

Borra la conversación y empieza de nuevo. Úsalo al cambiar a una tarea no relacionada. El contexto antiguo es ruido irrelevante que solo confundirá la nueva tarea.

• Claude Code: /clear
• OpenCode: /new (también con alias /clear)

Resume la conversación, conserva el resumen y descarta el resto. Úsalo cuando estás profundo en una misma tarea larga y el contexto se está inflando, pero no puedes perder el hilo.

• Ambas herramientas: /compact (en OpenCode, también con alias /summarize)

Puedes guiar qué debe conservar la compactación: /compact keep the API contract decisions and current file paths.

No son intercambiables. /clear es «nueva conversación». /compact es «misma conversación, menos equipaje». Elegir mal te hace perder contexto importante o conservar contexto inútil.

6. Reanudar sesiones

Las conversaciones se guardan. Ambas herramientas permiten reanudar, misma idea, comando distinto:

• Claude Code: claude --resume y elige una sesión de la lista.
• OpenCode: /sessions (también con alias /resume) dentro del TUI para cambiar entre sesiones guardadas.

Dos patrones donde esto importa:

• Retomar mañana. Las funciones largas rara vez caben en una sola sesión. Reanudar te permite parar sin perder la memoria de trabajo del modelo sobre el proyecto.
• Ejecutar varias ramas. Reanuda cualquier sesión, no solo la última. Puedes tener una sesión profunda en una tarea backend y otra trabajando en frontend, y cambiar entre ellas.

Si tienes un archivo de plan guardado (docs/plans/feature-x.md), incluso una sesión nueva puede ponerse al día con un solo mensaje: «read docs/plans/feature-x.md and continue from step 4». Reanudar es más rápido, pero el archivo de plan es la red de seguridad. (Para el patrón completo: cuándo reanudar, cuándo bifurcar, cuándo recuperarte después de un mal turno, consulta Capítulo 17 § Gestión de sesiones: reanudar, bifurcar y recuperar.)

Rewind existe en ambas, y ambas pueden revertir cambios de archivos. En Claude Code, presiona Esc dos veces (doble toque de Esc), o ejecuta /rewind, para abrir una lista de tus mensajes de usuario anteriores; eliges uno y decides qué restaurar: código, conversación o ambos. Esto funciona porque Claude Code crea checkpoints de las ediciones de archivos del modelo antes de cada prompt. En OpenCode, /undo rebobina el último mensaje de usuario y revierte los cambios de archivos de ese turno; /redo revierte el último /undo. Usa git por debajo, así que tu proyecto debe ser un repositorio git. La diferencia real: el checkpointing de Claude Code rastrea las ediciones de archivos del modelo, pero no los archivos cambiados por comandos bash (un rm o mv que ejecutó el modelo no queda en checkpoint); el /undo respaldado por git de OpenCode, al hacer diff de todo el árbol de trabajo, también atrapa cambios hechos por bash. Ambos te rescatan de un mal prompt; recurre específicamente al /undo de OpenCode cuando el mal turno incluyó comandos shell que tocaron archivos.

Regla rápida de decisión para los tres comandos:

Diagnóstico: cuando el contexto se deteriora

El deterioro del contexto tiene síntomas visibles. Observa cualquiera de estos:

• El modelo empieza a disculparse repetidamente sin avanzar.
• Reescribe el mismo bloque de código sin cambios significativos.
• Hace referencia a variables, archivos o funciones que no existen.
• Contradice una restricción que declaraste antes en la misma sesión.
• Cada respuesta se vuelve más larga, vaga y deferente.

Cuando veas esto, deja de escribir. El impulso de «solo una indicación aclaratoria más» es incorrecto; eso solo añade más contexto contaminado a un contexto que ya está contaminado. El movimiento correcto es reiniciar y volver a dar el brief. Ejecuta /compact si la conversación tiene un núcleo útil que preservar, /clear (o /new de OpenCode) si realmente deberías empezar de nuevo. Cinco minutos de reinicio vencen a una hora discutiendo con un modelo cuyo contexto está contaminado.

Diagnóstico: cuando se disparan los costos de contexto

La disciplina de costos es disciplina de contexto; solo sientes una de ellas en la cartera. Cada turno vuelve a facturar todo el contexto, así que la misma hinchazón que daña el recuerdo también daña la factura. Cinco síntomas cubren la mayoría de las sorpresas de costos que encontrarás, sin importar qué proveedor uses:

Symptom: token usage spiked suddenly mid-session
    → Cause: rules file or system prompt changed, breaking cache hits.
       Fix: revert the change, or accept the cache miss as a one-time cost.

Symptom: each turn costs noticeably more than the previous one
    → Cause: context is growing without bound. Files keep getting read in,
       exploration output is accumulating, conversation is long.
       Fix: /compact with a "keep architectural decisions and current
       file paths" hint.

Symptom: model is over-explaining, producing walls of text
    → Cause: reasoning effort is too high for the task; or the prompt
       invites narration.
       Fix: turn the reasoning effort down; ask for "code only,
       minimal commentary."

Symptom: monthly bill is much higher than expected
    → Cause: running a frontier-tier model on tasks an economy-tier
       model would handle correctly.
       Fix: route mechanical work (codemods, tests, formatting) to the
       cheaper tier; reserve the frontier model for planning and
       hard reasoning. See Part 8 Pattern 1 for the split.

Symptom: cache hits suddenly dropped from ~70% to ~10%
    → Cause: the system prompt, CLAUDE.md, or the first user message
       changed structure. Cache matches prefixes byte-for-byte.
       Fix: stabilize what comes first; let the variable content
       come later.

La mayoría se recupera con un solo cambio de configuración. La mecánica debajo de los cinco es la misma que viene defendiendo la Parte 2: el contexto estable y estrecho es más barato y se recuerda mejor que el contexto desbordado, en cada turno.

---

Parte 3: El archivo de reglas

7. CLAUDE.md / AGENTS.md, bien hecho

Ambas herramientas cargan un archivo Markdown en la raíz del proyecto al contexto al inicio de cada sesión. Es lo más parecido a una indicación de sistema a nivel de proyecto.

No escribas este archivo desde cero. En un proyecto nuevo, ejecuta /init en cualquiera de las herramientas. El modelo escanea tu carpeta y redacta el archivo por ti. Tu trabajo después es eliminar sin piedad las partes que no necesitas: esta es una tarea de edición, no de autoría. Todo lo que sigue trata sobre qué conservar y qué recortar. (Recorrido para principiantes: Capítulo 14 § CLAUDE.md y AGENTS.md. Avanzado: jerarquía de varios archivos, reglas acotadas por glob, convenciones de equipo: Capítulo 17 § La jerarquía de configuración de CLAUDE.md.)

Claude Code usa CLAUDE.md. OpenCode usa AGENTS.md. Para quienes migran, OpenCode también lee CLAUDE.md como fallback cuando no hay AGENTS.md; si ambos archivos existen, AGENTS.md gana y CLAUDE.md se ignora. Si ya mantienes un CLAUDE.md, OpenCode lo recogerá salvo que definas OPENCODE_DISABLE_CLAUDE_CODE=1 para desactivar esa compatibilidad por completo. Para una desactivación parcial, OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1 omite solo el fallback del archivo de reglas y OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 omite solo el fallback de skills. Esta es la mayor ventaja de portabilidad entre las dos herramientas.

El error que casi todos cometen es tratar este archivo como documentación, rellenándolo con panoramas de arquitectura, estándares de código completos y cada rareza de la base de código. El resultado es un archivo de 20.000 tokens que consume tu presupuesto de contexto en cada tarea, incluso en tareas donde el 90% es irrelevante. Recuerda la Parte 2: todo lo que está en este archivo se paga en cada mensaje, sea relevante o no.

El modelo correcto es tabla de contenidos, no enciclopedia. Apunta a menos de ~2.500 tokens. Referencia contexto más profundo que se cargue bajo demanda:

CLAUDE.md. La sintaxis @filename carga automáticamente los archivos referenciados cuando son relevantes:

# Project: my-app

## Stack

Next.js 14, TypeScript, Postgres, Drizzle ORM.

## Commands

- `npm run dev`: start local server
- `npm test`: run vitest
- `npm run db:migrate`: apply migrations

## Critical rules

- Never edit files in `src/generated/`. They're rebuilt by codegen.
- All API routes use the auth middleware in `src/lib/auth.ts`.
- See @docs/conventions.md for naming and folder rules.
- See @docs/db-schema.md for table structure.

La misma forma sirve para proyectos que no son de software. Una persona consultora que escribe informes, un docente que crea planes de clase, una pequeña empresa que gestiona operaciones: un archivo de reglas es «tabla de contenidos, no enciclopedia» sin importar el dominio. Ejemplo para un proyecto de escritura/contenido (CLAUDE.md o AGENTS.md, misma forma):

# Project: blog-and-newsletter

## What this is

A folder of drafts, research, and published posts. I write a weekly newsletter and occasional long-form posts.

## Where things live

- `drafts/`: in-progress posts, one per file
- `research/`: source notes and clippings, organized by topic
- `published/`: shipped posts (do not edit)

## Critical rules

- Never edit anything in `published/`. Fixes go in a new draft with a correction note.
- Footnotes go in `[brackets]` inline; we resolve them to numbered footnotes only at publish time.
- Tone: conversational, no bullet lists in body copy.

Los mismos principios que en la versión my-app: ajustado, declarativo, solo aquello que el modelo no podría inferir mirando la carpeta.

Por cada línea que tengas la tentación de agregar, pregunta: «si elimino esto, ¿el modelo cometerá un error que no cometería de otro modo?». Si no, elimínala. No le digas al modelo que use TypeScript: puede ver los archivos .ts. Dile las cosas que no puede inferir: la carpeta de codegen, el patrón de auth, lo que ya te mordió antes.

Este archivo debe crecer desde fallas reales, no desde fallas imaginadas. Hazle commit a git. Deja que tu equipo le agregue cosas.

---

Parte 4: Personalizar tu herramienta

Hay cuatro tipos de extensión en ambas herramientas. El árbol de decisión es idéntico:

Cada uno es una herramienta de gestión de contexto. Los comandos personalizados y las skills inyectan el contexto correcto bajo demanda. Los hooks y plugins hacen cumplir reglas sin gastar tokens en que el modelo las «recuerde». Los subagentes ponen el contexto en cuarentena para que no se filtre al hilo principal. Mismo problema, formas distintas.

8. Comandos slash

Un comando slash es una indicación guardada con un atajo fácil de recordar. Ambas herramientas los admiten, con formas muy similares.

Una advertencia que conviene señalar desde el principio: los comandos se cargan una vez, al inicio de la sesión. Si creas un comando nuevo a mitad de sesión (lo hayas escrito tú o se lo hayas pedido al modelo), no aparecerá en el autocompletado hasta que salgas y vuelvas a entrar a la CLI. Las dos carpetas de abajo se comportan igual en esto; reinicia la sesión después de cualquiera de las dos.

Archivos Markdown en .claude/commands/ (proyecto) o ~/.claude/commands/ (personal). Ejemplo .claude/commands/review.md:

Review the current diff for:

1. Bugs and edge cases
2. Test coverage gaps
3. Naming and readability
4. Adherence to @docs/conventions.md

Be specific. Quote the lines you're commenting on.

Este comando /review es el concepto 6 de Prompting de IA puesto a trabajar.

A los modelos de IA les gusta estar de acuerdo contigo. Pide «revisa mi diff» sin instrucciones y obtendrás se ve bien, está bien estructurado, buenos nombres, aunque no sea cierto.

La lista de cuatro puntos de arriba lo impide. El modelo ya no puede decir «se ve bien». Tiene que revisar cada punto uno por uno y señalar la línea donde falla.

Ambos se invocan como /review. Ambos admiten $ARGUMENTS (y OpenCode agrega argumentos posicionales $1, $2, etc.). OpenCode también admite !`shell command` para inyectar salida de comandos en la indicación y frontmatter agent: plan / subtask: true para enrutar el comando a un agente específico o ejecutarlo en un subagente. Esto es útil para mantener los flujos de revisión fuera de tu contexto principal.

Un ejemplo no relacionado con software. Un comando /standup para el ritual diario que tienen la mayoría de equipos. Guárdalo como .claude/commands/standup.md (o .opencode/commands/standup.md):

Read yesterday's note in `journal/`. Produce a 4-line standup:

1. What I shipped yesterday (1 line)
2. What I'm working on today (1 line)
3. Blockers (1 line, "none" if clear)
4. One thing I learned (1 line)

Tone: telegraphic. No filler.

Ahora /standup produce una actualización de estado limpia a partir de las notas de ayer cada vez que lo escribes. Misma forma que /review, otro dominio. El mismo truco sirve para /digest (convertir una carpeta de correos en acciones), /draft-reply (escribir una respuesta cordial al correo de esta ruta) o cualquier tarea repetitiva para la que escribas las mismas instrucciones más de dos veces.

La prueba unificadora en ambas herramientas: si te encuentras escribiendo las mismas instrucciones más de dos veces, deberían ser un comando. La versión profunda (estructura de carpetas, frontmatter, paso de argumentos, cuándo promover un comando a skill) está en Capítulo 14 § Enséñale a Claude tu forma de trabajar.

Nota (Claude Code, 2026): Desde 2026, los comandos slash y las skills se han unificado. Los archivos en .claude/commands/ siguen funcionando y aparecerán como comandos slash, pero el trabajo nuevo se está moviendo cada vez más a .claude/skills/ porque las skills admiten más (invocación automática, ejecución en subagentes, filtros de ruta de archivo). Trátalos como un continuo.

9. Skills

Una skill es la hermana mayor de un comando personalizado. Misma idea, expertise empaquetada, pero con tres mejoras importantes que son idénticas entre las dos herramientas:

1. Invocación automática. El modelo lee las descripciones de skills al inicio de cada sesión e invoca la skill correcta cuando una tarea coincide.
2. Revelación progresiva. Una skill tiene un archivo SKILL.md (el punto de entrada) y puede referenciar otros archivos de la misma carpeta. Solo SKILL.md se carga por adelantado; el resto se carga bajo demanda. Es el principio de gestión de contexto convertido en formato de archivo.
3. Controles de frontmatter. El YAML al inicio de SKILL.md configura el comportamiento.

El formato de archivo convergió. Una skill escrita para una herramienta funciona en gran medida en la otra.

.claude/skills/extract-transcript/SKILL.md:

---
name: extract-transcript
description: Extract a clean transcript from a YouTube video URL. Use when the user provides a YouTube link and asks for the transcript, captions, or text of the video.
---

# Extract YouTube transcript

1. Take the URL from the user's message.
2. Run `yt-dlp --skip-download --write-auto-sub --sub-format vtt "$URL"`.
3. Convert the VTT to plain text: strip timestamps, deduplicate overlapping captions.
4. Save to `transcripts/{video-id}.txt`.

For formatting conventions (paragraph breaks, speaker labels), see `references/style.md`.

Sí, son byte por byte idénticas. OpenCode también lee ~/.claude/skills/ y .claude/skills/ como fallbacks, así que cualquier skill que ya hayas escrito para Claude Code funciona en OpenCode sin cambios.

La descripción es el campo más importante: es lo que el modelo usa para decidir si la skill aplica. Las descripciones vagas («ayuda con videos») se activan para todo; las específicas («Use when the user provides a YouTube link...») se activan solo cuando corresponde.

Mantén el propio SKILL.md corto: menos de ~200 líneas es una buena regla. Empuja la profundidad a archivos de referencia en la misma carpeta y enlázalos. Así una tarea rápida solo paga por el resumen; una tarea profunda puede cargar las referencias que necesita. (Para el recorrido fundacional (qué es una skill, cuándo se activa, cómo funciona la revelación progresiva), consulta Capítulo 14 § El concepto detrás de las skills y Construir tus propias skills. Para la variante de equipo/CI (campos de frontmatter, activación acotada por glob), consulta Capítulo 17 § Skills personalizadas con frontmatter.)

No escribas skills desde cero. Claude Code incluye una skill skill-creator que crea el esqueleto de skills correctamente. Gracias al mismo fallback, instálala una vez y ambas herramientas pueden invocarla. (Nota: el descubrimiento de archivos se comparte, pero los cuerpos de skills que referencian herramientas específicas de Claude Code pueden necesitar ediciones ligeras para ejecutarse limpiamente en OpenCode. Para nuevos agentes, que son un concepto separado en OpenCode, usa opencode agent create para un scaffolder interactivo de agentes.)

Otro patrón: encadena skills pequeñas, no construyas monolitos. Una skill de «resumen semanal de contenido» que investiga, escribe, formatea y revisa de una vez es más difícil de mantener y peor en cada paso que cuatro skills separadas (research, draft, format, review) que se pasan el trabajo entre sí. El traspaso suele mediarse por el sistema de archivos: research escribe su salida en tmp/research.md, luego draft recibe la instrucción de leerlo; draft escribe en tmp/draft.md, y así sucesivamente. También puedes simplemente pedir al modelo que las ejecute en secuencia («usa la skill de investigación y luego redacta una publicación a partir de la salida»), pero el pipeline basado en archivos es más duradero entre /clear y más fácil de depurar. En ambos casos, cada skill se mantiene enfocada en su propio paso. La reutilización es útil, pero la victoria real es el aislamiento de contexto por paso: la skill format no necesita cargar las notas de investigación, y la skill research no necesita conocer las convenciones de formato. El mismo principio que los subagentes, aplicado a una granularidad menor.

10. Hooks (Claude Code) / Plugins (OpenCode)

Las skills son probabilísticas: el modelo decide si las invoca. Los hooks y plugins son deterministas: se disparan en eventos específicos, cada vez, sin juicio del modelo.

Misma idea, maquinaria distinta. Aquí es donde las dos herramientas divergen más. Una nota de nombres antes de las pestañas: Claude Code también tiene otra cosa que llama «plugins» (paquetes que agrupan comandos, skills y hooks). No es de eso de lo que trata esta sección. Aquí, «hook» siempre significa el hook de ciclo de vida de Claude Code, y «plugin» siempre significa el módulo de eventos de OpenCode. Ocupan el mismo lugar en cada herramienta: la salvaguarda determinista.

Hooks son comandos de shell conectados a eventos de ciclo de vida en .claude/settings.json. Los eventos grandes: SessionStart, UserPromptSubmit, PreToolUse (el código de salida 2 bloquea), PostToolUse. La estructura tiene tres niveles: el evento (PreToolUse), un grupo matcher que filtra por nombre de herramienta (Bash) y el handler que se ejecuta. El campo if del handler acota más al hacer match con el comando real, así el handler solo se lanza cuando hace falta. Ejemplo: bloquear rm -rf sin importar cómo se sienta el modelo:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm -rf *)",
            "command": "echo 'Blocked dangerous command' >&2; exit 2"
          }
        ]
      }
    ]
  }
}

El filtro if: "Bash(rm -rf *)" es lo que hace el match; cuando el command se ejecuta, la llamada de herramienta ya es un rm -rf conocido, así que el comando solo tiene que negarse (el código de salida 2 bloquea). Cuando un hook realmente necesita inspeccionar la entrada de la herramienta (no solo hacer match), Claude Code pasa esa entrada como JSON por stdin, que el comando lee con jq. Lo verás en el ejemplo de marcadores de posición de abajo.

Un ejemplo no relacionado con software: no publiques borradores que todavía tengan marcadores de posición. Supón que a veces dejas marcadores [TODO] o [FIX] en borradores y olvidas resolverlos antes de publicar. Un hook puede bloquear cualquier escritura dentro de published/ si el archivo todavía contiene un marcador:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -e '(.tool_input.file_path | test(\"/published/\")) and (.tool_input.content | test(\"\\\\[TODO\\\\]|\\\\[FIX\\\\]\"))' >/dev/null && { echo 'Refusing to publish draft with TODO/FIX markers' >&2; exit 2; }; exit 0"
          }
        ]
      }
    ]
  }
}

Este necesita mirar dentro del archivo, así que hace más que el bloqueo de rm -rf. El matcher captura cada Write; el command pasa el JSON que Claude Code entrega por stdin directamente a una prueba de jq que revisa dos cosas a la vez y bloquea solo cuando ambas son ciertas: el file_path está bajo published/ y el content contiene un marcador de posición. Un [TODO] en un archivo drafts/ pasa; un archivo limpio en published/ pasa; solo se detiene con código de salida 2 un archivo marcado que va hacia published/. El modelo escribe el archivo, el hook revisa, y si se filtró un marcador, el modelo debe resolverlo antes de que el archivo se publique.

El intercambio es real: los plugins de OpenCode son más capaces; los hooks de Claude Code son más simples.

Cualquiera que pueda escribir bash puede escribir un hook de Claude Code en cinco minutos y llevarlo a un repositorio sin toolchain de Node. Los plugins de OpenCode necesitan Bun o Node, dependencias npm y fluidez en TypeScript o JavaScript. Para una comprobación de una línea («bloquear rm -rf»), shell gana por costo. Para cualquier cosa que necesite logging estructurado, trabajo asíncrono o varias suscripciones a eventos, el módulo JS/TS es realmente más limpio. Elige la herramienta cuyas restricciones coincidan con lo que estás construyendo.

Un patrón útil de gente que ejecuta estas herramientas en bases de código de producción: no bloquees al escribir, bloquea al hacer commit. Deja que el modelo termine su trabajo (interrumpir a mitad de edición lo confunde) y ejecuta un hook/plugin en el paso de commit que compruebe que las pruebas pasan, los tipos verifican y el formateador está satisfecho. Si algo falla, fuerza al modelo a volver a un bucle de corrección.

Usa hooks/plugins para las cosas que necesitas que sean verdaderas el 100% de las veces. Usa skills para las cosas que te gustaría que el modelo recordara la mayor parte del tiempo.

11. Subagentes

Un subagente es una instancia aislada de agente con su propia ventana de contexto. Le delegas una tarea; trabaja en privado; devuelve un resumen. Sus búsquedas de archivos, volcados de logs y lecturas exploratorias nunca tocan tu hilo principal.

Por qué importa esto, en términos de gestión de contexto: lo más contaminante que puedes hacerle al contexto es «explorar la base de código para encontrar dónde ocurre X». Ese tipo de tarea atrae decenas de archivos al contexto, la mayoría de los cuales no necesitas. Hacerlo en un subagente significa que tu sesión principal ve solo la conclusión («X ocurre en src/services/billing.ts:142»), no la búsqueda.

Ambas herramientas incluyen un subagente Explore de solo lectura (entre otros; OpenCode también incluye un subagente General para trabajo delegado más amplio) que maneja exploración de bases de código sin contaminar tu hilo principal. En Claude Code, el modo plan delega automáticamente a Explore: casi siempre lo usarás sin pensarlo, y el propio modelo incluso puede entrar en modo plan por sí mismo cuando se lo piden. En OpenCode, el agente Plan puede invocar subagentes automáticamente de la misma forma (la delegación a subagentes es una capacidad normal del agente primario), o puedes llamarlo explícitamente con @explore; entrar al propio modo Plan, sin embargo, es una acción deliberada del usuario vía Tab.

Para subagentes personalizados:

.claude/agents/doc-fetcher.md:

---
name: doc-fetcher
description: Fetches and summarizes external library documentation. Use when the user references a library and we need to understand its current API.
tools: WebFetch, Read, Write
---

You are a documentation researcher. Given a library name and a topic, fetch the official docs, extract only the API surface relevant to the topic, and write a focused summary to `tmp/docs-{library}.md`. Don't paste full pages: extract the patterns and signatures we need.

Un ejemplo no relacionado con software: un subagente de investigación. Supón que tienes una carpeta de PDF largos (informes sectoriales, contratos legales, artículos académicos) y quieres que el agente extraiga un resumen enfocado sin arrastrar todo el documento a tu hilo principal:

---
name: pdf-summarizer
description: Reads a long PDF and writes a focused summary. Use when the user references a PDF and wants the key points without dumping the whole document into the conversation.
tools: Read, Write
---

You are a research summarizer. Given a PDF path and a question, read the document, extract only the passages relevant to the question, and write a focused summary to `tmp/summary-{pdf-name}.md`. Do not paste full pages: pull out the patterns, claims, and quotes the user actually needs.

Misma forma que el doc-fetcher anterior, otro dominio. El PDF de 200 páginas se queda fuera de tu conversación principal; solo vuelve la respuesta.

La invocación es igual en ambas herramientas. Ambas invocan automáticamente según la descripción del subagente (este es el camino que más usarás: escribe una buena descripción y el modelo elige el ayudante correcto cuando una tarea coincide). Ambas también admiten invocación explícita con @subagent-name en el prompt; OpenCode lo muestra de forma más prominente en el autocompletado, pero Claude Code lo acepta igual. Usa invocación automática por defecto; recurre a @name cuando quieras asegurarte de que se ejecute un subagente específico (o cuando la descripción sea ambigua entre varios candidatos).

La regla general, idéntica en ambas: si una tarea implica mucha lectura que no será relevante para la respuesta final, pertenece a un subagente. (Capítulo 14 § Subagentes y orquestación muestra cómo escribir los tuyos y encadenarlos.)

---

Parte 5: Conectarse al mundo

12. MCP, usado con honestidad

MCP (Model Context Protocol) es una forma estandarizada de exponer herramientas externas (Slack, Notion, tu base de datos, GitHub, lo que sea) al agente. Claude Code y OpenCode admiten MCP usando el mismo protocolo. Un servidor escrito para una funciona en la otra.

La forma de configuración difiere solo cosméticamente:

Normalmente se configura mediante la CLI (claude mcp add ...) o en .claude/settings.json.

La promesa es real en ambas herramientas: conectar el agente a tus herramientas significa que puede actuar sobre tu trabajo, no solo hablar de él. Leer un ticket de Linear, publicar una actualización en Slack, consultar réplicas de lectura de producción: todo razonable.

La calificación honesta, que aplica en ambas herramientas: MCP no siempre es la respuesta correcta, y algunos usuarios experimentados se han alejado del uso intensivo de MCP en favor de CLIs simples. El razonamiento: un servidor MCP abstrae la herramienta subyacente en un conjunto fijo de operaciones, y cada operación paga un costo de contexto por adelantado en descripciones de herramientas. Una CLI es simplemente una CLI: el agente puede leer su --help, componer flags, canalizar salidas e improvisar. Para herramientas sin estado (GitHub, AWS, Jira), las CLIs gh, aws y jira suelen ser más flexibles que sus equivalentes MCP.

La documentación de OpenCode lo dice explícitamente y advierte que los servidores MCP añaden a tu contexto y que debes tener cuidado con cuáles activas: "Certain MCP servers, like the GitHub MCP server, tend to add a lot of tokens and can easily exceed the context limit."

Un modelo de trabajo útil: usa MCP para servicios con estado o con autenticación pesada donde la capa de protocolo realmente hace trabajo (Playwright es el ejemplo canónico: gestionar una sesión de navegador es difícil). Usa CLIs para todo lo demás. No instales diez servidores MCP porque existen; instala uno cuando haya una razón real.

---

Parte 6: Un ejemplo trabajado completo, dos veces

Esta es la sección a la que apunta el resto del curso acelerado. Una tarea realista, todos los conceptos, ambas herramientas. Las mismas ocho decisiones, mostradas una vez en Claude Code y una vez en OpenCode, lado a lado, para que veas lo poco que realmente cambia.

No escribirás ni una línea de código. Cualquiera con un portátil y una carpeta de archivos puede seguirlo: un gerente, un docente, una pequeña empresa, un estudiante. La tarea usa notas de reuniones de un equipo pequeño, pero funciona igual para un comité escolar, un grupo voluntario, una práctica freelance o cualquier grupo de personas que guarda notas y necesita extraer acciones.

Tu tarea

Tienes una carpeta llamada notes/ con cinco archivos: las notas de reuniones de tu equipo de la semana pasada. Son un desastre. Algunas reuniones listan acciones bajo ## Action Items. Algunas usan ## Todos. Una usa ## todo en minúsculas. Algunas esconden acciones dentro de otras secciones. Algunos bullets están marcados [private] o [HR] y no deberían ir a ningún lugar público.

Quieres un archivo limpio, weekly-actions.md, que liste cada acción, agrupada por responsable, con un enlace a la reunión de la que salió. Nada privado debe filtrarse. Nada debe perderse. Y si alguna fecha límite cae en un feriado público, quieres una advertencia.

📁 Obtén primero los cinco archivos iniciales (haz clic para expandir)

Copia esto en una carpeta notes/ antes de empezar. El ejemplo está diseñado alrededor de ellos: cada archivo cumple un rol específico, así que si omites uno, uno de los pasos de abajo deja de funcionar. (¿Prefieres omitir la preparación de carpeta? Pega los cinco archivos directamente en el chat de tu herramienta y pídele que los trate como el contenido de notes/.)

notes/2026-12-07-monday-team-meeting.md

# Monday Team Meeting - 2026-12-07

Attendees: @sara, @diego, @priya, @marcus

## Discussion

Reviewed last month's customer satisfaction scores. Renewals are down slightly in the small-business segment.

## Action Items

- @sara: draft a revised welcome email by Dec 18
- @diego: check spam-folder reports with our email vendor by Dec 16
- @marcus: pull renewal numbers for the last two quarters and share with the team
- @sara: finalize offer terms for the new account manager [HR]

notes/2026-12-08-customer-feedback.md

# Customer Feedback Review - 2026-12-08

Attendees: @sara, @amara, @marcus

## Summary

Read through the top twenty customer comments from last week. Three themes came up: pricing page is confusing, the call-back service is slow, and the FAQ on the website is out of date.

## Todos

- rewrite the pricing page in plain language
- @marcus: log a complaint with the call center vendor about response times
- look into why the FAQ has not been updated in six months
- @amara: draft a customer note explaining the upcoming changes
- review all printed brochures for outdated photos and pricing

notes/2026-12-08-q1-planning.md

# Q1 2027 Planning - 2026-12-08

Attendees: @sara, @diego, @amara, @lukas

## Initiatives

We walked through the four candidate initiatives for Q1.

### Year-end promotional campaign

Time-bound: wraps before the holiday break.

#### Action Items

- @amara: finalize the year-end promotional brochure by Dec 25
- @lukas: confirm placement with paid media partners by Dec 20

### Onboarding overhaul

Top priority next quarter.

## todo

- @diego: write the project brief by Jan 15
- @sara: own messaging and visual direction

notes/2026-12-09-all-hands-prep.md

# All-Hands Prep - 2026-12-09

Attendees: @sara, @marcus

## Agenda

Walked through the December all-hands agenda. Most slides are in good shape; a couple still need owners.

## Next Steps

- @marcus: set up the video call and record a practice run
- @sara: finalize the Q4 numbers slide
- @sara: prepare the bonus and compensation talking points [private]
- @marcus: book the venue for the team holiday dinner

notes/2026-12-11-vendor-review.md

# Vendor Review - 2026-12-11

Attendees: @sara, @amara, external partner

## Summary

Confidential contract negotiation with our printing and fulfillment vendor. Details under NDA.

## Action Items

- @sara: circulate the revised contract to the vendor [private]
- @amara: draft the internal announcement once terms are agreed [private]
- @sara: review the legal redlines on the new pricing schedule [private]

Cómo leer esta sección

Cada una de las ocho decisiones de gestión de contexto de este capítulo recibe un paso numerado abajo. Cada paso tiene la misma forma:

• Qué haces: lo exacto que escribes o presionas
• Por qué: un párrafo sobre qué te compra esa decisión
• Qué cambia en OpenCode: la versión para la otra herramienta

Si un paso dice «idéntico en OpenCode», puedes saltar esa línea y seguir.

---

Decisión 1: Recortar el archivo de reglas

Qué haces (Claude Code). Abre Claude Code en la carpeta del proyecto. Ejecuta /init. Crea un archivo llamado CLAUDE.md que es demasiado largo. Borra la mayor parte. Deja solo esto:

# weekly-rollup

## Layout

- `notes/`: meeting notes, one file per meeting
- `weekly-actions.md`: the rollup we are creating
- `plans/weekly-rollup-plan.md`: the plan we will save and reuse

## Critical rules

- Action items can appear under `## Action Items`, `## Todos`, `## Next Steps`, or `## todo` (one meeting uses lowercase). Look at all heading levels, not just the top.
- Owners are written as `@name`. Items with no owner go to an "Unassigned" section.
- Never include any bullet tagged `[private]` or `[HR]`.

Por qué. Este archivo se lee al inicio de cada mensaje. Todo lo que pones aquí te cuesta, en cada turno. Por eso lo mantienes corto: solo las cosas que el modelo no puede deducir mirando la carpeta. La regla de privacidad, en especial, es algo que no puede adivinar.

Qué cambia en OpenCode. El archivo se llama AGENTS.md en lugar de CLAUDE.md. Mismo contenido, mismo propósito. (Y si ya tienes un CLAUDE.md de antes, OpenCode también lo leerá; no necesitas renombrar nada.)

---

Decisión 2: Planificar antes de escribir

Qué haces (Claude Code). Presiona Shift+Tab dos veces. Esto pone al modelo en modo plan: puede leer tus archivos, pero no puede cambiar nada. Luego escribe:

Read every file in notes/. Produce weekly-actions.md grouped by
owner. For each item include the action, the source filename, and
the meeting date. Skip anything tagged [private] or [HR]. Do not
lose any action items.

El modelo piensa durante un minuto y vuelve con un plan escrito que describe exactamente lo que pretende hacer.

Por qué. Esta es la función más infrautilizada en cualquiera de las dos herramientas. Leer un plan toma 30 segundos. Revertir un cambio malo toma mucho más. Siempre quieres el plan primero. (Fundamentos: Capítulo 14 § Hola Claude introduce el modo plan en ambas herramientas; Capítulo 17 § Modo plan frente a ejecución directa profundiza en cuándo compensa y cuándo solo ralentiza.)

Qué cambia en OpenCode. Presiona Tab para cambiar del agente Build al agente Plan. El brief y el resultado son idénticos; solo cambia la tecla.

---

Decisión 3: Cuestionar el plan

Qué haces (Claude Code). Lee el plan con cuidado. Probablemente tendrá dos errores.

El primero: solo mencionará los encabezados de primer nivel (## Action Items, ## Todos). Pero uno de tus archivos de reunión (las notas de planificación de Q1) esconde acciones dentro de ### Year-end promotional campaign, con un #### Action Items debajo. El plan las perdería.

El segundo: no dirá qué hacer con acciones que no tienen responsable (sin @name al lado, como «rewrite the pricing page in plain language» en el archivo de comentarios de clientes). Esas desaparecerían en silencio.

Lo corriges:

Two changes. (1) Look at all heading levels, not just the top.
Some action items live under sub-headings. (2) Items without an
owner go to an "Unassigned" section at the bottom; never drop
them.

El modelo actualiza el plan. Le pides que guarde el plan final en plans/weekly-rollup-plan.md para reutilizarlo el próximo viernes.

Por qué. El plan es un contrato. Atrapas problemas aquí, cuando no cuestan nada, no después de que el archivo ya fue escrito y tienes que limpiarlo.

Qué cambia en OpenCode. Idéntico.

---

Decisión 4: Dejar que haga el trabajo

Qué haces (Claude Code). Presiona Shift+Tab para salir del modo plan. Dile al modelo que continúe.

Lee los cinco archivos. Escribe weekly-actions.md. Agrupa acciones por responsable. Descarta los bullets [private] y [HR]. Coloca los elementos huérfanos en una sección Unassigned. Ves cómo ocurre.

Revisa dónde terminó el archivo

weekly-actions.md debería estar en la raíz del proyecto, junto a notes/, no dentro de notes/. Si el modelo lo escribió dentro de notes/, esa es la señal de que falta o se ignora la sección Layout de CLAUDE.md de la Decisión 1. Arréglalo ahora: la red de seguridad de la Decisión 6 busca nombres de archivo en un weekly-actions.md de raíz, y no encontrará un archivo en el lugar equivocado.

Qué cambia en OpenCode. Se te pedirá aprobar cada escritura de archivo la primera vez. Puedes decir que sí, o puedes preaprobar acciones comunes en opencode.json para que las ejecuciones posteriores sean más fluidas.

---

Decisión 5: Resumir cuando la conversación se alarga

Qué haces (Claude Code). La conversación ya es larga. El modelo leyó cada nota de reunión, y mucho de ese contenido crudo sigue en su memoria, incluidos algunos bullets privados que omitió correctamente. Ya no necesitas nada de eso. Escribes:

/compact keep the heading rules, the owner list, and the
private/HR exclusion rule

La conversación se resume hasta quedar solo con las partes que le pediste conservar.

Por qué. Una conversación larga y desordenada empeora al modelo, no lo mejora. También cuesta más. Limpias lo que ya no es relevante, especialmente contenido privado, que no debería permanecer en memoria más de lo necesario.

Qué cambia en OpenCode. Comando idéntico.

---

Decisión 6: Poner una red de seguridad para el commit

Qué haces (Claude Code). Antes de guardar tu trabajo en git, quieres asegurarte de que no se omitió accidentalmente ninguna reunión. Agregarás un hook de Claude Code: una pequeña red de seguridad que se ejecuta automáticamente antes de cada commit.

No le pidas al modelo que escriba este: pégalo tú

Este es el único lugar del capítulo donde pegas un bloque de configuración tú mismo en lugar de dejar que el modelo lo escriba. Hay dos razones, ambas aprendidas por las malas.

(1) «Hook» es ambiguo. Si le dices al modelo «crea un hook», Claude Code puede recurrir a un git hook (un archivo en .git/hooks/) en lugar de un hook de Claude Code (una entrada en .claude/settings.json). Son cosas distintas; quieres la segunda.

(2) El modelo intentará ser ingenioso y romperá la red de seguridad en silencio. Tu CLAUDE.md dice que se omitan elementos [private] y [HR]. Si preguntas de forma vaga, el modelo lee esa regla y «útilmente» hornea el mismo filtro dentro del script del hook, lo que significa que la reunión de vendor-review (todos los bullets son [private]) se ignora discretamente y el hook nunca se dispara. El punto completo del hook es atrapar ese caso. Pedirle al modelo que escriba su propio perro guardián contra reglas que ya le dijiste que respete es una batalla perdida.

El movimiento seguro es simplemente pegar la configuración.

Abre .claude/settings.json (crea el archivo si no existe) y pega esto exactamente:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git commit *)",
            "command": "for f in notes/*.md; do grep -q \"$(basename $f)\" weekly-actions.md || { echo \"Missing: $f\" >&2; exit 2; }; done"
          }
        ]
      }
    ]
  }
}

En lenguaje llano: el matcher dice «vigila la herramienta Bash»; el if lo acota solo a comandos git commit; el command recorre cada archivo .md en notes/, busca su basename dentro de weekly-actions.md y, si algún archivo no se menciona, sale con código 2 (lo que bloquea el commit). Sin filtros de contenido, sin comprobaciones [private], sin excepciones. Solo nombres de archivo. Ese es todo el punto.

Ahora dile al modelo que haga commit. La red de seguridad se dispara: Missing: notes/2026-12-11-vendor-review.md. La razón es lógica: cada acción de esa reunión estaba marcada [private], y tus reglas de la Decisión 1 dicen que se descarten; por eso, cuando se construyó el rollup, no había nada que escribir desde ese archivo y el nombre del archivo nunca apareció. El hook no sabe nada de eso; solo ve que el archivo no se menciona, y bloquea.

El modelo lee el error y parchea el rollup con una entrada de marcador que nombra el archivo explícitamente, por ejemplo:

## From 2026-12-11-vendor-review.md

- All items confidential — see meeting owner.

El nombre de archivo ahora está presente en weekly-actions.md, el grep del hook lo encuentra y el commit pasa. Nada privado se filtró al rollup; la pista de auditoría queda intacta.

No hiciste nada durante este bucle. La red de seguridad atrapó el error y el modelo se corrigió solo.

Por qué. Las cosas que quieres que sean verdaderas cada vez no deberían depender de que el modelo las recuerde. Deberían comprobarse automáticamente. Y la comprobación debería vivir en un lugar que el modelo no pueda reescribir en silencio para complacerse a sí mismo: por eso este se pega, no se pide.

Qué cambia en OpenCode. OpenCode llama a esto plugins en lugar de hooks, y se escriben como un archivo JavaScript pequeño. Misma idea, mismo resultado, misma lógica de pegar y no pedir. Crea .opencode/plugins/check-rollup-complete.js (puede que la carpeta aún no exista) y pega esto:

// .opencode/plugins/check-rollup-complete.js
import { readdirSync, readFileSync } from "fs";

export const CheckRollupCompletePlugin = async ({ $ }) => {
  return {
    "tool.execute.before": async (input, output) => {
      if (
        input.tool === "bash" &&
        output.args.command?.startsWith("git commit")
      ) {
        const rollup = readFileSync("weekly-actions.md", "utf8");
        const missing = readdirSync("notes")
          .filter((f) => f.endsWith(".md"))
          .filter((f) => !rollup.includes(f));
        if (missing.length) {
          throw new Error(`Missing from rollup: ${missing.join(", ")}`);
        }
      }
    },
  };
};

Misma forma: lista cada archivo en notes/, comprueba que cada basename esté en el rollup y lanza un error si falta alguno. Sin filtro [private] dentro. El comportamiento es idéntico al de Claude Code: archivo faltante, commit bloqueado, modelo se corrige.

El material profundo sobre hooks/plugins (códigos de salida, sintaxis de matcher, lista completa de eventos) está en Capítulo 14 § Hooks y extensibilidad (y Plugins: ponerlo todo junto para el lado de OpenCode).

---

Decisión 7: Enviar una tarea lateral a un ayudante

Qué haces (Claude Code). Algunas acciones tienen fechas límite como «by Dec 25» o «before year-end». Quieres marcar cualquiera que caiga en un feriado público para que los responsables puedan ajustarla. Escribes:

Use the doc-fetcher helper to look up the 2026 international
public holidays list and write the dates to tmp/holidays-2026.md.

Un ayudante separado se va, obtiene una página larga de la web, extrae solo las fechas y las escribe en un archivo pequeño. Tu conversación principal solo ve el archivo pequeño, no la página larga.

Luego el modelo lee las fechas límite del rollup, las cruza con los feriados y agrega una nota: ⚠ falls on Christmas Day junto a la fecha límite del brochure.

Por qué. Ir a buscar una página web directamente habría volcado páginas de texto en tu conversación, volviéndola lenta y desordenada. Enviar a un ayudante a hacerlo significa que solo vuelve la respuesta, no el ruido.

Qué cambia en OpenCode. Puedes escribir @doc-fetcher directamente para llamar al ayudante; aparece en el autocompletado. Mismo ayudante, más fácil de invocar.

---

Decisión 8: Guardar lo que aprendiste

Qué haces (Claude Code). Esto es un ritual de viernes; lo harás todas las semanas. No quieres recordar todas estas decisiones el próximo viernes. Así que le pides al modelo que las guarde como una skill:

Create a skill at ~/.claude/skills/weekly-meeting-rollup/SKILL.md
based on what we just did. Include: the four heading variants,
the all-headings rule, the private/HR exclusion, the Unassigned
section, the missing-file check, and the holiday cross-reference.

El próximo viernes, escribirás «do the weekly rollup» y el modelo cargará esta skill automáticamente. Cada decisión que tomaste hoy, aplicada gratis.

Por qué. Esta es la recompensa. El trabajo que hiciste esta semana no fue solo para esta semana; le enseñó al modelo a hacer esta tarea para siempre.

Qué cambia en OpenCode. La skill se guarda en una carpeta ligeramente distinta (~/.config/opencode/skills/...), pero el archivo en sí es byte por byte idéntico. Cópialo entre las dos herramientas y funciona en ambas. Esa es la prueba más fuerte posible de la tesis del capítulo.

---

Qué acaba de pasar

Vuelve a mirar los ocho pasos. Ninguno requirió que escribieras código. Ninguno requirió que supieras qué es una API. Lo que realmente hiciste fueron ocho actos pequeños de gestionar la atención del modelo: decirle qué mirar, cuándo planificar, cuándo olvidar, cuándo delegar, cuándo dejar de confiar en sí mismo y cuándo recordar.

Ese es todo el capítulo.

Y mira lo poco que cambió entre las dos herramientas:

• Un nombre de archivo distinto para el archivo de reglas (CLAUDE.md frente a AGENTS.md)
• Una tecla distinta para entrar en modo plan (Shift+Tab frente a Tab)
• Un lenguaje distinto para el archivo de red de seguridad (JSON frente a JavaScript)
• Una carpeta distinta para la skill al final (pero el mismo archivo)

Eso es todo.

El pensamiento es la herramienta. Las configuraciones son decoración. Aprende a pensar así y tus habilidades sobrevivirán a la herramienta que gane.

---

Parte 7: Dónde ejecutarlo y cómo crecer

13. Terminal, IDE o escritorio

Ambas herramientas se ejecutan en varios lugares.

Claude Code: terminal, plugins de VS Code / JetBrains, la app de escritorio de Claude y variantes alojadas en la nube para trabajo asíncrono.

OpenCode: terminal (el TUI es el producto principal), app de escritorio (en beta en macOS/Windows/Linux), extensión de IDE mediante soporte ACP, interfaz web mediante el SDK, además de integraciones con GitHub y GitLab.

Elige según lo que estés haciendo. Para desarrollo desde cero con mucha edición de archivos, los plugins de IDE son difíciles de superar: ves el diff suceder. Para tareas largas donde quieres notificaciones y sesiones paralelas, la terminal está bien. Para trabajo que no es de coding y jobs programados, las apps de escritorio son más agradables.

La recomendación fuerte, en cualquiera de las dos herramientas: empieza en la terminal o en un plugin de IDE. Una vez que entiendas qué ocurre por debajo (qué archivos lee el modelo, qué comandos ejecuta, qué decisiones toma), cualquier otra interfaz se vuelve una envoltura delgada que puedes leer. Si empiezas en una UI muy abstracta, te costará depurar cuando las cosas se tuerzan, porque no sabrás qué puede torcerse.

14. Construir una biblioteca personal de contexto, lentamente

Cuando tengas algunos proyectos usando cualquiera de las dos herramientas, notarás que escribes cosas parecidas en cada archivo de reglas: tu estilo de código, tus convenciones de commit, tu filosofía de pruebas. Deja de copiar y pegar.

Pon las partes compartidas en tu configuración de inicio y referéncialas desde el archivo de reglas de cada proyecto:

~/.claude/:

# CLAUDE.md

@~/.claude/style/typescript.md
@~/.claude/style/commits.md

## Project-specific

[only the things unique to this project]

La misma idea sirve para skills. Una skill commit-message o code-review en ~/.claude/skills/ (que OpenCode también lee) o ~/.config/opencode/skills/ está disponible automáticamente en todas partes.

La disciplina: no construyas esto de antemano. Es tentador dedicar un sábado a diseñar la configuración personal perfecta. Resiste. Cada entrada debería venir de una falla real: un momento en que el modelo se equivocó o escribiste lo mismo por tercera vez. Construye desde el arrepentimiento, no desde la imaginación. La biblioteca que crece desde fricción real es pequeña y útil; la diseñada por adelantado es grande e ignorada.

15. Memoria más allá de lo básico

La reanudación integrada + un archivo de reglas bien cuidado cubre a la mayoría de personas la mayoría del tiempo. Si necesitas más (buscar en conversaciones pasadas, notas persistentes de proyecto, conocimiento que sobrevive a /clear), tienes opciones:

• Una carpeta notes/ en el proyecto, con el agente escribiendo notas estructuradas después de trabajos importantes. Barata, duradera, fácil de buscar con grep. Sorprendentemente eficaz. Funciona en ambas herramientas sin ninguna configuración.
• Un servidor MCP de memoria. Existen varios; le dan al agente una API explícita de guardar/recuperar. Funciona en ambas herramientas.
• Búsqueda vectorial sobre tu historial de conversación para consultas del tipo «¿ya resolví esto antes?». Existen implementaciones específicas de herramientas; revisa las páginas del ecosistema.

Elige según lo que realmente quieras recordar. Si es «decisiones y gotchas para esta base de código», una carpeta notes/ basta. Si es «todo lo que le he dicho al modelo en todos los proyectos», quieres algo más pesado. No instales infraestructura para un problema que no tienes.

---

Parte 8: Componer Claude Code y OpenCode

Las partes anteriores trataron Claude Code y OpenCode como alternativas: elige una, apréndela. Ese encuadre fue deliberado: cada concepto debe tener sentido en cualquiera de las dos herramientas antes de complicar las cosas. Pero una vez que tienes los fundamentos, la pregunta más interesante es la composición. Dos herramientas usadas juntas en el mismo proyecto no son solo un fallback por si una falla. Son una forma distinta de trabajar, y la mecánica de usarlas juntas merece su propia parte.

El sustrato: git worktrees

Antes de los patrones, la capa operativa que hace que esto sea seguro.

Ambas herramientas admiten sesiones paralelas, pero si dos agentes editan el mismo archivo al mismo tiempo, la última escritura gana y terminas con diffs pisados. La solución son git worktrees: cada worktree es una copia checked-out de tu repositorio en una rama distinta, compartiendo el mismo directorio .git. Dos agentes en dos worktrees pueden editar archivos distintos en paralelo sin tocar nunca la misma ruta.

# from your main repo directory
git worktree add ../myproject-backend feature/auth-core
git worktree add ../myproject-frontend feature/auth-ui

# now you have two parallel working dirs, two branches
cd ../myproject-backend && claude
# in another terminal
cd ../myproject-frontend && opencode

Elimina worktrees con git worktree remove ../myproject-backend cuando el trabajo termine.

La regla de edición de archivos, en tres niveles:

Patrón	Veredicto
Dos sesiones editan el mismo archivo simultáneamente	Malo: la última escritura gana y se pierden las ediciones de la otra sesión
Dos sesiones editan directorios distintos	Bueno: sin contención, la aceleración paralela es real
Una sesión edita, hace commit y entrega a la otra	Aceptable: el commit es el artefacto de traspaso

Regla práctica: empieza con una sesión por tarea. Agrega una segunda solo cuando puedas señalar claramente qué archivos posee cada sesión. El costo cognitivo de cambiar entre dos sesiones agénticas es real; solo gana cuando el trabajo realmente se particiona.

La capa compartida que hace que todo esto funcione son las reglas y skills del proyecto. Ambas herramientas leen el mismo CLAUDE.md y el mismo directorio .claude/skills/ (los conceptos 7 y 9 cubren esto). Una fuente de verdad para las convenciones del proyecto; dos herramientas consumiéndola.

Patrón 1: División plan / ejecución

El trabajo cognitivo caro en el coding agéntico es planificar: leer la base de código, decidir el enfoque, anticipar casos borde. El trabajo mecánico barato es implementar un plan que ya existe. Los precios reflejan esto: los modelos de frontera cuestan aproximadamente un orden de magnitud más por token que los modelos económicos, y ganan ese precio en planificación, no en implementación.

La composición:

1. Abre Claude Code en modo plan (concepto 2). Presenta el brief. Deja que produzca un plan.
2. Guarda el plan en docs/plans/feature-x.md.
3. Abre OpenCode en un worktree separado, apuntando a un modelo económico (consulta opencode.ai/docs/providers para la configuración actual). Primer mensaje: read docs/plans/feature-x.md and implement it.
4. OpenCode hace las ediciones de archivo, ejecuta pruebas y corrige lint.
5. (Opcional) Abre Claude Code de nuevo para revisar el diff antes del merge.

El archivo de plan es el contrato. Sobrevive a la pérdida de sesión, codifica las decisiones arquitectónicas y permite que la sesión barata trabaje sin rehacer el pensamiento caro. Este patrón por sí solo suele entregar la mayor parte del ahorro de costos que los equipos esperan obtener de «cambiar a un modelo más barato», sin perder la calidad de la planificación de frontera.

Patrón 2: Revisión entre modelos

Esto es el concepto 13 de Prompting de IA promovido de hábito a arquitectura. Allí pasabas el mismo borrador por dos ventanas de chat; aquí, dos herramientas de coding revisan los diffs de la otra.

Distintos modelos tienen distintos puntos ciegos. Un modelo que escribió un fragmento de código es el peor revisor posible de ese código, porque tiene los mismos puntos ciegos que produjeron el original. Un modelo de otra familia (datos de entrenamiento distintos, hábitos de razonamiento distintos) atrapará cosas que el autor omitió.

La composición:

1. Herramienta A (cualquier modelo) implementa una función en su propio worktree.
2. Herramienta B (modelo distinto, idealmente de otra familia) lee el diff y escribe una crítica en docs/reviews/feature-x.md. El revisor no edita; produce texto.
3. Herramienta A lee la revisión y decide sobre qué puntos actuar.

Esto es más útil de lo que suena. Revisores que corren en modelos económicos detectan una cantidad sorprendente de valor real: casos borde faltantes, descuidos de seguridad, incoherencias de nombres, código muerto. El costo en dólares de ejecutar una pasada de revisión es bajo; el costo en tiempo de encontrar un bug después del merge es alto.

El patrón funciona mejor cuando revisor e implementador vienen de familias de modelos distintas: Claude revisando Claude se pierde lo que GPT o DeepSeek atraparían, y viceversa. La revisión dentro de la misma familia sigue siendo mejor que no revisar, pero el valor está en la diversidad, no en el acto.

Qué se queda en una sola herramienta

La composición tiene sobrecosto. Dos herramientas significan dos configuraciones, dos listas de permisos, dos sistemas de notificaciones. Para la mayoría de tareas cortas (una sola función, una refactorización rápida, una corrección de bug), una sesión única es más rápida, simple y barata que orquestar entre herramientas.

Recurre a la composición cuando la tarea sea lo bastante grande como para que la planificación sea realmente separable de la implementación, cuando el costo de un modelo de frontera para toda la tarea sea un desperdicio o cuando el valor de una revisión independiente supere su costo. Para todo lo demás, la disciplina de sesión única de las Partes 1–7 es el movimiento correcto.

La composición es simplemente lo que sucede cuando dejas de tratar una herramienta y un modelo como la unidad de trabajo, y empiezas a tratar la sesión de coding agéntico como la unidad.

---

Cómo volverse realmente bueno en esto

Leer este curso acelerado no te vuelve bueno en coding agéntico. Usarlo sí, y el camino se ve así:

Empiezas manualmente. Sientes la fricción: cada prompt de aprobación, cada «espera, ¿por qué no sabe X?». Esa fricción es el currículo. Cada pieza de fricción mapea a uno de los quince conceptos anteriores:

• «¿Por qué sigue olvidando el patrón de auth?» → falta el archivo de reglas o está inflado.
• «¿Por qué acaba de borrar mi carpeta de migraciones?» → los permisos no estaban lo bastante ajustados.
• «¿Por qué está tan lento después de una hora?» → deterioro del contexto; necesitabas /compact.
• «¿Por qué estoy escribiendo lo mismo cada lunes?» → eso es una skill.
• «¿Por qué mis pruebas pasan localmente pero fallan en CI?» → eso es un hook o plugin.
• «¿Por qué explorar la base de código siempre contamina mi conversación?» → eso es un subagente.

Construye la respuesta a cada problema cuando te choque, no antes. Tu archivo de reglas debería tener diez líneas, luego doce, luego veinte: cada línea ganada por un error que ahora previene. Tu carpeta de skills debería tener una skill antes de tener diez. Tus hooks/plugins deberían existir porque algo se rompió sin ellos, no porque alguien dijo que los hooks eran potentes.

El 80/20 no consiste en memorizar quince conceptos. Consiste en notar a cuál pertenece un problema dado, lo bastante rápido como para alcanzar la herramienta correcta. Esa capacidad de notar es la skill, y solo llega pasando tiempo viendo a las herramientas de coding agéntico tener éxito y fallar en trabajo real.

El dividendo de portabilidad. Una vez que construiste esa capacidad de notar en una herramienta, se transfiere. El mapa fricción-a-concepto de arriba es idéntico en Claude Code y OpenCode. Elige una para empezar, aprende su configuración específica y, cuando decidas cambiar (por costos, preferencia de modelo, licencia o una herramienta nueva que todavía no existe), tu conocimiento va contigo. Las configuraciones cambian. El pensamiento no.

Empieza con un proyecto. Usa modo plan para todo lo no trivial. Vigila tu contexto. El resto se construye solo.

---

Referencia rápida

Los 15 conceptos en una línea cada uno

1. Las herramientas ejecutan acciones, no solo responden. Escribe briefs, no preguntas.
2. Modo plan (Shift+Tab en CC, Tab al agente Plan en OC). Investigación de solo lectura antes de escribir.
3. Disciplina de permisos. Empieza manual, codifica allow/deny con el tiempo. Nunca apruebes automáticamente rm -rf.
4. El deterioro del contexto es real. El recuerdo se degrada mucho antes de que la ventana se llene, y cada turno vuelve a facturar todo el contexto.
5. /clear frente a /compact. Nueva tarea frente a misma tarea más ligera. Elige mal y pierdes lo incorrecto.
6. Reanudar sesiones. Retoma donde quedaste sin volver a explicar; combínalo con archivos de plan guardados.
7. CLAUDE.md / AGENTS.md es una tabla de contenidos. Menos de ~2.500 tokens, referencias cargadas bajo demanda.
8. Comandos slash. Indicaciones guardadas que disparas por nombre cuando sigues escribiendo lo mismo.
9. Skills. Expertise guardada que el modelo invoca automáticamente por descripción; revelación progresiva mediante SKILL.md más referencias.
10. Hooks (CC) / Plugins (OC). Salvaguardas deterministas en eventos del ciclo de vida. No son opcionales para producción.
11. Subagentes. Ventanas de contexto aisladas para lecturas ruidosas (exploración de base de código, búsqueda de documentación).
12. MCP, usado con cuidado. Protocolo estándar para herramientas externas; las CLIs suelen superar a MCP en servicios sin estado.
13. Dónde ejecutar. Empieza en la terminal o en un plugin de IDE para ver qué hace el agente.
14. Biblioteca personal de contexto, lentamente. Comparte configuraciones entre proyectos; construye desde el arrepentimiento, no desde la imaginación.
15. Memoria más allá de lo básico. Reanudación integrada + buen archivo de reglas basta para la mayoría. Carpeta notes/ si necesitas más.

Referencia rápida de comandos

Quieres...	Claude Code	OpenCode
Inicializar archivo de reglas	/init	/init
Entrar en modo plan	Shift+Tab (dos veces)	Tab (cambiar al agente Plan)
Borrar conversación y empezar de cero	/clear	/new (o /clear)
Resumir y continuar	/compact	/compact (o /summarize)
Reanudar una sesión guardada	claude --resume	/sessions (o /resume)
Volver a un mensaje anterior	Esc Esc (o /rewind)	/undo
Revertir ediciones de archivo del modelo	Esc Esc (checkpointing)	/undo (necesita git)
Revertir cambios de archivo hechos por bash	(no rastreado)	/undo (diff de todo el árbol)
Rehacer (revertir el último /undo)	(no incluido)	/redo
Compartir sesión	/share	/share

Referencia rápida de ubicaciones de archivos

Qué	Claude Code	OpenCode
Reglas de proyecto	CLAUDE.md	AGENTS.md (también lee CLAUDE.md como fallback)
Permisos de proyecto	.claude/settings.json	opencode.json
Comandos de proyecto	.claude/commands/*.md	.opencode/commands/*.md
Skills de proyecto	.claude/skills/<name>/SKILL.md	.opencode/skills/<name>/SKILL.md (también lee .claude/skills/)
Hooks/plugins de proyecto	.claude/settings.json (hooks block)	.opencode/plugins/*.{js,ts}
Subagentes de proyecto	.claude/agents/*.md	.opencode/agents/*.md
Reglas personales/globales	~/.claude/CLAUDE.md	~/.config/opencode/AGENTS.md
Comandos/skills/agentes personales	~/.claude/{commands,skills,agents}/	~/.config/opencode/{commands,skills,agents}/
Servidores MCP	.claude/settings.json (mcp block)	opencode.json (mcp block)

Árbol de decisión de tipos de extensión

Need to do the same thing repeatedly, manually?
    → Slash command (CC) / Custom command (OC)

Want the model to apply expertise automatically when a task matches?
    → Skill

Need something to happen every single time, no model judgment?
    → Hook (CC) / Plugin (OC)

Need a chunk of work done in isolation so it doesn't pollute main context?
    → Subagent

Cuando algo se siente mal

Model apologizing without progress, rewriting the same code,
hallucinating variables, contradicting earlier constraints?
    → Context is poisoned. Stop typing. Run /compact or /clear.
       Don't try to fix it with another prompt.

---

Ayuda de estudio con flashcards

---

Cuestionario: 50 preguntas sobre los 15 conceptos

Un banco completo que cubre todos los conceptos del curso acelerado. Cada sesión muestra un lote nuevo de 18 preguntas, así que repetirlo te da material nuevo. Elige tu herramienta arriba para anclar las respuestas en tu toolchain.

Checking access...