15 de septiembre de 202618 min de lectura

Claude Code: qué es, cómo funciona y buenas prácticas

Claude Code es el agente de programación de Anthropic que corre en la terminal: lee tu base de código, edita archivos, ejecuta comandos y pruebas, lee los errores y vuelve a intentar automáticamente. Para qué sirve Claude Code: para delegar tareas completas de desarrollo, no solo sugerencias línea por línea. Este artículo explica primero qué es Claude Code y cómo funciona (sesiones, archivos, comandos, CLAUDE.md) y después muestra mi configuración real: un orquestador que no escribe código, una escalera de modelos, un hook que bloquea el turno cuando un check falla y una etiqueta como único consentimiento humano.

Qué es Claude Code y para qué sirve

Claude Code es una herramienta de línea de comandos (CLI): la instalas, la abres dentro del directorio de tu proyecto y a partir de ahí conversas en lenguaje natural con un modelo que tiene acceso a esa base de código. No es autocompletado en el editor: es un proceso que planea, ejecuta herramientas, observa el resultado y corrige. El trabajo sucede en tu máquina local, sobre tus archivos y tu repositorio de git.

En la práctica puedes pedirle que lea un módulo y te explique qué hace, que implemente un cambio acotado y corra las pruebas, que persiga errores hasta la causa raíz, que prepare un commit o abra un pull request, o que haga una revisión de código sobre un diff. Lo que cambia frente a un chat no es el modelo: es el acceso. Un agente que ejecuta tus pruebas verifica su propio trabajo; uno que solo escribe texto no.

La diferencia entre Claude y Claude Code es esa misma. Claude, la aplicación de chat en claude.ai, es una interfaz de conversación: tú le pegas el contexto, te devuelve texto y tú lo llevas a tu editor. Claude Code es el agente de programación: lee los archivos por su cuenta, ejecuta el comando en la terminal y ve los errores reales en vez de imaginarlos. Comparten la cuenta de Claude y los modelos; cambia el acceso a tu entorno. Claude Code se usa desde tres superficies: el CLI de la terminal, la extensión de VS Code y una aplicación de escritorio que es el mismo Claude Code con interfaz gráfica, pensada para correr varias sesiones lado a lado. La extensión de VS Code ofrece la misma sesión con un subconjunto de funciones; algunas siguen siendo solo de la terminal.

La superficie y el control de autonomía también son parte de la respuesta. La aplicación funciona en macOS, Linux y Windows, se autentica con tu cuenta de Claude o con una clave de la API de Anthropic, y las organizaciones que ya corren sus modelos en la nube pueden apuntarla a esa puerta de enlace (Amazon Bedrock o Google Cloud) sin cambiar el flujo de trabajo local. Dentro de la sesión, el control de la autonomía es un modo: modo plan, donde investiga y propone paso a paso sin tocar archivos, o el modo en que aplica los cambios automáticamente y tú revisas el diff al final. Uso el primero para entender un problema y el segundo para tareas ya acotadas; casi todos los errores caros que he visto vienen de invertir ese orden.

Esto también define para qué no sirve: Claude Code no reemplaza tu CI, no sabe qué es correcto en tu dominio y no tiene forma de saber si los cambios que acaba de hacer valían la pena. Todo lo que sigue son maneras de compensar esas tres cosas.

Cómo funciona: sesiones, archivos, comandos y CLAUDE.md

Claude Code funciona por sesiones. Una sesión es una conversación con una ventana de contexto y un conjunto de herramientas: leer, escribir y editar archivos, buscar en el proyecto, ejecutar comandos en la terminal, y las que agregues tú vía servidores MCP. La sesión recuerda lo que pasó dentro de ella; al cerrarla, lo único que persiste es lo que quedó escrito en archivos. Por eso la configuración importante vive en archivos del repositorio y no en la conversación.

El archivo central es CLAUDE.md: se carga automáticamente al inicio de cada sesión y es donde van las reglas del proyecto (comandos de build y de pruebas, estilo, convenciones, límites). La regla práctica de las buenas prácticas oficiales de Anthropic es contraintuitiva: “Bloated CLAUDE.md files cause Claude to ignore your actual instructions!”. Un archivo largo no se obedece más; se obedece menos. El mío tiene las reglas transversales y apunta a documentos que se cargan solo cuando hacen falta.

Alrededor de ese archivo, el directorio .claude/ del proyecto guarda el resto de la configuración:

mi-proyecto/
  CLAUDE.md            reglas del proyecto, se cargan siempre
  .claude/
    settings.json      permisos (allow/deny) y hooks
    agents/*.md        subagentes: modelo, herramientas, encargo
    skills/*/SKILL.md  flujos de trabajo que se invocan con /
    check.sh           lint, tipos y pruebas en segundos (convención mía, la invoca el hook)

