Parte 1 — Fundamentos

1.1 Los Tres Niveles de Trabajo con IA

La mayoría de las personas están atrapadas en el Nivel 1 o 2. Esta guía te lleva al Nivel 3.

Nivel 1 — El Chat

Nivel 2 — El Asistente Configurado

Nivel 3 — El Sistema Agéntico

1.2 ¿Qué Son los Flujos Agénticos?

Definición: Un sistema de IA estructurado donde agentes especializados — cada uno con responsabilidades delimitadas y herramientas definidas — son coordinados por un orquestador para producir un resultado fiable y repetible a partir de una entrada dada.

Tres cosas hacen que un flujo sea "agéntico" en lugar de solo un system prompt largo:

1. Agentes especializados — cada uno sabe exactamente lo que hace y lo que no hace. Un Verificador de Hechos no edita estilo. Un Revisor de Estilo no verifica hechos. La restricción es una ventaja.
2. Un orquestador — recibe el objetivo de alto nivel, lo descompone en tareas, las enruta al agente correcto, gestiona excepciones y ensambla el resultado. Piensa en: gestor de proyecto, no ejecutor.
3. Resultado fiable y repetible — se ejecuta de la misma forma cada vez. Si los resultados varían enormemente entre ejecuciones, el flujo está roto.

El Cambio Mental

1.3 ¿Por Qué Claude Code?

Claude Code es una plataforma donde defines sistemas de IA usando archivos, y Claude los ejecuta. El nombre dice "code" — la realidad es mucho más amplia. Funciona igual de bien para:

• Pipelines de contenido (investigar → redactar → editar → publicar)
• Operaciones (extracción de datos → clasificación → reportes)
• Investigación (recopilar → sintetizar → resumir)
• Soporte al cliente (triaje → borrador de respuesta → escalado)
• Inteligencia de negocio (monitorear → analizar → reportar)

Tu Sistema Vive en Archivos

your-project/
├── CLAUDE.md                    ← constitución del sistema (siempre cargada)
└── .claude/
    ├── agents/
    │   ├── researcher.md        ← subagente: especialista en investigación
    │   ├── writer.md            ← subagente: redactor de contenido
    │   └── editor.md            ← subagente: revisión y edición
    ├── skills/
    │   └── weekly-report/
    │       └── SKILL.md         ← workflow reutilizable
    └── settings.json            ← hooks y permisos

2.1 Lo Que Necesitas

2.2 Abrir la Pestaña Code

Claude Desktop es la interfaz principal — no se necesita terminal.

1. Abre Claude Desktop → haz clic en la pestaña Code
2. Haz clic en Select folder → elige tu carpeta de proyecto
3. Selecciona un modelo — Sonnet 4.6 para la mayoría de tareas
4. Empieza a escribir en lenguaje natural

2.3 Tu Primera Sesión

Empieza con un prompt de solo lectura para que Claude explore sin cambiar nada:

Analyze this project folder and tell me what it contains.

Cada modificación pasa por el mismo ciclo de aprobación:

2.4 Cómo se Conectan Tus Archivos

Claude Code trabaja exclusivamente con archivos locales — nada se sube a la nube. Al seleccionar una carpeta, Claude descubre automáticamente CLAUDE.md y todo dentro de .claude/.

your-project/
├── CLAUDE.md                  ← siempre cargado al inicio de sesión
├── .claude/
│   ├── agents/                ← definiciones de subagentes
│   ├── skills/                ← workflows reutilizables
│   └── settings.json          ← hooks y permisos
└── your-other-files/

2.5 La Alternativa CLI

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

# Run inside your project folder
cd your-project && claude

2.6 Autenticación

3.1 El Bucle de Conversación

Claude Code no es un chatbot que toca archivos de paso. Es un bucle de lectura-modificación-ejecución contigo como aprobador en cada paso.

3.2 Comandos Esenciales

3.3 Plan Mode — Pensar Antes de Construir

Qué es: Claude analiza tu solicitud, produce un plan y espera tu aprobación antes de tocar cualquier archivo. Se activa con /plan o Shift+Tab.

Explore ──→ Plan ──→ Implement ──→ Commit

  Read files   Design approach   Execute steps   Done

3.4 Gestión del Contexto

Cada archivo leído, llamada a herramienta y respuesta consume tokens de la ventana de contexto de Claude. Cuando se llena, la calidad se degrada.

3.5 Selección de Modelo

Usa /model para cambiar a mitad de sesión. Regla por defecto: empieza con Sonnet, escala a Opus cuando sea necesario.

En el frontmatter de agentes y skills, usa el alias — no la cadena completa del modelo:

---
model: sonnet    # fast, cost-effective — use by default
model: opus      # complex reasoning
model: haiku     # fast, simple tasks
---

4.1 Componentes Principales

Todo sistema agéntico — sin importar su complejidad — se construye a partir de diez tipos de entidad. En Claude Code, cada uno corresponde a un archivo, directorio o configuración específica.

Convenciones de Nomenclatura

Cada archivo de entidad sigue un sistema estricto de prefijos. Esto hace que las entidades sean identificables de un vistazo y permite el descubrimiento automático.

