Bienvenido

1. CLAUDE.md: dale contexto permanente a tu proyecto#

El fichero más infrautilizado de Claude Code. Si lo pones en la raíz del proyecto, Claude lo lee automáticamente al inicio de cada sesión. Es tu forma de decirle “esto es lo que estás construyendo, así funciona, esto no toques”.

1
# Mi Proyecto
2

3
## Stack
4
- Astro 5 + Svelte + TypeScript
5
- Stylus para CSS (NO uses Tailwind)
6
- pnpm como gestor de paquetes
7

8
## Convenciones
9
- Los componentes van en `src/components/`
10
- Los estilos globales en `src/styles/global.styl`
11
- Commits en inglés, mensajes descriptivos
12

13
## Lo que NO debes hacer
14
- No instales dependencias sin preguntarme
15
- No toques `src/content/spec/` sin confirmar
16
- No hagas commits directamente a `main`

Cuanto más específico seas, menos correcciones tendrás que hacer. Un buen CLAUDE.md ahorra el 30% de los vaivenes de instrucciones repetidas.

TIP

Puedes usar el comando /init para crear un CLAUDE.md básico en el proyecto en base a lo que ya existe.

TIP

Puedes tener varios CLAUDE.md anidados: uno en la raíz del repo con las reglas generales, y otro dentro de una subcarpeta con instrucciones específicas para ese módulo. Claude los combina automáticamente.

2. MCPs: conecta herramientas externas#

MCP (Model Context Protocol) es el sistema que permite a Claude Code usar herramientas externas con credenciales reales. La idea básica: en lugar de copiar y pegar resultados, Claude llama directamente a la herramienta.

Algunos MCPs que vale la pena conocer:

Playwright — Claude ejecuta y valida tests de UI de forma autónoma. Le dices “asegúrate de que el formulario de contacto funciona en móvil” y lo hace sin que toques el navegador.

Figma — Flujo diseño → código. Claude lee los tokens de diseño del archivo de Figma y los implementa directamente en el código. Útil si trabajas con un diseñador.

GitHub — Crear PRs, consultar issues, revisar comentarios sin salir del contexto de Claude.

Para configurar un MCP, añádelo al fichero de configuración de Claude Code:

1
{
2
  "mcpServers": {
3
    "playwright": {
4
      "command": "npx",
5
      "args": ["@playwright/mcp@latest"],
6
      "env": {}
7
    }
8
  }
9
}

NOTE

Los MCPs se configuran por proyecto o globalmente. Si son credenciales de trabajo (tokens de GitHub, claves de API), ponlos en el nivel de usuario, no en el repositorio para evitar commits accidentales.

3. Subagentes: paralelismo real#

Esto cambia cómo piensas el trabajo con Claude Code. En lugar de una tarea larga y secuencial, puedes dividir el trabajo entre varios agentes que corren en paralelo usando git worktrees.

El concepto:

1
# Creas un worktree separado para cada rama de trabajo
2
git worktree add ../proyecto-feature-auth feature/auth
3
git worktree add ../proyecto-refactor-css refactor/css-tokens
4

5
# Lanzas un agente en cada uno
6
cd ../proyecto-feature-auth && claude "implementa el sistema de auth con JWT"
7
cd ../proyecto-refactor-css && claude "refactoriza todos los tokens de color al nuevo sistema"

Mientras el agente A trabaja en autenticación, el agente B está refactorizando estilos. Cuando terminan, haces merge. El tiempo de un refactor que afecta a cuatro módulos distintos pasa de ser secuencial a casi paralelo.

El Agent SDK (Python/TypeScript) te da control más fino sobre esto si quieres orquestar desde código:

1
import anthropic
2

3
client = anthropic.Anthropic()
4

5
# Lanza múltiples tareas de forma programática
6
tasks = [
7
    "Refactoriza el módulo de autenticación",
8
    "Añade tests unitarios al módulo de pagos",
9
    "Documenta la API pública del módulo de usuarios"
10
]
11

12
for task in tasks:
13
    # Cada uno corre en su propio worktree/contexto
