Parte 4 — Avanzado

12.1 Que es MCP

El Model Context Protocol (MCP) es un estandar abierto para conectar agentes de IA con herramientas y servicios externos. Claude Code es un cliente MCP — puede llamar herramientas de cualquier servidor MCP, dando a tus agentes acceso a sistemas mucho mas alla del sistema de archivos local.

Lo que esto habilita en la practica:

• Un agente investigador que consulta la base de datos de tu empresa directamente
• Un agente revisor que publica comentarios de revision en GitHub automaticamente
• Un agente de operaciones que lee y escribe en tu CRM
• Un pipeline que publica articulos terminados en tu CMS
• Cualquier workflow que necesite interactuar con una API o fuente de datos externa

Los servidores MCP son procesos separados que exponen herramientas a traves de una interfaz estandar. Claude Code los descubre desde tu configuracion y hace sus herramientas disponibles igual que las herramientas integradas (Read, Write, Bash).

12.2 Agregar Servidores MCP

Via CLI (configuracion unica)

# Add a remote HTTP MCP server
claude mcp add --transport http my-api https://api.mycompany.com/mcp

# Add a local stdio MCP server (runs as a subprocess)
claude mcp add --transport stdio github npx -y @modelcontextprotocol/server-github

# List configured servers
claude mcp list

# Remove a server
claude mcp remove github

Via settings.json (persistente por proyecto)

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase"],
      "env": {
        "SUPABASE_URL": "${SUPABASE_URL}",
        "SUPABASE_SERVICE_ROLE_KEY": "${SUPABASE_KEY}"
      }
    }
  }
}

12.3 MCP en Flujos Agenticos

Dar acceso a herramientas MCP a los agentes

Agrega herramientas MCP a la whitelist de tools del agente usando el formato mcp__server-name__tool-name:

---
name: github-reviewer
description: Reviews GitHub pull requests, posts comments, and updates PR
  status. Use when asked to review a PR or check open pull requests.
model: sonnet
tools: Read, mcp__github__list_pull_requests, mcp__github__get_pull_request,
       mcp__github__create_review, mcp__github__add_pull_request_review_comment
permissionMode: default
---

You are a GitHub PR reviewer. You review code changes and post structured
feedback directly to the pull request.

When invoked with a PR number:
1. Fetch the PR details and diff
2. Review for: correctness, security, test coverage, style
3. Post inline comments for specific issues
4. Submit a review with verdict: Approve / Request Changes / Comment

Combinacion de Skill + MCP

Los skills funcionan bien como orquestadores de MCP — definen el workflow, los agentes aportan la experiencia:

---
name: weekly-metrics
description: Pulls this week's key metrics from our database and generates
  an executive summary. Run every Monday. Invoke with /weekly-metrics.
user-invocable: true
allowed-tools: Read, Write, mcp__supabase__execute_sql
---

# Weekly Metrics Skill

Generate the weekly metrics report from our Supabase database.

## Data Queries
Run these queries and save results to /work/metrics-raw.json:

1. New signups this week:
   SELECT COUNT(*) FROM users WHERE created_at >= NOW() - INTERVAL '7 days'

2. Active users (any event in 7 days):
   SELECT COUNT(DISTINCT user_id) FROM events
   WHERE timestamp >= NOW() - INTERVAL '7 days'

3. Revenue this week:
   SELECT SUM(amount) FROM transactions
   WHERE created_at >= NOW() - INTERVAL '7 days' AND status = 'completed'

## After collecting data
Invoke @analyst agent to generate the executive summary from the raw data.
Save the summary to /output/weekly-metrics-{date}.md

12.4 Ejemplos Reales de Integracion

GitHub — workflow de revision de codigo

## MCP Setup
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

## Usage
"Review all open PRs in the anthropic/claude-code repository
that are more than 2 days old and haven't been reviewed yet."

Supabase — agente de analisis de datos

---
name: data-analyst
description: Queries the Supabase database and produces structured analysis.
  Use for any reporting, metrics, or data investigation task.
model: opus
tools: Read, Write, mcp__supabase__execute_sql, mcp__supabase__list_tables
permissionMode: default
---

You are a data analyst with direct database access.

Before writing any query:
1. List available tables to understand the schema
2. Write safe, read-only SELECT queries
3. Never use DELETE, UPDATE, DROP, or INSERT without explicit user permission

Format your output as: findings in prose + supporting tables + raw SQL used

Google Drive — pipeline de documentos

---
name: doc-publisher
description: Exports finished articles to Google Drive in the Publications
  folder. Use after /format-article completes and the article is approved.
model: haiku
tools: Read, mcp__gdrive__create_file, mcp__gdrive__move_file
permissionMode: default
---

When given an article path:
1. Read the article from /output/
2. Create a new Google Doc in the "Publications/Drafts" folder
3. Report the document URL to the user

