Guía para estructurar los archivos de instrucciones de Claude Code en los proyectos de Pampling.
Claude Code carga los archivos de instrucciones en cascada. Usamos 3 niveles, de más general a más específico:
~/.claude/CLAUDE.md ← Global (aplica a todos los proyectos)
proyecto/CLAUDE.md ← Proyecto (se commitea, compartido con el equipo)
proyecto/CLAUDE.local.md ← Local (gitignored, credenciales personales)
Cada nivel tiene un propósito claro. No mezclar contenidos entre niveles.
~/.claude/CLAUDE.md)Archivo personal de cada desarrollador. Aplica a todos los proyectos.
| Contenido | Ejemplo |
|---|---|
| Identidad y rol | "Jose, responsable de datos en Pampling" |
| Idioma | "Responder siempre en español" |
| Infraestructura general | Descripción del servidor, Coolify |
| Workflows transversales | Referencia a create_app.md |
| Credenciales generales | SSH, Coolify API token, email, Bitbucket API token |
CLAUDE.md en la raíz del repo)Se commitea al repositorio. Todo el equipo lo comparte.
| Contenido | Ejemplo |
|---|---|
| Descripción del proyecto | Qué hace, para qué sirve |
| Stack técnico | Python 3.12, FastAPI, PostgreSQL... |
| Estructura del proyecto | Árbol de directorios y archivos clave |
| Base de datos | Tablas, relaciones, funciones de acceso |
| Convenciones | Placeholders SQL, estilo de commits, ramas |
| Conceptos de negocio | Vocabulario del dominio (codalm, codart...) |
| Deploy | Cómo desplegar (sin tokens, usar <COOLIFY_TOKEN>) |
| Desarrollo local | Cómo arrancar el proyecto |
| Agentes | Especialización para trabajo en paralelo |
Definir los agentes especializados que Claude debe usar al trabajar en tareas complejas. Cada agente tiene un foco y trabaja en paralelo con los demás:
## Agentes
- **Backend/API**: Rutas, lógica de negocio, acceso a datos
- **Frontend**: HTML, JS, CSS, interacciones, gráficas
- **SQL/Datos**: Queries, esquema BD, ETL, optimización
- **Infra/Deploy**: Coolify, Docker, despliegues, configuración
Adaptar los agentes a las necesidades de cada proyecto.
CLAUDE.local.md en la raíz del repo)No se commitea. Cada desarrollador tiene el suyo. Debe estar en .gitignore.
| Contenido | Ejemplo |
|---|---|
| Connection strings con password | postgresql://user:pass@host/db |
| API keys propias del proyecto | Keys de servicios externos |
| Configuración local específica | Rutas locales, puertos de desarrollo |
Al clonar un repo, crear CLAUDE.local.md con las credenciales del proyecto. Pedir los valores al responsable del proyecto o consultar el gestor de credenciales.
No duplicar información. Si algo está en create_app.md (UUIDs de infra, constantes de Coolify), no repetirlo en el CLAUDE.md global.
Credenciales con secretos siempre en .local.md. Las connection strings, API keys con password, y tokens de proyecto van en el archivo local, nunca en el commiteable.
Tokens placeholder en el proyecto. En el CLAUDE.md del repo, usar <COOLIFY_TOKEN> y similares. El valor real viene del CLAUDE.md global o del .local.md.
Mantener actualizado. Si cambia el stack, la estructura o las convenciones, actualizar el CLAUDE.md del proyecto. Archivos desactualizados generan más problemas que no tener archivo.
.gitignore obligatorio. Todo repo debe incluir CLAUDE.local.md en su .gitignore.
~/.claude/CLAUDE.md → Quién soy, idioma, infra, credenciales generales
│
├── repo-A/
│ ├── CLAUDE.md → Stack, estructura, BD, convenciones, agentes
│ └── CLAUDE.local.md → Connection string, API keys (gitignored)
│
└── repo-B/
├── CLAUDE.md → Stack, estructura, BD, convenciones, agentes
└── CLAUDE.local.md → Connection string, API keys (gitignored)