Los comandos de Claude Code son de dos tipos: los del CLI, que se escriben en la terminal antes de entrar a la sesión, y los que empiezan con / dentro de la sesión, que controlan el estado de la conversación y disparan flujos de trabajo. Los que uso a diario son pocos: limpiar el contexto al cambiar de tarea, revisar permisos, y los míos, que son archivos de skills/ y aparecen como / más el nombre del directorio. Lo interesante es que cualquier flujo de trabajo repetido se vuelve un comando versionado en git.

El tercer mecanismo son los hooks: comandos de shell que Claude Code ejecuta automáticamente en eventos del ciclo de vida de la sesión, configurados en settings.json. El cuarto son los subagentes, archivos que definen un agente con su modelo, sus herramientas y su encargo; la documentación de Anthropic describe justo eso, elegir el modelo por agente en vez de por sesión. Esos dos son la base de todo lo que viene.

Cómo usar Claude Code con agentes: mi configuración

Mi sesión principal es un orquestador: planea, descompone, delega, decide y no escribe código. La razón es económica antes que arquitectónica: la sesión corre en el modelo más caro disponible, así que cada llamada directa a una herramienta se cobra a precio de frontera. Leer un archivo para reportar un dato, plomería de git, ejecutar un comando, aplicar una edición ya especificada: todo eso va a un worker (agente de trabajo). Dos de esos agentes son de solo lectura sobre el código, el investigador y el revisor, y el revisor escribe notas de revisión, nunca fuente, porque quien escribió el código es el peor juez de su propio trabajo, según la documentación de Anthropic: “When asked to evaluate work they’ve produced, agents tend to respond by confidently praising the work—even when, to a human observer, the quality is obviously mediocre.” Cómo repartir roles entre varios agentes lo desarrollo en agentes de IA para programar.

Cada agente trae su nivel de modelo en el archivo, y la escalera se decide por complejidad de la subtarea, no por la de la sesión:

Nivel Trabajo
haiku Reparto en paralelo mecánico: grep y reporte, inventarios de archivos, transformaciones rutinarias
sonnet Trabajo rutinario acotado: búsquedas puntuales, ediciones chicas ya especificadas
opus Agente de trabajo por defecto: implementación, primera ronda de revisión, análisis multiarchivo
modelo de la sesión Orquestación, más lo que de verdad exige razonamiento de frontera: depuración difícil, juicio de diseño, verificación adversarial

La regla de selección es deliberadamente laxa: entre dos niveles, el más barato, porque un agente de trabajo que falla es barato de correr un nivel arriba, y casi siempre falló porque el encargo era ambiguo, no por falta de modelo.

La pieza de mayor apalancamiento son unas 200 líneas de bash en tres archivos. El hook de Claude Code dispara en el evento Stop (y su gemelo SubagentStop) y ejecuta el .claude/check.sh del repositorio antes de dejar terminar el turno; si falla, el hook sale con código 2, los errores van a stderr y ese output regresa automáticamente al contexto del agente, que tiene que leerlo y corregirlo antes de poder terminar. Las buenas prácticas de Anthropic lo resumen en una línea: “Unlike CLAUDE.md instructions which are advisory, hooks are deterministic and guarantee the action happens.” Una instrucción en un archivo de contexto es una petición; un código de salida distinto de cero, no.

El hook se salta el check cuando nada cambió desde la última corrida verde, y su política de fallas es asimétrica a propósito: el de formato siempre sale con código 0, mientras que el de checks bloquea el turno y va activado por repositorio, sin efecto alguno en cualquier proyecto sin check.sh. El formato puede fallar de forma segura; correr la suite de pruebas equivocada no. Y tiene que durar segundos, porque bloquea cada stop: lint, tipos y pruebas unitarias en el hook, integración y despliegues en el CI completo.

El modo de falla que no anticipé es que los pull requests de los agentes llegan demasiado grandes. No incorrectos: grandes. Un encargo que dice “agrega una capa de caché” regresa con un módulo, una clase de configuración, una base abstracta para dos implementaciones que quizá quiera después y una sección de documentación explicando todo. Los revisores verifican que lo que existe sea correcto; nunca si debería existir. El arreglo está en la forma del encargo, que nombra resultados observables en vez de entregables:

Outcome:      una oración, comportamiento observable
Acceptance:   un check ejecutable
Mechanism:    una oración, o "decisión del implementador"
Touch:        archivos esperados; cualquier otro necesita checkpoint
Not in scope: lista explícita (hardening, documentación, refactors)
Tests:        comportamientos a probar, por nombre; nada más
Checkpoint:   sí (default) | no