Todos los nombres usan kebab-case, sin espacios, sin mayúsculas. El campo name en el frontmatter está limitado a 64 caracteres; el description a 250. Las descripciones deben seguir el patrón "qué + cuándo": qué hace y cuándo debe usarse.

4.2 Cómo se Relacionan

• Workflow (wor-) orquesta el flujo — invoca Agents, gestiona handoffs
• Specialists (age-spe-) ejecutan trabajo de dominio; Supervisors (age-sup-) validan el output
• Los Agents usan Skills y ejecutan Scripts
• Los Commands son invocados directamente por el usuario — omiten el Workflow
• Las Rules restringen a todos — incluido el Workflow
• Knowledge Base y Resources se consultan, nunca se ejecutan
• Los Hooks se disparan ante eventos, no ante comandos

4.3 Referencia de Componentes

Workflow (wor-)

• Recibe el objetivo de alto nivel; lo descompone en pasos; enruta a los agentes correctos; gestiona handoffs; ensambla el output
• En Claude Code: .claude/commands/wor-*.md
• El orquestador del sistema — no un ejecutor, sino un coordinador

Agent Specialist (age-spe-)

• Exactamente un dominio de responsabilidad — nada más
• Definido en .claude/agents/age-spe-*.md con frontmatter YAML
• Tiene su propia ventana de contexto aislada
• Se invoca automáticamente (coincidencia de descripción) o explícitamente vía @agent-name

Agent Supervisor (age-sup-)

• Revisa, valida o puntúa el output producido por los Specialists
• Definido en .claude/agents/age-sup-*.md
• Actúa como puerta de calidad — no produce trabajo primario, solo lo evalúa
• Úsalo cuando necesites "un segundo par de ojos" antes de que los resultados salgan de un paso

Skill (ski-)

• Paquete de capacidad reutilizable con nombre — no un ejecutor, sino un procedimiento
• Se activa por nombre (/skill-name) o coincidencia automática de descripción
• Vive en .claude/skills/ski-*/SKILL.md
• Puede abrir una nueva ventana de contexto para trabajo pesado

Command (com-)

• Acción directa y determinista — un "prompt guardado" que siempre produce el mismo comportamiento
• Solo se invoca por el usuario vía /command-name — ningún agente o workflow delega a un Command
• Vive en .claude/commands/com-*.md con frontmatter YAML mínimo
• Úsalo para tareas atómicas y repetibles: exportar un sistema, publicar una versión, aplicar optimizaciones

Rule (rul-)

• Una restricción, no una capacidad
• Dos ubicaciones: en CLAUDE.md (siempre activa, en cada sesión) o como archivos independientes en .claude/rules/rul-*.md (se cargan bajo demanda)
• Siempre se escribe como "En vez de X, haz Y" — nunca solo una prohibición
• Los archivos de Rule independientes usan formato estructurado: Contexto, Restricciones Fuertes, Restricciones Suaves

Knowledge Base (kno-)

• Contenido de referencia estático: guías de estilo, documentación de APIs, glosario de dominio
• Vive en .claude/knowledge-base/kno-*.md
• Indica a los agentes cuándo leerlo: "Si encuentras un error, lee kno-error-codes.md"

Resource (res-)

• Documento de soporte que extiende otra entidad cuando su contenido es demasiado extenso o detallado
• Vive en .claude/resources/res-*.md
• Se referencia condicionalmente: "Para uso avanzado de la API, lee res-api-full-reference.md"
• Mantiene la entidad principal liviana — el agente carga el resource solo cuando lo necesita

Script (scp-)

• Procedimiento automatizado ejecutable — validación, despliegue, procesamiento de datos
• En Claude Code: .claude/scripts/scp-*.sh o scp-*.py (archivos ejecutables)
• Los ejecutan agentes o hooks, no los invoca directamente el usuario

Hook (hok-)

• Se dispara automáticamente ante eventos del sistema — guardado de archivo, inicio de sesión, tarea completada
• Se configura en .claude/settings.json (la configuración de runtime)
• La documentación vive en .claude/hooks/hok-*.md (qué hace el hook y por qué)

4.4 Árbol de Decisión: ¿Qué Componente Necesito?

4.5 Un Sistema Mínimo Funcional

El sistema agéntico válido más pequeño necesita solo tres cosas:

your-project/
├── CLAUDE.md
└── .claude/
    └── agents/
        └── age-spe-researcher.md

CLAUDE.md

# Project: Market Research Assistant

## Purpose
This system researches topics and returns structured summaries.

## Rules
- Always cite sources
- Use the researcher agent for all information gathering
- Output in Markdown with clear section headers

## Agents
- **@age-spe-researcher** — handles all research and fact-finding tasks

.claude/agents/age-spe-researcher.md

---
name: age-spe-researcher
description: Researches topics using web search and returns structured
  summaries with citations. Use for any information gathering,
  fact-checking, or background research task.
model: sonnet
tools: WebSearch, Read
---

You are a research specialist. When given a topic:
1. Search for current, authoritative sources
2. Synthesize findings into a clear summary
3. List all sources with URLs

Output format:
## Summary
[2-3 paragraph synthesis]

## Key Facts
- [bullet list]

## Sources
- [URL] — [one-line description]

Un conjunto de reglas, un especialista. Empieza aquí — agrega complejidad solo cuando la tarea lo exija.