Primeros pasos para programar con IA: agentes, skills y plugins

Un agente de programación lee el repositorio, edita archivos y ejecuta órdenes por su cuenta. Con él, usted pasa a decidir qué se construye, a darle una comprobación que pueda ejecutar y a revisar lo que escribió.

Los ejemplos usan Claude Code en la terminal. Instálelo con el instalador nativo que publica su documentación. Después, abra una terminal en el directorio del proyecto y ejecute claude, que pide iniciar sesión la primera vez¹. Claude Code también existe como extensión de VS Code y de JetBrains, como aplicación de escritorio y en el navegador. Todas esas versiones leen la misma configuración¹. En Cursor, el agente viene integrado en el editor y no necesita una instalación aparte.

Las mediciones se hicieron el 26 y el 27 de septiembre de 2026 con Claude Code 2.1.283, git 2.49.0, Node.js 24.19.0 y npm 11.8.0. La documentación de Cursor se consultó el 8 de septiembre de 2026. Todo el código está reconstruido para el artículo.

El punto 13 describe un prompt que prepara lo básico en su proyecto: el archivo de instrucciones, el bloqueo de los secretos y una skill que revisa cada cambio. Cópielo con el botón «Copiar prompt» del panel «Preparar el proyecto». La configuración completa, con subagentes que revisan cada cambio, está en Cómo configurar un entorno completo para programar con agentes.

1. Qué diferencia a un agente de un chat

Un modelo de lenguaje se puede usar de tres formas para programar, y se diferencian en quién aplica el cambio.

El autocompletado propone el final de la línea que usted escribe, dentro del editor. Usted acepta o rechaza cada sugerencia, así que el control es completo y el alcance no pasa de una función.

El chat recibe una pregunta y devuelve texto. Usted copia ese código al proyecto, lo adapta a los nombres reales y comprueba que compila. Como el modelo no ha visto el repositorio, el código supone una estructura que puede no coincidir con la real.

El agente recibe una tarea, decide qué archivos leer, los lee, escribe los cambios y ejecuta órdenes para comprobarlos. La documentación de Claude Code lo define así: la IA lee archivos, ejecuta órdenes y hace cambios de forma autónoma. Mientras tanto, usted observa, la corrige o la deja trabajar sola. La documentación lo contrapone a los asistentes de chat, que solo responden con texto que hay que aplicar a mano².

Un modelo se convierte en agente cuando tiene herramientas. Una herramienta es una acción que el modelo puede pedir: leer un archivo, editarlo, ejecutar una orden en la terminal o buscar en el proyecto. Según la misma documentación, sin herramientas el modelo solo puede responder con texto².

Las tres formas tienen su uso. El autocompletado sirve para terminar una línea, el chat para preguntas que no tocan el repositorio y el agente para las tareas que abarcan varios archivos.

Cómo comprobarlo. En una sesión de agente, las llamadas a herramientas aparecen antes de la respuesta: qué archivo leyó, qué orden ejecutó y qué devolvió. En Claude Code, Ctrl+O abre y cierra el visor de transcripción, con el detalle de cada llamada³. Si la sesión solo produjo texto, no trabajó como agente.

2. Cómo trabaja un agente

Un agente no responde una sola vez. Repite un ciclo hasta que da la tarea por terminada. La documentación lo describe en cuatro pasos: reunir contexto, actuar, verificar el resultado y repetir. El resultado de cada herramienta decide el paso siguiente².

Un turno es una respuesta completa del agente. Empieza cuando usted envía un mensaje y termina cuando el agente acaba de responder, con tantas llamadas a herramientas como necesite². Por ejemplo, para corregir un fallo sencillo, el agente busca el archivo, lo lee, escribe el cambio y ejecuta las pruebas. Después lee el fallo que devuelven, lo corrige y vuelve a ejecutarlas. Son seis llamadas a herramientas en un turno, donde un chat habría dado una sola respuesta.

El modelo no ejecuta esas herramientas. Solo produce texto, incluida la petición de usar una herramienta. Un programa aparte interpreta esa petición, la ejecuta en el sistema de archivos o en la terminal y le devuelve la salida.

Ese programa se llama harness. La documentación lo define como las herramientas, la gestión del contexto y el entorno de ejecución que convierten un modelo en un agente. Claude Code es el harness, y Claude es el modelo que trabaja dentro².

Cursor describe su agente con tres piezas. Son las instrucciones que guían su comportamiento, las herramientas para editar, buscar y ejecutar órdenes, y el modelo que se elige para la tarea⁴. Por eso elegir el modelo y elegir el harness son dos decisiones distintas.

