Claude Code: cómo configurarlo para que entienda tu proyecto en 15 minutos

Claude Code es la CLI de Anthropic que convierte a Claude en un colaborador dentro de tu terminal. La diferencia entre usarlo sin configurar y con configuración es enorme: de "autocompletado glorificado" pasa a "un colega junior que entiende el proyecto y hace PRs decentes".

Este post te muestra las 4 piezas que valen la pena configurar.

CLAUDE.md: la memoria del proyecto

Lo primero y más importante. Crea un archivo CLAUDE.md en la raíz del repo con la información que cualquier dev nuevo necesitaría saber:

# Mi Proyecto

## Stack
- Next.js 16 App Router + TypeScript
- PostgreSQL + Prisma
- Redis + BullMQ para jobs

## Convenciones
- Componentes React en PascalCase, archivos en kebab-case
- Tests con Vitest, no con Jest
- Preferimos tipos explícitos sobre `any`

## Arquitectura
- `app/` — rutas Next.js
- `lib/` — lógica pura, sin React
- `components/` — UI reutilizable

## Qué NO hacer
- No usar `fetch()` directo en componentes: usar `lib/api-client.ts`
- No agregar dependencias sin aprobación

Claude lee este archivo en cada conversación. Resultado: no te propone cosas que contradicen tus convenciones.

Truco: también puedes crear un CLAUDE.md por subdirectorio. El del directorio es más específico que el del root.

Agentes personalizados: especialistas por tarea

Claude Code permite crear "agentes" que son sub-Claudes con un prompt específico y herramientas acotadas. Ejemplos útiles:

• backend-coder — solo toca APIs, modelos, middleware. No diseña UI.
• frontend-developer — solo componentes, estilos, accesibilidad.
• qa-engineer — revisa código buscando bugs, edge cases y regresiones.
• software-architect — te ayuda a decidir arquitectura sin escribir código.

Se definen en archivos en .claude/agents/ con su propio prompt de sistema. Cuando le pides a Claude algo que matchea con un agente, usa ese agente en lugar del default.

Ventaja real: el prompt del agente se mantiene corto y enfocado. No tienes que explicarle "eres un experto backend" cada vez.

Hooks: automatización antes/después de cada acción

Los hooks son comandos de shell que se ejecutan en momentos específicos del ciclo de Claude:

• PreToolUse — antes de ejecutar un tool (puede bloquear la acción).
• PostToolUse — después de ejecutar un tool (ej. para formatear).
• Stop — cuando Claude termina una respuesta.
• UserPromptSubmit — cuando mandas un prompt.

Ejemplos típicos:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "prettier --write $CLAUDE_FILE_PATHS"
      }]
    }]
  }
}

Esto formatea con Prettier cada archivo que Claude edita. No tienes que pedírselo, pasa solo.

Otros hooks útiles:

• Correr linter automáticamente después de editar.
• Ejecutar tests después de cambiar archivos de lógica.
• Registrar en un log qué archivos se modificaron.

Slash commands: flujos repetitivos empaquetados

Un slash command es un prompt predefinido que invocas con /nombre. Los más útiles que uso día a día:

/review — revisa los cambios no-comiteados buscando bugs, edge cases y mejoras.

/security-review — revisa el diff buscando vulnerabilidades: inyecciones SQL, XSS, tokens expuestos, permisos de más.

/simplify — busca código que se pueda simplificar sin perder funcionalidad.

/init — genera el CLAUDE.md inicial a partir de tu código.

Creas los tuyos en .claude/commands/. Son archivos markdown con el prompt adentro. Ejemplo propio:

---
description: Genera commit message siguiendo convenciones del repo
---

Revisa los cambios staged con `git diff --staged` y genera un commit
message en español, imperativo, bajo 70 caracteres en el título.
Agrega descripción si hay más de 3 archivos cambiados.

Invocas con /commit-message.

El setting que casi nadie activa: permisos

Por defecto Claude Code te pregunta permiso antes de cada comando bash o edición. Es seguro pero agota. En .claude/settings.json puedes preaprobar comandos que usas todo el día:

{
  "permissions": {
    "allow": [
      "Bash(npm run test:*)",
      "Bash(npm run build)",
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(prettier:*)"
    ]
  }
}

Los patrones son glob. Bash(npm run test:*) permite cualquier variante de npm run test (test:unit, test:e2e, etc.) sin preguntar.

Combinando todo: un flujo real

Con las 4 piezas juntas, un día típico se ve así:

1. Le pides a Claude "agrega endpoint POST /api/usuarios con validación Zod".
2. Claude Code usa el agente backend-coder (más eficiente para este scope).
3. Al editar archivos, el hook PostToolUse corre Prettier automático.
4. Al terminar, corres /review para que revise lo que hizo.
5. Corres /security-review para chequear que no metió nada sospechoso.
6. Commit con /commit-message.

Tiempo total: 5 minutos. Sin la config: 30–40 minutos con idas y vueltas.

¿Cuándo vale la pena?

• Trabajas en el mismo proyecto al menos 2 horas por semana.
• Tu equipo tiene convenciones que quieres que Claude respete.
• Ya usas linters, formatters y tests (para engancharlos con hooks).
• Haces muchos PRs y quieres un primer pase de review automático.

En ServerStack Solutions

Usamos Claude Code como parte del stack de desarrollo interno. Cada proyecto que arrancamos trae CLAUDE.md, agentes base y los comandos /review, /security-review, /simplify configurados desde el día 1.

Contáctanos si quieres que te ayudemos a integrar Claude Code en tu flujo de desarrollo.

---

Relacionado: IA cambia el desarrollo: necesitamos arquitectos y Pipelines multi-stage automatizados.