Del autocompletado al agente que ejecuta tareas completas
Durante años, la inteligencia artificial aplicada a la programación se limitó a sugerir la siguiente línea de código o a responder preguntas en una ventana de chat. El desarrollador copiaba, pegaba, ajustaba y volvía a preguntar. Claude Code, la herramienta de Anthropic para desarrollo de software, rompe ese patrón: no se limita a proponer fragmentos, sino que actúa dentro del proyecto. Lee archivos, edita código, ejecuta comandos en la terminal, corre pruebas, consulta documentación y puede abrir pull requests, todo bajo la dirección de la persona que lo utiliza.
Esa diferencia cambia la naturaleza del trabajo. Quien programa con un agente deja de escribir cada instrucción y pasa a especificar, revisar y decidir. El resultado depende menos de la velocidad para teclear y mucho más de la claridad con la que se describe lo que se quiere construir, de la estructura del proyecto y de la disciplina para verificar lo que el agente produce.
En esta guía se recorre todo el ciclo: instalación con el método recomendado actualmente, primeros pasos, redacción de instrucciones efectivas, planificación, construcción incremental, funcionamiento interno del agente, manejo del contexto, integraciones mediante el protocolo MCP, ejecución en paralelo con Git worktrees, instrucciones persistentes y criterios para usar bucles autónomos sin perder el control. Al final se incluyen errores frecuentes, problemas típicos de instalación y recomendaciones para llevar este flujo a equipos profesionales.
Qué distingue a un agente de un asistente conversacional
Un asistente conversacional produce texto a partir de texto. Puede explicar un algoritmo o redactar una función, pero quien actúa es el humano: crea el archivo, ejecuta el comando, interpreta el error. Un agente, en cambio, dispone de herramientas que le permiten actuar por sí mismo dentro de un entorno controlado.
En una sesión de Claude Code, el modelo puede listar directorios, abrir los archivos relevantes, proponer cambios, aplicarlos, ejecutar la suite de pruebas, leer los fallos y corregirlos. La filosofía de diseño de Anthropic consiste en exponer el modelo con un conjunto reducido de herramientas y poco andamiaje, de modo que sea el propio modelo quien decida qué herramienta usar, en qué orden y cómo combinarlas. Por eso la calidad de la herramienta está ligada directamente a la calidad del modelo que la impulsa.
Claude Code está disponible en la terminal (macOS, Linux y Windows), como extensión para Visual Studio Code y otros IDE, en la aplicación de escritorio de Claude, en la web y en integraciones como GitHub y Slack. El agente subyacente es el mismo en todas estas superficies; cambia la interfaz, no la capacidad.
Instalación actualizada y primera configuración
Durante su primera etapa, Claude Code se distribuía principalmente como paquete global de npm, lo que obligaba a tener Node.js instalado. Hoy la documentación oficial recomienda el instalador nativo, que no requiere Node.js, configura el binario automáticamente y se actualiza en segundo plano. El paquete de npm sigue disponible para quien lo necesite, pero ya no es la vía principal.
En macOS, Linux o WSL basta con un comando:
curl -fsSL https://claude.ai/install.sh | bash
En Windows, desde PowerShell:
irm https://claude.ai/install.ps1 | iex
En Windows nativo se recomienda tener Git for Windows instalado, porque aporta Git Bash, que la herramienta de shell de Claude Code utiliza; si no está presente, el agente recurre a PowerShell. También existen alternativas como Homebrew o WinGet:
brew install --cask claude-code
Si todavía se tiene una instalación antigua basada en npm, es posible migrar al binario nativo con un solo comando, cerrando antes todas las sesiones abiertas:
claude install
Para comprobar que todo funciona, se abre una nueva terminal y se consulta la versión:
claude --version
2.1.308 (Claude Code)
El número exacto variará, ya que la herramienta publica versiones con mucha frecuencia y el instalador nativo las aplica automáticamente. Para actualizar manualmente se usa claude update, y dentro de una sesión el comando /release-notes muestra los cambios recientes.
El siguiente paso es entrar en el directorio del proyecto y lanzar el agente:
cd ~/proyectos/biblioteca-digital
claude
La primera vez se solicitará autenticación con una cuenta de Claude. El uso de Claude Code requiere un plan de pago (Pro o Max) o una clave de la API de Anthropic con facturación por consumo. Una recomendación práctica es empezar con el plan más modesto que no frustre el trabajo diario y subir de nivel solo cuando los límites de uso empiecen a interrumpir sesiones con regularidad.
Una vez dentro, tres comandos conviene ejecutarlos desde el principio: /model para elegir el modelo, /permissions para revisar qué puede hacer el agente sin preguntar y /help para ver todos los comandos disponibles. Por defecto, Claude Code solicita aprobación antes de modificar archivos, un comportamiento que conviene mantener mientras se aprende cómo trabaja.
Elegir el modelo adecuado para cada tarea
Claude Code funciona con la familia de modelos Claude. En el momento de escribir esta guía, la generación disponible incluye Claude Opus 5.5, Claude Sonnet 5.5 y Claude Haiku 5.5, además de los modelos de la gama Mythos para casos específicos. Cada uno ofrece un equilibrio diferente entre capacidad de razonamiento, velocidad y coste.
Opus es la opción más capaz y la más adecuada para decisiones arquitectónicas, sesiones autónomas largas y flujos con varios agentes. Sonnet ofrece un rendimiento sólido en la mayoría de tareas de desarrollo con un coste por token menor. Haiku es el más rápido y económico, útil para consultas sencillas o subtareas ligeras.
Un argumento que se repite entre los usuarios avanzados es contraintuitivo: el modelo más barato por token no siempre resulta más barato por tarea. Un modelo con menos capacidad suele necesitar más ciclos de corrección, más aclaraciones y más lecturas de archivos para llegar al mismo resultado. En trabajo complejo, el modelo más potente puede terminar consumiendo menos tokens en total porque acierta antes. La recomendación razonable es no optimizar costes de forma prematura: usar el modelo más capaz mientras se valida un flujo y ajustar solo cuando el patrón de trabajo esté claro.
El modelo se puede cambiar en cualquier momento dentro de la sesión:
/model
Instrucciones precisas: la calidad de la salida depende de la entrada
La mayoría de resultados decepcionantes con un agente de código no se deben a falta de capacidad del modelo, sino a instrucciones incompletas. Cuando la descripción es vaga, el agente rellena los huecos con supuestos razonables, y esos supuestos rara vez coinciden exactamente con lo que se tenía en mente.
Compárese una petición mínima con una especificación útil. La primera:
Crea una app para gestionar préstamos de libros.
La segunda:
Crea una aplicación para gestionar préstamos en una biblioteca de barrio. Requisitos:
1. Cada libro tiene título, autor, ISBN y estado (disponible, prestado, en reparación)
2. Cada préstamo registra el libro, el nombre del socio, la fecha de salida y la fecha límite
3. Al devolver un libro se guarda la fecha real de devolución
4. La lista de préstamos se puede filtrar por socio y por préstamos vencidos
5. Los datos se guardan en localStorage, sin backend
6. Interfaz clara con tema claro, sin frameworks CSS externos
Tecnología: HTML, CSS y JavaScript sin dependencias.
La segunda versión cierra casi todas las decisiones que el agente tendría que adivinar. Una prueba útil consiste en preguntarse si un ingeniero competente, sin ningún otro contexto, podría construir exactamente lo que se quiere a partir de ese texto. Si la respuesta es no, faltan detalles.
También conviene ser explícito con lo que parece obvio: si se desea que el agente lea la documentación de una librería antes de escribir código, que no toque determinados archivos o que use una versión concreta de un paquete, hay que decirlo. Las expectativas implícitas son las que más a menudo se incumplen.
Planificar antes de escribir una sola línea
La planificación es la actividad con mayor retorno en el trabajo con agentes. Un plan revisado antes de tocar el código permite detectar malentendidos cuando corregirlos cuesta minutos, no horas. Sin ese paso, el agente toma decisiones arquitectónicas por su cuenta y algunas resultarán equivocadas cuando ya hay mucho código construido sobre ellas.
Claude Code incluye Plan Mode, un modo en el que el agente analiza la tarea, explora los archivos necesarios y propone un plan detallado sin modificar nada. En la terminal se activa pulsando Shift+Tab, que alterna entre los modos disponibles (normal, aceptación automática de ediciones y planificación) hasta que la interfaz indica que el modo de plan está activo. En la extensión de VS Code y en la aplicación de escritorio existe un selector visual equivalente.
El plan debe leerse de verdad: qué archivos se tocarán, en qué orden, cómo fluirán los datos y qué casos límite se contemplan. Es el punto de intervención más barato de todo el proceso. Se puede pedir que cambie el enfoque, que reduzca el alcance o que añada restricciones antes de aprobarlo.
Para proyectos nuevos resulta muy útil redactar un documento de requisitos, un archivo PRD.md en la raíz con lo que se va a construir, para quién, la lista de funcionalidades descritas por su comportamiento, la pila tecnológica y los criterios de aceptación. Una técnica eficaz para generarlo es pedir al agente que entreviste al usuario antes de planificar:
Quiero construir una aplicación de reservas para un pequeño estudio de yoga.
Antes de proponer un plan o escribir código, entrevístame de forma sistemática
sobre requisitos técnicos, funcionalidades, decisiones de interfaz, modelo de datos
y compromisos que debería considerar. Haz las preguntas en bloques breves.
No pases a la planificación hasta terminar la entrevista y resume después
las respuestas en un archivo PRD.md.
Este enfoque saca a la luz decisiones que todavía no se habían tomado de forma consciente, como qué ocurre si dos personas reservan la misma plaza o cómo se gestionan las cancelaciones de última hora.
Construir funcionalidad por funcionalidad
Intentar que el agente construya una aplicación completa en una sola pasada es tentador y casi siempre contraproducente. Un defecto en la base se propaga a todo lo que se construye encima. La alternativa es avanzar por funcionalidades, verificando cada una antes de pasar a la siguiente.
Un ciclo de trabajo sólido para cada funcionalidad sigue estos pasos:
- Describir la funcionalidad con detalle, incluyendo archivos implicados y criterios de aceptación.
- Activar Plan Mode y revisar la propuesta del agente.
- Aprobar el plan y revisar las diferencias de cada archivo modificado.
- Probar manualmente el comportamiento, incluidos los casos límite.
- Señalar con precisión cualquier discrepancia y pedir la corrección.
- Confirmar que funciona y avanzar a la siguiente funcionalidad.
Este método también tiene una ventaja menos evidente: quien revisa cada paso entiende cómo funciona el sistema. Esa comprensión es la que permite dirigir correcciones eficaces, tomar buenas decisiones de diseño y explicar el proyecto a otras personas.
Para quien empieza, los mejores primeros proyectos son pequeños y producen resultados visibles de inmediato: una página personal, una calculadora, un gestor de listas con persistencia local o un panel que consume una API pública. No requieren servidores ni despliegues, y el ciclo de retroalimentación es tan corto como abrir el archivo en el navegador.
Cómo funciona el agente por dentro
Entender el mecanismo interno ayuda a escribir mejores instrucciones y a diagnosticar problemas. Claude Code opera mediante un bucle de razonamiento: recibe una entrada, decide la siguiente acción, invoca una herramienta, observa el resultado y vuelve a razonar, repitiendo el ciclo hasta completar la tarea o necesitar información del usuario.
Las herramientas son funciones con nombre y parámetros: leer archivos, escribirlos, aplicar ediciones puntuales, ejecutar comandos de shell, buscar patrones en el código, consultar la web o pedir una aclaración al usuario. Cuando el agente ejecuta las pruebas, lanza el comando, lee qué falló, edita el archivo correspondiente y vuelve a ejecutar la suite.
Un detalle importante es que el agente no lee todo el repositorio al empezar. Explora de forma selectiva: lista la estructura, identifica los directorios relevantes y abre solo los archivos que parecen necesarios para la tarea. Su visión del proyecto siempre es parcial. Si una convención vive en un archivo que no ha leído, no la aplicará a menos que se le indique. Por eso es útil nombrar archivos concretos en la instrucción:
Antes de implementar el filtro de préstamos vencidos, lee src/services/loanService.js
y src/utils/dates.js. Reutiliza las funciones de fechas existentes en lugar de crear nuevas.
La excepción es CLAUDE.md, un archivo de instrucciones del proyecto que se carga automáticamente al inicio de cada sesión. Es el canal más fiable para que ciertas reglas estén siempre presentes.
Arquitectura pensada para trabajar con agentes
Existe una relación directa entre la organización del código y la eficacia del agente. En un proyecto donde cada archivo tiene una responsabilidad clara, los nombres describen su contenido y las dependencias fluyen en una sola dirección, el agente necesita leer pocos archivos para entender un componente y sus cambios encajan con lo existente. En un proyecto desordenado, cada cambio exige más contexto, más tokens y más riesgo de efectos secundarios.
Una estructura por capas funciona especialmente bien:
biblioteca-digital/
├── CLAUDE.md
├── PRD.md
├── README.md
├── src/
│ ├── components/ # Interfaz: cada componente muestra una sola cosa
│ ├── services/ # Lógica de negocio por dominio
│ ├── api/ # Manejadores HTTP por grupo de rutas
│ ├── db/ # Acceso a datos por entidad
│ ├── integrations/ # Servicios externos aislados
│ ├── utils/ # Funciones puras sin estado
│ └── config/ # Toda la configuración centralizada
└── tests/
Una práctica muy recomendable al iniciar un proyecto es pedir primero un esqueleto: archivos vacíos en su sitio, con importaciones y firmas de funciones, pero sin lógica. Revisar ese esqueleto permite detectar errores estructurales antes de que exista código que reescribir.
Los cambios que hace el agente también revelan información sobre el diseño. Si una funcionalidad sencilla obliga a modificar muchos archivos, el alcance está mal definido o hay demasiado acoplamiento. Si los mismos archivos se modifican en casi todas las funcionalidades, están asumiendo demasiadas responsabilidades. Leer esas señales como información sobre la arquitectura, y no como fallos del agente, es una forma de mejorar el proyecto con el tiempo.
Los nombres de archivo importan más de lo que parece. Un archivo llamado helpers.js no dice nada; isbnValidator.js o loanDates.js indican exactamente dónde buscar. Documentar estas convenciones en CLAUDE.md hace que el agente las respete de forma consistente.
CLAUDE.md, reglas persistentes y skills
CLAUDE.md es el lugar donde se documenta lo que el agente debe saber siempre: pila tecnológica, estructura, convenciones, librerías permitidas y prohibidas, reglas de seguridad y una definición de terminado bien explícita para cada funcionalidad. El comando /init genera un primer borrador analizando el repositorio, que después conviene revisar y ampliar a mano.
Un ejemplo de contenido para el proyecto de la biblioteca:
# Biblioteca Digital: contexto para Claude
## Arquitectura
- Node.js con Express en el backend, SQLite como base de datos
- Frontend en HTML, CSS y JavaScript con módulos ES
## Convenciones
- Siempre async/await, nunca cadenas de .then()
- Todo acceso a la base de datos pasa por src/db/\*Repo.js; no hay SQL en las rutas
- Componentes en PascalCase (LoanCard), servicios en camelCase (loanService)
- Pruebas junto al archivo probado, con sufijo .test.js
## Seguridad
- Nunca registrar datos personales de socios en los logs
- Consultas SQL siempre parametrizadas
## Definición de terminado
1. El comportamiento descrito funciona en todos los escenarios especificados
2. Los casos límite indicados están cubiertos
3. Existe una prueba unitaria que pasa
4. El linter no reporta errores nuevos
5. La interfaz funciona en anchos de escritorio y móvil
Con esa definición presente, el agente no declara una tarea terminada solo porque el camino feliz funciona.
Más allá de CLAUDE.md, Claude Code admite skills: carpetas con un archivo SKILL.md que describe cómo realizar un tipo de tarea concreta, por ejemplo preparar una versión, revisar código según una guía interna o desplegar en una plataforma específica. A diferencia de CLAUDE.md, que se carga siempre, una skill se carga cuando la tarea la requiere, lo que ahorra contexto. Pueden vivir en el proyecto, en la configuración del usuario o distribuirse mediante plugins.
.claude/
├── settings.json
├── agents/
│ └── revisor-seguridad.md
└── skills/
└── publicar-version/
└── SKILL.md
En la misma carpeta pueden definirse subagentes personalizados, con sus propias instrucciones y herramientas permitidas, y en settings.json las reglas de permisos que determinan qué comandos puede ejecutar el agente sin pedir confirmación.
Gestión de la ventana de contexto entre sesiones
Cada sesión trabaja dentro de una ventana de contexto: todo lo que el modelo tiene presente a la vez, incluida la conversación, los archivos leídos y la salida de los comandos. Su tamaño depende del modelo, pero en sesiones largas se llena más rápido de lo que parece. El síntoma típico de saturación es la deriva: el agente empieza a olvidar decisiones tomadas al principio o vuelve a supuestos por defecto.
Claude Code muestra el uso de contexto y ofrece comandos para gestionarlo. /context permite ver cómo se reparte, /compact resume la conversación para liberar espacio conservando lo esencial y /clear empieza de cero. Una convención extendida entre usuarios experimentados es iniciar una sesión nueva cuando el uso ronda la mitad de la ventana, antes de entrar en la zona de degradación.
Empezar de nuevo no significa perder el trabajo, siempre que el proyecto esté documentado. Una buena gestión de la ventana de contexto se apoya en cuatro archivos en la raíz:
biblioteca-digital/
├── CLAUDE.md # Convenciones y arquitectura, se carga siempre
├── PRD.md # Qué se construye y criterios de aceptación
├── README.md # Estado actual de la implementación
└── progress.md # Decisiones, enfoques descartados y dudas abiertas
El README.md puede incluir una sección de estado que se actualiza al completar cada funcionalidad:
## Estado de la implementación
### Completado
- [x] Alta y edición de libros
- [x] Registro de préstamos con fecha límite
### En curso
- [ ] Avisos por correo de préstamos vencidos (lógica lista, falta el proveedor)
### Pendiente
- [ ] Exportación a CSV
- [ ] Gestión de socios con historial
Al abrir una sesión nueva basta con una instrucción breve:
Sesión nueva. Lee PRD.md, la sección de estado de README.md y progress.md.
Resume en qué punto está el proyecto y cuál es la siguiente tarea pendiente.
En medio minuto el agente recupera el estado del proyecto y se pueden corregir malentendidos antes de continuar. Mantener estos archivos al día cuesta unos minutos por sesión y ahorra horas de reconstrucción.
Integraciones externas con Model Context Protocol
MCP es un protocolo abierto creado por Anthropic para conectar agentes de IA con herramientas y servicios externos. Con un servidor MCP configurado, Claude Code puede leer y modificar datos en otra aplicación, como un gestor de incidencias, una base de datos, un espacio de documentación o un navegador automatizado, sin que el usuario tenga que copiar información de un lado a otro.
La forma actual de añadir servidores es el subcomando claude mcp add, ejecutado desde la terminal. Para un servidor remoto por HTTP:
claude mcp add --transport http notion https://mcp.notion.com/mcp
Para un servidor local que se ejecuta como proceso, como el de sistema de archivos:
claude mcp add filesystem --scope user -- npx -y @modelcontextprotocol/server-filesystem ~/Documentos/referencias
El parámetro --scope define dónde se guarda la configuración. El ámbito local, que es el predeterminado, la limita al usuario y al proyecto actual. El ámbito user la hace disponible en todos los proyectos del usuario y se almacena en ~/.claude.json. El ámbito project la escribe en un archivo .mcp.json en la raíz, pensado para versionarse en Git y compartirse con el equipo:
{
"mcpServers": {
"sentry": {
"type": "http",
"url": "https://mcp.sentry.dev/mcp"
}
}
}
Para revisar la configuración existen varios comandos de terminal:
claude mcp list
claude mcp get notion
claude mcp remove notion
Dentro de una sesión, el comando /mcp muestra el estado de conexión de cada servidor, las herramientas que expone y, cuando hace falta, el flujo de autenticación OAuth. Tras añadir un servidor conviene reiniciar la sesión para que se cargue.
Una vez conectado, se trabaja en lenguaje natural:
Revisa los errores nuevos en Sentry de las últimas 24 horas relacionados con el
módulo de préstamos, localiza el código responsable y propón una corrección en Plan Mode.
La seguridad merece atención especial. Un servidor MCP amplía lo que el agente puede hacer en sistemas reales, y con ello el impacto de un error o de una instrucción maliciosa incrustada en datos externos. Las recomendaciones básicas son conceder solo los permisos necesarios (directorios concretos, tokens con alcance limitado), revisar las acciones que modifican datos o envían mensajes antes de aprobarlas, dar instrucciones precisas en lugar de ambiguas y no incluir credenciales en los prompts, sino en la configuración del servidor o en variables de entorno.
Sesiones paralelas y Git worktrees
Con experiencia, el siguiente paso natural es trabajar con varias sesiones a la vez, cada una dedicada a un frente distinto: una implementa el frontend, otra escribe pruebas de integración y una tercera actualiza la documentación. Bien organizadas, estas sesiones reproducen la capacidad de un pequeño equipo.
La regla que hace seguro este enfoque es delimitar el alcance de cada sesión con límites explícitos:
Tu alcance en esta sesión es únicamente el directorio server/tests/.
Lee CLAUDE.md y server/routes/loans.js. Escribe pruebas de integración con
Vitest y Supertest para GET, POST, PUT y DELETE de /api/loans, incluyendo
los casos de error 400 y 404. No modifiques ningún archivo fuera de server/tests/.
Cuando el riesgo de conflictos es mayor, la herramienta adecuada son los worktrees de Git: directorios de trabajo adicionales vinculados al mismo repositorio, cada uno con una rama distinta. Las sesiones paralelas con worktrees quedan aisladas físicamente, porque cada agente solo ve los archivos de su directorio:
git worktree add -b feature/avisos-vencidos ../biblioteca-avisos
git worktree add -b feature/exportar-csv ../biblioteca-exportar
git worktree list
/home/dev/biblioteca-digital a1b2c3d [main]
/home/dev/biblioteca-avisos a1b2c3d [feature/avisos-vencidos]
/home/dev/biblioteca-exportar a1b2c3d [feature/exportar-csv]
Se abre una sesión de Claude Code en cada directorio y, al terminar y verificar cada rama, se integran por el proceso habitual de revisión. Después se eliminan los worktrees que ya no se necesitan:
git worktree remove ../biblioteca-avisos
Además de las sesiones manuales, Claude Code puede lanzar subagentes por su cuenta cuando una tarea admite división, por ejemplo auditar varios módulos y consolidar los hallazgos en un único informe. El usuario da una instrucción y recibe un resultado coherente. Los worktrees no son imprescindibles para todo: en tareas con alcances bien separados basta con un solo directorio y límites claros en cada instrucción.
Bucles autónomos: cuándo sí y cuándo no
En modo autónomo, el agente recibe una lista de tareas y la completa sin pedir aprobación entre pasos. La ganancia de eficiencia es real para trabajo repetitivo, pero un bucle amplifica tanto la calidad de las instrucciones como sus defectos. Un malentendido al principio se replicará de forma consistente en todo lo que siga.
Encajan bien en un bucle tareas como documentar un conjunto definido de funciones, generar pruebas para componentes con comportamiento claro, aplicar un patrón de refactorización uniforme o ejecutar un análisis sobre una serie de entradas. No encajan las funcionalidades nuevas con alcance difuso, el trabajo de arquitectura, cualquier tarea cuyo resultado aceptable no pueda especificarse de antemano ni el trabajo en bases de código desconocidas.
La secuencia recomendable es supervisar primero una muestra representativa y, solo cuando el patrón esté validado, lanzar el lote completo con reglas claras:
Vas a añadir comentarios JSDoc a todas las funciones del directorio src/utils/.
Reglas:
- Para cada función: descripción de una línea, @param con nombre, tipo y descripción,
y @returns con tipo y descripción
- No cambies ninguna lógica, solo añade comentarios
- No modifiques archivos fuera de src/utils/
- Procesa los archivos en orden alfabético sin pedir aprobación entre ellos
- Al terminar, muestra qué archivos modificaste y cuántas funciones documentaste
Lo que hace seguro este bucle es la combinación de condiciones: tarea uniforme, criterio de terminado inequívoco, alcance acotado, operación aditiva y una muestra ya verificada. Si falla cualquiera de ellas, lo prudente es volver a la ejecución supervisada. Al final, git diff permite revisar el conjunto de cambios antes de confirmarlos.
Revisión, seguridad y verificación del código generado
Las capacidades del agente no eliminan la necesidad de revisar. El código generado por IA se somete a los mismos estándares que cualquier otro. Hay categorías de fallo conocidas que conviene tener presentes: referencias a funciones o parámetros que no existen o que cambiaron entre versiones, omisión de casos límite como entradas vacías o fallos de red, introducción de vulnerabilidades como inyección SQL o validación insuficiente, y una confianza en el tono que no guarda relación con la corrección del resultado.
Una revisión del código generado eficaz combina varias capas. Primero, leer el código lo suficiente para poder explicarlo. Después, probar el comportamiento manualmente, incluidos los extremos. A continuación, pedir pruebas automatizadas que cubran explícitamente los casos límite. Y por último, aplicar un escrutinio adicional en áreas sensibles como autenticación, pagos o datos personales.
Un ejemplo de prueba que conviene exigir para una función de fechas de préstamo:
import { describe, it, expect } from "vitest";
import { isOverdue } from "../src/utils/loanDates.js";
describe("isOverdue", () => {
it("devuelve false si la fecha límite es hoy", () => {
const today = new Date("2026-10-31T10:00:00");
expect(isOverdue("2026-10-31", today)).toBe(false);
});
it("devuelve true si la fecha límite ya pasó", () => {
const today = new Date("2026-11-02T10:00:00");
expect(isOverdue("2026-10-31", today)).toBe(true);
});
it("lanza un error con una fecha inválida", () => {
expect(() => isOverdue("no-es-fecha", new Date())).toThrow();
});
});
Anthropic también ofrece herramientas específicas de revisión y seguridad que analizan el código en busca de vulnerabilidades y proponen correcciones. Son una capa adicional útil, nunca un sustituto de la revisión experta en sistemas de producción.
Escribir parte del código uno mismo sigue teniendo valor. Quien delega absolutamente todo pierde progresivamente la comprensión del sistema, y esa comprensión es precisamente la que permite detectar errores sutiles. Lo más productivo es delegar el trabajo mecánico y mantener la implicación en las decisiones de diseño.
Errores comunes y cómo evitarlos
El error más frecuente es pedir demasiado de una vez. Solicitar una aplicación completa en un único mensaje produce resultados difíciles de revisar y defectos que se descubren tarde. La solución es dividir en funcionalidades y validar cada una.
Otro fallo habitual es aprobar planes sin leerlos. Plan Mode solo aporta valor si el plan se examina con atención; aprobarlo de forma refleja equivale a no usarlo.
Activar la aceptación automática de ediciones demasiado pronto también genera problemas. Ese modo tiene sentido después de revisar y aprobar un plan, cuando la estrategia ya está validada, pero no como configuración por defecto mientras se aprende.
Ignorar el uso de contexto lleva a sesiones que se degradan sin que el usuario entienda por qué. Vigilar el indicador, compactar o empezar de nuevo a tiempo evita respuestas incoherentes.
No mantener actualizados CLAUDE.md, el README.md y las notas de progreso obliga a reconstruir el contexto en cada sesión. Y por último, conectar servidores MCP con permisos excesivos expone sistemas reales a acciones no deseadas.
Solución de problemas frecuentes
Si después de instalar la terminal responde que no encuentra el comando, el directorio de instalación no está en el PATH. Basta con abrir una terminal nueva y, si persiste, revisar la configuración del shell:
zsh: command not found: claude
echo $PATH
source ~/.zshrc
claude --version
Si conviven una instalación antigua de npm y la nativa, pueden producirse conflictos de versión. Lo más limpio es desinstalar el paquete global y quedarse con el binario nativo:
npm uninstall -g @anthropic-ai/claude-code
curl -fsSL https://claude.ai/install.sh | bash
En distribuciones basadas en musl, como Alpine, el instalador nativo requiere bibliotecas adicionales y ripgrep instalados mediante el gestor de paquetes. Si las búsquedas dentro del proyecto fallan, la causa suele estar relacionada con ripgrep.
Cuando un servidor MCP no aparece en /mcp, conviene comprobar con claude mcp list en qué ámbito quedó registrado, ya que un servidor añadido en ámbito local no estará disponible en otro proyecto. Si aparece como desconectado, claude mcp get muestra el comando o la URL configurados, y los servidores remotos con OAuth pueden requerir autenticarse de nuevo desde /mcp.
Si el agente empieza a contradecir decisiones anteriores, lo más probable es que el contexto esté saturado. La respuesta es compactar o abrir una sesión nueva apoyada en los archivos de continuidad.
Claude Code frente a otras herramientas de programación con IA
El ecosistema de herramientas de desarrollo asistido por IA es amplio: editores con IA integrada, extensiones de autocompletado, CLI de otros proveedores y agentes en la nube. La elección depende del tipo de trabajo.
Las herramientas de autocompletado son excelentes para acelerar la escritura línea a línea cuando el desarrollador ya sabe exactamente qué quiere. Los editores con IA integrada ofrecen una experiencia visual muy pulida para ediciones localizadas. Los agentes de terminal como Claude Code destacan cuando la tarea implica explorar un repositorio, ejecutar comandos, iterar con las pruebas y coordinar cambios en varios archivos, y además se integran bien con scripts, CI y flujos basados en Git.
En la práctica, muchos equipos combinan herramientas: autocompletado para el trabajo fino, un agente para tareas de varios pasos y revisiones automatizadas en los pull requests. Lo importante es que el flujo de trabajo con agentes se apoye en los mismos principios sin importar la herramienta: especificación clara, planificación, verificación y documentación del proyecto.
Buenas prácticas para equipos y entornos de producción
Llevar Claude Code a un equipo requiere acordar convenciones. Versionar CLAUDE.md y .mcp.json en el repositorio garantiza que todos los miembros trabajan con el mismo contexto y las mismas integraciones. Las reglas de permisos en .claude/settings.json pueden restringir comandos peligrosos y permitir sin preguntar los habituales, como el linter o las pruebas:
{
"permissions": {
"allow": ["Bash(npm run lint)", "Bash(npm test:*)"],
"deny": ["Bash(rm -rf:*)", "Read(./.env)"]
}
}
El código generado por el agente debe pasar por el mismo proceso de revisión que cualquier otro cambio: pull request, revisión humana, pruebas automáticas y análisis de seguridad. Para equipos que necesitan coherencia entre desarrolladores, el instalador nativo permite fijar versiones o elegir entre el canal estable y el canal más reciente.
También conviene acordar cuándo se usan bucles autónomos y quién revisa sus resultados, así como mantener secretos fuera del alcance del agente mediante reglas de denegación y variables de entorno. Un equipo que documenta estas reglas reduce sorpresas y obtiene resultados más consistentes.
Conclusiones
Claude Code representa un cambio en la forma de construir software: el agente asume la traducción mecánica entre intención e implementación, y la persona se concentra en especificar, decidir y verificar. Ese cambio no elimina la necesidad de criterio técnico; la hace más visible.
Los resultados dependen de un puñado de hábitos: instalar con el método nativo recomendado, escribir instrucciones precisas, planificar con Plan Mode antes de tocar código, avanzar funcionalidad por funcionalidad, documentar el proyecto en CLAUDE.md, PRD.md, README.md y las notas de progreso, vigilar el contexto y revisar cada cambio con el mismo rigor que el código escrito a mano.
Sobre esa base, las capacidades avanzadas como las integraciones MCP, los subagentes, los worktrees y los bucles autónomos multiplican lo que una sola persona puede construir. Usadas sin esa base, multiplican también los errores. Empezar con proyectos pequeños, revisar con atención y ganar confianza de forma progresiva sigue siendo el camino más corto hacia un uso profesional de los agentes de programación.