Cómo comprobarlo. Ejecute una tarea y cuente las llamadas a herramientas anteriores a la respuesta final. Si el agente resolvió algo sin leer ningún archivo, lo escribió de memoria.

3. Qué es la ventana de contexto y cómo medirla

La ventana de contexto es el texto que el modelo tiene disponible durante la sesión. Incluye el historial de la conversación, los archivos leídos, la salida de las órdenes, el archivo de instrucciones del proyecto y las instrucciones del sistema². El agente no conoce nada que no esté ahí. Su tamaño se mide en tokens, la unidad en la que el modelo cuenta el texto. En Claude, un token equivale a unos 3,5 caracteres de texto en inglés⁵.

La orden /context muestra cómo se reparte. Esta es su salida, recortada, al abrir una sesión nueva en un repositorio de ejemplo. El archivo de instrucciones del proyecto ocupa 29 tokens y el personal, 96:

**Tokens:** 19k / 1m (2%)

| Category                | Tokens | Percentage |
|-------------------------|--------|------------|
| System prompt           | 2.3k   | 0.2%       |
| System tools            | 4.6k   | 0.5%       |
| MCP server instructions | 686    | 0.1%       |
| Custom agents           | 374    | 0.0%       |
| Memory files            | 125    | 0.0%       |
| Skills                  | 9.9k   | 1.0%       |
| Messages                | 1k     | 0.1%       |
| Free space              | 948k   | 94.8%      |
| Autocompact buffer      | 33k    | 3.3%       |

Salvo Free space y Autocompact buffer, cada fila es texto que se envía en todas las peticiones de la sesión:

• System prompt y System tools: las instrucciones fijas de Claude Code y la descripción de sus herramientas. No dependen del proyecto.
• MCP server instructions: lo que añaden los servidores de herramientas externas conectados, que el punto 10 explica.
• Custom agents y Skills: la descripción de cada subagente y de cada skill instalados, no su contenido completo.
• Memory files: los archivos de instrucciones del proyecto y personales, que explica el punto 8.
• Messages: la conversación. Es la fila que crece con cada archivo leído y cada orden ejecutada.
• Autocompact buffer: el espacio reservado para resumir la conversación cuando la ventana se llena.

Ese resumen automático se llama compactación. Primero descarta las salidas antiguas de las herramientas y después resume el resto. El archivo de instrucciones se vuelve a leer del disco, pero lo que solo se dijo en la conversación se puede perder². Además, la conversación entera se envía en cada petición, así que una sesión larga cuesta más⁶.

Cómo hacerlo.

1. Ejecute /context al abrir la sesión y anote el total.
2. Al terminar una tarea, ejecute /clear para empezar una conversación nueva, con el contexto vacío, antes de la siguiente.
3. Si una tarea larga se acerca al límite, ejecute /compact para resumir la conversación en ese momento. Admite una instrucción: /compact conserva la lista de archivos tocados.
4. Escriba en el archivo de instrucciones, y no en un mensaje, lo que tenga que conservarse tras la compactación.

Cómo comprobarlo. Ejecute /context antes y después de la primera tarea. La diferencia en Messages es lo que ocupó esa tarea. Con ese dato puede decidir cuándo cerrar la sesión.

4. Qué tareas encargar a un agente

Una tarea es adecuada para un agente cuando existe una orden que decide si está terminada. La documentación llama a eso bucle de verificación. Usted le da al agente una comprobación que pueda ejecutar: una prueba, una compilación o una comparación. El agente repite el trabajo hasta que la comprobación pasa. Sin ella, lo único que decide si terminó es el propio agente².

Le va bien	Orden que decide el final
Corregir un fallo que se reproduce con una prueba	la prueba pasa
Migrar una llamada a una biblioteca en veinte archivos	el proyecto compila
Escribir pruebas para código que no las tiene	las pruebas pasan y fallan al romper el código
Resolver los avisos de un linter	el linter termina sin avisos

Las tareas sin esa orden le van mal, como decidir la arquitectura de un módulo nuevo o ajustar un diseño visual sin una imagen de referencia. Tampoco le va bien una tarea cuyo único criterio es que a alguien le parezca bien. En esos casos, el agente sirve para explorar alternativas, pero la decisión es suya.

Declare esa condición con /goal. Al final de cada turno, un modelo pequeño comprueba si se cumple. Mientras no se cumpla, el agente empieza otro turno en lugar de devolverle el control⁷.

/goal todas las pruebas de test/auth pasan y el linter termina sin avisos, o parar tras 20 turnos

