## Plan de Investigación – Sub-agentes para Claude Code, Codex CLI y OpenCode

---

### 1. `## Objetivo de la documentación`

Documentar de forma exhaustiva el ecosistema actual de **sub-agentes** (también llamados *custom agents*, *specialized agents*, *task agents* o *slash commands* avanzados) en tres plataformas CLI de codificación asistida por IA: **Claude Code** (Anthropic), **Codex CLI** (OpenAI) y **OpenCode**. El documento cubrirá:

- Qué son los sub-agentes y cómo difieren entre plataformas.
- Cómo crearlos, configurarlos, compartirlos y encadenarlos.
- Catálogo comunitario de sub-agentes para: eficiencia, seguridad, buenas prácticas, validaciones, código limpio, UX/UI, testing, revisión de código, etc.
- Integración con modelos externos (DeepSeek, OpenRouter, etc.) para reducción de costos.
- Herramientas y wrappers open-source que habilitan o facilitan el uso de sub-agentes.
- Estado del arte a principios de 2026.

---

### 2. `## Audiencia y nivel técnico`

**Audiencia primaria:** Desarrolladores full-stack y de plataforma con experiencia en CLI, que ya utilizan al menos una de estas herramientas y quieren multiplicar su productividad mediante sub-agentes especializados.

**Prerrequisitos esperados del lector:**
- Familiaridad con terminal / shell (bash, zsh).
- Conocimiento básico de al menos una herramienta: Claude Code, Codex CLI u OpenCode.
- Nociones de YAML/TOML/JSON para archivos de configuración.
- Comprensión de APIs de LLMs (API keys, endpoints, modelos).
- Experiencia con Git y workflows de desarrollo.
- (Para secciones avanzadas) Conocimiento de MCP (Model Context Protocol) y tool-use.

---

### 3. `## Alcance y versiones`

| Eje | Cubierto | Fuera de alcance |
|---|---|---|
| **Plataformas** | Claude Code (CLI), Codex CLI (OpenAI), OpenCode | Cursor, Copilot Chat, Aider (salvo mención comparativa), plugins IDE |
| **Versiones** | Últimas estables a Q1 2026 + nightly/community forks relevantes | Versiones legacy anteriores a 2025 |
| **Modelos** | Claude 3.5/4, GPT-4o/o3/o4, DeepSeek V3/R1, open-source vía OpenRouter/Ollama | Modelos de pago enterprise no accesibles al público general |
| **Tipo de sub-agentes** | Especializados en código, seguridad, UX/UI, validación, buenas prácticas, eficiencia | Agentes de propósito general no técnicos (e.g., escritura creativa) |
| **Compartición** | Repositorios comunitarios, gists, registros de agentes, formatos de intercambio | Marketplaces propietarios cerrados |

---

### 4. `## Estructura del documento`

| # | Sección | Propósito |
|---|---|---|
| 1 | **Resumen ejecutivo** | Visión general en 3-4 párrafos: qué son los sub-agentes, por qué importan, estado actual del ecosistema. |
| 2 | **Conceptos fundamentales** | Definición precisa de «sub-agente» en cada plataforma. Diferencias entre sub-agente, custom slash command, MCP server, tool y hook. |
| 3 | **Claude Code: sub-agentes** | Arquitectura de sub-agentes en Claude Code. `CLAUDE.md`, custom slash commands, hooks, `.claude/` directory. Cómo crear, invocar y encadenar. Limitaciones actuales. |
| 4 | **Codex CLI: sub-agentes** | Arquitectura de Codex CLI. Sistema de agents (`--agent`), configuración (`codex.yaml`), custom prompts y system prompts. Workflows multi-agente. |
| 5 | **OpenCode: sub-agentes** | Arquitectura de OpenCode. Soporte multi-modelo, configuración de agents, prompts personalizados. Cómo agregar DeepSeek vía API. |
| 6 | **Catálogo comunitario de sub-agentes** | Tabla/reseña de sub-agentes compartidos por la comunidad (2025-2026), organizados por dominio: |
| | 6.1 Seguridad | SAST ligero, revisión de dependencias, detección de secretos, OWASP checks. |
| | 6.2 Eficiencia y rendimiento | Análisis de complejidad, detección de N+1 queries, profiling helpers. |
| | 6.3 Código limpio y buenas prácticas | Linting semántico, convenciones de naming, principios SOLID, DRY/KISS. |
| | 6.4 Validaciones | Type checking avanzado, validación de schemas, edge cases. |
| | 6.5 UX/UI | Revisión de accesibilidad, consistencia de diseño, patrones de interacción. |
| | 6.6 Testing | Generación de tests, análisis de cobertura, property-based testing. |
| | 6.7 DevOps / CI | Sub-agentes para pipelines, Dockerfile optimization, infra as code. |
| 7 | **Compartición y descubrimiento** | Formatos de intercambio (YAML/TOML portables). Repositorios comunitarios. Cómo publicar y reutilizar sub-agentes entre plataformas. |
| 8 | **Tool-use y extensibilidad** | Cómo los sub-agentes invocan herramientas externas: MCP, shell commands, APIs REST. Ejemplos prácticos. |
| 9 | **Integración con DeepSeek y otros modelos low-cost** | Guía paso a paso para usar DeepSeek V3/R1 como modelo principal o fallback en cada plataforma. Comparativa de costos. OpenRouter como alternativa unificada. |
| 10 | **Proyectos open-source relevantes** | Repositorios, wrappers, y herramientas que extienden o complementan el ecosistema de sub-agentes. |
| 11 | **Tabla comparativa** | Comparación lado a lado: capacidades de sub-agentes, modelo de configuración, tool-use, costos, madurez. |
| 12 | **Buenas prácticas y recomendaciones** | Patrones efectivos, anti-patrones comunes, seguridad al ejecutar sub-agentes de terceros. |
| 13 | **Referencias y recursos** | Enlaces a documentación oficial, repositorios, artículos, comunidades. |

