Lección 01: Modelo de Ejecución y Arquitectura Interna
- Claude Code no es un plugin de IDE. Es una CLI agéntica que opera directamente sobre tu sistema de archivos y terminal.
- Su arquitectura sigue un ciclo Read-Think-Act: lee tu codebase, razona sobre el problema y ejecuta acciones (editar archivos, ejecutar comandos).
- El sistema de permisos granulares controla qué acciones puede ejecutar sin confirmación y cuáles requieren aprobación explícita.
- A diferencia de Copilot o Cursor, Claude Code no autocompleta líneas: ejecuta tareas completas de forma autónoma.
La mayoría de herramientas de desarrollo asistido por IA funcionan como autocompletado glorificado. Sugieres una línea, aceptas con Tab, y sigues adelante. Claude Code opera en un paradigma completamente diferente: es un agente que vive en tu terminal, lee tu proyecto completo, toma decisiones y ejecuta acciones reales sobre tu código.
En m8d.io, no tratamos Claude Code como un "copiloto". Lo tratamos como un operador autónomo al que le describes el objetivo y él navega, edita, ejecuta tests y corrige errores. Entender su arquitectura interna es el primer paso para usarlo con precisión.
Qué es Claude Code
Claude Code es la interfaz de línea de comandos (CLI) oficial de Anthropic para desarrollo de software. Se instala como un paquete npm global, se ejecuta directamente en tu terminal y tiene acceso completo a tu sistema de archivos, a tu shell y a tus herramientas de desarrollo.
La diferencia fundamental con otras herramientas es su naturaleza agéntica. Mientras un autocompletado predice el siguiente token, Claude Code:
- Lee tu codebase completo (o las partes relevantes) para entender el contexto.
- Razona sobre la tarea utilizando el modelo Claude (Opus, Sonnet).
- Actúa ejecutando herramientas reales: editar archivos, ejecutar comandos en bash, buscar patrones con grep, crear commits con git.
- Itera sobre los resultados: si un test falla, lee el error, corrige el código y vuelve a ejecutar.
Modelo Mental Correcto
No pienses en Claude Code como "una IA que escribe código". Piensa en él como un desarrollador junior muy rápido sentado en tu terminal, al que le das instrucciones en lenguaje natural y él las ejecuta. Tu rol es supervisar, aprobar y dirigir.
Arquitectura Interna: El Bucle Agéntico
Cuando ejecutas claude en tu terminal y le das una instrucción, internamente se dispara un bucle agéntico que no se detiene hasta resolver la tarea (o hasta encontrar un bloqueo que requiera tu intervención). Este es el flujo:
Las Herramientas Internas
Claude Code no "escribe código en el vacío". Tiene acceso a un conjunto de herramientas internas que usa según la necesidad. Cada herramienta es una función con parámetros específicos:
- Read: Lee archivos del sistema de archivos local. Es la herramienta principal para entender el código existente.
- Edit: Modifica archivos existentes enviando solo el diff, no el archivo completo. Eficiente y preciso.
- Write: Crea archivos nuevos desde cero.
- Bash: Ejecuta cualquier comando en tu shell: tests, builds, git, instalaciones, scripts.
- Glob: Busca archivos por patrones (
**/*.ts,src/**/*.test.js). - Grep: Busca contenido dentro de archivos. Equivalente a
grep -rpero integrado. - Agent: Lanza sub-agentes en paralelo para tareas de investigación independientes.
# Iniciar Claude Code en tu proyecto $ claude # Claude analiza el proyecto automáticamente > Leyendo estructura del proyecto... > Detectado: Next.js 15 + TypeScript + Prisma > Archivos: 847 | Tests: 124 | Cobertura: 78% # Le das una instrucción en lenguaje natural Tu: El endpoint /api/users devuelve 500 cuando el email tiene caracteres unicode. Arréglalo y añade tests. # Claude ejecuta su bucle agéntico: > [Read] src/api/users/route.ts > [Read] src/lib/validators.ts > [Grep] "email" en src/lib/** > [Think] El validador usa regex ASCII-only... > [Edit] src/lib/validators.ts (líneas 23-31) > [Write] src/__tests__/users-unicode.test.ts > [Bash] npm test -- --grep unicode > Tests: 3 passed, 0 failed
Modelo de Permisos
Un agente con acceso completo a tu terminal y archivos necesita un sistema de seguridad robusto. Claude Code implementa un modelo de permisos de tres niveles que controla qué acciones puede ejecutar de forma autónoma:
| Herramienta | Acción | Auto | Requiere Permiso |
|---|---|---|---|
Read |
Leer archivos del proyecto | Sí | No |
Glob |
Buscar archivos por patrón | Sí | No |
Grep |
Buscar contenido en archivos | Sí | No |
Edit |
Modificar archivos existentes | Depende | Según modo de permisos |
Write |
Crear archivos nuevos | Depende | Según modo de permisos |
Bash |
Ejecutar comandos en terminal | Depende | Comandos destructivos siempre piden permiso |
Bash |
git push, rm -rf, force ops |
No | Siempre requiere aprobación explícita |
Los modos de permiso disponibles son:
- Default (Plan): Lectura libre. Escritura y bash requieren aprobación cada vez.
- Auto-edit: Lectura y escritura libre. Solo bash requiere aprobación.
- Full auto (Yolo): Todo se ejecuta sin confirmación. Solo para entornos aislados o sandboxes.
Regla de Oro
Claude Code aplica un principio de reversibilidad: las acciones fáciles de revertir (leer, editar un archivo) son menos restrictivas que las acciones destructivas (push, borrar, desplegar). Si no está seguro, pregunta antes de actuar.
Comparativa: Claude Code vs. Copilot vs. Cursor
Entender dónde se posiciona Claude Code frente a otras herramientas de desarrollo con IA es clave para elegir la correcta según tu flujo de trabajo. No son competidores directos: operan en paradigmas diferentes.
grep, navega directorios. Acceso real al filesystem. Contexto de hasta 200K tokens.El Archivo CLAUDE.md: Memoria Persistente
Un concepto clave de la arquitectura de Claude Code es el archivo CLAUDE.md. Es un archivo de texto plano en la raíz de tu proyecto (o en ~/.claude/ para configuración global) que Claude lee automáticamente al inicio de cada sesión. Funciona como una "memoria persistente" donde defines:
- Convenciones del proyecto: "Usamos TypeScript strict, Prisma como ORM, tests con Vitest".
- Reglas de estilo: "No uses any. Siempre usa interfaces, nunca types para objetos".
- Contexto de negocio: "Este es un SaaS B2B. Los 'workspaces' son la entidad central".
- Comandos frecuentes: "
npm run devpara levantar,npm testpara tests".
# CLAUDE.md - Proyecto: Dashboard Analytics ## Stack - Next.js 15 (App Router) - TypeScript (strict mode) - Prisma + PostgreSQL - Tailwind CSS - Vitest + Playwright ## Convenciones - Componentes en PascalCase, archivos en kebab-case - Server Components por defecto. "use client" solo si es necesario - No usar `any`. Preferir `unknown` + type guards - Commits en Conventional Commits (feat:, fix:, refactor:) ## Comandos npm run dev # Servidor de desarrollo (puerto 3000) npm test # Vitest en watch mode npm run db:push # Prisma push schema changes npm run lint # ESLint + Prettier check ## Reglas - NUNCA modifiques archivos en /prisma/migrations/ directamente - Siempre ejecuta tests antes de hacer commit - Las API routes van en /src/app/api/[recurso]/route.ts
Este archivo es lo que transforma a Claude Code de un agente genérico a un agente que entiende tu proyecto. Sin él, Claude aún funciona (lee tu código para inferir convenciones), pero con él, la precisión aumenta drásticamente desde el primer comando.
Preguntas Frecuentes
Sobre la arquitectura y funcionamiento de Claude Code
rm -rf, git push --force) siempre requieren confirmación, incluso en modo auto. La recomendación es nunca usar el modo "Yolo" en máquinas de producción.