Cada parte de esa línea cumple una función. «Todas las pruebas de test/auth pasan» es el estado final que se puede medir. «El linter termina sin avisos» es una restricción que se tiene que cumplir durante todo el trabajo. «O parar tras 20 turnos» limita la duración.

El evaluador no ejecuta nada: juzga lo que el agente dejó escrito en la conversación. Por eso la condición tiene que poder demostrarse con la salida de una orden⁷. /goal clear retira la condición antes de tiempo.

Cómo comprobarlo. Antes de escribir la petición, nombre la orden que decidirá si la tarea está terminada. Si no encuentra ninguna, la tarea todavía no está lista para un agente.

5. Cómo escribir una petición

El agente resuelve el enunciado que recibe, así que el enunciado tiene que incluir la condición que se va a comprobar después. «Añade la cancelación de pedidos» no la incluye. Esta petición sí:

En src/pedidos.js, añade cancelarPedido(pedidos, id).
Devuelve null si el pedido no existe.
Si existe, cambia estado a 'cancelado' y devuelve el pedido.
No añadas dependencias.
Criterio: node --test pasa con las dos pruebas de tests/pedidos.test.js.

Qué hace cada línea:

• El archivo limita dónde se escribe y evita que el agente lea medio repositorio para encontrarlo.
• El comportamiento en cada caso, incluido el de error, da algo con lo que contrastar el resultado.
• La restricción fija de antemano algo que, si la petición no lo dice, el agente decide por su cuenta.
• El criterio nombra la orden que decide el final y el resultado que tiene que devolver.

Añada también lo que el modelo no puede deducir del código, como la versión del gestor de paquetes. En la primera sesión, inclúyalo en la petición. El punto 8 explica dónde guardarlo para no repetirlo.

En modo plan, el agente lee, busca y ejecuta órdenes de exploración, pero no edita el código: presenta un plan y espera su aprobación². Así, la primera revisión se hace sobre un texto corto. Un enfoque equivocado se corrige en ese texto, sin revertir archivos.

Cómo hacerlo.

1. Escriba /plan seguido de la petición, o pulse Shift+Tab hasta que la barra de estado muestre plan mode on⁸.
2. Lea el plan. Si nombra archivos que la petición no pedía tocar, corríjalo en su respuesta.
3. Apruebe el plan. El agente sale del modo plan y aplica los cambios.

Cómo comprobarlo. La petición contiene una orden ejecutable y el resultado que esa orden tiene que devolver. Si no lo contiene, tendrá que leer el cambio entero para decidir si está terminado.

6. Cómo detener, corregir y deshacer el trabajo del agente

Un agente trabaja durante varios turnos, así que usted necesita poder detenerlo a mitad de una tarea y volver atrás. Hay tres mecanismos, y cada uno cubre un caso distinto:

Mecanismo	Qué hace	Cuándo se usa
Esc	Detiene la respuesta o la herramienta en curso y conserva lo hecho hasta ese momento	el agente hace algo distinto de lo pedido y basta con una indicación
/rewind o Esc Esc	Abre el menú de puntos de restauración	una tanda de ediciones sobra entera
git	Devuelve el repositorio a un commit	todo lo que los dos anteriores no cubren

Ctrl+C también interrumpe. Si no hay nada en ejecución, la primera pulsación borra la entrada y la segunda cierra Claude Code³.

Claude Code guarda el estado del código antes de cada petición que inicia un turno, y llama a cada captura punto de restauración. Conserva las copias de los archivos de los cien puntos de restauración más recientes de la sesión⁹. /rewind muestra la lista de peticiones enviadas y, al elegir una, ofrece cinco acciones⁹:

1. «Restore code and conversation»: devuelve el código y la conversación a ese punto.
2. «Restore conversation»: vuelve a ese mensaje y deja el código como está.
3. «Restore code»: deshace los cambios en los archivos y conserva la conversación.
4. «Summarize from here»: resume la conversación desde ese punto para liberar espacio en la ventana de contexto.
5. «Summarize up to here»: resume la conversación anterior a ese punto y conserva intactos los mensajes posteriores.

Las dos acciones que restauran código solo aparecen si hubo ediciones después de ese punto. «Never mind» vuelve a la lista sin cambiar nada⁹.

Cómo hacerlo.

1. Antes de la petición, ejecute git status --porcelain. La salida tiene que estar vacía; si no lo está, confirme lo pendiente o apártelo con git stash.
2. Si el agente se desvía de lo pedido, pulse Esc y corríjalo con una frase.
3. Si el resultado sobra entero, ejecute /rewind, elija la petición y pulse «Restore code».
4. Después, ejecute otra vez git status --porcelain.

