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
Sistemas IA
Future With ML - Sistemas IA
Patrones de Diseño en Machine Learning, MLOps e Ingeniería de IA por Christian Picon Calderon
Zola2026-01-06T12:00:00+00:00https://futurewithml.netlify.app/es/tags/sistemas-ia/atom.xml
La Paradoja de la Herencia: Scoping de Herramientas en Sistemas Multi-Agente
2026-01-06T12:00:00+00:00
2026-01-06T12:00:00+00:00
Christian Picon Calderon
https://futurewithml.netlify.app/es/posts/claude-code-plugin-journey-part2/
<h1 id="la-paradoja-de-la-herencia-scoping-de-herramientas-en-sistemas-multi-agente">La Paradoja de la Herencia: Scoping de Herramientas en Sistemas Multi-Agente</h1>
<blockquote>
<p><em>Esta es la Parte 2 de una serie de tres partes. Ve <a href="/posts/claude-code-plugin-journey-part0/">Parte 0</a> para la visión general del plugin e instalación, o <a href="/posts/claude-code-plugin-journey-part1/">Parte 1</a> para el viaje de desarrollo.</em></p>
</blockquote>
<p><strong>Resumen</strong>: Este artículo presenta observaciones empíricas del desarrollo de un plugin de Claude Code, revelando patrones fundamentales en el diseño de sistemas IA multi-agente. A través de sesiones de desarrollo documentadas, identificamos tres hallazgos clave: (1) los modelos de herencia implícita de herramientas fallan consistentemente en la práctica, requiriendo contratos de scope explícitos; (2) las restricciones de topología impuestas por la plataforma impulsan la emergencia de patrones arquitectónicos específicos; y (3) las convenciones de nombres se convierten en requisitos funcionales en sistemas IA. Estos hallazgos tienen implicaciones para el diseño de frameworks de agentes más allá de la plataforma específica estudiada.</p>
<span id="continue-reading"></span>
<hr />
<h2 id="1-introduccion">1. Introducción</h2>
<p>Las plataformas de desarrollo basadas en agentes representan un paradigma emergente en ingeniería de software, donde instancias de IA colaboran en tareas complejas a través de orquestación estructurada. Estas plataformas ofrecen mecanismos de extensión—plugins, commands, agentes—que permiten a los desarrolladores personalizar el comportamiento para dominios específicos.</p>
<p>Este artículo examina Claude Code como caso de estudio en diseño de frameworks de agentes. Claude Code permite a los desarrolladores construir plugins personalizados con commands (atajos invocados por usuario), agentes (instancias especializadas de Claude), skills (proveedores de contexto), hooks (manejadores de eventos), e integraciones MCP (conexiones a servicios externos).</p>
<p>Durante el desarrollo de <code>agent-team-creator</code>, un plugin para generar agentes IA específicos del proyecto, documentamos observaciones sistemáticas sobre el comportamiento de la plataforma. Estas observaciones revelan patrones relevantes para el diseño de sistemas multi-agente de manera más amplia.</p>
<h3 id="preguntas-de-investigacion">Preguntas de Investigación</h3>
<ol>
<li>¿Cómo se comportan los modelos de herencia de herramientas en práctica versus documentación?</li>
<li>¿Qué patrones arquitectónicos emergen de las restricciones de topología de la plataforma?</li>
<li>¿Cómo influyen las convenciones de nombres en el comportamiento de agentes en sistemas IA?</li>
</ol>
<hr />
<h2 id="2-analisis-de-arquitectura-de-plataforma">2. Análisis de Arquitectura de Plataforma</h2>
<h3 id="2-1-taxonomia-de-tipos-de-componentes">2.1 Taxonomía de Tipos de Componentes</h3>
<p>Los plugins de Claude Code soportan cinco tipos de extensión distintos, cada uno con diferentes mecanismos de activación y scope:</p>
<table><thead><tr><th>Componente</th><th>Activador</th><th>Invocación</th><th>Scope</th></tr></thead><tbody>
<tr><td>Skills</td><td>Auto (Claude decide)</td><td>Implícita</td><td>Cross-producto</td></tr>
<tr><td>Commands</td><td>Usuario (<code>/sintaxis</code>)</td><td>Explícita</td><td>Claude Code</td></tr>
<tr><td>Agents</td><td>Spawn (herramienta Task)</td><td>Explícita/Implícita</td><td>Claude Code</td></tr>
<tr><td>Hooks</td><td>Eventos</td><td>Automática</td><td>Claude Code</td></tr>
<tr><td>MCPs</td><td>Llamadas a herramientas</td><td>Explícita</td><td>Claude Code</td></tr>
</tbody></table>
<p><strong>Observación Clave</strong>: Los Skills son únicos en ser cross-producto (funcionales en web UI, API, y CLI), mientras todos los otros componentes son específicos de Claude Code. Esto sugiere que diferentes modelos de herencia pueden aplicarse a diferentes tipos de componentes.</p>
<h3 id="2-2-inventario-de-herramientas">2.2 Inventario de Herramientas</h3>
<p>La plataforma provee 15 herramientas built-in disponibles para agentes:</p>
<ol>
<li>Read, Write, Edit, MultiEdit (operaciones de archivo)</li>
<li>Glob, Grep, LS (operaciones de búsqueda)</li>
<li>Bash (comandos de sistema)</li>
<li>WebFetch, WebSearch (acceso web)</li>
<li>NotebookRead, NotebookEdit (soporte Jupyter)</li>
<li>TodoRead, TodoWrite (seguimiento de tareas)</li>
<li>exit_plan_mode (control de flujo de trabajo)</li>
</ol>
<p>Adicionalmente, los servidores MCP (Model Context Protocol) proveen integraciones de servicios externos—acceso a bases de datos, conexiones API, servicios de terceros.</p>
<h3 id="2-3-eventos-de-ciclo-de-vida">2.3 Eventos de Ciclo de Vida</h3>
<p>Nueve eventos de hook definen el ciclo de vida del agente:</p>
<table><thead><tr><th>Evento</th><th>Activador</th></tr></thead><tbody>
<tr><td>PreToolUse</td><td>Antes de cualquier ejecución de herramienta</td></tr>
<tr><td>PostToolUse</td><td>Después de ejecución de herramienta</td></tr>
<tr><td>UserPromptSubmit</td><td>Mensaje de usuario recibido</td></tr>
<tr><td>Stop</td><td>Completación de agente</td></tr>
<tr><td>SubagentStop</td><td>Completación de subagente</td></tr>
<tr><td>SessionStart</td><td>Inicialización de sesión</td></tr>
<tr><td>SessionEnd</td><td>Terminación de sesión</td></tr>
<tr><td>PreCompact</td><td>Antes de compactación de contexto</td></tr>
<tr><td>Notification</td><td>Notificación del sistema</td></tr>
</tbody></table>
<p>Los códigos de salida de hooks siguen convenciones Unix: 0 para éxito, 2 para errores bloqueantes (Claude procesa stderr), otros códigos para errores no bloqueantes.</p>
<hr />
<h2 id="3-hallazgos-clave">3. Hallazgos Clave</h2>
<h3 id="3-1-la-paradoja-de-la-herencia">3.1 La Paradoja de la Herencia</h3>
<p><strong>Afirmación de Documentación</strong>:</p>
<blockquote>
<p>“Herramientas MCP: Los subagentes pueden acceder a herramientas MCP de servidores MCP configurados. Cuando el campo tools se omite, los subagentes heredan todas las herramientas MCP disponibles para el hilo principal.”</p>
</blockquote>
<p><strong>Comportamiento Observado</strong>: Los subagentes definidos en plugins no pueden acceder a herramientas MCP bajo ninguna configuración probada.</p>
<p>Esta discrepancia está documentada en cuatro issues de GitHub (#13605, #15810, #14496, #7296), cada uno describiendo una manifestación diferente de fallo de herencia de scope:</p>
<table><thead><tr><th>Issue</th><th>Modo de Fallo</th><th>Contexto de Scope</th></tr></thead><tbody>
<tr><td>#13605</td><td>Agentes de plugin no pueden acceder a MCP</td><td>Plugin vs built-in</td></tr>
<tr><td>#15810</td><td>Subagentes no heredan MCP</td><td>Jerarquía padre-hijo</td></tr>
<tr><td>#14496</td><td>Prompts complejos rompen acceso MCP</td><td>Complejidad de prompt</td></tr>
<tr><td>#7296</td><td>Agentes lanzados con Task carecen de MCP</td><td>Herencia de scope de usuario</td></tr>
</tbody></table>
<p><strong>Análisis</strong>: El patrón sugiere un problema arquitectónico fundamental en lugar de bugs aislados. La herencia de herramientas opera diferentemente a través de límites de scope:</p>
<ol>
<li><strong>Agentes built-in</strong> heredan herramientas MCP correctamente</li>
<li><strong>Agentes definidos en plugins</strong> no heredan herramientas MCP</li>
<li><strong>Agentes lanzados con Task</strong> reciben un scope fresco sin configuraciones de nivel de usuario</li>
</ol>
<p><strong>Implicación para Diseño de Frameworks</strong>: Los modelos de herencia implícita de herramientas requieren contratos explícitos en límites de scope. Asumir que las herramientas se propagan a través de jerarquías de agentes crea dependencias frágiles. Las declaraciones explícitas de herramientas en cada nivel de scope, aunque verbose, producen comportamiento predecible.</p>
<h3 id="3-2-restricciones-de-topologia-y-patrones-emergentes">3.2 Restricciones de Topología y Patrones Emergentes</h3>
<p><strong>Descubrimiento</strong>: La plataforma impone un límite de anidamiento de un solo nivel para spawn de agentes.</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 = ['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>Cuando un agente intenta spawnear un subagente anidado, la plataforma retorna:</p>
<pre class="z-code"><code><span class="z-text z-plain">Error: Subagents cannot spawn subagents
</span></code></pre>
<p><strong>Justificación de Diseño (Inferida)</strong>:</p>
<ul>
<li>Previene recursión infinita en sistemas autónomos</li>
<li>Mantiene consumo de recursos acotado</li>
<li>Asegura topología de ejecución predecible</li>
<li>Simplifica debugging y monitoreo</li>
</ul>
<p><strong>Arquitectura Emergente: Hub-and-Spoke</strong></p>
<div class="hub-spoke-container" id="hub-spok">
<canvas class="hub-spoke-canvas" aria-label="Hub-and-spoke agent topology visualization"></canvas>
<div class="hub-spoke-info">
<span class="info-label">Topology</span>
<span class="info-value">Hub-and-Spoke</span>
</div>
</div>
<script>
(function() {
const containerId = 'hub-spok';
// Decode HTML entities (Tera encodes / as /)
function decodeHTML(str) {
const textarea = document.createElement('textarea');
textarea.innerHTML = str;
return textarea.value;
}
const hubName = decodeHTML('Agente Principal');
const spokeNames = [decodeHTML('Agente 1'), decodeHTML('Agente 2'), decodeHTML('Agente 3')];
const showUser = true;
const showCommand = true;
function initHubSpoke() {
const container = document.getElementById(containerId);
if (!container) return;
const canvas = container.querySelector('.hub-spoke-canvas');
const ctx = canvas.getContext('2d');
let particles = [];
let time = 0;
// Colors
const colors = {
user: '#ff0080',
command: '#ff8800',
hub: '#00d4ff',
spoke: '#8b5cf6',
particle: '#00ff88',
connection: 'rgba(0, 212, 255, 0.3)'
};
function resize() {
const rect = container.getBoundingClientRect();
canvas.width = rect.width;
canvas.height = 300;
}
resize();
window.addEventListener('resize', resize);
// Get node positions
function getNodes() {
const centerX = canvas.width / 2;
const centerY = canvas.height / 2 + 20;
const spokeRadius = Math.min(canvas.width * 0.35, 120);
const nodes = [];
// User node
if (showUser) {
nodes.push({
type: 'user',
label: 'User',
x: centerX,
y: 40,
radius: 20,
color: colors.user
});
}
// Command node
if (showCommand) {
nodes.push({
type: 'command',
label: 'Command',
x: centerX,
y: showUser ? 100 : 50,
radius: 22,
color: colors.command
});
}
// Hub node
const hubY = showUser && showCommand ? centerY : centerY - 30;
nodes.push({
type: 'hub',
label: hubName,
x: centerX,
y: hubY,
radius: 32,
color: colors.hub
});
// Spoke nodes
const spokeCount = spokeNames.length;
const angleStep = Math.PI / (spokeCount + 1);
const startAngle = Math.PI;
spokeNames.forEach((name, i) => {
const angle = startAngle - angleStep * (i + 1);
nodes.push({
type: 'spoke',
label: name,
x: centerX + Math.cos(angle) * spokeRadius,
y: hubY + Math.sin(angle) * spokeRadius * 0.7,
radius: 24,
color: colors.spoke
});
});
return nodes;
}
function createParticle(from, to) {
return {
fromX: from.x,
fromY: from.y,
toX: to.x,
toY: to.y,
progress: Math.random(),
speed: 0.005 + Math.random() * 0.003,
x: from.x,
y: from.y
};
}
function draw() {
ctx.clearRect(0, 0, canvas.width, canvas.height);
const nodes = getNodes();
const hub = nodes.find(n => n.type === 'hub');
const spokes = nodes.filter(n => n.type === 'spoke');
const command = nodes.find(n => n.type === 'command');
const user = nodes.find(n => n.type === 'user');
// Draw connections
ctx.lineWidth = 2;
ctx.strokeStyle = colors.connection;
// User -> Command
if (user && command) {
ctx.beginPath();
ctx.moveTo(user.x, user.y + user.radius);
ctx.lineTo(command.x, command.y - command.radius);
ctx.stroke();
}
// Command -> Hub
if (command && hub) {
ctx.beginPath();
ctx.moveTo(command.x, command.y + command.radius);
ctx.lineTo(hub.x, hub.y - hub.radius);
ctx.stroke();
} else if (user && hub) {
ctx.beginPath();
ctx.moveTo(user.x, user.y + user.radius);
ctx.lineTo(hub.x, hub.y - hub.radius);
ctx.stroke();
}
// Hub -> Spokes
spokes.forEach(spoke => {
ctx.beginPath();
ctx.moveTo(hub.x, hub.y);
ctx.lineTo(spoke.x, spoke.y);
ctx.stroke();
});
// Draw nodes
nodes.forEach(node => {
// Glow
const gradient = ctx.createRadialGradient(
node.x, node.y, 0,
node.x, node.y, node.radius * 2
);
gradient.addColorStop(0, node.color.replace(')', ', 0.3)').replace('#', 'rgba(').replace(/^rgba\(([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})/, (m, r, g, b) => `rgba(${parseInt(r, 16)}, ${parseInt(g, 16)}, ${parseInt(b, 16)}`));
gradient.addColorStop(1, 'transparent');
// Simpler glow approach
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 = node.color;
ctx.lineWidth = 2;
ctx.stroke();
// Label
ctx.fillStyle = '#e0e0e4';
ctx.font = node.type === 'hub' ? 'bold 11px JetBrains Mono' : '10px JetBrains Mono';
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
// Wrap long labels
const maxWidth = node.radius * 1.8;
const words = node.label.split(' ');
if (words.length > 1 && ctx.measureText(node.label).width > maxWidth) {
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);
}
// Type indicator below node
if (node.type === 'hub') {
ctx.fillStyle = '#8888a0';
ctx.font = '9px JetBrains Mono';
ctx.fillText('(Hub)', node.x, node.y + node.radius + 14);
}
});
// Update and draw particles
particles.forEach(p => {
p.progress += p.speed;
if (p.progress >= 1) {
p.progress = 0;
// Reverse direction
[p.fromX, p.toX] = [p.toX, p.fromX];
[p.fromY, p.toY] = [p.toY, p.fromY];
}
const ease = p.progress * p.progress * (3 - 2 * p.progress);
p.x = p.fromX + (p.toX - p.fromX) * ease;
p.y = p.fromY + (p.toY - p.fromY) * ease;
ctx.fillStyle = colors.particle;
ctx.beginPath();
ctx.arc(p.x, p.y, 3, 0, Math.PI * 2);
ctx.fill();
// Glow
ctx.shadowColor = colors.particle;
ctx.shadowBlur = 10;
ctx.beginPath();
ctx.arc(p.x, p.y, 3, 0, Math.PI * 2);
ctx.fill();
ctx.shadowBlur = 0;
});
time++;
requestAnimationFrame(draw);
}
// Initialize particles
const nodes = getNodes();
const hub = nodes.find(n => n.type === 'hub');
const spokes = nodes.filter(n => n.type === 'spoke');
spokes.forEach(spoke => {
particles.push(createParticle(hub, spoke));
});
// Respect reduced motion
if (!window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
draw();
} else {
// Static version
const nodes = getNodes();
const hub = nodes.find(n => n.type === 'hub');
const spokes = nodes.filter(n => n.type === 'spoke');
const command = nodes.find(n => n.type === 'command');
const user = nodes.find(n => n.type === 'user');
ctx.lineWidth = 2;
ctx.strokeStyle = colors.connection;
if (user && command) {
ctx.beginPath();
ctx.moveTo(user.x, user.y + user.radius);
ctx.lineTo(command.x, command.y - command.radius);
ctx.stroke();
}
if (command && hub) {
ctx.beginPath();
ctx.moveTo(command.x, command.y + command.radius);
ctx.lineTo(hub.x, hub.y - hub.radius);
ctx.stroke();
}
spokes.forEach(spoke => {
ctx.beginPath();
ctx.moveTo(hub.x, hub.y);
ctx.lineTo(spoke.x, spoke.y);
ctx.stroke();
});
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 = '#e0e0e4';
ctx.font = node.type === 'hub' ? 'bold 11px JetBrains Mono' : '10px JetBrains Mono';
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
ctx.fillText(node.label, node.x, node.y);
});
}
}
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', initHubSpoke);
} else {
initHubSpoke();
}
})();
</script>
<style>
.hub-spoke-container {
background: var(--bg-0);
border: 1px solid var(--divider-color);
border-radius: 12px;
padding: 1rem;
margin: 1.5rem 0;
position: relative;
}
.hub-spoke-canvas {
width: 100%;
height: 300px;
display: block;
}
.hub-spoke-info {
position: absolute;
bottom: 1rem;
right: 1rem;
background: rgba(0, 0, 0, 0.6);
padding: 0.5rem 0.75rem;
border-radius: 6px;
font-family: 'JetBrains Mono', monospace;
font-size: 0.75rem;
}
.hub-spoke-info .info-label {
color: var(--meta-color);
display: block;
margin-bottom: 0.25rem;
}
.hub-spoke-info .info-value {
color: #00d4ff;
}
@media (max-width: 768px) {
.hub-spoke-canvas {
height: 250px;
}
}
</style>
<p>Esta restricción elimina jerarquías de agentes en estructura de árbol en favor de topologías planas coordinadas por hub. El agente “hub” coordina ejecución paralela de agentes “spoke”. Ningún spoke puede spawnear agentes adicionales.</p>
<p><strong>Trade-off Observado</strong>:</p>
<table><thead><tr><th>Capacidad Perdida</th><th>Propiedad Ganada</th></tr></thead><tbody>
<tr><td>Descomposición recursiva</td><td>Profundidad de ejecución acotada</td></tr>
<tr><td>Jerarquía dinámica</td><td>Topología predecible</td></tr>
<tr><td>Anidamiento arbitrario</td><td>Gestión de recursos simplificada</td></tr>
</tbody></table>
<p><strong>Implicación para Diseño de Frameworks</strong>: Las restricciones de topología son decisiones de diseño, no meras limitaciones. El patrón hub-and-spoke que emerge del anidamiento de un solo nivel produce sistemas más fáciles de razonar, depurar, y monitorear que estructuras recursivas arbitrarias.</p>
<h3 id="3-3-naming-como-comportamiento">3.3 Naming como Comportamiento</h3>
<p><strong>Descubrimiento</strong>: Claude Code infiere comportamiento de agente a partir de nombres de agentes.</p>
<p>Un agente llamado <code>code-reviewer</code> activa comportamientos de revisión built-in que pueden sobrescribir instrucciones personalizadas del system prompt. La plataforma aplica heurísticas basadas en convenciones de nombres.</p>
<p><strong>Patrón Observado</strong>:</p>
<table><thead><tr><th>Nombre de Agente</th><th>Comportamiento Inferido</th></tr></thead><tbody>
<tr><td><code>code-reviewer</code></td><td>Patrones genéricos de revisión de código</td></tr>
<tr><td><code>test-writer</code></td><td>Patrones de generación de tests</td></tr>
<tr><td><code>implementation-planner</code></td><td>Menos inferencia, más control personalizado</td></tr>
</tbody></table>
<p><strong>Análisis</strong>: Esto representa un paradigma de “convención sobre configuración” aplicado a sistemas de agentes IA. La plataforma asume que nombres semánticamente significativos llevan intención de comportamiento.</p>
<p><strong>Implicaciones</strong>:</p>
<ol>
<li>Las convenciones de nombres se convierten en requisitos funcionales</li>
<li>Nombres distintivos, no genéricos preservan comportamiento personalizado</li>
<li>El diseño de sistemas de agentes debe considerar inferencia basada en nombres</li>
</ol>
<hr />
<h2 id="4-patrones-emergentes">4. Patrones Emergentes</h2>
<h3 id="4-1-separacion-i-o-arquitectura-hibrida">4.1 Separación I/O (Arquitectura Híbrida)</h3>
<p>En respuesta a las limitaciones de acceso MCP, emergió un patrón arquitectónico claro: separar operaciones de I/O de operaciones de inteligencia.</p>
<p><strong>Modelo de Capas</strong>:</p>
<table><thead><tr><th>Capa</th><th>Responsabilidades</th><th>Componentes</th></tr></thead><tbody>
<tr><td>I/O</td><td>Acceso MCP, operaciones de archivo, interacción con usuario, caché</td><td>Commands</td></tr>
<tr><td>Inteligencia</td><td>Razonamiento, análisis, formateo, decisiones</td><td>Agents</td></tr>
</tbody></table>
<p><strong>Ejemplo de Pipeline de 6 Fases</strong>:</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": "Disponibilidad", "io": "external"},
{"phase": 1, "owner": "Command", "label": "Resolver Datos", "io": "external"},
{"phase": 2, "owner": "Command", "label": "Cargar Contenido", "io": "local"},
{"phase": 3, "owner": "Command", "label": "Validación", "io": "external"},
{"phase": 4, "owner": "Agent", "label": "Razonamiento", "io": "none"},
{"phase": 5, "owner": "Agent", "label": "Formateo", "io": "none"},
{"phase": 6, "owner": "Command", "label": "Entrega", "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><strong>Generalizabilidad</strong>: Esta separación aplica a cualquier framework donde existan restricciones de acceso a herramientas. La capa de inteligencia se vuelve portable y testeable en aislamiento. La capa de I/O se convierte en el adaptador específico de plataforma.</p>
<h3 id="4-2-validacion-basada-en-fases">4.2 Validación Basada en Fases</h3>
<p>Cada transición de fase representa un checkpoint de validación:</p>
<table><thead><tr><th>Checkpoint</th><th>Validación</th></tr></thead><tbody>
<tr><td>Pre-fase</td><td>Verificación de contrato de entrada</td></tr>
<tr><td>Mid-fase</td><td>Checkpoint de progreso</td></tr>
<tr><td>Post-fase</td><td>Cumplimiento de contrato de salida</td></tr>
<tr><td>Inter-fase</td><td>Validación de transformación de datos</td></tr>
</tbody></table>
<p><strong>Estrategias de Recuperación de Errores</strong>:</p>
<ol>
<li>Rollback al último estado válido</li>
<li>Reintentar con parámetros modificados</li>
<li>Escalar a modo fallback</li>
<li>Preservar resultados parciales</li>
</ol>
<h3 id="4-3-degradacion-graciosa">4.3 Degradación Graciosa</h3>
<p><strong>Patrón FALLBACK_MODE</strong>:</p>
<p>Cuando los servicios externos se vuelven no disponibles, el sistema degrada graciosamente:</p>
<div class="comparison-container" id="comparis">
<canvas class="comparison-canvas" aria-label="Mode comparison visualization"></canvas>
</div>
<script>
(function() {
const containerId = 'comparis';
const mode1Title = 'Modo Normal';
const mode1Steps = ['Fase 1: Resolver MCP', 'Fase 3: Verificar Dups', 'Fase 6: Crear Issue'];
const mode2Title = 'Modo Fallback';
const mode2Steps = ['Fase 1: Saltar', 'Fase 3: Saltar', 'Fase 6: Archivo Local'];
const sharedTitle = 'Capa de Inteligencia (Siempre Activa)';
const sharedSteps = ['Fase 4: Razonamiento', 'Fase 5: Formateo'];
function initComparison() {
const container = document.getElementById(containerId);
if (!container) return;
const canvas = container.querySelector('.comparison-canvas');
const ctx = canvas.getContext('2d');
let particles = [];
let time = 0;
const colors = {
mode1: '#00d4ff',
mode2: '#ff8800',
shared: '#00ff88',
skip: '#444466',
particle: '#00ff88',
connection: 'rgba(255, 255, 255, 0.2)',
text: '#e0e0e4',
subtext: '#8888a0'
};
function resize() {
const rect = container.getBoundingClientRect();
canvas.width = rect.width;
canvas.height = 320;
}
resize();
window.addEventListener('resize', resize);
function draw() {
ctx.clearRect(0, 0, canvas.width, canvas.height);
const leftX = canvas.width * 0.25;
const rightX = canvas.width * 0.75;
const centerX = canvas.width / 2;
const headerY = 35;
const stepsStartY = 80;
const stepSpacing = 45;
const sharedY = 240;
// Draw mode headers
function drawHeader(x, title, color) {
ctx.fillStyle = color;
ctx.font = 'bold 14px JetBrains Mono';
ctx.textAlign = 'center';
ctx.shadowColor = color;
ctx.shadowBlur = 10;
ctx.fillText(title, x, headerY);
ctx.shadowBlur = 0;
// Underline
ctx.strokeStyle = color;
ctx.lineWidth = 2;
ctx.beginPath();
ctx.moveTo(x - 60, headerY + 8);
ctx.lineTo(x + 60, headerY + 8);
ctx.stroke();
}
drawHeader(leftX, mode1Title, colors.mode1);
drawHeader(rightX, mode2Title, colors.mode2);
// Draw steps for each mode
function drawStep(x, y, text, color, isSkip) {
const width = 130;
const height = 32;
ctx.shadowColor = color;
ctx.shadowBlur = isSkip ? 0 : 12;
ctx.fillStyle = isSkip ? colors.skip : color;
ctx.beginPath();
ctx.roundRect(x - width/2, y - height/2, width, height, 6);
ctx.fill();
ctx.shadowBlur = 0;
if (!isSkip) {
ctx.strokeStyle = '#00ff88';
ctx.lineWidth = 1;
ctx.stroke();
} else {
ctx.setLineDash([4, 4]);
ctx.strokeStyle = '#666';
ctx.lineWidth = 1;
ctx.stroke();
ctx.setLineDash([]);
}
ctx.fillStyle = isSkip ? '#666' : '#0a0a0f';
ctx.font = isSkip ? '10px JetBrains Mono' : 'bold 10px JetBrains Mono';
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
ctx.fillText(text, x, y);
return { x, y, width, height };
}
// Mode 1 steps
const mode1Nodes = [];
mode1Steps.forEach((step, i) => {
const y = stepsStartY + i * stepSpacing;
mode1Nodes.push(drawStep(leftX, y, step, colors.mode1, false));
});
// Mode 2 steps
const mode2Nodes = [];
mode2Steps.forEach((step, i) => {
const y = stepsStartY + i * stepSpacing;
const isSkip = step.toLowerCase().includes('skip');
mode2Nodes.push(drawStep(rightX, y, step, colors.mode2, isSkip));
});
// Connections between steps
ctx.strokeStyle = colors.connection;
ctx.lineWidth = 1;
for (let i = 0; i < mode1Nodes.length - 1; i++) {
const from = mode1Nodes[i];
const to = mode1Nodes[i + 1];
ctx.beginPath();
ctx.moveTo(from.x, from.y + from.height/2);
ctx.lineTo(to.x, to.y - to.height/2);
ctx.stroke();
}
for (let i = 0; i < mode2Nodes.length - 1; i++) {
const from = mode2Nodes[i];
const to = mode2Nodes[i + 1];
ctx.beginPath();
ctx.moveTo(from.x, from.y + from.height/2);
ctx.lineTo(to.x, to.y - to.height/2);
ctx.stroke();
}
// Shared section
ctx.fillStyle = colors.shared;
ctx.font = 'bold 13px JetBrains Mono';
ctx.textAlign = 'center';
ctx.shadowColor = colors.shared;
ctx.shadowBlur = 10;
ctx.fillText(sharedTitle, centerX, sharedY - 25);
ctx.shadowBlur = 0;
// Shared steps box
const sharedWidth = 200;
const sharedHeight = 50;
ctx.fillStyle = 'rgba(0, 255, 136, 0.15)';
ctx.strokeStyle = colors.shared;
ctx.lineWidth = 2;
ctx.beginPath();
ctx.roundRect(centerX - sharedWidth/2, sharedY - 10, sharedWidth, sharedHeight, 8);
ctx.fill();
ctx.stroke();
// Shared step text
ctx.fillStyle = colors.text;
ctx.font = '11px JetBrains Mono';
sharedSteps.forEach((step, i) => {
ctx.fillText(step, centerX, sharedY + 8 + i * 16);
});
// Arrows from both modes to shared
ctx.strokeStyle = colors.connection;
ctx.lineWidth = 2;
// Left arrow
const lastMode1 = mode1Nodes[mode1Nodes.length - 1];
ctx.beginPath();
ctx.moveTo(lastMode1.x, lastMode1.y + lastMode1.height/2);
ctx.quadraticCurveTo(lastMode1.x, sharedY - 30, centerX - sharedWidth/2, sharedY + 15);
ctx.stroke();
// Right arrow
const lastMode2 = mode2Nodes[mode2Nodes.length - 1];
ctx.beginPath();
ctx.moveTo(lastMode2.x, lastMode2.y + lastMode2.height/2);
ctx.quadraticCurveTo(lastMode2.x, sharedY - 30, centerX + sharedWidth/2, sharedY + 15);
ctx.stroke();
// "Always Active" badge
ctx.fillStyle = colors.shared;
ctx.font = 'bold 9px JetBrains Mono';
ctx.fillText('✓ ALWAYS ACTIVE', centerX, sharedY + sharedHeight + 8);
// Animate particles
particles.forEach(p => {
p.progress += p.speed;
if (p.progress >= 1) {
p.progress = 0;
p.side = p.side === 'left' ? 'right' : 'left';
}
const nodes = p.side === 'left' ? mode1Nodes : mode2Nodes;
const segmentIndex = Math.floor(p.progress * nodes.length);
const segmentProgress = (p.progress * nodes.length) % 1;
if (segmentIndex < nodes.length - 1) {
const from = nodes[segmentIndex];
const to = nodes[segmentIndex + 1];
const x = from.x + (to.x - from.x) * segmentProgress;
const y = from.y + (to.y - from.y) * segmentProgress;
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
particles.push({ side: 'left', progress: 0, speed: 0.008 });
particles.push({ side: 'right', progress: 0.5, speed: 0.008 });
if (!window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
draw();
} else {
draw();
// Just draw once for static
}
}
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', initComparison);
} else {
initComparison();
}
})();
</script>
<style>
.comparison-container {
background: var(--bg-0);
border: 1px solid var(--divider-color);
border-radius: 12px;
padding: 1rem;
margin: 1.5rem 0;
position: relative;
}
.comparison-canvas {
width: 100%;
height: 320px;
display: block;
}
@media (max-width: 768px) {
.comparison-container {
overflow-x: auto;
}
.comparison-canvas {
min-width: 500px;
}
}
</style>
<p>Las capas de inteligencia (Fases 4-5) funcionan idénticamente en ambos modos. El razonamiento core se preserva incluso cuando las capacidades de I/O están reducidas.</p>
<hr />
<h2 id="5-implicaciones-para-diseno-de-frameworks">5. Implicaciones para Diseño de Frameworks</h2>
<h3 id="5-1-filosofia-de-acceso-a-herramientas">5.1 Filosofía de Acceso a Herramientas</h3>
<p><strong>Recomendación</strong>: Preferir declaraciones explícitas de herramientas sobre herencia implícita.</p>
<p>La paradoja de la herencia demuestra que los modelos implícitos crean límites de scope inesperados. Las declaraciones explícitas, aunque verbose, producen comportamiento predecible:</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-comment z-line z-number-sign z-yaml"><span class="z-punctuation z-definition z-comment z-line z-number-sign z-yaml">#</span> Explícito (recomendado)
</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">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">Grep</span>
</span><span class="z-source z-yaml">
</span><span class="z-source z-yaml"><span class="z-comment z-line z-number-sign z-yaml"><span class="z-punctuation z-definition z-comment z-line z-number-sign z-yaml">#</span> Implícito (problemático)
</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 class="z-string z-unquoted z-plain z-out z-yaml">inherit</span> <span class="z-comment z-line z-number-sign z-yaml"><span class="z-punctuation z-definition z-comment z-line z-number-sign z-yaml">#</span> Comportamiento varía por contexto
</span></span></code></pre>
<h3 id="5-2-fidelidad-de-documentacion">5.2 Fidelidad de Documentación</h3>
<p><strong>Requisito</strong>: La implementación debe coincidir con la documentación.</p>
<p>La brecha entre comportamiento documentado y real de MCP consumió esfuerzo significativo de debugging. Pruebas automatizadas de comportamientos documentados captarían tales discrepancias antes de que lleguen a usuarios.</p>
<h3 id="5-3-testing-en-contextos-reales">5.3 Testing en Contextos Reales</h3>
<p><strong>Requisito</strong>: Probar con restricciones reales de plataforma.</p>
<p>El acceso MCP funciona en testing aislado pero falla en contextos de plugin. Los tests de integración deben ejecutarse en ambientes similares a producción con límites de scope reales.</p>
<h3 id="5-4-consideraciones-de-experiencia-de-desarrollador">5.4 Consideraciones de Experiencia de Desarrollador</h3>
<p><strong>Observación</strong>: Los requisitos complejos de deployment desalientan la experimentación.</p>
<p>El requisito de sincronización en tres ubicaciones, falta de hot reload, y validación estricta de schema añaden fricción al ciclo de desarrollo. Cada restricción añade aproximadamente 2-5 minutos por ciclo de cambio versus segundos para sistemas con hot-reload.</p>
<p><strong>Análisis de Trade-off</strong>:</p>
<table><thead><tr><th>Restricción</th><th>Beneficio</th><th>Costo</th></tr></thead><tbody>
<tr><td>Sync en tres ubicaciones</td><td>Consistencia de versión</td><td>Overhead de sync manual</td></tr>
<tr><td>Sin hot reload</td><td>Predictabilidad de estado</td><td>Delay de reinicio</td></tr>
<tr><td>Schema estricto</td><td>Detección temprana de errores</td><td>Dificultad de debugging</td></tr>
</tbody></table>
<hr />
<h2 id="6-conclusion">6. Conclusión</h2>
<h3 id="resumen-de-contribuciones">Resumen de Contribuciones</h3>
<p>Este estudio empírico del desarrollo de plugins de Claude Code revela patrones aplicables al diseño de sistemas IA multi-agente:</p>
<ol>
<li>
<p><strong>La Paradoja de la Herencia</strong>: Los modelos de herencia de acceso a herramientas documentados en especificaciones pueden no funcionar a través de todos los límites de scope. Los contratos explícitos previenen comportamiento inesperado.</p>
</li>
<li>
<p><strong>Arquitectura Impulsada por Topología</strong>: Las restricciones impuestas por plataforma (como anidamiento de un solo nivel) impulsan la emergencia de patrones específicos (hub-and-spoke) que pueden ser superiores a diseños sin restricciones.</p>
</li>
<li>
<p><strong>Naming como Comportamiento</strong>: En sistemas de agentes IA, las convenciones de nombres llevan implicaciones funcionales más allá del etiquetado.</p>
</li>
<li>
<p><strong>Separación I/O</strong>: Separar I/O de inteligencia crea sistemas portables, testeables, con degradación graciosa.</p>
</li>
</ol>
<h3 id="limitaciones">Limitaciones</h3>
<p>Este estudio está basado en observaciones de una sola plataforma (Claude Code) durante un período específico de desarrollo. Los hallazgos pueden no generalizarse a todos los frameworks de agentes. Adicionalmente, el comportamiento de la plataforma puede cambiar a medida que se resuelven bugs.</p>
<h3 id="direcciones-futuras-de-investigacion">Direcciones Futuras de Investigación</h3>
<ol>
<li>Análisis comparativo de modelos de herencia de herramientas a través de plataformas de agentes</li>
<li>Especificación formal de contratos de scope para sistemas multi-agente</li>
<li>Estudios empíricos de acoplamiento naming-comportamiento en otros sistemas IA</li>
<li>Patrones de diseño de frameworks que explícitamente aprovechan restricciones de topología</li>
</ol>
<hr />
<h2 id="apendice-resumen-de-evidencia">Apéndice: Resumen de Evidencia</h2>
<h3 id="issues-de-github-referenciados">Issues de GitHub Referenciados</h3>
<table><thead><tr><th>Issue</th><th>Descripción</th></tr></thead><tbody>
<tr><td>#13605</td><td>Agentes de plugin personalizados no pueden acceder a MCP</td></tr>
<tr><td>#15810</td><td>Subagentes no heredan 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>
<h3 id="metricas-de-investigacion">Métricas de Investigación</h3>
<ul>
<li><strong>Período de Observación</strong>: Enero 3-4, 2026</li>
<li><strong>Inversión de Tokens</strong>: ~265,000 tokens a través de sesiones</li>
<li><strong>Observaciones Distintas</strong>: 13 hallazgos documentados</li>
<li><strong>Tipos de Hallazgo</strong>: 4 Decisiones, 8 Descubrimientos, 1 Cambio</li>
</ul>
<h3 id="metodologia">Metodología</h3>
<p>Las observaciones fueron recolectadas a través de sesiones de desarrollo usando el sistema de memoria persistente claude-mem. Cada hallazgo fue cruzado contra documentación y, donde aplicable, reportes de issues de GitHub. Los workarounds fueron desarrollados a través de experimentación iterativa.</p>
<hr />
<h2 id="obten-el-plugin">Obtén el Plugin</h2>
<p>El plugin discutido en esta investigación 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>: <a href="/posts/claude-code-plugin-journey-part1/">El Patrón de Arquitectura Híbrida</a> — Construyendo el plugin, lecciones aprendidas</li>
<li><strong>Parte 2</strong> (Estás aquí): Insights de investigación, patrones</li>
</ul>
<hr />
<p><em>Este artículo está basado en observaciones empíricas del desarrollo del plugin agent-team-creator de Claude Code. Para guía práctica de implementación, ve Parte 1.</em></p>
La Paradoja de la Herencia: Scoping de Herramientas en Sistemas Multi-Agente
Esta es la Parte 2 de una serie de tres partes. Ve Parte 0 para la visión general del plugin e instalación, o Parte 1 para el viaje de desarrollo.
Resumen: Este artículo presenta observaciones empíricas del desarrollo de un plugin de Claude Code, revelando patrones fundamentales en el diseño de sistemas IA multi-agente. A través de sesiones de desarrollo documentadas, identificamos tres hallazgos clave: (1) los modelos de herencia implícita de herramientas fallan consistentemente en la práctica, requiriendo contratos de scope explícitos; (2) las restricciones de topología impuestas por la plataforma impulsan la emergencia de patrones arquitectónicos específicos; y (3) las convenciones de nombres se convierten en requisitos funcionales en sistemas IA. Estos hallazgos tienen implicaciones para el diseño de frameworks de agentes más allá de la plataforma específica estudiada.
…