De ahí cuelgan tres mecanismos. El checkpoint, activado por defecto: antes de editar, el agente de trabajo regresa un plan y el orquestador borra lo que el Acceptance no requiere, porque recortar un plan es barato y recortar un diff terminado es una negociación. El paso de recorte, ya con el check en verde: el agente de trabajo relee su diff, quita lo que sobra y cierra con una línea Not built: … para que los recortes queden visibles. Y el paso de alcance del revisor, antes de la correctitud: por cada bloque del diff se pregunta si el Outcome lo requería, y cada “no” es un hallazgo cuya dirección por defecto es borrarlo.

Medí el problema antes de construir el contrato, así que puedo decir cuál era la base:

Pull request (2026-09-15) Primera versión Cambio realmente necesario Ratio
PR A (cambio pequeño de API) +455 / −47 ~80 líneas ~5.7x
PR B (ajuste de CLI) +322 / −43 ~120 líneas ~2.7x

Ambos repositorios son privados, así que estas filas son ilustrativas y no verificables de forma independiente; la fuente es git diff --stat contra mi estimación al escribir cada encargo. La meta es una primera versión dentro de 1.5x. El conteo de líneas, aun así, no es el criterio que decide: el costo son los archivos tocados y las preocupaciones entrelazadas, y el único número que aparece es un techo de ~400 líneas, nunca la meta.

El último eslabón es el consentimiento humano. Los agentes actúan con mis credenciales de GitHub, que prohíbe aprobar tu propio pull request, así que el botón de aprobar está deshabilitado en todo lo que abre el sistema. El consentimiento se mueve a una etiqueta: un pull request con merge-me tiene mi permiso para integrarse, es barato de poner desde el celular y el orquestador la consulta con gh pr view --json state,labels,comments. La etiqueta está condicionada a CI en verde: si los checks están en rojo, el orquestador no integra ni me vuelve a preguntar, regresa el pull request al implementador y la etiqueta se queda donde está, porque el consentimiento es al cambio, no a un build roto. Que yo integre a mano cuenta como la misma señal, y un comentario mío se trata como petición de cambios sin contar contra el límite de tres rondas.

Buenas prácticas de programación agéntica con Claude Code

En septiembre de 2026 califiqué esta configuración contra la práctica publicada. Sale fuerte en proceso y débil en evidencia, que sospecho es lo habitual.

Buena práctica Estado Cómo se implementa Fuente
Cambios chicos y acotados Implementado Contrato de versión mínima viable, techo de ~400 líneas, tabla de tamaño recalculada por el revisor Google, small CLs
Orquestador y agentes de trabajo Implementado La sesión principal planea y no escribe código Building effective agents
Un modelo por agente, no por sesión Implementado Escalera de arriba; el nivel se fija en el archivo de cada agente Subagentes
Verificación obligatoria Implementado Hook de Stop con exit 2, activado por repositorio Buenas prácticas de Claude Code
Quien genera no evalúa Implementado Revisor aparte, de solo lectura sobre el código Harness design
Consentimiento humano explícito Implementado Etiqueta merge-me; escalamiento a las 3 rondas DORA 2025
Permisos y control de acceso Implementado Lista de denegación: curl, sudo, rm -rf, git push --force, más lectura de .env, *.pem y *.key Buenas prácticas de Claude Code
Contexto por capas Implementado CLAUDE.md corto que apunta a documentos bajo demanda Don’t Build Multi-Agents
Evitar la sobreingeniería Implementado Checkpoint, paso de recorte y línea Not built: arXiv 2608.13292
Especificación antes del código Parcial El encargo de investigación es obligatorio, pero sin criterios de aceptación mapeados a pruebas Buenas prácticas de Claude Code
Medición del resultado Falta Dos puntos de datos y un log de trazas del hook Demystifying evals
Revisión con otro modelo Rechazado Medido y asimétrico: Claude revisando Codex gana, al revés pierde arXiv 2607.21656

Si tuviera que quedarme con una sola fila, es la de verificación obligatoria: todo lo demás es preferencia de diseño, y esa es la que convierte “el agente dijo que terminó” en un hecho comprobable.

Vibe coding vs programación agéntica

Se confunden porque en ambos casos el código sale del modelo, pero la diferencia es dónde vive la verificación. En el vibe coding no vive en ningún lado: aceptas lo que sale, corres la aplicación y si se ve bien sigues. En la programación agéntica vive en un check que el agente tiene que pasar antes de terminar su turno, y esa es toda la distancia entre un prototipo desechable y un cambio que llega a producción. La frase de DORA que me sigue rondando es “AI doesn’t fix a team; it amplifies what’s already there.”: obligar a verificar amplifica a un equipo que ya verifica. Lo desarrollo con ejemplos en vibe coding vs programación agéntica.