Cómo comprobarlo. Si en el último paso quedan archivos modificados, son los que el menú no cubre. Descártelos con git; el punto 12 explica las dos órdenes que lo hacen y su riesgo.

7. Cómo usar el agente para aprender

Cuando el agente escribe el código, usted no pasa por la parte del trabajo en la que se aprende. Estas tres formas de pedir mantienen esa parte, y las tres son peticiones normales:

En lugar de	Pida	Qué obtiene
«Arregla el fallo de validación»	«En modo plan, explica qué archivos intervienen y por qué falla»	la explicación sobre el código real, sin cambios
«Añade validación al endpoint»	«Dónde se valida el cuerpo de la petición y en qué archivo empieza el camino»	un mapa útil para las tareas siguientes
«Escribe la función»	«Revisa esta versión mía contra manejo de errores, casos límite y nombres»	la diferencia entre las dos versiones

Un agente responde bien a las preguntas sobre dónde está algo, porque puede buscarlo en el repositorio en lugar de suponerlo. En cambio, contraste con la documentación lo que afirme sobre una biblioteca o un estándar. El tono de la respuesta es igual de seguro cuando el dato es correcto y cuando no lo es.

Cómo comprobarlo. Después de una explicación, cierre la sesión e intente reconstruir lo explicado sin ella. Lo que no pueda reconstruir es lo que tiene que volver a leer.

¿Se aprende a programar si la IA escribe el código? explica qué midieron los experimentos sobre este tema y cómo comprobar lo aprendido.

8. Cómo documentar el proyecto: AGENTS.md y CLAUDE.md

Cada sesión de Claude Code empieza con una ventana de contexto nueva, sin nada de las conversaciones anteriores¹⁰. El archivo de instrucciones guarda lo que el agente tiene que saber del proyecto. Usted lo escribe una vez y Claude Code lo carga al principio de cada sesión.

AGENTS.md es el nombre de archivo que leen varios agentes de programación. Claude Code lo lee directamente desde la versión 2.1.277 si el repositorio no tiene un CLAUDE.md. Si lo tiene, por omisión lee solo CLAUDE.md, que puede importar AGENTS.md con una línea @AGENTS.md¹⁰. Además, un archivo personal en ~/.claude/CLAUDE.md guarda sus preferencias para todos los proyectos. Claude Code suma en el contexto todos los archivos que encuentra, en lugar de quedarse con uno¹⁰.

Este es un archivo completo para un proyecto pequeño:

# pedidos

## Órdenes
- Instalar: npm ci
- Pruebas: node --test
- Una sola prueba: node --test tests/pedidos.test.js
- Linter: npx eslint .

## Entorno
- Node.js 24, npm 11. Módulos ES.

## Convenciones
- Las fechas se guardan en UTC y se formatean solo en la interfaz.
- Las funciones de src/ no escriben en consola; devuelven el error.

## Antes de dar una tarea por terminada
1. node --test termina en 0.
2. npx eslint . termina sin avisos.
3. No se añadió ninguna dependencia que la tarea no pidiera.

Qué hace cada apartado:

• Órdenes: el agente no tiene que adivinar cómo se prueba ni con qué gestor se instala. La orden de una sola prueba le evita ejecutar la suite entera en cada intento.
• Entorno: lo que no se deduce con certeza leyendo el código.
• Convenciones: las decisiones del proyecto que el código no explica.
• Antes de dar una tarea por terminada: el bucle de verificación del punto 4, escrito una vez para todas las tareas.

No incluya lo que el agente puede leer del disco, como la lista de directorios o de dependencias. La documentación recomienda menos de 200 líneas, porque un archivo largo ocupa más contexto y el modelo sigue peor sus instrucciones. También pide instrucciones que se puedan comprobar: «usa indentación de 2 espacios» en lugar de «formatea bien el código»¹⁰.

El archivo de instrucciones es contexto: el modelo lo lee, pero nada lo obliga a cumplirlo. Configure como hook lo que tenga que ocurrir siempre en un momento fijo, como formatear el código después de cada edición. Un hook es una orden que Claude Code ejecuta en ese punto del ciclo sin consultar al modelo¹⁰.

Cómo hacerlo.

1. Ejecute /init, que analiza el proyecto y genera un primer CLAUDE.md. Si el proyecto ya usa AGENTS.md, escriba en ese archivo.
2. Ejecute cada orden que nombra el archivo y borre la que no funcione.
3. Añada las convenciones y la lista «Antes de dar una tarea por terminada».
4. Para editar más adelante los archivos de instrucciones, ejecute /memory.

