Comunidad · Recurso

Plantilla de proyecto en Claude Code

Cómo dejar un proyecto listo para trabajar con Claude Code: CLAUDE.md, agentes, skills, comandos, hooks, MCP y memoria. Copia cada bloque y adáptalo a lo tuyo.

1 · Estructura del proyecto

raíz del repositorio

Claude Code lee esta estructura al abrir el proyecto. Casi todo vive en la carpeta .claude/ más un CLAUDE.md en la raíz. Empieza por aquí.

mi-proyecto/
├─ CLAUDE.md                 # memoria del proyecto (reglas, contexto)
├─ .mcp.json                 # servidores MCP del proyecto
└─ .claude/
   ├─ settings.json          # config compartida (hooks, permisos)
   ├─ agents/                # subagentes
   │  └─ revisor.md
   ├─ skills/                # skills (capacidades)
   │  └─ deploy/SKILL.md
   └─ commands/              # comandos /slash
      └─ pr.md

2 · CLAUDE.md — la memoria

CLAUDE.md

Es lo primero que Claude lee en cada sesión. Pon aquí las reglas del proyecto, los comandos que más usas, el estilo y lo que NO debe hacer. Corto y concreto.

# Proyecto: <nombre>

## Comandos
- Instalar: `npm install`
- Dev: `npm run dev`
- Test: `npm test`

## Reglas
- Usa TypeScript estricto.
- No toques /legacy sin avisar.
- Commits en español, en imperativo.

## Contexto
- Backend en Supabase.
- Deploy automático en Vercel al hacer push a main.

3 · Subagentes

.claude/agents/revisor.md

Un subagente es un Claude especializado, con su propio prompt y sus herramientas. Ideal para tareas repetibles (revisar código, investigar). Se invoca solo o cuando lo pides.

---
name: revisor
description: Revisa el código en busca de bugs y malas prácticas. Úsalo al terminar una función.
tools: Read, Grep, Bash
---

Eres un revisor de código senior. Señala solo problemas reales:
bugs, seguridad y complejidad innecesaria. Sé breve y directo.
Formato: `archivo:línea — problema → arreglo`.

4 · Skills

.claude/skills/deploy/SKILL.md

Una skill empaqueta instrucciones para una tarea concreta (desplegar, generar un reporte). Claude la carga sola cuando aplica, según su description.

---
name: deploy
description: Despliega el proyecto a producción. Úsala cuando pidan "deploy" o "subir a prod".
---

# Pasos de deploy
1. `npm run build` — si falla, detente y reporta.
2. `npm test` — todos deben pasar.
3. `vercel --prod`.
4. Verifica que la URL responda 200.

5 · Comandos /slash

.claude/commands/pr.md

Un comando /slash es un prompt reutilizable. Escribes /pr y Claude ejecuta esas instrucciones. Perfecto para flujos que repites siempre igual.

---
description: Crea un pull request con resumen de los cambios.
---
Revisa el diff con `git diff main`, escribe un título claro
y un cuerpo con: qué cambió, por qué y cómo probarlo.
Luego crea el PR con `gh pr create`.

6 · Hooks

.claude/settings.json

Los hooks ejecutan comandos tuyos automáticamente en ciertos momentos (antes o después de una herramienta, al terminar). Sirven para formatear, correr tests o bloquear acciones.

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

7 · Servidores MCP

.mcp.json

MCP conecta Claude con herramientas externas: bases de datos, APIs, un navegador. Los defines aquí y quedan disponibles como herramientas dentro del proyecto.

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase", "--project-ref=TU_REF"],
      "env": { "SUPABASE_ACCESS_TOKEN": "tu-token" }
    }
  }
}

8 · Memoria (jerarquía + imports)

CLAUDE.md

Claude combina varias memorias: la del proyecto (CLAUDE.md), la tuya personal (~/.claude/CLAUDE.md) y las que importes. Usa @ruta para incluir otros archivos y mantener el CLAUDE.md corto.

# CLAUDE.md

@./docs/estilo-codigo.md
@./docs/arquitectura.md

## Notas rápidas
- Prioriza claridad sobre soluciones "clever".
- Si algo no está en la memoria, pregúntame antes de asumir.

¿Quieres montar todo esto paso a paso, en vivo? Mira el curso completo →