https://futurewithml.netlify.app
|
Esta es una fuente web, también conocida como fuente Atom. Suscríbete copiando la URL de la barra de direcciones en tu lector de noticias. Visita About Feeds para aprender más y empezar. Es gratis.
Visita la web
Publicaciones recientes
Actualizado el $DATE
date
Agentes IA
Future With ML - Agentes IA
Patrones de Diseño en Machine Learning, MLOps e Ingeniería de IA por Christian Picon Calderon
Zola2026-01-06T11:00:00+00:00https://futurewithml.netlify.app/es/tags/agentes-ia/atom.xml
El Patrón de Arquitectura Híbrida: Lecciones de agent-team-creator
2026-01-06T11:00:00+00:00
2026-01-06T11:00:00+00:00
Christian Picon Calderon
https://futurewithml.netlify.app/es/posts/claude-code-plugin-journey-part1/
<h1 id="el-patron-de-arquitectura-hibrida-lecciones-de-agent-team-creator">El Patrón de Arquitectura Híbrida: Lecciones de agent-team-creator</h1>
<blockquote>
<p><em>Esta es la Parte 1 de una serie de tres partes. Comienza con <a href="/posts/claude-code-plugin-journey-part0/">Parte 0: Agent Team Creator</a> para ver qué hace el plugin, o continúa aquí para el viaje de desarrollo.</em></p>
</blockquote>
<p>Pensé que construir un plugin de Claude Code tomaría un fin de semana. Tres días después de luchar con bugs de acceso a herramientas MCP, sincronización de archivos en tres ubicaciones, y documentación que prometía features que no funcionaban, me di cuenta de que estaba construyendo algo más valioso que un plugin—estaba mapeando territorio inexplorado.</p>
<p>Esta es la historia de construir <strong>agent-team-creator</strong>, un plugin de Claude Code que analiza códigos base y genera agentes IA específicos del proyecto. En el camino, descubrí un patrón que convirtió las limitaciones de la plataforma en claridad arquitectónica: el <strong>Patrón de Arquitectura Híbrida</strong>.</p>
<span id="continue-reading"></span>
<hr />
<h2 id="acto-i-la-configuracion">Acto I: La Configuración</h2>
<h3 id="la-vision">La Visión</h3>
<p>La idea era simple: analizar cualquier código base y generar automáticamente un equipo de agentes Claude Code especializados adaptados a ese proyecto. ¿Un frontend React? Genera un agente diseñador de componentes. ¿Un pipeline ML de Python? Spawn un agente entrenador de modelos. El plugin entendería tu código y crearía colaboradores IA que hablan el lenguaje de tu proyecto.</p>
<p>Había leído la documentación. Los plugins de Claude Code soportan cinco tipos de componentes—commands, agents, skills, hooks, e integraciones MCP. Los agentes pueden spawnear subagentes usando la herramienta Task. Los servidores MCP proveen acceso a servicios externos. Parecía directo.</p>
<p>Esto es lo que esperaba versus lo que encontré:</p>
<table><thead><tr><th>Expectativa</th><th>Realidad</th></tr></thead><tbody>
<tr><td>Los agentes de plugin pueden acceder a herramientas MCP</td><td>Los agentes de plugin <strong>no pueden</strong> acceder a MCP (bug documentado)</td></tr>
<tr><td>Los agentes pueden spawnear subagentes anidados</td><td>Solo un nivel de anidamiento</td></tr>
<tr><td>La documentación describe el comportamiento real</td><td>Los docs dicen que MCP funciona, pero no lo hace</td></tr>
<tr><td>Los cambios se propagan automáticamente</td><td>Se requiere sincronización manual en 3 ubicaciones</td></tr>
<tr><td>La herencia de modelo funciona</td><td>Por defecto usa Sonnet 4 sin importar la configuración</td></tr>
</tbody></table>
<p>La brecha entre expectativa y realidad se convertiría en mi currículo.</p>
<h3 id="entendiendo-el-terreno">Entendiendo el Terreno</h3>
<p>Antes de profundizar en los puntos de dolor, déjame compartir el panorama. Los plugins de Claude Code tienen cinco tipos de componentes, cada uno con mecanismos de activación distintos:</p>
<table><thead><tr><th>Componente</th><th>Activador</th><th>Propósito</th></tr></thead><tbody>
<tr><td><strong>Skills</strong></td><td>Auto-invocados</td><td>Proveedores de contexto basados en matching de descripción</td></tr>
<tr><td><strong>Commands</strong></td><td>Iniciado por usuario (<code>/command</code>)</td><td>Atajos de comandos slash</td></tr>
<tr><td><strong>Agents</strong></td><td>Spawneados via herramienta Task</td><td>Instancias separadas de Claude para trabajo especializado</td></tr>
<tr><td><strong>Hooks</strong></td><td>Basados en eventos</td><td>Handlers de automatización (PreToolUse, PostToolUse, etc.)</td></tr>
<tr><td><strong>MCPs</strong></td><td>Llamadas a herramientas</td><td>Integraciones de servicios externos</td></tr>
</tbody></table>
<p>La estructura de directorios sigue un patrón predecible:</p>
<div class="tree-container" id="tree-202">
<canvas class="tree-canvas" aria-label="Directory structure visualization"></canvas>
</div>
<script>
(function() {
const containerId = 'tree-202';
// Decode HTML entities (Tera encodes / as /)
function decodeHTML(str) {
const textarea = document.createElement('textarea');
textarea.innerHTML = str;
return textarea.value;
}
const rootName = decodeHTML('plugin-root');
const nodeData = decodeHTML('.claude-plugin/:marketplace.json;plugin.json,commands/:*.md,agents/:*.md,skills/:SKILL.md,hooks/:*.md,.mcp.json:config');
function parseNodes(data) {
const folders = [];
data.split(',').forEach(folder => {
const [name, childrenStr] = folder.split(':');
const children = childrenStr ? childrenStr.split(';').map(c => c.trim()) : [];
folders.push({ name: name.trim(), children, type: 'folder' });
});
return folders;
}
function initTree() {
const container = document.getElementById(containerId);
if (!container) return;
const canvas = container.querySelector('.tree-canvas');
const ctx = canvas.getContext('2d');
let particles = [];
let time = 0;
const colors = {
root: '#ff0080',
folder: '#00d4ff',
file: '#8b5cf6',
config: '#ff8800',
accent: '#00ff88',
connection: 'rgba(0, 212, 255, 0.3)',
text: '#e0e0e4'
};
const folders = parseNodes(nodeData);
function resize() {
const rect = container.getBoundingClientRect();
canvas.width = rect.width;
canvas.height = 320;
}
resize();
window.addEventListener('resize', resize);
function getNodePositions() {
const nodes = [];
const centerX = canvas.width / 2;
const rootY = 50;
const folderY = 140;
const fileY = 230;
// Root node
nodes.push({
type: 'root',
label: rootName,
x: centerX,
y: rootY,
radius: 28,
color: colors.root
});
// Folder nodes
const folderSpacing = Math.min(120, (canvas.width - 100) / folders.length);
const startX = centerX - ((folders.length - 1) * folderSpacing) / 2;
folders.forEach((folder, i) => {
const x = startX + i * folderSpacing;
const isConfig = folder.name.includes('.') || folder.name.includes('json');
nodes.push({
type: 'folder',
label: folder.name,
x: x,
y: folderY,
radius: 22,
color: isConfig ? colors.config : colors.folder,
parentIndex: 0,
children: folder.children
});
});
// File nodes (spread under their parent folders)
let fileIndex = 0;
folders.forEach((folder, folderIdx) => {
const parentNode = nodes[folderIdx + 1];
const childCount = folder.children.length;
folder.children.forEach((child, childIdx) => {
const offset = (childIdx - (childCount - 1) / 2) * 50;
nodes.push({
type: 'file',
label: child,
x: parentNode.x + offset,
y: fileY + (childIdx % 2) * 35,
radius: 18,
color: colors.file,
parentIndex: folderIdx + 1
});
fileIndex++;
});
});
return nodes;
}
function draw() {
ctx.clearRect(0, 0, canvas.width, canvas.height);
const nodes = getNodePositions();
// Draw connections
ctx.strokeStyle = colors.connection;
ctx.lineWidth = 2;
nodes.forEach((node, i) => {
if (node.parentIndex !== undefined) {
const parent = nodes[node.parentIndex];
ctx.beginPath();
ctx.moveTo(parent.x, parent.y + parent.radius);
ctx.lineTo(node.x, node.y - node.radius);
ctx.stroke();
}
});
// Draw nodes
nodes.forEach((node, i) => {
// Glow effect
ctx.shadowColor = node.color;
ctx.shadowBlur = 15;
// Node circle
ctx.fillStyle = node.color;
ctx.beginPath();
ctx.arc(node.x, node.y, node.radius, 0, Math.PI * 2);
ctx.fill();
ctx.shadowBlur = 0;
// Border
ctx.strokeStyle = colors.accent;
ctx.lineWidth = 2;
ctx.stroke();
// Icon based on type
ctx.fillStyle = '#0a0a0f';
ctx.font = node.type === 'root' ? '16px sans-serif' : '12px sans-serif';
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
if (node.type === 'root') {
ctx.fillText('📁', node.x, node.y);
} else if (node.type === 'folder') {
ctx.fillText('📂', node.x, node.y);
} else {
ctx.fillText('📄', node.x, node.y);
}
// Label
ctx.fillStyle = colors.text;
ctx.font = node.type === 'root' ? 'bold 12px JetBrains Mono' : '10px JetBrains Mono';
ctx.fillText(node.label, node.x, node.y + node.radius + 14);
});
// Animated particles
if (time % 60 === 0 && particles.length < 8) {
const randomFolder = Math.floor(Math.random() * folders.length) + 1;
const parentNode = nodes[randomFolder];
if (parentNode) {
particles.push({
x: nodes[0].x,
y: nodes[0].y,
targetX: parentNode.x,
targetY: parentNode.y,
progress: 0,
speed: 0.02
});
}
}
particles = particles.filter(p => p.progress < 1);
particles.forEach(p => {
p.progress += p.speed;
const ease = p.progress * p.progress * (3 - 2 * p.progress);
const x = p.x + (p.targetX - p.x) * ease;
const y = p.y + (p.targetY - p.y) * ease;
ctx.fillStyle = colors.accent;
ctx.shadowColor = colors.accent;
ctx.shadowBlur = 10;
ctx.beginPath();
ctx.arc(x, y, 4, 0, Math.PI * 2);
ctx.fill();
ctx.shadowBlur = 0;
});
time++;
requestAnimationFrame(draw);
}
if (!window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
draw();
} else {
// Static version
const nodes = getNodePositions();
nodes.forEach(node => {
ctx.fillStyle = node.color;
ctx.beginPath();
ctx.arc(node.x, node.y, node.radius, 0, Math.PI * 2);
ctx.fill();
ctx.fillStyle = colors.text;
ctx.font = '10px JetBrains Mono';
ctx.textAlign = 'center';
ctx.fillText(node.label, node.x, node.y + node.radius + 14);
});
}
}
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', initTree);
} else {
initTree();
}
})();
</script>
<style>
.tree-container {
background: var(--bg-0);
border: 1px solid var(--divider-color);
border-radius: 12px;
padding: 1rem;
margin: 1.5rem 0;
position: relative;
}
.tree-canvas {
width: 100%;
height: 320px;
display: block;
}
@media (max-width: 768px) {
.tree-container {
overflow-x: auto;
}
.tree-canvas {
min-width: 500px;
}
}
</style>
<p>Armado con este conocimiento, construí mi primer prototipo. Funcionó—más o menos. Los commands se ejecutaron. Los agentes se spawnearon. Y entonces todo empezó a romperse de formas que la documentación no me preparó.</p>
<hr />
<h2 id="acto-ii-el-descenso">Acto II: El Descenso</h2>
<h3 id="punto-de-dolor-1-el-bug-de-acceso-a-herramientas-mcp">Punto de Dolor #1: El Bug de Acceso a Herramientas MCP</h3>
<p>Mi plugin agent-team-creator necesitaba integrarse con Jira. El plugin MCP de Atlassian estaba instalado y funcionando perfectamente en la sesión principal de Claude Code. Siguiendo la documentación, configuré mi agente de plugin para acceder a estas herramientas MCP.</p>
<p>El error fue inmediato y confuso:</p>
<pre class="z-code"><code><span class="z-text z-plain">Error: No such tool available: mcp__plugin_atlassian__getJiraIssue
</span></code></pre>
<p>Pasé horas depurando. ¿Estaba mal mi configuración? ¿Nombré mal la herramienta? Entonces los encontré—cuatro issues de GitHub documentando el mismo problema:</p>
<table><thead><tr><th>Issue</th><th>Descripción</th></tr></thead><tbody>
<tr><td>#13605</td><td>Los subagentes de plugin personalizados no pueden acceder a herramientas MCP</td></tr>
<tr><td>#15810</td><td>Los subagentes no heredan herramientas MCP de agentes definidos en plugins</td></tr>
<tr><td>#14496</td><td>Acceso inconsistente a MCP con prompts complejos</td></tr>
<tr><td>#7296</td><td>Fallo de herencia de scope para agentes lanzados con Task</td></tr>
</tbody></table>
<p>La documentación decía:</p>
<blockquote>
<p>“Cuando el campo tools se omite, los subagentes heredan todas las herramientas MCP disponibles para el hilo principal.”</p>
</blockquote>
<p>La realidad discrepaba. Los agentes definidos en plugins viven en un scope diferente—pueden ver las herramientas MCP listadas en la sesión principal, pero no pueden invocarlas.</p>
<hr />
<p><strong>★ Momento de Enseñanza: La Realidad del Scope MCP</strong></p>
<p>Las herramientas MCP funcionan confiablemente en dos contextos:</p>
<ol>
<li>La sesión principal de Claude Code</li>
<li>Commands (que corren en el scope de la sesión principal)</li>
</ol>
<p>Las herramientas MCP <strong>no funcionan</strong> en:</p>
<ul>
<li>Agentes definidos en plugins spawneados via herramienta Task</li>
<li>Subagentes de cualquier tipo</li>
</ul>
<p>Si tu plugin necesita acceso a servicios externos, tus <strong>commands</strong> deben manejarlo, no tus agentes.</p>
<hr />
<h3 id="punto-de-dolor-2-infierno-de-sincronizacion-en-tres-ubicaciones">Punto de Dolor #2: Infierno de Sincronización en Tres Ubicaciones</h3>
<p>Después de modificar mis definiciones de agentes, recargué Claude Code. Mis cambios no estaban ahí. Edité de nuevo. Todavía nada.</p>
<p>Resulta que los plugins de Claude Code existen en tres ubicaciones separadas que deben sincronizarse manualmente:</p>
<table><thead><tr><th>Ubicación</th><th>Ruta</th><th>Propósito</th></tr></thead><tbody>
<tr><td>Fuente Marketplace</td><td><code>~/.claude/local-marketplace/</code></td><td>Donde editas</td></tr>
<tr><td>Plugin Instalado</td><td><code>~/.claude/plugins/plugin-name/</code></td><td>Donde Claude lee</td></tr>
<tr><td>Cache</td><td><code>~/.claude/plugins/cache/marketplace/plugin/version/</code></td><td>Backup versionado</td></tr>
</tbody></table>
<p>No hay hot reload. No hay auto-sync. Editas en un lugar, pero Claude lee de otro.</p>
<p>¿La solución? Un script de sincronización:</p>
<pre data-lang="bash" class="language-bash z-code"><code class="language-bash" data-lang="bash"><span class="z-source z-shell z-bash"><span class="z-comment z-line z-number-sign z-shell"><span class="z-punctuation z-definition z-comment z-begin z-shell">#</span></span><span class="z-comment z-line z-number-sign z-shell">!/bin/bash</span><span class="z-comment z-line z-number-sign z-shell">
</span></span><span class="z-source z-shell z-bash"><span class="z-variable z-other z-readwrite z-assignment z-shell">PLUGIN_NAME</span><span class="z-keyword z-operator z-assignment z-shell">=</span><span class="z-string z-unquoted z-shell"><span class="z-string z-quoted z-double z-shell"><span class="z-punctuation z-definition z-string z-begin z-shell">"</span>agent-team-creator<span class="z-punctuation z-definition z-string z-end z-shell">"</span></span></span>
</span><span class="z-source z-shell z-bash"><span class="z-variable z-other z-readwrite z-assignment z-shell">MARKETPLACE</span><span class="z-keyword z-operator z-assignment z-shell">=</span><span class="z-string z-unquoted z-shell"><span class="z-string z-quoted z-double z-shell"><span class="z-punctuation z-definition z-string z-begin z-shell">"</span><span class="z-meta z-group z-expansion z-parameter z-shell"><span class="z-punctuation z-definition z-variable z-shell">$</span><span class="z-variable z-other z-readwrite z-shell">HOME</span></span>/.claude/local-marketplace<span class="z-punctuation z-definition z-string z-end z-shell">"</span></span></span>
</span><span class="z-source z-shell z-bash"><span class="z-variable z-other z-readwrite z-assignment z-shell">INSTALLED</span><span class="z-keyword z-operator z-assignment z-shell">=</span><span class="z-string z-unquoted z-shell"><span class="z-string z-quoted z-double z-shell"><span class="z-punctuation z-definition z-string z-begin z-shell">"</span><span class="z-meta z-group z-expansion z-parameter z-shell"><span class="z-punctuation z-definition z-variable z-shell">$</span><span class="z-variable z-other z-readwrite z-shell">HOME</span></span>/.claude/plugins/<span class="z-meta z-group z-expansion z-parameter z-shell"><span class="z-punctuation z-definition z-variable z-shell">$</span><span class="z-variable z-other z-readwrite z-shell">PLUGIN_NAME</span></span><span class="z-punctuation z-definition z-string z-end z-shell">"</span></span></span>
</span><span class="z-source z-shell z-bash"><span class="z-variable z-other z-readwrite z-assignment z-shell">CACHE</span><span class="z-keyword z-operator z-assignment z-shell">=</span><span class="z-string z-unquoted z-shell"><span class="z-string z-quoted z-double z-shell"><span class="z-punctuation z-definition z-string z-begin z-shell">"</span><span class="z-meta z-group z-expansion z-parameter z-shell"><span class="z-punctuation z-definition z-variable z-shell">$</span><span class="z-variable z-other z-readwrite z-shell">HOME</span></span>/.claude/plugins/cache/local-marketplace/<span class="z-meta z-group z-expansion z-parameter z-shell"><span class="z-punctuation z-definition z-variable z-shell">$</span><span class="z-variable z-other z-readwrite z-shell">PLUGIN_NAME</span></span>/1.0.0<span class="z-punctuation z-definition z-string z-end z-shell">"</span></span></span>
</span><span class="z-source z-shell z-bash">
</span><span class="z-source z-shell z-bash"><span class="z-meta z-function-call z-shell"><span class="z-variable z-function z-shell">rsync</span></span><span class="z-meta z-function-call z-arguments z-shell"><span class="z-variable z-parameter z-option z-shell"><span class="z-punctuation z-definition z-parameter z-shell"> -</span>av</span> <span class="z-string z-quoted z-double z-shell"><span class="z-punctuation z-definition z-string z-begin z-shell">"</span><span class="z-meta z-group z-expansion z-parameter z-shell"><span class="z-punctuation z-definition z-variable z-shell">$</span><span class="z-variable z-other z-readwrite z-shell">MARKETPLACE</span></span>/commands/<span class="z-punctuation z-definition z-string z-end z-shell">"</span></span> <span class="z-string z-quoted z-double z-shell"><span class="z-punctuation z-definition z-string z-begin z-shell">"</span><span class="z-meta z-group z-expansion z-parameter z-shell"><span class="z-punctuation z-definition z-variable z-shell">$</span><span class="z-variable z-other z-readwrite z-shell">INSTALLED</span></span>/commands/<span class="z-punctuation z-definition z-string z-end z-shell">"</span></span></span>
</span><span class="z-source z-shell z-bash"><span class="z-meta z-function-call z-shell"><span class="z-variable z-function z-shell">rsync</span></span><span class="z-meta z-function-call z-arguments z-shell"><span class="z-variable z-parameter z-option z-shell"><span class="z-punctuation z-definition z-parameter z-shell"> -</span>av</span> <span class="z-string z-quoted z-double z-shell"><span class="z-punctuation z-definition z-string z-begin z-shell">"</span><span class="z-meta z-group z-expansion z-parameter z-shell"><span class="z-punctuation z-definition z-variable z-shell">$</span><span class="z-variable z-other z-readwrite z-shell">MARKETPLACE</span></span>/commands/<span class="z-punctuation z-definition z-string z-end z-shell">"</span></span> <span class="z-string z-quoted z-double z-shell"><span class="z-punctuation z-definition z-string z-begin z-shell">"</span><span class="z-meta z-group z-expansion z-parameter z-shell"><span class="z-punctuation z-definition z-variable z-shell">$</span><span class="z-variable z-other z-readwrite z-shell">CACHE</span></span>/commands/<span class="z-punctuation z-definition z-string z-end z-shell">"</span></span></span>
</span><span class="z-source z-shell z-bash"><span class="z-meta z-function-call z-shell"><span class="z-variable z-function z-shell">rsync</span></span><span class="z-meta z-function-call z-arguments z-shell"><span class="z-variable z-parameter z-option z-shell"><span class="z-punctuation z-definition z-parameter z-shell"> -</span>av</span> <span class="z-string z-quoted z-double z-shell"><span class="z-punctuation z-definition z-string z-begin z-shell">"</span><span class="z-meta z-group z-expansion z-parameter z-shell"><span class="z-punctuation z-definition z-variable z-shell">$</span><span class="z-variable z-other z-readwrite z-shell">MARKETPLACE</span></span>/agents/<span class="z-punctuation z-definition z-string z-end z-shell">"</span></span> <span class="z-string z-quoted z-double z-shell"><span class="z-punctuation z-definition z-string z-begin z-shell">"</span><span class="z-meta z-group z-expansion z-parameter z-shell"><span class="z-punctuation z-definition z-variable z-shell">$</span><span class="z-variable z-other z-readwrite z-shell">INSTALLED</span></span>/agents/<span class="z-punctuation z-definition z-string z-end z-shell">"</span></span></span>
</span><span class="z-source z-shell z-bash"><span class="z-meta z-function-call z-shell"><span class="z-variable z-function z-shell">rsync</span></span><span class="z-meta z-function-call z-arguments z-shell"><span class="z-variable z-parameter z-option z-shell"><span class="z-punctuation z-definition z-parameter z-shell"> -</span>av</span> <span class="z-string z-quoted z-double z-shell"><span class="z-punctuation z-definition z-string z-begin z-shell">"</span><span class="z-meta z-group z-expansion z-parameter z-shell"><span class="z-punctuation z-definition z-variable z-shell">$</span><span class="z-variable z-other z-readwrite z-shell">MARKETPLACE</span></span>/agents/<span class="z-punctuation z-definition z-string z-end z-shell">"</span></span> <span class="z-string z-quoted z-double z-shell"><span class="z-punctuation z-definition z-string z-begin z-shell">"</span><span class="z-meta z-group z-expansion z-parameter z-shell"><span class="z-punctuation z-definition z-variable z-shell">$</span><span class="z-variable z-other z-readwrite z-shell">CACHE</span></span>/agents/<span class="z-punctuation z-definition z-string z-end z-shell">"</span></span></span>
</span><span class="z-source z-shell z-bash"><span class="z-meta z-function-call z-shell"><span class="z-support z-function z-echo z-shell">echo</span></span><span class="z-meta z-function-call z-arguments z-shell"> <span class="z-string z-quoted z-double z-shell"><span class="z-punctuation z-definition z-string z-begin z-shell">"</span>Plugin sincronizado en todas las ubicaciones<span class="z-punctuation z-definition z-string z-end z-shell">"</span></span></span>
</span></code></pre>
<p>Después de cada cambio: sync, cerrar Claude Code, reiniciar. Esto se volvió memoria muscular.</p>
<hr />
<p><strong>★ Momento de Enseñanza: Depurando Tu Plugin</strong></p>
<p>Cuando las cosas van mal, estos comandos son tus amigos:</p>
<pre data-lang="bash" class="language-bash z-code"><code class="language-bash" data-lang="bash"><span class="z-source z-shell z-bash"><span class="z-comment z-line z-number-sign z-shell"><span class="z-punctuation z-definition z-comment z-begin z-shell">#</span></span><span class="z-comment z-line z-number-sign z-shell"> Verificar si el plugin está cargado</span><span class="z-comment z-line z-number-sign z-shell">
</span></span><span class="z-source z-shell z-bash"><span class="z-meta z-function-call z-shell"><span class="z-variable z-function z-shell">ls</span></span><span class="z-meta z-function-call z-arguments z-shell"> <span class="z-meta z-group z-expansion z-tilde"><span class="z-variable z-language z-tilde z-shell">~</span></span>/.claude/plugins/</span>
</span><span class="z-source z-shell z-bash">
</span><span class="z-source z-shell z-bash"><span class="z-comment z-line z-number-sign z-shell"><span class="z-punctuation z-definition z-comment z-begin z-shell">#</span></span><span class="z-comment z-line z-number-sign z-shell"> Verificar sincronización del cache</span><span class="z-comment z-line z-number-sign z-shell">
</span></span><span class="z-source z-shell z-bash"><span class="z-meta z-function-call z-shell"><span class="z-variable z-function z-shell">diff</span></span><span class="z-meta z-function-call z-arguments z-shell"><span class="z-variable z-parameter z-option z-shell"><span class="z-punctuation z-definition z-parameter z-shell"> -</span>r</span> <span class="z-meta z-group z-expansion z-tilde"><span class="z-variable z-language z-tilde z-shell">~</span></span>/.claude/plugins/agent-team-creator/ <span class="z-punctuation z-separator z-continuation z-line z-shell">\
</span></span></span><span class="z-source z-shell z-bash"><span class="z-meta z-function-call z-arguments z-shell"> <span class="z-meta z-group z-expansion z-tilde"><span class="z-variable z-language z-tilde z-shell">~</span></span>/.claude/plugins/cache/local-marketplace/agent-team-creator/1.0.0/</span>
</span><span class="z-source z-shell z-bash">
</span><span class="z-source z-shell z-bash"><span class="z-comment z-line z-number-sign z-shell"><span class="z-punctuation z-definition z-comment z-begin z-shell">#</span></span><span class="z-comment z-line z-number-sign z-shell"> Validar sintaxis de marketplace.json</span><span class="z-comment z-line z-number-sign z-shell">
</span></span><span class="z-source z-shell z-bash"><span class="z-meta z-function-call z-shell"><span class="z-variable z-function z-shell">cat</span></span><span class="z-meta z-function-call z-arguments z-shell"> <span class="z-meta z-group z-expansion z-tilde"><span class="z-variable z-language z-tilde z-shell">~</span></span>/.claude/local-marketplace/.claude-plugin/marketplace.json</span> <span class="z-keyword z-operator z-logical z-pipe z-shell">|</span> <span class="z-meta z-function-call z-shell"><span class="z-variable z-function z-shell">jq</span></span><span class="z-meta z-function-call z-arguments z-shell"> .</span>
</span><span class="z-source z-shell z-bash">
</span><span class="z-source z-shell z-bash"><span class="z-comment z-line z-number-sign z-shell"><span class="z-punctuation z-definition z-comment z-begin z-shell">#</span></span><span class="z-comment z-line z-number-sign z-shell"> Ver estructura del plugin</span><span class="z-comment z-line z-number-sign z-shell">
</span></span><span class="z-source z-shell z-bash"><span class="z-meta z-function-call z-shell"><span class="z-variable z-function z-shell">tree</span></span><span class="z-meta z-function-call z-arguments z-shell"> <span class="z-meta z-group z-expansion z-tilde"><span class="z-variable z-language z-tilde z-shell">~</span></span>/.claude/plugins/agent-team-creator/</span>
</span></code></pre>
<hr />
<h3 id="punto-de-dolor-3-problemas-de-validacion-de-schema">Punto de Dolor #3: Problemas de Validación de Schema</h3>
<p>Mi primer marketplace.json fue rechazado con errores crípticos:</p>
<pre class="z-code"><code><span class="z-text z-plain">owner: Expected object, received string
</span><span class="z-text z-plain">source: Invalid input
</span></code></pre>
<p>El schema es estricto y poco documentado. Esto es lo que funciona:</p>
<pre data-lang="json" class="language-json z-code"><code class="language-json" data-lang="json"><span class="z-source z-json"><span class="z-meta z-mapping z-json"><span class="z-punctuation z-section z-mapping z-begin z-json">{</span>
</span></span><span class="z-source z-json"><span class="z-meta z-mapping z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>$schema<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>https://anthropic.com/claude-code/marketplace.schema.json<span class="z-punctuation z-definition z-string z-end z-json">"</span></span><span class="z-punctuation z-separator z-mapping z-pair z-json">,</span>
</span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>name<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-value z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>local-marketplace<span class="z-punctuation z-definition z-string z-end z-json">"</span></span><span class="z-punctuation z-separator z-mapping z-pair z-json">,</span>
</span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>description<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-value z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>Plugins locales para Claude Code<span class="z-punctuation z-definition z-string z-end z-json">"</span></span><span class="z-punctuation z-separator z-mapping z-pair z-json">,</span>
</span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>owner<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-value z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-mapping z-json"><span class="z-punctuation z-section z-mapping z-begin z-json">{</span>
</span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-mapping z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>name<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>Tu Nombre<span class="z-punctuation z-definition z-string z-end z-json">"</span></span><span class="z-punctuation z-separator z-mapping z-pair z-json">,</span>
</span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-mapping z-value z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>email<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-value z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>tu@email.com<span class="z-punctuation z-definition z-string z-end z-json">"</span></span>
</span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-mapping z-value z-json"> <span class="z-punctuation z-section z-mapping z-end z-json">}</span></span><span class="z-punctuation z-separator z-mapping z-pair z-json">,</span>
</span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>plugins<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-value z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-sequence z-json"><span class="z-punctuation z-section z-sequence z-begin z-json">[</span>
</span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-sequence z-json"> <span class="z-meta z-mapping z-json"><span class="z-punctuation z-section z-mapping z-begin z-json">{</span>
</span></span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-sequence z-json"><span class="z-meta z-mapping z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>name<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>plugin-name<span class="z-punctuation z-definition z-string z-end z-json">"</span></span><span class="z-punctuation z-separator z-mapping z-pair z-json">,</span>
</span></span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-sequence z-json"><span class="z-meta z-mapping z-value z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>description<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-value z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>Descripción del plugin<span class="z-punctuation z-definition z-string z-end z-json">"</span></span><span class="z-punctuation z-separator z-mapping z-pair z-json">,</span>
</span></span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-sequence z-json"><span class="z-meta z-mapping z-value z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>version<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-value z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>1.0.0<span class="z-punctuation z-definition z-string z-end z-json">"</span></span><span class="z-punctuation z-separator z-mapping z-pair z-json">,</span>
</span></span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-sequence z-json"><span class="z-meta z-mapping z-value z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>author<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-value z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-mapping z-json"><span class="z-punctuation z-section z-mapping z-begin z-json">{</span>
</span></span></span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-sequence z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-mapping z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>name<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>Nombre del Autor<span class="z-punctuation z-definition z-string z-end z-json">"</span></span><span class="z-punctuation z-separator z-mapping z-pair z-json">,</span>
</span></span></span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-sequence z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-mapping z-value z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>email<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-value z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>author@email.com<span class="z-punctuation z-definition z-string z-end z-json">"</span></span>
</span></span></span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-sequence z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-mapping z-value z-json"> <span class="z-punctuation z-section z-mapping z-end z-json">}</span></span><span class="z-punctuation z-separator z-mapping z-pair z-json">,</span>
</span></span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-sequence z-json"><span class="z-meta z-mapping z-value z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>source<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-value z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>./<span class="z-punctuation z-definition z-string z-end z-json">"</span></span><span class="z-punctuation z-separator z-mapping z-pair z-json">,</span>
</span></span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-sequence z-json"><span class="z-meta z-mapping z-value z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>category<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-value z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>development<span class="z-punctuation z-definition z-string z-end z-json">"</span></span>
</span></span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-sequence z-json"><span class="z-meta z-mapping z-value z-json"> <span class="z-punctuation z-section z-mapping z-end z-json">}</span></span>
</span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-sequence z-json"> <span class="z-punctuation z-section z-sequence z-end z-json">]</span></span>
</span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-punctuation z-section z-mapping z-end z-json">}</span></span>
</span></code></pre>
<p>Trampas clave:</p>
<ul>
<li><code>owner</code> debe ser un objeto con <code>name</code> y <code>email</code>, no un string</li>
<li><code>source</code> debe ser <code>"./"</code> con la barra diagonal</li>
<li>Faltar cualquier campo requerido causa fallos silenciosos</li>
</ul>
<hr />
<h2 id="acto-iii-el-descubrimiento">Acto III: El Descubrimiento</h2>
<h3 id="la-brecha-documentacion-vs-realidad">La Brecha Documentación vs. Realidad</h3>
<p>El punto de quiebre llegó cuando construí una arquitectura multi-agente completa basada en comportamiento documentado—solo para que fallara completamente.</p>
<p>Los docs prometían:</p>
<blockquote>
<p>“Herramientas MCP: Los subagentes pueden acceder a herramientas MCP de servidores MCP configurados.”</p>
</blockquote>
<p>Probé extensivamente. Los subagentes definidos en plugins <strong>no pueden</strong> acceder a herramientas MCP. Esto no es un problema de configuración—es un bug conocido rastreado en múltiples issues de GitHub.</p>
<p><strong>La lección</strong>: La documentación representa comportamiento <em>intencionado</em>, no comportamiento <em>garantizado</em>. Siempre valida suposiciones empíricamente antes de construir arquitecturas dependientes.</p>
<h3 id="el-muro-del-anidamiento">El Muro del Anidamiento</h3>
<p>Mi diseño original tenía agentes spawneando sub-agentes especializados en una estructura de árbol recursivo. Elegante en teoría. Imposible en práctica.</p>
<p>Cuando intenté:</p>
<div class="blocked-flow-container" id="blocked-">
<canvas class="blocked-flow-canvas" aria-label="Flow diagram with blocked step"></canvas>
</div>
<script>
(function() {
const containerId = 'blocked-';
const nodeNames = ['Usuario', 'Command', 'Agente', 'SubAgente'];
const blockedName = 'SubSubAgente';
function initBlockedFlow() {
const container = document.getElementById(containerId);
if (!container) return;
const canvas = container.querySelector('.blocked-flow-canvas');
const ctx = canvas.getContext('2d');
let particles = [];
let time = 0;
let pulsePhase = 0;
const colors = {
nodes: ['#ff0080', '#00d4ff', '#00ff88', '#8b5cf6'],
blocked: '#ff4444',
blockedBg: '#442222',
particle: '#00ff88',
connection: 'rgba(0, 212, 255, 0.4)',
blockedConnection: 'rgba(255, 68, 68, 0.5)',
text: '#e0e0e4'
};
function resize() {
const rect = container.getBoundingClientRect();
canvas.width = rect.width;
canvas.height = 180;
}
resize();
window.addEventListener('resize', resize);
function getNodePositions() {
const allNodes = [...nodeNames, blockedName];
const margin = 60;
const spacing = (canvas.width - margin * 2) / (allNodes.length - 1);
const y = canvas.height / 2;
return allNodes.map((name, i) => ({
label: name,
x: margin + i * spacing,
y: y,
radius: 26,
isBlocked: i === allNodes.length - 1,
color: i < nodeNames.length ? colors.nodes[i % colors.nodes.length] : colors.blockedBg
}));
}
function draw() {
ctx.clearRect(0, 0, canvas.width, canvas.height);
const nodes = getNodePositions();
pulsePhase += 0.05;
// Draw connections
for (let i = 0; i < nodes.length - 1; i++) {
const from = nodes[i];
const to = nodes[i + 1];
const isBlockedConnection = to.isBlocked;
ctx.beginPath();
ctx.moveTo(from.x + from.radius, from.y);
ctx.lineTo(to.x - to.radius, to.y);
if (isBlockedConnection) {
ctx.strokeStyle = colors.blockedConnection;
ctx.setLineDash([8, 4]);
} else {
ctx.strokeStyle = colors.connection;
ctx.setLineDash([]);
}
ctx.lineWidth = 3;
ctx.stroke();
ctx.setLineDash([]);
// Arrow
if (!isBlockedConnection) {
const midX = (from.x + to.x) / 2;
ctx.fillStyle = colors.connection;
ctx.beginPath();
ctx.moveTo(midX - 5, from.y - 6);
ctx.lineTo(midX + 8, from.y);
ctx.lineTo(midX - 5, from.y + 6);
ctx.closePath();
ctx.fill();
}
}
// Draw "BLOCKED" label on the blocked connection
const lastNormal = nodes[nodes.length - 2];
const blocked = nodes[nodes.length - 1];
const midX = (lastNormal.x + blocked.x) / 2;
ctx.save();
ctx.fillStyle = colors.blocked;
ctx.font = 'bold 11px JetBrains Mono';
ctx.textAlign = 'center';
// Pulsing X
const pulse = Math.sin(pulsePhase) * 0.3 + 1;
ctx.font = `bold ${14 * pulse}px JetBrains Mono`;
ctx.fillText('❌', midX, nodes[0].y - 20);
ctx.font = 'bold 10px JetBrains Mono';
ctx.fillText('BLOCKED', midX, nodes[0].y + 32);
ctx.restore();
// Draw nodes
nodes.forEach((node, i) => {
if (node.isBlocked) {
// Blocked node - pulsing red border
ctx.shadowColor = colors.blocked;
ctx.shadowBlur = 10 + Math.sin(pulsePhase) * 5;
ctx.fillStyle = node.color;
ctx.beginPath();
ctx.arc(node.x, node.y, node.radius, 0, Math.PI * 2);
ctx.fill();
ctx.strokeStyle = colors.blocked;
ctx.lineWidth = 3;
ctx.setLineDash([4, 4]);
ctx.stroke();
ctx.setLineDash([]);
ctx.shadowBlur = 0;
// Strikethrough effect
ctx.strokeStyle = colors.blocked;
ctx.lineWidth = 2;
ctx.beginPath();
ctx.moveTo(node.x - node.radius + 5, node.y - node.radius + 5);
ctx.lineTo(node.x + node.radius - 5, node.y + node.radius - 5);
ctx.stroke();
} else {
// Normal node
ctx.shadowColor = node.color;
ctx.shadowBlur = 15;
ctx.fillStyle = node.color;
ctx.beginPath();
ctx.arc(node.x, node.y, node.radius, 0, Math.PI * 2);
ctx.fill();
ctx.shadowBlur = 0;
ctx.strokeStyle = '#00ff88';
ctx.lineWidth = 2;
ctx.stroke();
}
// Label
ctx.fillStyle = node.isBlocked ? '#666' : '#0a0a0f';
ctx.font = 'bold 10px JetBrains Mono';
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
// Wrap text if needed
const words = node.label.split(/(?=[A-Z])/);
if (words.length > 1 && node.label.length > 8) {
ctx.fillText(words[0], node.x, node.y - 6);
ctx.fillText(words.slice(1).join(''), node.x, node.y + 6);
} else {
ctx.fillText(node.label, node.x, node.y);
}
});
// Particles (only on valid connections)
particles.forEach(p => {
p.progress += p.speed;
if (p.progress >= 1) {
p.segmentIndex++;
p.progress = 0;
if (p.segmentIndex >= nodes.length - 2) {
p.segmentIndex = 0;
}
}
const from = nodes[p.segmentIndex];
const to = nodes[p.segmentIndex + 1];
if (from && to && !to.isBlocked) {
const ease = p.progress * p.progress * (3 - 2 * p.progress);
const x = from.x + (to.x - from.x) * ease;
const y = from.y + (to.y - from.y) * ease;
ctx.fillStyle = colors.particle;
ctx.shadowColor = colors.particle;
ctx.shadowBlur = 10;
ctx.beginPath();
ctx.arc(x, y, 4, 0, Math.PI * 2);
ctx.fill();
ctx.shadowBlur = 0;
}
});
time++;
requestAnimationFrame(draw);
}
// Initialize particles
for (let i = 0; i < 2; i++) {
particles.push({
segmentIndex: i,
progress: 0,
speed: 0.015
});
}
if (!window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
draw();
} else {
// Static version
const nodes = getNodePositions();
nodes.forEach(node => {
ctx.fillStyle = node.color;
ctx.beginPath();
ctx.arc(node.x, node.y, node.radius, 0, Math.PI * 2);
ctx.fill();
ctx.fillStyle = node.isBlocked ? '#666' : '#0a0a0f';
ctx.font = 'bold 10px JetBrains Mono';
ctx.textAlign = 'center';
ctx.fillText(node.label, node.x, node.y);
});
}
}
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', initBlockedFlow);
} else {
initBlockedFlow();
}
})();
</script>
<style>
.blocked-flow-container {
background: var(--bg-0);
border: 1px solid var(--divider-color);
border-radius: 12px;
padding: 1rem;
margin: 1.5rem 0;
position: relative;
}
.blocked-flow-canvas {
width: 100%;
height: 180px;
display: block;
}
@media (max-width: 768px) {
.blocked-flow-container {
overflow-x: auto;
}
.blocked-flow-canvas {
min-width: 500px;
}
}
</style>
<p>Claude Code respondió:</p>
<pre class="z-code"><code><span class="z-text z-plain">Error: Subagents cannot spawn subagents
</span></code></pre>
<p>Este es un límite duro de la plataforma. Solo un nivel de anidamiento. La restricción existe por buenas razones—prevenir recursión infinita, mantener consumo de recursos acotado, asegurar ejecución predecible. Pero invalidó toda mi arquitectura.</p>
<h3 id="herencia-de-modelo-que-no-hereda">Herencia de Modelo que No Hereda</h3>
<p>Configuré mis agentes para usar <code>model: inherit</code>, esperando que usaran cualquier modelo que usara la sesión padre. Cada subagente usó por defecto Sonnet 4, sin importar:</p>
<ul>
<li>Modelo padre</li>
<li>Configuración global</li>
<li>Configuración local</li>
<li>Configuración explícita del agente</li>
</ul>
<p>Otro descubrimiento: Claude Code infiere comportamiento del agente a partir del nombre. Un agente llamado “code-reviewer” activa comportamientos de revisión built-in que pueden sobrescribir tus instrucciones personalizadas. Nombrar no es solo etiquetar—es funcional.</p>
<hr />
<h2 id="acto-iv-la-solucion">Acto IV: La Solución</h2>
<h3 id="el-patron-de-arquitectura-hibrida">El Patrón de Arquitectura Híbrida</h3>
<p>Las restricciones crían creatividad. Enfrentando bugs de acceso MCP, límites de anidamiento, y fallos de herencia de modelo, desarrollé lo que ahora llamo el <strong>Patrón de Arquitectura Híbrida</strong>.</p>
<p>La insight central: <strong>Commands y Agents tienen capacidades diferentes. Usa cada uno para lo que hace bien.</strong></p>
<p><strong>Capa de Command (I/O)</strong>:</p>
<ul>
<li>Acceso a herramientas MCP (funciona confiablemente)</li>
<li>Operaciones de sistema de archivos</li>
<li>Interacción con usuario (AskUserQuestion)</li>
<li>Caché de respuestas</li>
<li>Comunicación con servicios externos</li>
</ul>
<p><strong>Capa de Agent (Inteligencia)</strong>:</p>
<ul>
<li>Razonamiento y análisis puro</li>
<li>Formateo de contenido</li>
<li>Toma de decisiones</li>
<li>Reconocimiento de patrones</li>
<li><strong>Sin dependencias directas de I/O</strong></li>
</ul>
<p>Los commands se convierten en adaptadores de I/O. Los agentes se convierten en motores de razonamiento. Ninguno intenta hacer el trabajo del otro.</p>
<h3 id="el-pipeline-de-6-fases">El Pipeline de 6 Fases</h3>
<p>Así es como esto se manifiesta en mi comando <code>/generate-jira-task</code>:</p>
<div class="pipeline-container" id="pipeline">
<canvas class="pipeline-canvas" aria-label="Pipeline flow visualization"></canvas>
<div class="pipeline-legend">
<span class="legend-item"><span class="legend-dot command"></span> Command (I/O)</span>
<span class="legend-item"><span class="legend-dot agent"></span> Agent (Intelligence)</span>
</div>
</div>
<script>
(function() {
const containerId = 'pipeline';
const phasesData = [
{"phase": 0, "owner": "Command", "label": "Verificar MCP", "io": "external"},
{"phase": 1, "owner": "Command", "label": "Resolver Proyecto", "io": "external"},
{"phase": 2, "owner": "Command", "label": "Cargar Informe", "io": "local"},
{"phase": 3, "owner": "Command", "label": "Verificar Dups", "io": "external"},
{"phase": 4, "owner": "Agent", "label": "Razonamiento", "io": "none"},
{"phase": 5, "owner": "Agent", "label": "Formateo", "io": "none"},
{"phase": 6, "owner": "Command", "label": "Salida", "io": "external"}
];
function initPipeline() {
const container = document.getElementById(containerId);
if (!container) return;
const canvas = container.querySelector('.pipeline-canvas');
const ctx = canvas.getContext('2d');
// Responsive sizing
function resize() {
const rect = container.getBoundingClientRect();
canvas.width = rect.width;
canvas.height = 180;
}
resize();
window.addEventListener('resize', resize);
// Colors
const colors = {
command: '#00d4ff',
agent: '#00ff88',
external: '#8b5cf6',
local: '#ff8800',
none: '#444466',
particle: '#00ff88',
bg: 'rgba(10, 10, 15, 0.8)'
};
// Animation state
let particles = [];
let time = 0;
// Get phase positions
function getPhasePositions() {
const phases = phasesData;
const margin = 60;
const spacing = (canvas.width - margin * 2) / (phases.length - 1);
return phases.map((p, i) => ({
...p,
x: margin + i * spacing,
y: canvas.height / 2,
radius: 24
}));
}
// Create particle
function createParticle(positions) {
return {
phaseIndex: 0,
progress: 0,
speed: 0.01 + Math.random() * 0.01,
x: positions[0].x,
y: positions[0].y
};
}
// Draw
function draw() {
ctx.clearRect(0, 0, canvas.width, canvas.height);
const positions = getPhasePositions();
// Draw connections
ctx.lineWidth = 2;
ctx.strokeStyle = 'rgba(0, 212, 255, 0.3)';
ctx.beginPath();
positions.forEach((pos, i) => {
if (i === 0) ctx.moveTo(pos.x, pos.y);
else ctx.lineTo(pos.x, pos.y);
});
ctx.stroke();
// Draw arrows
for (let i = 0; i < positions.length - 1; i++) {
const from = positions[i];
const to = positions[i + 1];
const midX = (from.x + to.x) / 2;
const midY = (from.y + to.y) / 2;
ctx.fillStyle = 'rgba(0, 212, 255, 0.5)';
ctx.beginPath();
ctx.moveTo(midX - 6, midY - 4);
ctx.lineTo(midX + 6, midY);
ctx.lineTo(midX - 6, midY + 4);
ctx.closePath();
ctx.fill();
}
// Draw phase nodes
positions.forEach((pos, i) => {
const isCommand = pos.owner === 'Command';
const color = isCommand ? colors.command : colors.agent;
// Glow
const gradient = ctx.createRadialGradient(pos.x, pos.y, 0, pos.x, pos.y, pos.radius * 2);
gradient.addColorStop(0, color.replace(')', ', 0.3)').replace('rgb', 'rgba'));
gradient.addColorStop(1, 'transparent');
ctx.fillStyle = gradient;
ctx.beginPath();
ctx.arc(pos.x, pos.y, pos.radius * 2, 0, Math.PI * 2);
ctx.fill();
// Node
ctx.fillStyle = color;
ctx.beginPath();
ctx.arc(pos.x, pos.y, pos.radius, 0, Math.PI * 2);
ctx.fill();
// Phase number
ctx.fillStyle = '#0a0a0f';
ctx.font = 'bold 14px JetBrains Mono, monospace';
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
ctx.fillText(pos.phase, pos.x, pos.y);
// Label
ctx.fillStyle = '#e0e0e4';
ctx.font = '11px JetBrains Mono, monospace';
ctx.fillText(pos.label, pos.x, pos.y + pos.radius + 16);
// I/O indicator
if (pos.io !== 'none') {
ctx.fillStyle = pos.io === 'external' ? colors.external : colors.local;
ctx.font = '9px JetBrains Mono, monospace';
ctx.fillText(pos.io.toUpperCase(), pos.x, pos.y - pos.radius - 10);
}
});
// Update and draw particles
particles.forEach(p => {
if (p.phaseIndex >= positions.length - 1) {
p.phaseIndex = 0;
p.progress = 0;
}
const from = positions[p.phaseIndex];
const to = positions[p.phaseIndex + 1];
p.progress += p.speed;
if (p.progress >= 1) {
p.phaseIndex++;
p.progress = 0;
}
if (to) {
p.x = from.x + (to.x - from.x) * p.progress;
p.y = from.y + (to.y - from.y) * p.progress;
}
// Draw particle
ctx.fillStyle = colors.particle;
ctx.beginPath();
ctx.arc(p.x, p.y, 4, 0, Math.PI * 2);
ctx.fill();
// Particle glow
const pGrad = ctx.createRadialGradient(p.x, p.y, 0, p.x, p.y, 12);
pGrad.addColorStop(0, 'rgba(0, 255, 136, 0.4)');
pGrad.addColorStop(1, 'transparent');
ctx.fillStyle = pGrad;
ctx.beginPath();
ctx.arc(p.x, p.y, 12, 0, Math.PI * 2);
ctx.fill();
});
time++;
requestAnimationFrame(draw);
}
// Initialize particles
const positions = getPhasePositions();
for (let i = 0; i < 3; i++) {
const p = createParticle(positions);
p.phaseIndex = i * 2;
particles.push(p);
}
// Respect reduced motion
if (!window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
draw();
} else {
// Static version
const positions = getPhasePositions();
ctx.clearRect(0, 0, canvas.width, canvas.height);
ctx.lineWidth = 2;
ctx.strokeStyle = 'rgba(0, 212, 255, 0.5)';
ctx.beginPath();
positions.forEach((pos, i) => {
if (i === 0) ctx.moveTo(pos.x, pos.y);
else ctx.lineTo(pos.x, pos.y);
});
ctx.stroke();
positions.forEach((pos) => {
const color = pos.owner === 'Command' ? colors.command : colors.agent;
ctx.fillStyle = color;
ctx.beginPath();
ctx.arc(pos.x, pos.y, pos.radius, 0, Math.PI * 2);
ctx.fill();
ctx.fillStyle = '#0a0a0f';
ctx.font = 'bold 14px JetBrains Mono, monospace';
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
ctx.fillText(pos.phase, pos.x, pos.y);
ctx.fillStyle = '#e0e0e4';
ctx.font = '11px JetBrains Mono, monospace';
ctx.fillText(pos.label, pos.x, pos.y + pos.radius + 16);
});
}
}
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', initPipeline);
} else {
initPipeline();
}
})();
</script>
<style>
.pipeline-container {
background: var(--bg-0);
border: 1px solid var(--divider-color);
border-radius: 12px;
padding: 1.5rem 1rem 1rem;
margin: 1.5rem 0;
position: relative;
}
.pipeline-canvas {
width: 100%;
height: 180px;
display: block;
}
.pipeline-legend {
display: flex;
justify-content: center;
gap: 2rem;
margin-top: 0.5rem;
font-family: 'JetBrains Mono', monospace;
font-size: 0.8rem;
color: var(--meta-color);
}
.legend-item {
display: flex;
align-items: center;
gap: 0.5rem;
}
.legend-dot {
width: 12px;
height: 12px;
border-radius: 50%;
}
.legend-dot.command {
background: #00d4ff;
}
.legend-dot.agent {
background: #00ff88;
}
@media (max-width: 768px) {
.pipeline-container {
overflow-x: auto;
}
.pipeline-canvas {
min-width: 600px;
}
}
</style>
<p>Los commands manejan toda la comunicación externa (nodos cyan). Los agentes manejan todo el pensamiento (nodos verdes). El límite es limpio—nota cómo las operaciones de I/O (marcadas EXTERNAL/LOCAL) se agrupan en la capa de Command.</p>
<h3 id="degradacion-graciosa">Degradación Graciosa</h3>
<p>¿Qué pasa si MCP no está disponible? El patrón maneja esto elegantemente:</p>
<pre class="z-code"><code><span class="z-text z-plain">FALLBACK_MODE se activa cuando:
</span><span class="z-text z-plain"> - Plugin MCP de Atlassian no disponible
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">Acciones:
</span><span class="z-text z-plain"> - Saltar Fase 1 (resolución de proyecto)
</span><span class="z-text z-plain"> - Saltar Fase 3 (verificación de duplicados)
</span><span class="z-text z-plain"> - Fase 6: Output markdown a .claude/reports/jira-drafts/
</span></code></pre>
<p>La capa de inteligencia (Fases 4-5) funciona idénticamente ya sea conectada a Jira o no. La capa de I/O degrada graciosamente a output de archivo local.</p>
<hr />
<p><strong>★ Momento de Enseñanza: Frontmatter de Command y Agent</strong></p>
<p><strong>Template de Command</strong>:</p>
<pre data-lang="yaml" class="language-yaml z-code"><code class="language-yaml" data-lang="yaml"><span class="z-source z-yaml"><span class="z-entity z-other z-document z-begin z-yaml">---</span>
</span><span class="z-source z-yaml"><span class="z-string z-unquoted z-plain z-out z-yaml"><span class="z-entity z-name z-tag z-yaml">name</span></span><span class="z-punctuation z-separator z-key-value z-mapping z-yaml">:</span> <span class="z-string z-unquoted z-plain z-out z-yaml">generate-jira-task</span>
</span><span class="z-source z-yaml"><span class="z-string z-unquoted z-plain z-out z-yaml"><span class="z-entity z-name z-tag z-yaml">description</span></span><span class="z-punctuation z-separator z-key-value z-mapping z-yaml">:</span> <span class="z-string z-unquoted z-plain z-out z-yaml">Generar tarea Jira desde informe de depuración</span>
</span><span class="z-source z-yaml"><span class="z-string z-unquoted z-plain z-out z-yaml"><span class="z-entity z-name z-tag z-yaml">allowed-tools</span></span><span class="z-punctuation z-separator z-key-value z-mapping z-yaml">:</span>
</span><span class="z-source z-yaml"> <span class="z-punctuation z-definition z-block z-sequence z-item z-yaml">-</span> <span class="z-string z-unquoted z-plain z-out z-yaml">Read</span>
</span><span class="z-source z-yaml"> <span class="z-punctuation z-definition z-block z-sequence z-item z-yaml">-</span> <span class="z-string z-unquoted z-plain z-out z-yaml">Write</span>
</span><span class="z-source z-yaml"> <span class="z-punctuation z-definition z-block z-sequence z-item z-yaml">-</span> <span class="z-string z-unquoted z-plain z-out z-yaml">Glob</span>
</span><span class="z-source z-yaml"> <span class="z-punctuation z-definition z-block z-sequence z-item z-yaml">-</span> <span class="z-string z-unquoted z-plain z-out z-yaml">Grep</span>
</span><span class="z-source z-yaml"> <span class="z-punctuation z-definition z-block z-sequence z-item z-yaml">-</span> <span class="z-string z-unquoted z-plain z-out z-yaml">Task</span>
</span><span class="z-source z-yaml"> <span class="z-punctuation z-definition z-block z-sequence z-item z-yaml">-</span> <span class="z-string z-unquoted z-plain z-out z-yaml">AskUserQuestion</span>
</span><span class="z-source z-yaml"><span class="z-string z-unquoted z-plain z-out z-yaml"><span class="z-entity z-name z-tag z-yaml">argument-hint</span></span><span class="z-punctuation z-separator z-key-value z-mapping z-yaml">:</span> <span class="z-string z-quoted z-double z-yaml"><span class="z-punctuation z-definition z-string z-begin z-yaml">"</span>[archivo-informe]<span class="z-punctuation z-definition z-string z-end z-yaml">"</span></span>
</span><span class="z-source z-yaml"><span class="z-entity z-other z-document z-begin z-yaml">---</span>
</span></code></pre>
<p><strong>Template de Agent</strong>:</p>
<pre data-lang="yaml" class="language-yaml z-code"><code class="language-yaml" data-lang="yaml"><span class="z-source z-yaml"><span class="z-entity z-other z-document z-begin z-yaml">---</span>
</span><span class="z-source z-yaml"><span class="z-string z-unquoted z-plain z-out z-yaml"><span class="z-entity z-name z-tag z-yaml">name</span></span><span class="z-punctuation z-separator z-key-value z-mapping z-yaml">:</span> <span class="z-string z-unquoted z-plain z-out z-yaml">implementation-planner</span>
</span><span class="z-source z-yaml"><span class="z-string z-unquoted z-plain z-out z-yaml"><span class="z-entity z-name z-tag z-yaml">description</span></span><span class="z-punctuation z-separator z-key-value z-mapping z-yaml">:</span> <span class="z-keyword z-control z-flow z-block-scalar z-literal z-yaml">|</span>
</span><span class="z-source z-yaml"><span class="z-string z-unquoted z-block z-yaml"> Usa este agente para analizar informes de depuración y crear planes de implementación.
</span></span><span class="z-source z-yaml"><span class="z-string z-unquoted z-block z-yaml"></span><span class="z-string z-unquoted z-plain z-out z-yaml"><span class="z-entity z-name z-tag z-yaml">model</span></span><span class="z-punctuation z-separator z-key-value z-mapping z-yaml">:</span> <span class="z-string z-unquoted z-plain z-out z-yaml">inherit</span>
</span><span class="z-source z-yaml"><span class="z-string z-unquoted z-plain z-out z-yaml"><span class="z-entity z-name z-tag z-yaml">color</span></span><span class="z-punctuation z-separator z-key-value z-mapping z-yaml">:</span> <span class="z-string z-unquoted z-plain z-out z-yaml">cyan</span>
</span><span class="z-source z-yaml"><span class="z-string z-unquoted z-plain z-out z-yaml"><span class="z-entity z-name z-tag z-yaml">tools</span></span><span class="z-punctuation z-separator z-key-value z-mapping z-yaml">:</span>
</span><span class="z-source z-yaml"> <span class="z-punctuation z-definition z-block z-sequence z-item z-yaml">-</span> <span class="z-string z-unquoted z-plain z-out z-yaml">Read</span>
</span><span class="z-source z-yaml"> <span class="z-punctuation z-definition z-block z-sequence z-item z-yaml">-</span> <span class="z-string z-unquoted z-plain z-out z-yaml">Grep</span>
</span><span class="z-source z-yaml"> <span class="z-punctuation z-definition z-block z-sequence z-item z-yaml">-</span> <span class="z-string z-unquoted z-plain z-out z-yaml">Glob</span>
</span><span class="z-source z-yaml"><span class="z-entity z-other z-document z-begin z-yaml">---</span>
</span></code></pre>
<p>Nota: Los agentes <strong>no</strong> deben incluir herramientas MCP en su lista de tools—no funcionarán de todos modos.</p>
<hr />
<h2 id="acto-v-el-retorno">Acto V: El Retorno</h2>
<h3 id="lo-que-funciona-ahora">Lo Que Funciona Ahora</h3>
<p>El plugin agent-team-creator ahora funciona confiablemente con tres commands:</p>
<ul>
<li><code>/generate-agent-team</code> - Analiza códigos base y genera agentes especializados</li>
<li><code>/generate-debugger</code> - Crea agentes de depuración específicos del proyecto</li>
<li><code>/generate-jira-task</code> - Convierte informes de depuración a tareas Jira</li>
</ul>
<p>Cada uno sigue el Patrón de Arquitectura Híbrida. Los commands manejan I/O. Los agentes manejan razonamiento. El sistema degrada graciosamente cuando los servicios no están disponibles.</p>
<h3 id="lecciones-aprendidas">Lecciones Aprendidas</h3>
<table><thead><tr><th>Lección</th><th>Implicación</th></tr></thead><tbody>
<tr><td>Confía pero verifica documentación</td><td>Construye pruebas mínimas de concepto antes de comprometerte con arquitecturas</td></tr>
<tr><td>Las restricciones revelan claridad</td><td>El patrón híbrido es más limpio que mi diseño original sin restricciones</td></tr>
<tr><td>La sincronización es tu responsabilidad</td><td>Automatízala. Hazla memoria muscular.</td></tr>
<tr><td>Nombrar es funcional</td><td>Los nombres de agentes influencian el comportamiento de la plataforma</td></tr>
<tr><td>Explícito sobre implícito</td><td>Nunca asumas herencia de herramientas; declara todo</td></tr>
</tbody></table>
<h3 id="checklist-de-inicio-rapido-para-nuevos-desarrolladores-de-plugins">Checklist de Inicio Rápido para Nuevos Desarrolladores de Plugins</h3>
<ol>
<li><strong>Setup</strong>: Crea estructura de marketplace con schema JSON apropiado</li>
<li><strong>Desarrolla</strong>: Edita archivos solo en la fuente del marketplace</li>
<li><strong>Sync</strong>: Ejecuta script rsync después de cada cambio</li>
<li><strong>Reinicia</strong>: Cierra y reinicia Claude Code (no hay hot reload)</li>
<li><strong>Prueba</strong>: Verifica disponibilidad del command con <code>/help</code></li>
<li><strong>Depura</strong>: Usa <code>diff -r</code> y <code>jq</code> para validación</li>
</ol>
<p>La lección clave: <strong>Commands para I/O, Agents para razonamiento</strong>. Este patrón evita cada bug que encontré.</p>
<hr />
<h2 id="conclusion">Conclusión</h2>
<p>Construir agent-team-creator me enseñó más sobre arquitectura de agentes IA que cualquier documentación podría. Los bugs no fueron obstáculos—fueron maestros. Las restricciones no fueron limitaciones—fueron principios de diseño disfrazados.</p>
<p>El Patrón de Arquitectura Híbrida emergió de la necesidad, pero ahora creo que es superior a diseños sin restricciones. Límites claros entre capas de I/O e inteligencia hacen sistemas más fáciles de probar, depurar, y extender. La degradación graciosa se vuelve natural cuando ya has separado concerns.</p>
<p>En la Parte 2 de esta serie, daré un paso atrás de los detalles prácticos y examinaré qué revelan estos descubrimientos sobre el diseño de frameworks de agentes más ampliamente. ¿Por qué los modelos de herencia se rompen en sistemas multi-agente? ¿Qué hace que la topología hub-and-spoke emerja naturalmente? ¿Y qué nos dice naming-as-behavior sobre sistemas IA en general?</p>
<p>Por ahora, si estás construyendo plugins de Claude Code: abraza las restricciones. Te enseñarán cosas que la documentación no puede.</p>
<hr />
<h2 id="obten-el-plugin">Obtén el Plugin</h2>
<p>El plugin es open source: <a href="https://github.com/Cpicon/claude-code-plugins">Cpicon/claude-code-plugins</a></p>
<p>Usa la pestaña <a href="https://github.com/Cpicon/claude-code-plugins/issues">GitHub Issues</a> para solicitar features, reportar bugs, o discutir mejoras.</p>
<hr />
<p><strong>Navegación de la Serie:</strong></p>
<ul>
<li><strong>Parte 0</strong>: <a href="/posts/claude-code-plugin-journey-part0/">Agent Team Creator</a> — Qué hace el plugin y cómo usarlo</li>
<li><strong>Parte 1</strong> (Estás aquí): Construyendo el plugin, lecciones aprendidas</li>
<li><strong>Parte 2</strong>: <a href="/posts/claude-code-plugin-journey-part2/">La Paradoja de la Herencia</a> — Insights de investigación, patrones</li>
</ul>
<hr />
<p><em>Este post está basado en observaciones empíricas de construir el plugin agent-team-creator. Todos los puntos de dolor y soluciones fueron documentados a través de sesiones reales de desarrollo.</em></p>
El Patrón de Arquitectura Híbrida: Lecciones de agent-team-creator
Esta es la Parte 1 de una serie de tres partes. Comienza con Parte 0: Agent Team Creator para ver qué hace el plugin, o continúa aquí para el viaje de desarrollo.
Pensé que construir un plugin de Claude Code tomaría un fin de semana. Tres días después de luchar con bugs de acceso a herramientas MCP, sincronización de archivos en tres ubicaciones, y documentación que prometía features que no funcionaban, me di cuenta de que estaba construyendo algo más valioso que un plugin—estaba mapeando territorio inexplorado.
Esta es la historia de construir agent-team-creator, un plugin de Claude Code que analiza códigos base y genera agentes IA específicos del proyecto. En el camino, descubrí un patrón que convirtió las limitaciones de la plataforma en claridad arquitectónica: el Patrón de Arquitectura Híbrida.
…
Claude Code Plugin Journey Parte 0: Agent Team Creator
2026-01-06T10:00:00+00:00
2026-01-06T10:00:00+00:00
Christian Picon Calderon
https://futurewithml.netlify.app/es/posts/claude-code-plugin-journey-part0/
<h1 id="claude-code-plugin-journey-parte-0-agent-team-creator">Claude Code Plugin Journey Parte 0: Agent Team Creator</h1>
<p>¿Qué pasaría si pudieras apuntar una IA a tu proyecto y hacer que genere especialistas que realmente entienden tu stack? No asistentes genéricos—agentes que conocen tu arquitectura, tus patrones, tus convenciones.</p>
<p>Eso es lo que hace <code>agent-team-creator</code>. Déjame mostrarte el flujo de trabajo.</p>
<span id="continue-reading"></span>
<hr />
<h2 id="escenario-1-genera-tu-equipo-de-agentes">Escenario 1: Genera tu Equipo de Agentes</h2>
<p>Comienzas un nuevo proyecto—o te unes a uno existente. El código base es desconocido. Necesitas ayuda, pero los consejos genéricos de IA no son suficientes.</p>
<p><strong>Paso 1: Genera tu equipo de agentes</strong></p>
<pre class="z-code"><code><span class="z-text z-plain">/generate-agent-team
</span></code></pre>
<p>Observa cómo el plugin analiza tu proyecto:</p>
<pre class="z-code"><code><span class="z-text z-plain">Analizando código base...
</span><span class="z-text z-plain">├── Lenguajes: Python (75%), TypeScript (20%), SQL (5%)
</span><span class="z-text z-plain">├── Frameworks: FastAPI, React, SQLAlchemy
</span><span class="z-text z-plain">├── Arquitectura: Monorepo con separación backend/frontend
</span><span class="z-text z-plain">├── Patrones: Patrón repository, inyección de dependencias
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">Generando agentes especializados...
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">✓ fastapi-expert
</span><span class="z-text z-plain"> Conoce: Tus patrones de endpoints, modelos Pydantic, stack de middleware
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">✓ react-specialist
</span><span class="z-text z-plain"> Conoce: Tu librería de componentes, gestión de estado, patrones de hooks
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">✓ database-architect
</span><span class="z-text z-plain"> Conoce: Tus modelos SQLAlchemy, patrones de migración, convenciones de consultas
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">✓ test-strategist
</span><span class="z-text z-plain"> Conoce: Tus fixtures de pytest, patrones de mocking, utilidades de testing
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">Equipo guardado en .claude/agents/
</span></code></pre>
<p><strong>Paso 2: Usa tus agentes inmediatamente</strong></p>
<p>Ahora tienes especialistas conscientes del proyecto. Así es como usarlos:</p>
<p><strong>Pregunta sobre arquitectura:</strong></p>
<pre class="z-code"><code><span class="z-text z-plain">Usa el agente fastapi-expert para explicar cómo funciona
</span><span class="z-text z-plain">la autenticación en este proyecto
</span></code></pre>
<p><strong>Implementa una funcionalidad:</strong></p>
<pre class="z-code"><code><span class="z-text z-plain">Usa el agente react-specialist para ayudarme a añadir un nuevo
</span><span class="z-text z-plain">componente de dashboard siguiendo nuestros patrones existentes
</span></code></pre>
<p><strong>Depura un problema:</strong></p>
<pre class="z-code"><code><span class="z-text z-plain">Usa el agente database-architect para ayudarme a entender por qué
</span><span class="z-text z-plain">esta consulta es lenta - revisa src/repositories/user_repo.py
</span></code></pre>
<p><strong>Escribe tests:</strong></p>
<pre class="z-code"><code><span class="z-text z-plain">Usa el agente test-strategist para escribir tests de integración para
</span><span class="z-text z-plain">el nuevo endpoint de pagos siguiendo nuestras convenciones de testing
</span></code></pre>
<p><strong>¿La diferencia?</strong> Estos agentes no dan consejos genéricos. Referencian <em>tus</em> archivos, <em>tus</em> patrones, <em>tus</em> convenciones.</p>
<hr />
<h2 id="escenario-2-flujo-de-trabajo-avanzado-de-depuracion">Escenario 2: Flujo de Trabajo Avanzado de Depuración</h2>
<p>Después de generar tu equipo de agentes, puedes crear un <strong>Project Debugger</strong>—un orquestador que coordina a tus especialistas para diagnosticar problemas complejos.</p>
<p><strong>Paso 1: Genera el Project Debugger</strong></p>
<pre class="z-code"><code><span class="z-text z-plain">/generate-debugger
</span></code></pre>
<pre class="z-code"><code><span class="z-text z-plain">Descubriendo agentes del proyecto...
</span><span class="z-text z-plain">├── Encontrados: fastapi-expert, react-specialist, database-architect, test-strategist
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">Analizando arquitectura del proyecto...
</span><span class="z-text z-plain">├── Puntos de entrada identificados
</span><span class="z-text z-plain">├── Patrones de manejo de errores mapeados
</span><span class="z-text z-plain">├── Convenciones de logging detectadas
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">Generando project-debugger.md...
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">✓ Creado: .claude/agents/project-debugger.md
</span><span class="z-text z-plain"> - Orquesta tus 4 agentes especialistas
</span><span class="z-text z-plain"> - Produce informes de depuración estructurados
</span><span class="z-text z-plain"> - Identifica causas raíz con referencias archivo:línea
</span></code></pre>
<p><strong>Paso 2: Usa el Debugger para investigar</strong></p>
<p>Cuando encuentres un bug, invoca el project debugger:</p>
<pre class="z-code"><code><span class="z-text z-plain">Usa el agente project-debugger para investigar: Los usuarios están
</span><span class="z-text z-plain">recibiendo errores 500 cuando envían el formulario de checkout
</span></code></pre>
<p>El debugger orquesta a tus especialistas:</p>
<pre class="z-code"><code><span class="z-text z-plain">Consultando fastapi-expert...
</span><span class="z-text z-plain">├── Trazado flujo de request a través de api/routes/checkout.py
</span><span class="z-text z-plain">├── Encontrado: PaymentService.process() lanza excepción no manejada
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">Consultando database-architect...
</span><span class="z-text z-plain">├── Verificado manejo de transacciones en repositories/order_repo.py
</span><span class="z-text z-plain">├── Encontrado: Falta rollback en fallo de pago
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">Consultando test-strategist...
</span><span class="z-text z-plain">├── Revisada cobertura de tests para flujo de checkout
</span><span class="z-text z-plain">├── Encontrado: No hay test para escenario de fallo de pago
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">Generando informe de depuración...
</span></code></pre>
<p><strong>Paso 3: Genera un informe de depuración</strong></p>
<p>El debugger produce un informe estructurado guardado en <code>.claude/reports/debugging/</code>:</p>
<pre data-lang="markdown" class="language-markdown z-code"><code class="language-markdown" data-lang="markdown"><span class="z-text z-html z-markdown"><span class="z-meta z-block-level z-markdown"><span class="z-markup z-heading z-1 z-markdown"><span class="z-punctuation z-definition z-heading z-begin z-markdown">#</span> </span><span class="z-markup z-heading z-1 z-markdown"><span class="z-entity z-name z-section z-markdown">Informe de Depuración: Errores 500 en Checkout</span><span class="z-meta z-whitespace z-newline z-markdown">
</span></span></span></span><span class="z-text z-html z-markdown">
</span><span class="z-text z-html z-markdown"><span class="z-meta z-block-level z-markdown"><span class="z-markup z-heading z-2 z-markdown"><span class="z-punctuation z-definition z-heading z-begin z-markdown">##</span> </span><span class="z-markup z-heading z-2 z-markdown"><span class="z-entity z-name z-section z-markdown">Causa Raíz</span><span class="z-meta z-whitespace z-newline z-markdown">
</span></span></span></span><span class="z-text z-html z-markdown"><span class="z-meta z-paragraph z-markdown">Falta manejo de excepciones en PaymentService.process()
</span></span><span class="z-text z-html z-markdown"><span class="z-meta z-paragraph z-markdown">(src/services/payment.py:45) combinado con falta de
</span></span><span class="z-text z-html z-markdown"><span class="z-meta z-paragraph z-markdown">rollback de transacción (src/repositories/order_repo.py:78)
</span></span><span class="z-text z-html z-markdown"><span class="z-meta z-paragraph z-markdown">
</span></span><span class="z-text z-html z-markdown"><span class="z-meta z-block-level z-markdown"><span class="z-markup z-heading z-2 z-markdown"><span class="z-punctuation z-definition z-heading z-begin z-markdown">##</span> </span><span class="z-markup z-heading z-2 z-markdown"><span class="z-entity z-name z-section z-markdown">Evidencia</span><span class="z-meta z-whitespace z-newline z-markdown">
</span></span></span></span><span class="z-text z-html z-markdown"><span class="z-markup z-list z-unnumbered z-bullet z-markdown"><span class="z-punctuation z-definition z-list_item z-markdown">-</span></span><span class="z-markup z-list z-unnumbered z-markdown"> <span class="z-meta z-paragraph z-list z-markdown">Archivo: src/services/payment.py:45-52
</span></span></span><span class="z-text z-html z-markdown"><span class="z-markup z-list z-unnumbered z-markdown"><span class="z-meta z-paragraph z-list z-markdown"></span></span><span class="z-markup z-list z-unnumbered z-bullet z-markdown"><span class="z-punctuation z-definition z-list_item z-markdown">-</span></span><span class="z-markup z-list z-unnumbered z-markdown"><span class="z-meta z-paragraph z-list z-markdown"> Archivo: src/repositories/order_repo.py:78-85
</span></span></span><span class="z-text z-html z-markdown"><span class="z-markup z-list z-unnumbered z-markdown"><span class="z-meta z-paragraph z-list z-markdown"></span></span><span class="z-markup z-list z-unnumbered z-bullet z-markdown"><span class="z-punctuation z-definition z-list_item z-markdown">-</span></span><span class="z-markup z-list z-unnumbered z-markdown"><span class="z-meta z-paragraph z-list z-markdown"> Test faltante: tests/integration/test_checkout.py
</span></span></span><span class="z-text z-html z-markdown"><span class="z-markup z-list z-unnumbered z-markdown"><span class="z-meta z-paragraph z-list z-markdown"></span></span><span class="z-markup z-list z-unnumbered z-markdown">
</span></span><span class="z-text z-html z-markdown"><span class="z-markup z-list z-unnumbered z-markdown"></span><span class="z-meta z-block-level z-markdown"><span class="z-markup z-heading z-2 z-markdown"><span class="z-punctuation z-definition z-heading z-begin z-markdown">##</span> </span><span class="z-markup z-heading z-2 z-markdown"><span class="z-entity z-name z-section z-markdown">Corrección Recomendada</span><span class="z-meta z-whitespace z-newline z-markdown">
</span></span></span></span><span class="z-text z-html z-markdown"><span class="z-markup z-list z-numbered z-bullet z-markdown">1<span class="z-punctuation z-definition z-list_item z-markdown">.</span></span><span class="z-markup z-list z-numbered z-markdown"> <span class="z-meta z-paragraph z-list z-markdown">Añadir try/except en payment.py:45
</span></span></span><span class="z-text z-html z-markdown"><span class="z-markup z-list z-numbered z-markdown"><span class="z-meta z-paragraph z-list z-markdown"></span></span><span class="z-markup z-list z-numbered z-bullet z-markdown">2<span class="z-punctuation z-definition z-list_item z-markdown">.</span></span><span class="z-markup z-list z-numbered z-markdown"><span class="z-meta z-paragraph z-list z-markdown"> Implementar rollback en order_repo.py:78
</span></span></span><span class="z-text z-html z-markdown"><span class="z-markup z-list z-numbered z-markdown"><span class="z-meta z-paragraph z-list z-markdown"></span></span><span class="z-markup z-list z-numbered z-bullet z-markdown">3<span class="z-punctuation z-definition z-list_item z-markdown">.</span></span><span class="z-markup z-list z-numbered z-markdown"><span class="z-meta z-paragraph z-list z-markdown"> Añadir test de escenario de fallo
</span></span></span><span class="z-text z-html z-markdown"><span class="z-markup z-list z-numbered z-markdown"><span class="z-meta z-paragraph z-list z-markdown"></span></span><span class="z-markup z-list z-numbered z-markdown">
</span></span><span class="z-text z-html z-markdown"><span class="z-markup z-list z-numbered z-markdown"></span><span class="z-meta z-block-level z-markdown"><span class="z-markup z-heading z-2 z-markdown"><span class="z-punctuation z-definition z-heading z-begin z-markdown">##</span> </span><span class="z-markup z-heading z-2 z-markdown"><span class="z-entity z-name z-section z-markdown">Efectos Secundarios</span><span class="z-meta z-whitespace z-newline z-markdown">
</span></span></span></span><span class="z-text z-html z-markdown"><span class="z-markup z-list z-unnumbered z-bullet z-markdown"><span class="z-punctuation z-definition z-list_item z-markdown">-</span></span><span class="z-markup z-list z-unnumbered z-markdown"> <span class="z-meta z-paragraph z-list z-markdown">Los pedidos pueden estar en estado inconsistente (necesita migración)
</span></span></span></code></pre>
<p><strong>Paso 4: Crea un ticket de Jira desde el informe</strong></p>
<p>Ahora convierte ese informe en una tarea de Jira. El comando encuentra automáticamente el informe de depuración más reciente:</p>
<pre class="z-code"><code><span class="z-text z-plain">/generate-jira-task
</span></code></pre>
<pre class="z-code"><code><span class="z-text z-plain">Buscando último informe de depuración...
</span><span class="z-text z-plain">├── Encontrado: .claude/reports/debugging/report-2026-01-06-1430.md
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">Cargando informe de depuración...
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">Buscando issues similares...
</span><span class="z-text z-plain">├── Buscando: "checkout payment exception rollback"
</span><span class="z-text z-plain">├── Encontrados 2 issues potencialmente relacionados:
</span><span class="z-text z-plain">
</span><span class="z-text z-plain"> PROJ-234: "Payment processing timeout errors"
</span><span class="z-text z-plain"> Estado: En Progreso
</span><span class="z-text z-plain">
</span><span class="z-text z-plain"> PROJ-189: "Checkout form validation issues"
</span><span class="z-text z-plain"> Estado: Hecho
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">¿Cómo deseas proceder?
</span><span class="z-text z-plain">> Crear nueva tarea de todos modos
</span><span class="z-text z-plain">> Abortar - Actualizaré un issue existente
</span></code></pre>
<p>Si eliges crear una nueva tarea:</p>
<pre class="z-code"><code><span class="z-text z-plain">Creando issue de Jira...
</span><span class="z-text z-plain">✓ Creado: PROJ-456 "Fix checkout 500 errors: missing exception handling"
</span><span class="z-text z-plain"> https://yourcompany.atlassian.net/browse/PROJ-456
</span></code></pre>
<p>La verificación de duplicados previene llenar tu backlog con issues relacionados. Si el bug es una variante de un issue existente, puedes actualizar ese ticket en lugar de crear uno nuevo.</p>
<p><strong>¿No tienes Jira configurado?</strong> El comando degrada gracefully a generar un archivo markdown listo para copiar en <code>.claude/reports/jira-drafts/</code>.</p>
<hr />
<h2 id="escenario-3-flujo-de-trabajo-repetible-para-multiples-bugs">Escenario 3: Flujo de Trabajo Repetible para Múltiples Bugs</h2>
<p>Cada investigación de bug crea su propio informe de depuración, que lleva a su propio ticket de Jira. Así es como el flujo escala a través de múltiples issues:</p>
<p><strong>Lunes: Problema de rendimiento de API</strong></p>
<pre class="z-code"><code><span class="z-text z-plain">Usa el agente project-debugger para investigar: ¿Por qué están
</span><span class="z-text z-plain">subiendo los tiempos de respuesta de la API durante horas pico?
</span></code></pre>
<p>Informe guardado: <code>.claude/reports/debugging/report-2026-01-06-0900.md</code></p>
<pre class="z-code"><code><span class="z-text z-plain">/generate-jira-task
</span></code></pre>
<p>Creado: <code>PROJ-457 "Optimize database connection pooling for peak load"</code></p>
<hr />
<p><strong>Martes: Bug de renderizado en frontend</strong></p>
<pre class="z-code"><code><span class="z-text z-plain">Usa el agente project-debugger para investigar: El gráfico del
</span><span class="z-text z-plain">dashboard no se actualiza cuando llegan nuevos datos
</span></code></pre>
<p>Informe guardado: <code>.claude/reports/debugging/report-2026-01-07-1100.md</code></p>
<pre class="z-code"><code><span class="z-text z-plain">/generate-jira-task
</span></code></pre>
<p>Creado: <code>PROJ-458 "Fix React state synchronization in DashboardChart component"</code></p>
<hr />
<p><strong>Miércoles: Caso edge de autenticación</strong></p>
<pre class="z-code"><code><span class="z-text z-plain">Usa el agente project-debugger para investigar: Los usuarios están
</span><span class="z-text z-plain">siendo deslogueados aleatoriamente después de cambios de contraseña
</span></code></pre>
<p>Informe guardado: <code>.claude/reports/debugging/report-2026-01-08-1400.md</code></p>
<pre class="z-code"><code><span class="z-text z-plain">/generate-jira-task
</span></code></pre>
<p>Creado: <code>PROJ-459 "Handle session invalidation on password change correctly"</code></p>
<hr />
<p>Cada investigación es independiente. El debugger crea informes con timestamp, y <code>/generate-jira-task</code> siempre toma el más reciente. Tu historial de depuración se acumula en <code>.claude/reports/debugging/</code>, dándote un archivo buscable de investigaciones pasadas.</p>
<hr />
<h2 id="el-flujo-de-trabajo-completo">El Flujo de Trabajo Completo</h2>
<div class="workflow-container" id="workflow">
<canvas class="workflow-canvas" aria-label="Workflow visualization"></canvas>
</div>
<script>
(function() {
const containerId = 'workflow';
// Decode HTML entities (Tera encodes / as /)
function decodeHTML(str) {
const textarea = document.createElement('textarea');
textarea.innerHTML = str;
return textarea.value;
}
const stepsData = [
{ title: decodeHTML('/generate-agent-team'), desc: decodeHTML('Crea agentes especialistas') },
{ title: decodeHTML('Usa agentes diariamente'), desc: decodeHTML('fastapi-expert react-specialist') },
{ title: decodeHTML('/generate-debugger'), desc: decodeHTML('Crea project-debugger') },
{ title: decodeHTML('Depura issues'), desc: decodeHTML('Guarda en .claude/reports/') },
{ title: decodeHTML('/generate-jira-task'), desc: decodeHTML('Crea ticket de Jira') }
];
function initWorkflow() {
const container = document.getElementById(containerId);
if (!container) return;
const canvas = container.querySelector('.workflow-canvas');
const ctx = canvas.getContext('2d');
let particles = [];
let time = 0;
const colors = {
primary: '#00d4ff',
secondary: '#8b5cf6',
accent: '#00ff88',
particle: '#00ff88',
connection: 'rgba(0, 212, 255, 0.4)',
text: '#e0e0e4',
subtext: '#8888a0'
};
function resize() {
const rect = container.getBoundingClientRect();
canvas.width = rect.width;
canvas.height = Math.max(550, stepsData.length * 130 + 100);
container.style.height = canvas.height + 'px';
}
resize();
window.addEventListener('resize', resize);
function getStepPositions() {
const centerX = canvas.width / 2;
const startY = 70;
const stepHeight = 120;
return stepsData.map((step, i) => ({
...step,
x: centerX,
y: startY + i * stepHeight,
width: Math.min(450, canvas.width * 0.85),
height: 90,
color: i % 2 === 0 ? colors.primary : colors.secondary
}));
}
function createParticle(from, to) {
return {
fromX: from.x,
fromY: from.y + from.height / 2,
toX: to.x,
toY: to.y - to.height / 2,
progress: Math.random(),
speed: 0.008 + Math.random() * 0.004
};
}
function draw() {
ctx.clearRect(0, 0, canvas.width, canvas.height);
const positions = getStepPositions();
// Draw connections
ctx.strokeStyle = colors.connection;
ctx.lineWidth = 3;
for (let i = 0; i < positions.length - 1; i++) {
const from = positions[i];
const to = positions[i + 1];
ctx.beginPath();
ctx.moveTo(from.x, from.y + from.height / 2);
ctx.lineTo(to.x, to.y - to.height / 2);
ctx.stroke();
// Arrow
const midY = (from.y + from.height / 2 + to.y - to.height / 2) / 2;
ctx.fillStyle = colors.connection;
ctx.beginPath();
ctx.moveTo(from.x - 6, midY - 4);
ctx.lineTo(from.x, midY + 6);
ctx.lineTo(from.x + 6, midY - 4);
ctx.closePath();
ctx.fill();
}
// Draw step boxes
positions.forEach((pos, i) => {
const x = pos.x - pos.width / 2;
const y = pos.y - pos.height / 2;
// Glow
ctx.shadowColor = pos.color;
ctx.shadowBlur = 20;
// Box with rounded corners
ctx.fillStyle = pos.color;
ctx.beginPath();
const radius = 8;
ctx.moveTo(x + radius, y);
ctx.lineTo(x + pos.width - radius, y);
ctx.quadraticCurveTo(x + pos.width, y, x + pos.width, y + radius);
ctx.lineTo(x + pos.width, y + pos.height - radius);
ctx.quadraticCurveTo(x + pos.width, y + pos.height, x + pos.width - radius, y + pos.height);
ctx.lineTo(x + radius, y + pos.height);
ctx.quadraticCurveTo(x, y + pos.height, x, y + pos.height - radius);
ctx.lineTo(x, y + radius);
ctx.quadraticCurveTo(x, y, x + radius, y);
ctx.closePath();
ctx.fill();
ctx.shadowBlur = 0;
// Border
ctx.strokeStyle = colors.accent;
ctx.lineWidth = 2;
ctx.stroke();
// Step number
ctx.fillStyle = '#0a0a0f';
ctx.font = 'bold 18px JetBrains Mono, monospace';
ctx.textAlign = 'left';
ctx.textBaseline = 'middle';
ctx.fillText((i + 1) + '.', x + 16, pos.y);
// Title
ctx.fillStyle = '#0a0a0f';
ctx.font = 'bold 16px JetBrains Mono, monospace';
ctx.textAlign = 'center';
ctx.fillText(pos.title, pos.x + 12, pos.y - 10);
// Description (if exists)
if (pos.desc) {
ctx.fillStyle = 'rgba(10, 10, 15, 0.8)';
ctx.font = '14px JetBrains Mono, monospace';
ctx.fillText(pos.desc, pos.x + 12, pos.y + 16);
}
});
// Update and draw particles
particles.forEach(p => {
p.progress += p.speed;
if (p.progress >= 1) {
p.progress = 0;
}
const ease = p.progress * p.progress * (3 - 2 * p.progress);
const x = p.fromX + (p.toX - p.fromX) * ease;
const y = p.fromY + (p.toY - p.fromY) * ease;
ctx.fillStyle = colors.particle;
ctx.shadowColor = colors.particle;
ctx.shadowBlur = 12;
ctx.beginPath();
ctx.arc(x, y, 4, 0, Math.PI * 2);
ctx.fill();
ctx.shadowBlur = 0;
});
time++;
requestAnimationFrame(draw);
}
// Initialize particles
const positions = getStepPositions();
for (let i = 0; i < positions.length - 1; i++) {
const p = createParticle(positions[i], positions[i + 1]);
p.progress = i * 0.3;
particles.push(p);
}
if (!window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
draw();
} else {
// Static version
const positions = getStepPositions();
positions.forEach((pos, i) => {
const x = pos.x - pos.width / 2;
const y = pos.y - pos.height / 2;
ctx.fillStyle = pos.color;
ctx.beginPath();
ctx.roundRect(x, y, pos.width, pos.height, 8);
ctx.fill();
ctx.fillStyle = '#0a0a0f';
ctx.font = 'bold 16px JetBrains Mono';
ctx.textAlign = 'center';
ctx.fillText(pos.title, pos.x, pos.y);
});
}
}
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', initWorkflow);
} else {
initWorkflow();
}
})();
</script>
<style>
.workflow-container {
background: var(--bg-0);
border: 1px solid var(--divider-color);
border-radius: 12px;
padding: 1rem;
margin: 1.5rem 0;
position: relative;
min-height: 550px;
}
.workflow-canvas {
width: 100%;
display: block;
}
@media (max-width: 768px) {
.workflow-container {
padding: 0.5rem;
}
}
</style>
<hr />
<h2 id="inicio-rapido">Inicio Rápido</h2>
<h3 id="instalacion">Instalación</h3>
<p>Instala directamente desde el marketplace de GitHub—no requiere clonar:</p>
<pre data-lang="bash" class="language-bash z-code"><code class="language-bash" data-lang="bash"><span class="z-source z-shell z-bash"><span class="z-comment z-line z-number-sign z-shell"><span class="z-punctuation z-definition z-comment z-begin z-shell">#</span></span><span class="z-comment z-line z-number-sign z-shell"> Añade el marketplace (configuración única)</span><span class="z-comment z-line z-number-sign z-shell">
</span></span><span class="z-source z-shell z-bash"><span class="z-meta z-function-call z-shell"><span class="z-variable z-function z-shell">/plugin</span></span><span class="z-meta z-function-call z-arguments z-shell"> marketplace add Cpicon/claude-code-plugins</span>
</span><span class="z-source z-shell z-bash">
</span><span class="z-source z-shell z-bash"><span class="z-comment z-line z-number-sign z-shell"><span class="z-punctuation z-definition z-comment z-begin z-shell">#</span></span><span class="z-comment z-line z-number-sign z-shell"> Instala el plugin</span><span class="z-comment z-line z-number-sign z-shell">
</span></span><span class="z-source z-shell z-bash"><span class="z-meta z-function-call z-shell"><span class="z-variable z-function z-shell">/plugin</span></span><span class="z-meta z-function-call z-arguments z-shell"> install agent-team-creator</span>
</span></code></pre>
<p>Eso es todo. El plugin está listo para usar inmediatamente.</p>
<h3 id="primeros-comandos">Primeros Comandos</h3>
<ol>
<li>Navega a tu proyecto</li>
<li>Ejecuta <code>/generate-agent-team</code> para crear tus agentes especialistas</li>
<li>Comienza a usar tus especialistas: <code>Usa el agente [nombre-agente] para...</code></li>
<li>Ejecuta <code>/generate-debugger</code> para crear tu project debugger</li>
<li>Usa el debugger para investigar bugs: <code>Usa el agente project-debugger para investigar...</code></li>
<li>Ejecuta <code>/generate-jira-task</code> para convertir el informe de depuración en un ticket</li>
</ol>
<hr />
<h2 id="lo-que-obtienes">Lo Que Obtienes</h2>
<table><thead><tr><th>Comando</th><th>Salida</th><th>Valor</th></tr></thead><tbody>
<tr><td><code>/generate-agent-team</code></td><td>3-6 agentes especialistas</td><td>Ayuda consciente del proyecto para features, preguntas, depuración</td></tr>
<tr><td><code>/generate-debugger</code></td><td>Agente orquestador</td><td>Coordina especialistas para investigaciones complejas</td></tr>
<tr><td><code>/generate-jira-task</code></td><td>Ticket Jira o markdown</td><td>Auto-encuentra último informe, crea ticket accionable</td></tr>
</tbody></table>
<h3 id="ahorro-de-tiempo">Ahorro de Tiempo</h3>
<table><thead><tr><th>Tarea</th><th>Antes</th><th>Después</th></tr></thead><tbody>
<tr><td>Obtener ayuda consciente del proyecto</td><td>N/A (solo genérico)</td><td>Inmediato</td></tr>
<tr><td>Depurar issues complejos</td><td>Horas de investigación</td><td>Informes estructurados</td></tr>
<tr><td>Escribir tickets de Jira</td><td>15-30 min</td><td>2-5 min</td></tr>
</tbody></table>
<hr />
<h2 id="pruebalo-tu-mismo">Pruébalo Tú Mismo</h2>
<p>El plugin es open source y está disponible en GitHub: <a href="https://github.com/Cpicon/claude-code-plugins">Cpicon/claude-code-plugins</a></p>
<p>Instálalo con dos comandos, ejecuta <code>/generate-agent-team</code>, y observa qué especialistas emergen para tu proyecto.</p>
<h3 id="contribuir-y-feedback">Contribuir y Feedback</h3>
<p>¿Tienes ideas para mejoras? ¿Encontraste un bug? La pestaña <a href="https://github.com/Cpicon/claude-code-plugins/issues">GitHub Issues</a> es donde puedes:</p>
<ul>
<li><strong>Solicitar features</strong> — Sugerir nuevas capacidades o mejoras</li>
<li><strong>Reportar bugs</strong> — Ayudar a mejorar la fiabilidad reportando issues que encuentres</li>
<li><strong>Discutir mejoras</strong> — Compartir ideas para mantenimiento y desarrollo del plugin</li>
</ul>
<p>Tu feedback da forma al roadmap del plugin.</p>
<p>En la <a href="/posts/claude-code-plugin-journey-part1/">Parte 1</a>, te mostraré cómo construí este plugin—los bugs que encontré, los patrones que descubrí, y por qué la arquitectura funciona como lo hace.</p>
<hr />
<p><strong>Navegación de la Serie:</strong></p>
<ul>
<li><strong>Parte 0</strong> (Estás aquí): Qué hace el plugin y cómo usarlo</li>
<li><strong>Parte 1</strong>: <a href="/posts/claude-code-plugin-journey-part1/">El Patrón de Arquitectura Híbrida</a> — Construyendo el plugin</li>
<li><strong>Parte 2</strong>: <a href="/posts/claude-code-plugin-journey-part2/">La Paradoja de la Herencia</a> — Insights de investigación</li>
</ul>
Claude Code Plugin Journey Parte 0: Agent Team Creator
¿Qué pasaría si pudieras apuntar una IA a tu proyecto y hacer que genere especialistas que realmente entienden tu stack? No asistentes genéricos—agentes que conocen tu arquitectura, tus patrones, tus convenciones.
Eso es lo que hace agent-team-creator. Déjame mostrarte el flujo de trabajo.
…