Cómo comprobarlo. Ejecute /context all. La lista Memory Files muestra los archivos cargados, con su ruta y sus tokens. Si el archivo no aparece ahí, el agente no lo está leyendo.

9. Qué son las reglas por ruta y las skills

El archivo de instrucciones se carga entero en cada sesión, así que todo lo que usted le añade ocupa contexto en todas las tareas. Para lo que solo hace falta a veces hay dos mecanismos que se cargan bajo condición.

Las reglas por ruta son archivos de .claude/rules/ con una cabecera paths. Solo entran en el contexto cuando el agente trabaja con un archivo que coincide con esas rutas¹⁰:

---
paths:
  - "src/api/**/*.ts"
---

- Todo endpoint valida la entrada antes de usarla.
- Los errores usan el formato de respuesta estándar.

Una skill es una carpeta con un archivo SKILL.md que contiene instrucciones, conocimiento o un procedimiento. Al abrir la sesión solo se carga su descripción. El contenido completo entra cuando una petición encaja con esa descripción o cuando usted la invoca con /nombre¹¹.

---
name: resumen-de-cambios
description: Resume los cambios sin confirmar y señala lo que tenga riesgo. Úsala cuando se pregunte qué cambió o se pida un mensaje de commit.
disable-model-invocation: false
---

Cambios actuales:

!`git diff HEAD --stat`

Resume esos cambios en dos o tres puntos y después enumera los riesgos:
manejo de errores ausente, valores fijos en el código o pruebas por actualizar.
Si no hay cambios, dilo.

Qué hace cada parte:

• name: el nombre de la orden, /resumen-de-cambios. Usa minúsculas, números y guiones, igual que la carpeta¹².
• description: el único texto con el que el agente decide si carga la skill por su cuenta. Dice qué hace y cuándo se usa, con las palabras que alguien escribiría al pedirlo.
• disable-model-invocation: con true, la skill solo se ejecuta cuando alguien escribe su orden, nunca por decisión del agente¹¹.
• !`orden`: se ejecuta antes de enviar la skill al modelo, y su salida sustituye a la línea¹¹.
• El cuerpo: las instrucciones, que entran en la conversación como un solo mensaje.

La skill también admite la variable $ARGUMENTS, que se sustituye por lo que se escriba después de la orden. Con /arreglar-issue 123, el cuerpo recibe 123¹¹.

El formato no pertenece a un solo producto. Las skills siguen el estándar abierto Agent Skills, que fija name y description como obligatorios y license, compatibility, metadata y allowed-tools como opcionales¹². disable-model-invocation es una extensión de Claude Code.

Cómo hacerlo.

1. Cree .claude/skills/resumen-de-cambios/SKILL.md para este proyecto, o en ~/.claude/skills/ para todos los proyectos de la máquina¹¹.
2. Pegue el ejemplo y ajuste la descripción a cómo lo pediría su equipo.
3. Abra una sesión nueva, porque las descripciones se leen al empezar.

Cómo comprobarlo. Escriba / en la sesión: la skill tiene que aparecer en la lista. Después haga una petición que encaje con su descripción, sin nombrarla, y compruebe si se cargó sola. Si no se carga, el problema está en la descripción.

10. Qué son los plugins y qué cuesta instalarlos

Un plugin es un paquete instalable que agrupa skills, agentes, hooks y servidores MCP¹³. MCP, siglas de Model Context Protocol, es un protocolo abierto para conectar un modelo con fuentes de datos y herramientas externas⁵. Un servidor MCP añade herramientas nuevas al agente, por ejemplo para Slack, Jira, una base de datos o un navegador.

Los plugins se distribuyen en catálogos, llamados marketplaces. El catálogo oficial de Anthropic, claude-plugins-official, se registra la primera vez que usted abre una sesión interactiva, así que instalar desde él es una sola orden¹³:

/plugin install commit-commands@claude-plugins-official

commit-commands es el nombre del plugin, que añade órdenes para confirmar, subir y abrir pull requests. Lo que va detrás de @ es el catálogo del que sale. Un catálogo de terceros se registra antes con /plugin marketplace add <usuario>/<repositorio>, que no instala nada¹³. /plugin sin argumentos abre el panel de catálogos, plugins instalados y errores de carga, y /mcp gestiona las conexiones con servidores MCP¹⁴.

Antes de instalar, la ficha de cada plugin muestra dos datos. «Context cost» es lo que añade a cada mensaje y lo que añaden sus skills y agentes al cargarse. «Will install» lista las órdenes, agentes, skills, hooks y servidores que trae¹³. El primero ocupa contexto en todas las sesiones, también en las que no usan el plugin.