14
    result = client.messages.create(
15
        model="claude-opus-4-5",
16
        max_tokens=8096,
17
        messages=[{"role": "user", "content": task}]
18
    )

4. El plugin de VS Code (y por qué importa)#

Si tu flujo de trabajo no es 100% terminal, el plugin oficial de VS Code cambia bastante la experiencia. Lo que añade respecto a la CLI pura:

• Diffs inline: ves qué cambió directamente en el editor, con la misma interfaz de git diff que ya conoces
• Context sharing: Claude ve qué archivo tienes abierto y en qué línea está el cursor, sin que se lo digas
• Aceptar/rechazar cambios con un clic, por bloque o por fichero

Instalación:

1
# Desde la terminal de VS Code o el marketplace
2
code --install-extension anthropic.claude-code

El plugin de JetBrains funciona igual de bien si tu editor principal es IntelliJ, WebStorm o similar. Ambos muestran el diff interactivo antes de aplicar cambios.

5. Gestiona el contexto en sesiones largas#

Este es el mayor punto ciego cuando empiezas: el contexto tiene límite. Cuando una sesión larga empieza a perder precisión en las últimas instrucciones, es síntoma de que el contexto se saturó.

Estrategias que funcionan:

Sesiones cortas y orientadas. En lugar de una sesión de dos horas, varias sesiones de 30 minutos con objetivos claros. “Sesión 1: refactoriza los componentes de navegación. Sesión 2: adapta los estilos al nuevo sistema de tokens.”

Usa /compact cuando el contexto empiece a crecer. Es el comando que resume la conversación manteniendo el contexto esencial.

Puntos de control. Al final de cada sesión, pídele a Claude que resuma qué hizo y qué queda pendiente. Guarda ese resumen en el CLAUDE.md como sección de “Estado actual del proyecto” y bórrala cuando ya no la necesites.

1
# Al final de una sesión larga
2
claude "Resume qué cambios hemos hecho hoy y qué tareas quedan pendientes, \
3
en formato bullet points para pegar en CLAUDE.md"

6. /security-review antes de cualquier commit importante#

Claude Code tiene un comando específico para revisar el código generado desde el punto de vista de seguridad:

1
/security-review

Analiza el código de la sesión actual buscando vulnerabilidades comunes: inyecciones, secretos hardcodeados, dependencias con CVEs conocidos, permisos excesivos. No es infalible, pero es una capa más antes del git push.

El 48% del código generado por IA en general contiene algún tipo de vulnerabilidad según estudios del sector. /security-review no cuesta nada y puede evitar un incidente.

7. Modos de operación: cuándo usar cuál#

Claude Code tiene dos modos principales de trabajo:

Modo interactivo (el por defecto) — Pregunta antes de actuar en decisiones importantes. Ideal para desarrollo activo donde quieres mantener el control.

Modo no interactivo / headless — Para pipelines CI/CD y scripts automatizados:

1
# Sin interfaz interactiva, ideal para CI
2
claude --headless "ejecuta los tests y corrije los que fallen, sin preguntar"
3

4
# Con aprobación automática de acciones seguras
5
claude --auto-approve-safe "refactoriza según el estilo del proyecto"

Úsalo para tareas repetitivas: generar documentación, actualizar dependencias, ejecutar suites de tests y reparar los que fallen.

8. Pídale que explique, no solo que cambie#

El error más común con Claude Code es usarlo como una caja negra que genera código. Cuando algo falla o no entiendes por qué tomó una decisión, pregunta:

1
¿Por qué pusiste el @import de Google Fonts aquí y no antes del CSS local?
2
¿Qué consecuencias tendría hacer X en lugar de Y?
3
Explícame qué hace este componente antes de modificarlo.

La diferencia entre usarlo como autocomplete inteligente y como colega que razona es cómo preguntas. Cuanto más hagas que explique su razonamiento, más entiendes el código que genera y mejor puedes detectar cuando se equivoca.

El post anterior tenía razón en algo: no es magia. Pero con estos ocho puntos aplicados, empieza a parecerse bastante.