Guía para estructurar los ficheros de instrucciones de tu asistente IA (Claude Code y Codex) en los proyectos de Pampling.
Tanto Claude Code como Codex cargan los archivos de instrucciones en cascada. Usamos 3 niveles, de más general a más específico:
| Nivel | Claude Code | Codex |
|---|---|---|
| Global (todos los proyectos) | ~/.claude/CLAUDE.md |
~/.codex/AGENTS.md |
| Proyecto (commiteado) | CLAUDE.md en raíz |
AGENTS.md en raíz |
| Local (gitignored) | CLAUDE.local.md |
AGENTS.local.md o .env |
Cada nivel tiene un propósito claro. No mezclar contenidos entre niveles.
Si trabajáis con ambas herramientas en un mismo repo, generad los dos ficheros de proyecto (
CLAUDE.mdyAGENTS.md). El contenido es similar pero cada herramienta usa el suyo.
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, Bitbucket workspace |
| Criterio de trabajo | Reglas de comportamiento (no commitear secrets, confirmar acciones irreversibles, etc.) |
| Workflows transversales | Referencia a create_app.md o equivalente |
| Credenciales generales | Token de Coolify, email + token de Bitbucket |
Se commitea al repositorio. Todo el equipo lo comparte.
| Herramienta | Ruta |
|---|---|
| Claude Code | CLAUDE.md en la raíz del repo |
| Codex | AGENTS.md en la raíz del repo |
| 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 |
| Comandos | Instalar, desarrollo, tests, build, deploy |
| Convenciones | Placeholders SQL, estilo de commits, ramas |
| Conceptos de negocio | Vocabulario del dominio |
| Variables de entorno | Lista de variables necesarias sin valores |
| Deploy | Cómo desplegar (sin tokens, usar <COOLIFY_TOKEN>) |
| Agentes / sub-tareas | Especialización para trabajo en paralelo |
| Checklist antes de deploy | Tests, build, variables revisadas |
AGENTS.md de proyecto# AGENTS.md — NOMBRE-APP
## Contexto
NOMBRE-APP es una aplicación de Pampling para [descripción breve].
## Stack
- Lenguaje/framework:
- Base de datos:
- Deploy:
- Dominio:
## Comandos
- Instalar:
- Desarrollo local:
- Tests:
- Lint:
- Build:
- Deploy:
## Infraestructura
- Bitbucket repo:
- Proyecto Bitbucket:
- Coolify app UUID:
- Coolify project:
- URL producción:
- DB UUID:
## Variables de entorno
**No incluir valores secretos.** Solo nombres.
Variables necesarias:
- DATABASE_URL
- ...
Los valores locales viven en `.env` o en `AGENTS.local.md` (gitignored).
## Reglas para Codex
- No modificar infraestructura sin explicar el plan.
- No crear una base de datos nueva si ya existe una conexión documentada.
- No sobrescribir configuraciones de Vercel/Coolify sin confirmar.
- Antes de deploy, ejecutar los checks definidos en este archivo.
## Checklist antes de entregar
- Tests ejecutados o motivo si no se han podido ejecutar.
- Build verificado si aplica.
- Variables de entorno revisadas.
- Deploy verificado en URL final.
Para Claude Code, definir los agentes especializados que 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.
No se commitea. Cada desarrollador tiene el suyo. Debe estar en .gitignore.
| Herramienta | Ruta |
|---|---|
| Claude Code | CLAUDE.local.md |
| Codex | AGENTS.local.md o .env |
| Genérico | .env (cualquier framework) |
| 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 el fichero local con las credenciales del proyecto. Pedir los valores al responsable 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 fichero global.
Credenciales con secretos siempre en local. Las connection strings, API keys con password y tokens van en el fichero local, nunca en el commiteable.
Tokens placeholder en el proyecto. En el fichero de proyecto usar <COOLIFY_TOKEN> y similares. El valor real viene del fichero global o del local.
Mantener actualizado. Si cambia el stack, la estructura o las convenciones, actualizar el fichero de proyecto. Archivos desactualizados generan más problemas que no tener archivo.
.gitignore obligatorio. Todo repo debe incluir CLAUDE.local.md, AGENTS.local.md y .env en su .gitignore.
~/.claude/CLAUDE.md → Quién soy, idioma, infra, credenciales (Claude Code)
~/.codex/AGENTS.md → Quién soy, idioma, infra, credenciales (Codex)
│
├── repo-A/
│ ├── CLAUDE.md → Stack, estructura, BD, convenciones, agentes
│ ├── AGENTS.md → Lo mismo pero para Codex
│ ├── CLAUDE.local.md → Credenciales (gitignored)
│ └── .env → Variables locales (gitignored)
│
└── repo-B/
├── CLAUDE.md → ...
├── AGENTS.md → ...
└── .env → ...