Los plugins de inteligencia de código conectan un servidor de lenguaje, el componente que da al editor funciones como ir a la definición. Con uno instalado, el agente ve los errores de tipos que introducen sus propias ediciones sin esperar a compilar. El plugin no incluye el servidor, que se instala aparte¹⁵.

Cómo comprobarlo. Ejecute /context antes y después de instalar. Si un plugin añade contexto en cada turno y usted no lo usa nunca, desinstálelo.

11. Qué permisos darle al agente

Un agente ejecuta órdenes y lee archivos. Antes de la primera sesión larga hay que decidir dos cosas: en qué casos se detiene a preguntar y qué archivos puede leer.

Lo primero lo fija el modo de permiso, que se cambia con Shift+Tab y se ve en la barra de estado. Estos son los modos principales y lo que cada uno hace sin preguntar⁸:

Modo	Qué hace sin preguntar
default	Solo lee. Claude Code lo llama Manual, y la barra lo muestra como manual mode on.
acceptEdits	Lee, edita archivos y ejecuta órdenes básicas de archivos, como mkdir o mv.
plan	Lee y explora, pero no edita el código.
auto	Todo, con comprobaciones de seguridad en segundo plano.
bypassPermissions	Todo, sin ninguna comprobación.

Desde la versión 2.1.283, las sesiones de la terminal y de VS Code empiezan en auto⁸. La documentación limita bypassPermissions a entornos aislados, como contenedores o máquinas virtuales, donde el agente no pueda causar daño¹⁷.

Lo segundo importa porque el agente envía al servidor del proveedor el contenido de los archivos que lee. Un .env con credenciales se envía igual que el código. Para excluirlo, declare la regla en .claude/settings.json¹⁸:

{
	"permissions": {
		"deny": ["Read(./.env)", "Read(./.env.*)"]
	}
}

deny es la lista de acciones que Claude Code rechaza siempre. Read(./.env) es la herramienta de lectura sobre ese archivo exacto, y Read(./.env.*) cubre .env.local, .env.production y los demás.

Que el archivo esté en .gitignore no lo protege. En la medición, sin la regla, la herramienta de lectura devolvió el archivo sin error. Con la regla, devuelve este bloqueo:

File is in a directory that is denied by your permission settings.

La regla también cubre las órdenes de terminal que nombran el archivo, como cat .env o head .env. No cubre un guion que abra el archivo por su cuenta, como un programa de Node o de Python¹⁷.

Cursor funciona de otra forma. Por omisión ignora lo que lista .gitignore y una lista propia que incluye .env*, y el resto se excluye en .cursorignore. Su documentación advierte que la terminal y las herramientas externas del agente no pueden bloquear el acceso a lo que cubre ese archivo¹⁹.

En los dos productos, la exclusión se declara en la configuración y no en el archivo de instrucciones. Las reglas de permiso las aplica el harness, no el modelo¹⁷. Por eso una línea en AGENTS.md que diga «no leas .env» no cambia lo que Claude Code permite.

Queda una decisión de coste: qué modelo usa la sesión. Cámbielo con /model. La documentación recomienda empezar con Sonnet, que resuelve bien la mayoría de las tareas de programación y cuesta menos que Opus⁶.

Cómo comprobarlo. Pida al agente el contenido de .env. Con la regla puesta, la herramienta de lectura devuelve el bloqueo en lugar del archivo. Que el modelo conteste que no piensa hacerlo no comprueba nada, porque esa respuesta no la produce la regla.

12. Cómo revisar lo que hizo el agente

El agente edita los archivos directamente, así que al terminar queda un diff. Un diff es la lista de líneas que cambiaron entre el estado anterior del repositorio y el actual. El diff solo sirve si el punto de partida estaba limpio. Por eso git status --porcelain tiene que salir vacío antes de la petición.

La orden habitual para ver qué archivos cambiaron no muestra los nuevos:

git diff --stat

 package.json   | 2 +-
 src/pedidos.js | 8 ++++++++
 2 files changed, 9 insertions(+), 1 deletion(-)

La sesión había creado además src/util/fecha.js. git diff sin argumentos compara los archivos del directorio de trabajo con el índice, el área donde se preparan los cambios del siguiente commit²⁰. Un archivo nuevo todavía no está en el índice, así que no aparece. git status sí lo muestra, marcado con ??:

git status --short --untracked-files=all

 M package.json
 M src/pedidos.js
?? src/util/fecha.js

