Category: Claude Code

Claude Code – La guía práctica: Ingeniería de agentes en la terminal

Tiempo estimado de lectura: 4 min

• Claude Code es un agente CLI que lee árbol de archivos, ejecuta bash, corre tests y propone parches; requiere sandboxes y gobernanza técnica.
• Controla tokens y contexto desde el día 1 usando comandos operativos como /cost, /compact y flags como --safe.
• Define prompts como contratos con contexto, tarea, restricciones, verificación y condición de parada para evitar bucles.
• Extiende de forma segura con MCP y orquesta validaciones con n8n; nunca expongas credenciales y aísla ejecuciones en contenedores.
• Aplica políticas de seguridad, revisión humana obligatoria y auditoría de logs antes de producción.

Claude Code – La guía práctica es el manual operativo que necesitas si tu equipo va a delegar trabajo real en un agente CLI. Claude Code (Claude 3.7 Sonnet) no es un autocompletador: es un agente que lee el árbol de archivos, ejecuta bash, corre tests y propone parches. Dominarlo exige reglas claras, sandboxes y gobernanza técnica.

Resumen rápido (lectores con prisa)

Claude Code es un agente CLI capaz de operar sobre repositorios (leer archivos, ejecutar comandos, proponer parches). Úsalo con sandboxes (Docker/DevContainers), define prompts como contratos y controla costes con comandos como /cost. Extiende funciones con MCP y orquesta validaciones con n8n, manteniendo revisión humana para cambios sensibles.

Claude Code – La guía práctica: qué aprender primero

Arranca por lo esencial. La documentación oficial y el MCP son la base:

• Docs Anthropic (Claude Code)
• Model Context Protocol (MCP)
• Ejemplos MCP en GitHub

Instalación básica

Instalación global con npm:

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

Crea un .claudeignore en la raíz para proteger secretos:

.env*
node_modules/
dist/
secrets/
*.log

Lee “Permissions and Security” en la docs antes de ejecutar en repos real. No es opcional.

Fundamentos operativos: control de contexto y coste

Claude Code consume tokens por lectura/escritura. Controla eso desde el día 1.

Operaciones y flags

• /cost — audita tokens de la sesión. Obliga a revisar antes de tareas largas.
• /compact — comprime historial de conversación para evitar alucinaciones si el agente lleva horas iterando.
• /abort — detiene loops. Úsalo rápido si ves repetición.
• Flags: --safe (revisar comandos propuestos), --read-only (auditoría sin mutar), --detach (tareas largas en background).

Estos comandos son tus palancas operativas para no perder control.

Ingeniería de prompts y contratos de ejecución

Un prompt es un contrato, no un deseo. Estructura clara:

• Contexto (stack, convenciones).
• Tarea (qué cambiar).
• Restricciones (qué no tocar).
• Verificación (tests, coverage, linter).
• Condición de parada (máx iteraciones).

Ejemplo compactado

Contexto: Angular 22 Zoneless.
Tarea: Migrar src/dashboard a Standalone Components usando Signals.
Restricciones: No tocar auth-service.
Verificación: Ejecutar `vitest --coverage` y superar 90%.
Parada: Abortar si >3 iteraciones fallidas.

Sin eso, el agente entra en bucles y consume tokens sin producir valor.

Extensibilidad: MCP y orquestación con n8n

MCP te permite dar herramientas seguras al agente. Monta un servidor MCP interno y expón solo capacidades limitadas (leer DB, disparar webhooks), nunca credenciales.

Ejemplo conceptual de servidor MCP (Node.js)

// mcp-server.js (conceptual)
const { createServer } = require('mcp');
const server = createServer({
  capabilities: {
    read_file: true,
    execute_shell: { shell: 'bash', workingDir: '/workspace' },
    trigger_n8n: { url: 'http://localhost:5678/webhook' }
  }
});
server.listen(8080);

Integra con Claude Code: /mcp add --url http://localhost:8080.

Flujo n8n recomendado

1. Claude genera diff + artefactos.
2. MCP envia payload a n8n.
3. n8n ejecuta validaciones (linters, tests), crea ticket y notifica Slack.

Así mantienes trazabilidad y control humano.

Seguridad y sandboxing: reglas innegociables

• Nunca ejecutes tareas destructivas en la host machine. Usa Docker/DevContainers.
• .claudeignore obligatorio y auditado por SAST.
• Políticas de gasto: quotas por usuario/equipo en Anthropic Console.
• Revisión humana obligatoria para cambios que modifiquen infra o credenciales.
• Logs y auditoría: guarda transcripts de sesiones y resultados de /cost.

Riesgos comunes y mitigaciones rápidas

• Bucles por flaky tests → define max_iterations en prompt; usa --safe.
• Consumo inesperado de tokens → descompón tareas; monitoriza /cost.
• Fuga de secretos → .claudeignore + escaneo pre-run.
• Dependencias legacy (p. ej. zone.js en Angular) → audita npm ls previo y fija tests que cubran edge cases.

Cuándo adoptarlo (criterio para Tech Leads)

Adopta Claude Code si:

• Tienes stack moderno (TypeScript, Angular 22+, Next.js).
• La base tiene tests automáticos (Vitest/Playwright).
• Puedes aislar ejecuciones en contenedores y aplicar políticas de gasto.

Pospón si:

• Repo monolítico sin cobertura.
• Equipo sin habilidades de prompt engineering.
• Restricciones presupuestarias que no toleran picos de tokens.

Roadmap práctico (4 semanas)

• Semana 1: Sandbox + --safe, .claudeignore, métricas /cost.
• Semana 2: Prompts estructurados y pruebas automáticas con Vitest.
• Semana 3: Implementa servidor MCP mínimo y flujo n8n.
• Semana 4: Políticas de gobernanza, cuotas, playbook de incidentes.

Claude Code no es magia; es ingeniería aplicada. Monta sandbox, define contratos de prompts, limita el alcance con MCP y registra todo. Hazlo bien y convertirás la terminal en un colaborador que acelera refactors y tareas repetitivas sin apagar el control humano. Esto empieza hoy: configura el sandbox y documenta las reglas internas; el resto viene después.

Dominicode Labs

Para equipos que diseñan flujos de automatización y orquestación con agentes, una fuente útil de referencia y experimentación es Dominicode Labs. Puede servir como continuación lógica para prototipar MCP + n8n y playbooks de gobernanza.

Referencias y recursos

• Docs Anthropic (Claude Code)
• Model Context Protocol (MCP)
• Ejemplos MCP en GitHub

FAQ

• ¿Qué es Claude Code y en qué se diferencia de un autocompletador?
• ¿Cómo evito que el agente consuma tokens excesivos?
• ¿Qué medidas de seguridad son obligatorias antes de ejecutar en repos reales?
• ¿Qué es MCP y por qué usarlo?
• ¿Cuándo debo usar --safe o --read-only?
• ¿Cómo integro validaciones automáticas con n8n?
• ¿Qué debe incluir un prompt para evitar bucles?