Agente Entrenado por la Comunidad: Aprendiendo de un Repo, No de la Documentación

Cuando construís configuraciones no triviales en Claude Code — skills que encadenan workflows, hooks que inyectan contexto, agentes que auditan tu propia configuración — rápidamente superás la documentación oficial. Está mejorando, pero la documentación se mueve más lento que la herramienta misma. Las funcionalidades y patrones de uso que más importan son los que nadie documentó todavía.

Necesitaba construir un agente experto en Claude Code. Uno que sepa cómo estructurar hooks, configurar agentes, manejar estado entre sesiones. No el tipo de conocimiento que encontrás en una guía de referencia.

La pregunta era: ¿dónde encontrás una fuente confiable de ese conocimiento?

Te muestro lo que encontró antes de explicar cómo

Apunté el agente terminado a mi propio directorio .claude/ — la configuración completa de producción para una plataforma SaaS con 197+ PRs — y le pedí que auditara todo.

Encontró 25 problemas. Dos eran críticos:

CRÍTICO — Secretos Expuestos

settings.local.json
- Connection strings de MongoDB PROD con contraseña
  y API key de SendGrid en texto plano dentro del array allow
- Archivo: .claude/settings.local.json (líneas ~27, 124, 150)
- Acción: Eliminar entradas con secretos, mantener patterns genéricos

.mcp.json
- API key LIVE de Stripe (sk_live_...) hardcodeada
- Acción: Mover a variable de entorno

Un hallazgo de severidad media fue más sutil: un archivo de agente de 800 líneas que se cargaba en cada sesión, quemando ventana de contexto antes de empezar cualquier trabajo real. El agente señaló la ruta exacta del archivo y recomendó dividirlo en sub-agentes enfocados.

Esa auditoría vino de un agente que aprendió cómo deberían verse las configuraciones de Claude Code estudiando cómo miles de ingenieros realmente las configuran.

La fuente: un repo que no me gusta pero respeto

Había encontrado Get Shit Done hace un tiempo. Más de 20.000 estrellas. Comunidad activa. Lo instalé, lo probé, y decidí que no era para mí. Creo que mi propio patrón IA-docs — archivos markdown jerárquicos colocados en cada nivel de directorio — funciona mejor para estructurar contexto de IA. Esa opinión no ha cambiado.

Pero la implementación era sólida. Sus patrones de hooks, estructuras de agentes, manejo de estado — todo en producción en diferentes proyectos, mantenido por miles de ingenieros. Cada PR mergeado pasó revisión por personas resolviendo problemas reales.

Cómo construí el agente experto

En lugar de escribir instrucciones desde cero, apunté un agente de tarea al repositorio de GSD y le dije: estudiá cómo este repo estructura todo. Este es el flujo real:

# Paso 1: Leer estructura del repo vía GitHub API
gh api "repos/gsd-build/get-shit-done/contents/.claude/agents" \
  -q '.[].name'
 
# Paso 2: Leer archivos de implementación específicos
gh api "repos/gsd-build/get-shit-done/contents/.claude/hooks/gsd-context-monitor.js" \
  -q '.content' | base64 -d
 
# Paso 3: Guardar descubrimientos como archivos de memoria con fecha
# Ruta: .claude/agent-memory/claude-code-expert/2026-02-26-gsd-patterns.md

El agente lee código fuente del repo, extrae patrones, y los guarda en archivos de memoria con timestamp. Así se ve uno de esos archivos en la realidad — esto es output real de estudiar la estructura de agentes de GSD:

# Patrones aprendidos de get-shit-done (GSD)
 
> Fuente: https://github.com/gsd-build/get-shit-done
> Estrellas: ~20.5k (feb 2026)
> Fecha de análisis: 2026-02-26
 
## Estructura de agentes (.claude/agents/*.md)
 
GSD usa tags XML para estructurar secciones de agentes:
- <role> — Quién sos, responsabilidades
- <project_context> — Cómo descubrir contexto del proyecto
- <execution_flow> con <step name="..." priority="...">
- <deviation_rules> — Qué auto-fixear vs qué preguntar
- <success_criteria> — Cuándo considerar el trabajo completo
 
## Crítico: Node.js sobre Bash para hooks
 
El operador // de jq trata 0 como falsy, rompiendo
silenciosamente la lógica de exit codes. GSD migró
todos los hooks a Node.js.

Esos tags XML — <role>, <project_context>, <execution_flow>, <deviation_rules> — los adopté directamente para mis propios agentes. Antes de estudiar GSD, mis definiciones de agentes eran markdown plano sin estructura consistente. Después, tienen secciones claras que Claude Code puede parsear de forma predecible. El descubrimiento de jq solo me ahorró una sesión de debugging que no hubiera visto venir.

La próxima vez que le hago una pregunta al agente, lee su memoria primero antes de investigar de nuevo. Sin trabajo repetido, y cada descubrimiento se construye sobre el anterior.

El agente completo y sus archivos de memoria son públicos en claude-production-toolkit.

Las desventajas reales

Esta estrategia tiene riesgos reales. Estás acoplando el conocimiento de tu agente a un repositorio de terceros. Si ese repo cambia de dirección, se archiva, o introduce patrones que contradicen tu arquitectura, tu agente hereda ese drift. Ya convivo con esta tensión — no estoy de acuerdo con el concepto central de GSD pero dependo de sus patrones de implementación.

También hay un costo en tokens. Procesar un repositorio completo no es gratis. Y el agente podría aprender patrones que funcionan bien en el repo fuente pero no encajan en tu proyecto. Necesitás revisar lo que produce, no confiar ciegamente.

Lo que no planifiqué

Los contribuidores de GSD estaban resolviendo sus propios problemas, revisando el código de otros, creando issues sobre cosas que se rompían. Mi agente simplemente aprendió de todo eso.

El patrón funciona para cualquier herramienta que evoluciona más rápido que su documentación. Encontrá un repo bien mantenido que la use en producción, apuntá un agente hacia él, y dejá que el uso real llene el vacío que la documentación aún no alcanzó.