Para leer también el contenido de los archivos nuevos en el diff, márquelos con git add -N. La opción registra el archivo en el índice sin su contenido, así que git diff lo compara con un archivo vacío y lo muestra entero²⁰. No prepara nada para el commit:

git add -N . && git diff --stat

 package.json      | 2 +-
 src/pedidos.js    | 8 ++++++++
 src/util/fecha.js | 3 +++
 3 files changed, 12 insertions(+), 1 deletion(-)

El archivo que faltaba importa una dependencia nueva declarada en package.json, y la petición no pedía ninguna. Esa dependencia entra en el archivo de bloqueo, se instala en cada despliegue y hay que mantenerla actualizada.

Lea primero tres cosas:

1. Los archivos que la petición no nombraba.
2. Las líneas borradas, porque un agente que reescribe una función entera puede quitar una comprobación necesaria.
3. Los cambios en la configuración, el Dockerfile y la integración continua, que deciden lo que se ejecuta fuera de su máquina.

Que el cambio compile tampoco demuestra que haga lo pedido, porque puede pasar el linter sin cumplir la petición. La última comprobación es ejecutar el programa por la ruta que toca el cambio. Dentro de la sesión, /diff muestra lo mismo, incluidas las ediciones del agente¹⁴.

Cómo comprobarlo. Ejecute git status --short --untracked-files=all y compare esa lista con la petición. Lea entero cada archivo que sobre antes de continuar.

13. Cómo preparar lo básico con un prompt

Los puntos 8, 11 y 12 se pueden aplicar a mano. También puede hacerlo el agente con un prompt. Cópielo con el botón «Copiar prompt» del panel «Preparar el proyecto» y péguelo en una sesión abierta en la raíz del proyecto. El agente sigue seis fases:

1. Reconoce el proyecto sin escribir nada: dónde lee su herramienta cada archivo, las órdenes reales de pruebas, linter y tipos, y los archivos de secretos, sin abrirlos.
2. Propone y espera. Presenta los archivos que va a crear y el resultado de cada orden, y se detiene hasta que usted confirma.
3. Escribe AGENTS.md con las órdenes comprobadas y la lista «Antes de dar una tarea por terminada» del punto 8.
4. Bloquea la lectura de secretos con la regla de permisos del punto 11, y lo comprueba intentando leer .env.
5. Crea la skill revisar-cambio, que aplica al diff las comprobaciones del punto 12 y termina con un veredicto.
6. Comprueba y entrega un informe con lo que creó, las órdenes que fallaron y lo que no pudo comprobar.

El prompt se ejecutó una vez, como demostración, con Claude Code 2.1.283 en modo no interactivo (claude -p). El proyecto de ejemplo era una API en Express con una prueba y un .env. Las fases 1 y 2 tardaron algo más de un minuto, y el resto, otro minuto.

.claude/ es una ruta protegida: Claude Code nunca aprueba sola su escritura, y en ese modo, sin nadie que responda a la pregunta, la deniega. La regla y la skill se crearon después de conceder el permiso. Al intentar leer .env, la herramienta devolvió «File is in a directory that is denied by your permission settings.»

El agente avisó además de dos cosas que no le correspondía tocar: .gitignore no ignoraba .env.*, y una ruta devolvía los pedidos de todos los usuarios.

Cómo comprobarlo. Las skills nuevas se registran al abrir la sesión, así que ciérrela y vuelva a abrirla. Entonces /revisar-cambio aparece al escribir /, y la lectura de .env devuelve el bloqueo. git status --porcelain muestra solo los archivos que el agente propuso en la fase 2.

Los subagentes que revisan cada cambio, los agentes de trabajo y las herramientas opcionales están en Cómo configurar un entorno completo para programar con agentes.

Qué órdenes usar desde el primer día

Escríbalas dentro de la sesión; /help muestra la lista completa¹⁴.

Orden	Qué hace	Cuándo se usa
/init	Genera un primer CLAUDE.md analizando el proyecto.	La primera sesión en un repositorio.
/memory	Abre los archivos de instrucciones y la memoria automática.	Para corregir una instrucción.
/context	Enseña el reparto de la ventana de contexto.	Al abrir la sesión y tras cada tarea.
/clear	Empieza una conversación nueva con el contexto vacío.	Entre dos tareas distintas.
/compact	Resume la conversación para liberar contexto.	Cuando una tarea larga se acerca al límite.
/plan	Entra en modo plan; admite la tarea detrás.	Antes de dejar editar.
/goal	Fija una condición y el agente sigue hasta cumplirla.	Tareas con una orden que decide el final.
/rewind	Abre el menú de puntos de restauración.	Para descartar una tanda de ediciones.
/diff	Muestra los cambios sin confirmar.	Al terminar, antes de confirmar.
/permissions	Gestiona las reglas allow, ask y deny.	Para añadir la regla de .env.
/plugin	Gestiona plugins y catálogos.	Antes y después de instalar uno.
/mcp	Gestiona las conexiones con servidores MCP.	Para ver qué herramientas externas hay.
/model	Cambia de modelo y lo guarda como predeterminado.	Para ajustar coste y capacidad.
/usage	Enseña el uso de la sesión. Alias: /cost.	Para saber cuánto costó una tarea.

