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

Ayer un ganador de un hackathon de Anthropic compartió públicamente su guía de configuración de Claude Code, y la apliqué entera de inmediato. Me tomó todo el día, y la diferencia fue real.

La guía es de affaan (@affaanmustafa), que lleva 10 meses usando Claude Code a diario. Mientras revisaba su configuración, lo primero que pensé fue: “¿Qué he estado haciendo 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 contexto de 200K de Claude Code es un máximo teórico. Si cargas demasiados servidores MCP y plugins, el contexto utilizable baja 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 al mismo tiempo.

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 separación de roles es la clave

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

• Skills: Viven 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 cuando hay console.log, y más. El plugin hookify permite generar hooks a través de una conversación.
• Subagentes: Viven en ~/.claude/agents. Roles dedicados como planner, architect, tdd-guide y security-reviewer que se encargan de tareas delegadas.

affaan ubica los hooks en tres puntos de ejecución - PreToolUse, PostToolUse y Stop - automatizando formato, verificación de tipos y auditorías de seguridad. Este patrón también fue respaldado por Boris Cherny.

mgrep y Git Worktrees son un antes y un después

Los consejos prácticos más valiosos 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 trabajan con varias funcionalidades a la vez, creen checkouts independientes y ejecuten Claude Code en cada uno. También pueden usar /fork para ramificar conversaciones. Hay un debate abierto sobre si los worktrees o los clones del repositorio son la mejor opción - ambos tienen pros y contras dependiendo de su flujo de trabajo.

Editor Zed

Construido sobre Rust, así que se mantiene liviano. 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 consistencia

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

• security.md - Cero secretos hardcodeados
• coding-style.md - Inmutabilidad, lineamientos 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

Agreguen reglas como “nunca commitear console.log” ahí, y refuércenlas con un hook Stop que audite los cambios. Los errores desaparecen cuando la automatización los atrapa antes de que lleguen a producción.

Los principios fundamentales

affaan destila su filosofía en cinco principios:

• Traten la configuración como fine-tuning, no como arquitectura. Los ajustes pequeños y específicos le ganan a las reestructuraciones masivas.
• La ventana de contexto es un recurso valioso. Desactiven todo lo que no estén usando activamente.
• Aprovechen la ejecución en paralelo. Usen /fork y worktrees para correr agentes de forma concurrente.
• Automaticen el trabajo repetitivo. Los hooks eliminan pasos manuales que los frenan.
• Limiten el alcance de los subagentes. Denle a cada agente una responsabilidad acotada y bien definida.

La configuración excesiva es contraproducente. Mantener activas solo las herramientas que realmente necesitan es lo que se ve como productividad real. Restar es lo más difícil para la mayoría, y esta guía es un recordatorio contundente de eso.

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

La configuración completa está disponible en el repositorio de GitHub de affaan. En lugar de copiarla tal cual, entiendan el razonamiento detrás de cada decisión y adáptenla a su propio flujo de trabajo. Ahí es donde está el valor real.