La guía de Claude Code que me hizo replantearme todo

Ayer, un ganador de hackathon de Anthropic publicó su guía de configuración de Claude Code, y la apliqué entera de inmediato. Pasé el día entero con ello, y la diferencia fue real.

La guía es de affaan (@affaanmustafa), que lleva 10 meses usando Claude Code a diario. Al leer su configuración, lo primero que pensé fue: “¿Qué he estado haciendo yo todo este tiempo?”

La guía está disponible como repositorio en GitHub, y su mensaje central es claro: no se trata de tener más, sino de tener exactamente lo que necesitas.

La ventana de contexto de 200K es un mito - el número real es 70K

La ventana de 200K tokens de Claude Code es un máximo teórico. Si cargas demasiados servidores MCP y plugins, el contexto útil se reduce a unos 70K.

El enfoque de affaan:

1. Configura 14 servidores MCP, pero solo activa 5 o 6 por proyecto.
2. Mantiene menos de 80 herramientas habilitadas a la vez.

Su configuración real incluye GitHub, Supabase, Vercel, Railway, la serie de Cloudflare, ClickHouse y más - 14 servidores en total. Pero desactiva explícitamente los que no usa mediante disabledMcpServers. Desde que adopté este patrón, la calidad de las respuestas mejoró de forma notable.

Skills vs Hooks vs Subagentes - La clave es separar responsabilidades

Estos tres conceptos confunden al principio, pero la distinción importa mucho.

• Skills: Se ubican en ~/.claude/skills. Ejecutan un flujo de trabajo completo con un solo comando, como /refactor-clean.
• Hooks: Automatización basada en eventos. Formatean automáticamente con Prettier al editar archivos .ts, avisan si dejas un console.log, y más. El plugin hookify permite generar hooks mediante conversación.
• Subagentes: Se ubican en ~/.claude/agents. Roles dedicados como planner, architect, tdd-guide y security-reviewer que se encargan de tareas delegadas.

affaan coloca hooks en tres puntos de ejecución - PreToolUse, PostToolUse y Stop - automatizando el formateo, la comprobación de tipos y las auditorías de seguridad. Este patrón también fue respaldado por Boris Cherny.

mgrep y Git Worktrees: dos herramientas que lo cambian todo

Los consejos más prácticos e impactantes de la guía:

mgrep

Más preciso que ripgrep, con búsqueda web integrada. Un solo comando como /mgrep 'function handleSubmit' busca simultáneamente en archivos locales y en la web.

Git Worktrees

Cuando trabajas en varias funcionalidades a la vez, crea checkouts independientes y ejecuta Claude Code en cada uno. También puedes usar /fork para bifurcar conversaciones. Hay un debate abierto sobre si los worktrees o los clones del repositorio son mejor opción - ambos tienen ventajas e inconvenientes según tu flujo de trabajo.

Editor Zed

Construido en Rust, así que se mantiene ligero. El Agent Panel rastrea las modificaciones de archivos de Claude en tiempo real, y CMD+Shift+R ejecuta comandos personalizados al instante.

Estructura de reglas para mantener la coherencia

Modulariza ~/.claude/rules por área de responsabilidad:

• security.md - Nada de secretos en el código
• coding-style.md - Inmutabilidad, directrices de estructura de archivos
• testing.md - Flujo TDD, cobertura mínima del 80 %
• git-workflow.md - Formato de mensajes de commit
• performance.md - Criterios de selección de modelos

Añade reglas como “nunca hacer commit de console.log” aquí y aplícalas con un hook Stop que audite los cambios. Los errores desaparecen cuando la automatización los intercepta antes de que lleguen a producción.

Los principios fundamentales

affaan destila su filosofía en cinco principios:

• Trata la configuración como fine-tuning, no como arquitectura. Los ajustes pequeños y precisos superan a las reformas generales.
• La ventana de contexto es oro. Desactiva todo lo que no estés usando activamente.
• Aprovecha la ejecución en paralelo. Usa /fork y worktrees para lanzar agentes de forma concurrente.
• Automatiza el trabajo repetitivo. Los hooks eliminan los pasos manuales que te frenan.
• Limita el alcance de los subagentes. Asigna a cada agente una responsabilidad concreta y bien definida.

Configurar en exceso es contraproducente. Mantener activas solo las herramientas que realmente necesitas es lo que de verdad significa ser productivo. Para la mayoría de la gente, lo más difícil es quitar en lugar de añadir, y esta guía es un recordatorio contundente de ello.

Una nota personal: para automatización del navegador, he comprobado que agent-browser de Vercel es bastante más estable que Playwright y herramientas similares mencionadas en la guía original. La velocidad y la variedad de tareas que maneja están a otro nivel.

La configuración completa está disponible en el repositorio de GitHub de affaan. En lugar de copiarla tal cual, merece la pena entender el razonamiento detrás de cada decisión y adaptarla a tu propio flujo de trabajo. Ahí es donde está el valor real.