Hacen falta cuatro atajos de teclado³:

Atajo	Qué hace
Esc	Interrumpe a mitad de turno, o cierra un diálogo.
Esc Esc	Con la entrada vacía, abre el menú de restauración.
Shift+Tab	Recorre los modos de permiso.
Ctrl+O	Abre el visor de transcripción, con el detalle de cada herramienta.

Por dónde seguir

Empiece por la comprobación: una orden que diga si una tarea está terminada (punto 4). Después, añada el archivo de instrucciones y las skills a medida que una tarea se repita, o prepárelos con el prompt del punto 13. Cuando el proyecto crezca, Cómo configurar un entorno completo para programar con agentes añade subagentes que revisan cada cambio y agentes de trabajo.

Quedan dos temas, cada uno con su propio artículo. El primero es qué buscar en el código que genera el agente. Ocho cosas que revisar en el código que genera la IA recoge ocho fallos de seguridad habituales, cada uno con su corrección y la orden que la comprueba.

El segundo es cómo conseguir que la revisión se ejecute sola en cada cambio, sin depender de que alguien la recuerde. Ese es el tema de cómo pedirle a la IA código seguro.

Cuando el entorno esté listo, Cómo proteger una página web recorre las diez capas de seguridad de una aplicación con usuarios y enlaza el artículo de cada una.

Referencias

1. Claude Code. Overviewinstalación, arranque en el directorio del proyecto y superficies disponibles.code.claude.com↩
2. Claude Code. Glosariodefiniciones de codificación agéntica, harness, bucle agéntico, herramienta, ventana de contexto, compactación, modo plan y bucle de verificación.code.claude.com↩
3. Claude Code. Interactive modetabla de atajos de teclado: Esc, Esc doble, Shift+Tab, Ctrl+O y Ctrl+C.code.claude.com↩
4. Cursor. Agent, overviewconsultado el 8 de septiembre de 2026.cursor.com↩
5. Anthropic. Glosario de la plataformadefiniciones de token y de MCP.platform.claude.com↩
6. Claude Code. Manage costs effectivelyla conversación completa viaja en cada petición; recomendación de modelo para empezar.code.claude.com↩
7. Claude Code. Keep Claude working toward a goalsintaxis de /goal, cómo se evalúa la condición y qué la retira.code.claude.com↩
8. Claude Code. Permission modesciclo de Shift+Tab, texto de la barra de estado y descripción de cada modo.code.claude.com↩
9. Claude Code. Checkpointingcreación de los puntos de restauración, acciones del menú y limitaciones.code.claude.com↩
10. Claude Code. How Claude remembers your projectlectura directa de AGENTS.md desde la 2.1.277, importación, tamaño recomendado, reglas por ruta y hooks.code.claude.com↩
11. Claude Code. Skillsubicaciones, campos de la cabecera, $ARGUMENTS, inyección con !`orden` y qué se carga al empezar.code.claude.com↩
12. Agent Skills. Specificationcampos obligatorios y opcionales de SKILL.md y restricciones de name.agentskills.io↩
13. Claude Code. Discover and install prebuilt plugins through marketplacescatálogo oficial, orden de instalación y datos de la ficha de cada plugin.code.claude.com↩
14. Claude Code. Commandsdescripciones de las órdenes de la tabla.code.claude.com↩
15. Claude Code. Code intelligence pluginsservidor de lenguaje, errores tras cada edición e instalación aparte del binario.code.claude.com↩
16. Claude Code. Plugin security and trustejecución de código con los privilegios del usuario y límites de lo que Anthropic verifica.code.claude.com↩
17. Claude Code. Configure permissionsaviso sobre bypassPermissions y quién aplica las reglas.code.claude.com↩
18. Claude Code. Settings files and precedenceejemplo de reglas deny sobre archivos .env.code.claude.com↩
19. Cursor. Ignore filesconsultado el 8 de septiembre de 2026.cursor.com↩
20. Git. git-diffgit-scm.com↩