13.1 Que son los Plugins

Un plugin es un paquete portable de agentes, skills, hooks y comandos que se instala una vez y se puede usar en todos tus proyectos. Mientras que el directorio .claude/ de un proyecto es local a un unico codebase, un plugin es global — disponible en todas partes.

Dos razones para crear un plugin:

• Reutilizacion personal: Has construido algo excelente (un revisor de codigo, un generador de reportes semanales, un asistente de investigacion) y lo quieres en cada proyecto sin copiar archivos.
• Distribucion: Quieres compartir tu sistema con tu equipo, publicarlo como open-source o subirlo al marketplace de plugins de Claude.

13.2 Crear un Plugin

Estructura de directorios

my-plugin/
├── .claude-plugin/
│   └── marketplace.json          ← manifiesto del plugin (obligatorio)
├── agents/
│   ├── code-reviewer.md
│   └── doc-writer.md
├── skills/
│   └── pr-review/
│       └── SKILL.md
└── hooks/
    └── auto-lint.json

El archivo de manifiesto

{
  "name": "my-dev-toolkit",
  "version": "1.2.0",
  "description": "Code review, documentation, and PR workflow tools for development teams",
  "author": "Your Name",
  "license": "MIT",
  "repository": "https://github.com/you/my-dev-toolkit",
  "components": {
    "agents": ["agents/code-reviewer.md", "agents/doc-writer.md"],
    "skills": ["skills/pr-review/SKILL.md"],
    "hooks": ["hooks/auto-lint.json"]
  },
  "permissions": {
    "tools": ["Read", "Grep", "Bash"],
    "network": false
  }
}

Que incluir vs. que excluir

13.3 Instalar y Gestionar Plugins

Instalar desde una URL

# Install from GitHub
/plugin install https://github.com/you/my-dev-toolkit

# Install from the marketplace
/plugin marketplace add my-dev-toolkit

# List installed plugins
/plugin list

# Update a plugin
/plugin update my-dev-toolkit

# Remove a plugin
/plugin remove my-dev-toolkit

Usar componentes de plugins instalados

Los agentes de un plugin aparecen en el autocompletado de @ como plugin-name:agent-name:

@my-dev-toolkit:code-reviewer please review this file

Los skills de un plugin aparecen como slash commands con el prefijo del nombre del plugin:

/my-dev-toolkit:pr-review

14.1 La Capa de QA: Sistemas que se Auto-auditan

En sistemas agenticos en produccion, la Capa de QA es un ciclo de tres roles que se ejecuta automaticamente despues de cada paso completado. Es externa al proceso creativo: observa, mide y propone — pero nunca modifica ni toma decisiones en nombre del usuario.

Tres roles de QA

Rubrica de puntuacion

El Evaluator puntua cada fase en cuatro dimensiones ponderadas:

Puntuaciones: Excelente (≥9.0) | Bueno (7.0-8.9) | Mejorable (5.0-6.9) | Critico (<5.0)

El ciclo de QA en la practica

Despues de cada paso aprobado, el ciclo se dispara automaticamente:

1. Auditor lee las reglas desde disco y verifica cumplimiento → agrega el Informe de Auditoria a qa-report.md
2. Evaluator puntua la fase → agrega el bloque de Puntuacion a qa-report.md
3. Al cierre del proceso: Optimizer analiza todos los bloques de auditoria/puntuacion → propone mejoras priorizadas

El archivo qa-report.md es solo de adicion — nunca se sobrescribe, creando un historial de auditoria completo.

Ejemplo: Agente Auditor

---
name: age-spe-auditor
description: Audits phase outputs for rule compliance by reading rules
  from disk at audit time. Use after each approved checkpoint to verify
  the output follows all active constraints.
model: opus
tools: Read, Grep, Glob
permissionMode: plan
---

You are a compliance auditor. Read each active rule file from
.claude/rules/ at audit time — never rely on cached versions.