Lo que todavía no tengo

  • Un registro de medición. No hay historial de líneas, rondas de revisión ni tiempo hasta la integración, así que una regresión que yo introduzca hoy al editar un encargo es invisible, como advierte Anthropic: “Without them, it’s easy to get stuck in reactive loops—catching issues only in production.”
  • Evals. Cada cambio a CLAUDE.md o al encargo de un agente sale sin verificar. La barra no es alta, según la misma publicación de evals: “In reality, 20-50 simple tasks drawn from real failures is a great start.” Ya tengo la lista en transcripciones; no la he congelado.
  • Un artefacto de especificación. Antes del código, nada dice qué significa “terminado” como criterios de aceptación mapeados uno a uno a pruebas.
  • Sandboxing real. Los worktrees en mi máquina son una frontera más débil que las máquinas virtuales aisladas de red de los proveedores; la lista de denegación y la etiqueta son los únicos controles compensatorios, suficientes solo mientras los agentes no puedan desplegar.

Revisión cruzada entre modelos, un no deliberado. Un revisor Claude sobre código escrito por Claude invita la objeción evidente: un LLM que juzga su propia salida muestra sesgo de auto-preferencia. Panickssery et al. (2024) hallaron un vínculo causal entre reconocer el propio texto y sobrevalorarlo, y Wataoka et al. (2024) lo atribuyen a la perplejidad: el modelo premia lo que le resulta familiar.

La mitigación más fuerte no es otro proveedor, sino la verificación: con ejecución de código (Findeis et al. 2025), el acuerdo del juez con la verdad sube de menos de 42% a cerca de 72%, según la revisión de literatura. Mi revisor corre después de los hooks de pruebas y lint, en un agente aparte sin memoria de haber escrito el código: la condición ciega bajo la cual Chae et al. (2026) encontraron que la auto-preferencia desaparece.

El único estudio controlado de revisión cruzada, Xiang et al. (2026), tampoco respalda el cambio: Claude revisando Codex subió de 71.6% a 89.7%, pero Codex revisando Claude bajó de 91.4% a 82.8%, peor que no revisar. Cambiar de proveedor es apostar a que el otro modelo revisa mejor, y aquí era el más débil. Lo reconsideraría al revisar algo que ninguna prueba pueda verificar, porque ahí Pombal et al. (2026) muestran que el sesgo sobrevive a rúbricas objetivas.

Preguntas frecuentes

¿Qué es Claude Code y para qué sirve?

Claude Code es el agente de programación de Anthropic que corre en la terminal y trabaja directamente sobre tu proyecto. Sirve para delegar tareas completas: leer una base de código, implementar cambios, ejecutar las pruebas, corregir los errores y preparar un commit. A diferencia de un chat, ejecuta comandos en tu entorno, así que verifica su propio trabajo en vez de solo proponerlo.

¿Cuál es la diferencia entre Claude y Claude Code?

Claude, en claude.ai, es el asistente de chat: tú llevas el contexto y te regresa texto. Claude Code es el agente de programación, disponible como CLI de terminal, extensión de VS Code y aplicación de escritorio: lee y edita archivos, ejecuta comandos y usa git por su cuenta. Comparten cuenta y modelos; cambia el acceso al entorno de desarrollo.

¿Qué se puede hacer con Claude Code?

Se puede pedir que explique un módulo desconocido, que implemente cambios acotados con sus pruebas, que persiga errores hasta la causa raíz en la terminal, o que automatice tareas repetidas. Con subagentes y hooks se va más lejos: repartir las tareas entre agentes con modelos distintos y bloquear el final del turno hasta que el lint, los tipos y las pruebas pasen.

¿Cómo usar Claude Code en VS Code?

Anthropic publica una extensión de VS Code que integra Claude Code en una barra lateral del editor: ofrece la misma sesión con un subconjunto de funciones, y algunas siguen siendo solo de la terminal. La configuración es la misma del proyecto, CLAUDE.md y .claude/, así que aplica igual desde el editor o desde la terminal, que a mí me sigue resultando más cómoda para correr varias sesiones en paralelo.

¿Cuáles son los comandos de Claude Code?

Hay dos familias. Los comandos del CLI se escriben en la terminal para iniciar o configurar una sesión; los que empiezan con / se escriben dentro de la sesión para controlar el contexto, los permisos y los flujos de trabajo. La segunda familia la extiendes tú: cada directorio que agregas en .claude/skills/ aparece como un comando / propio, versionado en git.

Lo siguiente en mi fila es el registro de medición, porque casi todo lo demás que afirmo aquí sigue sin medirse. Si vas a empezar hoy, empieza por ahí: un check.sh que corra lint, tipos y pruebas en segundos, conectado a un hook que bloquee el turno cuando falle. Los agentes vienen después.

Fuentes

claude codeprogramación agénticaia aplicadacaso práctico
← Volver al blog