---

### 5. `## Aspectos técnicos a investigar`

La siguiente tabla detalla **qué requiere búsqueda activa en web** (búsqueda en tiempo real o consulta a documentación oficial) vs. lo que puede sintetizarse a partir de conocimiento existente.

| Tema | Necesita investigación web | Fuentes sugeridas |
|---|---|---|
| Anatomía exacta de sub-agentes en Claude Code (Q1 2026) | ✅ Sí — documentación oficial Anthropic, changelogs, blog posts | docs.anthropic.com, GitHub anthropics/claude-code |
| Anatomía exacta de sub-agentes en Codex CLI | ✅ Sí | GitHub openai/codex, docs oficiales OpenAI |
| Anatomía exacta de sub-agentes en OpenCode | ✅ Sí | GitHub del proyecto, documentación, issues/PRs |
| Formato de intercambio portable de agentes | ✅ Sí — ¿existe ya un estándar de facto? | Aider, OpenCode, comunidades |
| Repositorios comunitarios activos (2025-2026) | ✅ Sí | GitHub topics, Reddit r/ClaudeCode, r/OpenAI, Discord |
| Catálogo de sub-agentes por dominio | ✅ Sí — búsqueda y curación | GitHub gists, awesome-lists, blogs |
| MCP: tool-use desde sub-agentes | 🔶 Parcial — concepto conocido, detalles de implementación requieren verificación | modelcontextprotocol.io |
| Precios actualizados de APIs (DeepSeek, Claude, GPT) | ✅ Sí | Páginas oficiales de pricing |
| Comparativa de costos reales | 🔶 Síntesis a partir de precios + estimaciones publicadas | Benchmarks comunitarios |
| Anti-patrones y seguridad de sub-agentes de terceros | 🔶 Síntesis + búsqueda de incidentes reportados | Hacker News, blogs de seguridad |
| Proyectos open-source wrappers | ✅ Sí | GitHub search |

---

### 6. `## Convenciones`

| Elemento | Convención |
|---|---|
| **Idioma** | Español (México/neutro). Términos técnicos en inglés cuando no tengan traducción establecida. |
| **Formato** | Markdown con frontmatter YAML. |
| **Código** | Bloques delimitados con triple backtick y lenguaje (```yaml, ```bash, ```json, ```python). Líneas largas truncadas con comentario `# …`. |
| **Comandos shell** | Precedidos por `$` para usuario normal, `#` si requiere root (raro aquí). |
| **Notas** | `> ℹ️ Nota:` para información complementaria. |
| **Warnings** | `> ⚠️ Precaución:` para riesgos de seguridad, breaking changes, o limitaciones. |
| **Tips** | `> 💡 Tip:` para consejos prácticos. |
| **Nombres de archivo** | En backticks: `CLAUDE.md`, `codex.yaml`, `.opencode.toml`. |
| **Nombres de herramientas** | Claude Code, Codex CLI, OpenCode — con mayúscula inicial consistente. |
| **Diagramas** | Mermaid. Arquitectura de agentes, flujos multi-agente, tool-use. |
| **Tablas comparativas** | Markdown nativo, columnas alineadas. |
| **Referencias** | Enlaces inline `[texto](url)` con fecha de acceso entre paréntesis. |

---

### 7. `## Entregable esperado`

Un único documento Markdown de nombre:

```
sub-agentes-claude-code-codex-opencode-2026.md
```

Con las siguientes características:
- **Extensión estimada:** 12–18 secciones, 4000–7000 palabras.
- **Diagramas Mermaid:** 3–5 diagramas (arquitectura general, flujo multi-agente, tool-use, comparativa de costos).
- **Fragmentos de código:** 15–25 bloques (configuraciones YAML/TOML, ejemplos de sub-agentes, invocaciones shell).
- **Tablas:** 4–7 (catálogo de sub-agentes, comparativa de plataformas, costos, proyectos open-source).
- **Idioma:** Español, con términos técnicos en inglés donde corresponda.
- **Navegabilidad:** Tabla de contenidos al inicio con enlaces a cada sección.
- **Estado:** Documento técnico objetivo, sin opiniones personales, con referencias verificables.

---

### Siguientes pasos

Una vez aprobado este plan, procederé a la fase de **investigación web activa** para recopilar la información detallada de cada sección, seguida de la **redacción** del documento conforme a las convenciones establecidas.