For each rule, verify compliance and report:
- ✅ Compliant (with supporting evidence)
- ⚠️ Partially compliant (what's missing)
- ❌ Non-compliant (specific violation)

Append your report to qa-report.md. Never modify any other file.

Puertas de calidad en CLAUDE.md

## Quality Gate Rules
After each approved checkpoint:
1. Invoke @age-spe-auditor — reads rules from disk, appends audit to qa-report.md
2. Invoke @age-spe-evaluator — scores the phase, appends score block
3. If score < 5.0 (Critical): warn the user before proceeding
4. At process close: invoke @age-spe-optimizer for improvement proposals

Never skip the quality gate for outputs going to /output/ (published content).

Iterar sobre sistemas generados

Una vez que un sistema esta en produccion, puedes evolucionarlo sin empezar desde cero usando tres modos de iteracion:

Cada iteracion crea una rama (ej. iter/0.2.0-add-email-skill). Cuando esta lista, se fusiona a main y se etiqueta la version.

14.2 Estrategias Multi-Modelo

Asignar el modelo correcto a cada agente es una de las decisiones de mayor impacto en el diseno de sistemas. La diferencia entre Haiku y Opus es de 10-20x en costo y 3-5x en latencia — para la tarea adecuada, ambos extremos del espectro son correctos.

El ejemplo del content pipeline, optimizado

14.3 Las Reglas de Oro

Estas reglas emergen consistentemente de sistemas en produccion. Si las violas al principio, pasaras horas depurando problemas que no necesitaban existir.

14.4 Anti-Patrones Comunes

El Agente Dios

Un agente que investiga, escribe, edita, formatea y publica. La descripcion es un parrafo. Las instrucciones son 4,000 palabras. Funciona a veces y falla de forma inconsistente.

Solucion: Aplica el arbol de decision del Capitulo 4. Cada responsabilidad distinta se convierte en su propio agente.

La Novela de Prompts

CLAUDE.md tiene 80KB de instrucciones detalladas, casos borde, ejemplos e historia. Cada sesion carga todo. El contexto se consume un 40% antes de que el usuario escriba una palabra.

Solucion: Aplica la regla de oro: si es especifico de un workflow, es un Skill. CLAUDE.md deberia poder escanearse en 30 segundos.

La Regla Invisible

Una restriccion critica esta enterrada en el parrafo 7 de un system prompt de 12 parrafos. Los agentes la leen una vez, la cumplen el 60% de las veces y la violan silenciosamente el otro 40%.

Solucion: Las reglas van en una seccion ## Rules claramente etiquetada con viñetas. Una regla por viñeta. Las reglas mas importantes primero.

El Sistema Sobre-Ingenierizado

Un workflow de 3 pasos con 12 agentes, 8 skills, 15 reglas y 6 hooks. Construido en un fin de semana. Depurado durante un mes.

Solucion: Empieza con el minimo que funcione. Agrega un agente o skill solo cuando un problema especifico y recurrente lo requiera. La complejidad es facil de agregar; dificil de quitar.

La Perdida Silenciosa de Contexto

El Agente B se invoca despues del Agente A, pero el orquestador no le dice a B lo que A produjo. B empieza de cero, duplica trabajo o hace suposiciones diferentes.

Solucion: Establece una convencion de handoff por archivos. Cada agente escribe su salida en una ruta predecible. Cada prompt de invocacion referencia esa ruta explicitamente.

La Descripcion Vaga

Dos agentes con descripciones que se solapan: "maneja tareas de escritura" y "crea contenido". Claude duda entre ambos, elige arbitrariamente o te pregunta cada vez.

Solucion: Cada descripcion debe responder: ¿en que situacion especifica debe invocarse este agente? Empieza con frases de activacion. Sin solapamiento entre agentes.

14.5 Depurar Flujos Agenticos

Cuando algo sale mal en un flujo multi-agente, el enfoque de depuracion es sistematico — no exploratorio.

Paso 1: Identifica donde se rompio el flujo

Revisa los archivos intermedios. Si /work/research-topic.md existe y se ve bien pero /work/draft-topic.md esta mal, el problema esta en el writer, no en el researcher.

Paso 2: Verifica que contexto recibio el agente

Agrega una regla temporal a CLAUDE.md:

## Debugging Rule (temporary — remove after fixing)
Each agent, at the very start of its task, must output:
"CONTEXT RECEIVED: [paste first 200 characters of your spawn prompt here]"

Paso 3: Usa Plan Mode antes de ejecutar

Ejecuta /plan antes de activar el workflow. Claude mostrara su plan completo de delegacion — que agente planea invocar, con que contexto, en que orden. Detecta problemas aqui, antes de que se toque ningun archivo.

Paso 4: Ejecuta /doctor

/doctor

Verifica tu configuracion de Claude Code en busca de problemas comunes: frontmatter faltante, nombres de herramientas invalidos, servidores MCP inalcanzables, settings.json malformado.

Paso 5: Aisla y prueba un solo agente

Invoca el agente sospechoso explicitamente con una entrada conocida y correcta:

@writer I'm going to give you a test research brief. Read it carefully and write a draft.

Research: [paste brief directly here]

Write the draft to /work/test-draft.md

Si el agente funciona correctamente en aislamiento, el problema es la transferencia de contexto. Si falla en aislamiento, el problema son las instrucciones del agente.

Registrar las salidas de los agentes en archivos

Agrega una regla a CLAUDE.md que persista el razonamiento de los agentes:

## Logging Rules
Every agent must append a summary of what it did to /logs/agent-log.md:

Format:
---
[timestamp] @agent-name
Input received: [one line summary]
Action taken: [one line summary]
Output written to: [file path]
Issues encountered: [none / description]
---

14.6 Casos de Uso No Relacionados con Codigo

Claude Code se promociona como una herramienta de desarrollo, pero el runtime de agentes que proporciona es de proposito general. El sistema de archivos es tu espacio de trabajo; los agentes son tus especialistas; los skills son tus procedimientos. Nada de eso requiere codigo.

El patron es identico en cada caso: descomponer el proceso en fases, asignar un agente por fase, disenar los handoffs de archivos, codificar la orquestacion en CLAUDE.md. El dominio cambia; la arquitectura no.

15.1 Iterar sobre tus Sistemas

Todo sistema que construyas necesitara refinamiento. Los patrones que ayudan:

Versiona tu directorio .claude/ con control de versiones

Haz commit despues de cada cambio significativo. Tus archivos de agentes son codigo de configuracion — merecen la misma disciplina que el codigo de aplicacion. Un sistema funcional que no puede reproducirse ni revertirse no es un sistema; es suerte.

git add .claude/ CLAUDE.md
git commit -m "refine: tighten researcher description to prevent overlap with writer"

Mantiene un changelog de tu sistema de agentes

Agrega un AGENTS-CHANGELOG.md en la raiz de tu proyecto. Que cambio y por que:

# Agent System Changelog

## 2026-04-10
- researcher: added explicit instruction to flag conflicting sources
- writer: tightened sentence length rule (was 30 words, now 25)
- REASON: reviewer consistently flagged complex sentences; upstream fix is cleaner

## 2026-04-03
- Added qa-auditor agent as final gate before /output/
- REASON: two articles published with uncited claims; gate catches this now

## 2026-03-28
- Moved style guide from CLAUDE.md to .claude/knowledge/style-guide.md
- REASON: CLAUDE.md was 8KB; style guide is only relevant for writer agent

Empieza simple, mide, mejora

La secuencia correcta: un agente funcionando correctamente → dos agentes con handoff de archivos → agregar reviewer → agregar puerta de calidad → agregar hooks. Cada adicion debe resolver un problema concreto y observado — no uno teorico.

15.2 Adopcion en Equipo

Compartir via Git

Como tu sistema son archivos, compartir es un pull request. Haz commit de tu directorio .claude/ y CLAUDE.md. Los companeros de equipo clonan el repo y lo abren en la pestana Code — inmediatamente tienen los mismos agentes, skills y reglas.

Alcance de proyecto vs. alcance de usuario para equipos

• Alcance de proyecto (.claude/agents/) — agentes especificos de este codebase. En Git. Todo el equipo los obtiene.
• Alcance de usuario (~/.claude/agents/) — agentes de productividad personal. No estan en Git. Solo tuyos.

Incorporar nuevos miembros al equipo

Agrega una seccion al README de tu proyecto:

## AI-Assisted Workflows

This project includes Claude Code agent configurations in `.claude/`.

To use them:
1. Install Claude Desktop and enable the Code tab
2. Open this project folder in the Code tab
3. The agents and skills are auto-discovered

Available agents:
- @code-reviewer — review any file or diff
- @doc-writer — generate documentation from code
- @test-writer — generate tests from implementation

Type /help inside Claude Code to see all available skills.

Subagentes gestionados (nivel organizacion)

Las cuentas empresariales de Claude pueden configurar agentes a nivel organizacion que estan disponibles para todos los usuarios sin necesidad de estar en el directorio .claude/ de cada proyecto. Contacta a tu account manager o consulta code.claude.com/docs para conocer las capacidades actuales de agentes gestionados.

15.3 Recursos

15.4 El Cambio de Mentalidad

Esta guia comenzo con una observacion simple: la mayoria de personas usan IA en Nivel 1 o 2. Hacen preguntas y obtienen respuestas. Escriben prompts y obtienen respuestas. Son buenos en ello — pero siguen en modo conversacion.

El cambio que esta guia ha ido construyendo es arquitectonico. Ya no preguntas "¿que prompt deberia escribir?" Preguntas "¿que sistema deberia disenar?" La IA no es tu contraparte en una conversacion — es tu fuerza de trabajo, estructurada y desplegada.

El rol del arquitecto, como has visto a lo largo de estos capitulos, es:

• Descomponer — dividir cualquier proceso en fases con responsabilidades claras
• Delegar — asignar cada fase al especialista correcto con las herramientas adecuadas
• Revisar — construir puertas de calidad, no solo rutas de ejecucion

Los sistemas que construyas sobreviviran a las conversaciones que los inspiraron. Un agente bien disenado, commiteado en Git, incorporado a tu equipo, ejecutandose de forma fiable en produccion — esa es una categoria de trabajo diferente a un buen prompt.

Empieza con el sistema minimo que funcione. Haz commit. Ejecutalo. Observa que se rompe. Corrige exactamente eso. Repite.