Si usas agentes IA para programar — ya sea Claude Code, GitHub Copilot, OpenAI Codex o OpenCode — probablemente te has encontrado con el mismo lío: un puñado de ficheros markdown (CLAUDE.md, AGENTS.md, copilot-instructions.md…), conceptos que se solapan (skills, commands, agents, prompts, hooks…) y documentación repartida en quince sitios distintos.
El resultado: un cacao mental impresionante. ¿Dónde pongo las instrucciones del proyecto? ¿Qué fichero lee cada herramienta? ¿Puedo compartir configuración entre todas? ¿Qué es un skill? ¿Y un command? ¿Y un prompt? ¿No es lo mismo?
Esta guía lo aclara todo. Cada fichero, cada concepto, con ejemplos concretos de qué poner y qué NO poner. Sin teoría de más, sin repetir lo que el modelo ya sabe hacer solo.
Agárrate, que esto es largo. Pero cuando termines, no volverás a confundirte.
📊 Las 4 herramientas de un vistazo
Antes de meternos en ficheros, situemos a los protagonistas:
| Claude Code | GitHub Copilot | OpenAI Codex | OpenCode | |
|---|---|---|---|---|
| Creador | Anthropic | GitHub/Microsoft | OpenAI | SST (open source) |
| Modelo base | Claude Sonnet/Opus | GPT-4o / Claude / Gemini | codex-1 (o3-based) | Cualquiera (configurable) |
| Ejecución | Terminal / VS Code / JetBrains / Web | VS Code / JetBrains / CLI | Sandbox en la nube | Terminal (TUI) |
| Open Source | No (código visible) | No | No | Sí (MIT) |
| Precio | Suscripción Claude / API | Copilot Pro+ / Business | API de OpenAI | Gratis + tu API key |
| Fichero principal | CLAUDE.md | copilot-instructions.md | AGENTS.md | AGENTS.md |
1️⃣ AGENTS.md — El fichero universal
Quién lo lee: Copilot, Codex, OpenCode, Cursor y (probablemente) cualquier herramienta nueva que aparezca. Claude Code no lo lee de forma nativa, pero OpenCode sí lee CLAUDE.md como fallback.
Dónde va: En la raíz de tu repositorio. En monorepos, puedes tener uno por subdirectorio.
Para qué sirve: Instrucciones de proyecto compartidas entre herramientas. Estructura del código, convenciones, reglas de estilo, flujo de trabajo del equipo.
✅ Buen ejemplo de AGENTS.md
# Mi Proyecto SaaS
## Estructura
- `packages/api/` — Backend en Go con Chi router
- `packages/web/` — Frontend en Next.js 15 con App Router
- `packages/shared/` — Tipos TypeScript compartidos
- `infra/` — Infraestructura con SST v3
## Convenciones de código
- TypeScript strict mode siempre
- Imports con alias `@/` para rutas internas
- Tests con Vitest, mínimo 80% cobertura en packages/api
- Commits en formato Conventional Commits
## Comandos útiles
- `bun test` — ejecutar tests
- `bun run dev` — arrancar entorno de desarrollo
- `bun run lint` — linter + format check
## Flujo de trabajo
- Nunca hagas push a main directamente
- Crea un PR con descripción clara
- Los cambios de API necesitan actualizar los tipos en packages/shared❌ Mal ejemplo de AGENTS.md
# Instrucciones
Eres un desarrollador senior con 20 años de experiencia.
Siempre escribe código limpio y eficiente.
Usa mejores prácticas de programación.
Piensa paso a paso antes de responder.
Sé conciso pero exhaustivo.¿Por qué es malo? Porque no dice nada específico de tu proyecto. El modelo ya sabe programar. No necesita que le digas que sea “senior” o que “piense paso a paso” — eso es ruido puro que gasta tokens sin aportar contexto útil.
2️⃣ CLAUDE.md — El específico de Claude Code
Quién lo lee: Solo Claude Code (y OpenCode como fallback si no hay AGENTS.md).
Dónde va: En la raíz del proyecto (./CLAUDE.md o ./.claude/CLAUDE.md).
Claude Code tiene una jerarquía de ficheros que merece la pena entender:
| Nivel | Ubicación | Propósito | Compartido con |
|---|---|---|---|
| Managed Policy | /etc/claude-code/CLAUDE.md (Linux) | Políticas de empresa | Todos los usuarios |
| Proyecto | ./CLAUDE.md o .claude/CLAUDE.md | Instrucciones del equipo | Equipo (via git) |
| Personal global | ~/.claude/CLAUDE.md | Tus preferencias | Solo tú |
| Personal local | ./CLAUDE.local.md | Config personal por proyecto | Solo tú (no se commitea) |
Además, Claude Code soporta reglas por path en .claude/rules/ con frontmatter YAML:
# .claude/rules/api-endpoints.md
---
paths:
- "src/api/**/*.ts"
---
# Reglas para endpoints de API
- Toda endpoint debe validar input con Zod
- Usar el formato estándar de error del proyecto
- Incluir comentarios OpenAPI
- Rate limiting obligatorio en endpoints públicosCLAUDE.md también puede importar otros ficheros con la sintaxis @ruta/fichero:
# CLAUDE.md
Ver @README.md para visión general del proyecto.
Comandos disponibles en @package.json.
Guía de git: @docs/git-workflow.md✅ Buen ejemplo de CLAUDE.md
# Proyecto: API de Pagos
## Build y test
- `npm run build` — compilar TypeScript
- `npm test` — ejecutar Vitest
- `npm run test:e2e` — tests end-to-end (requiere Docker)
## Arquitectura
- Clean Architecture: domain → application → infrastructure
- Los handlers de API están en src/infrastructure/http/
- La lógica de negocio NUNCA importa de infrastructure/
## Reglas inquebrantables
- NUNCA hardcodear secretos. Siempre usar variables de entorno.
- Los migrations de DB van en src/infrastructure/db/migrations/
- Cada PR debe incluir tests para el código nuevo
## Contexto importante
- Estamos migrando de Express a Hono (en progreso)
- El módulo de facturación (src/domain/billing/) está legacy, no tocar sin consultar❌ Mal ejemplo de CLAUDE.md
# Instrucciones para Claude
- Responde siempre en español
- Usa TypeScript
- Escribe tests
- Sigue las mejores prácticas
- Sé profesionalOtra vez: nada concreto. ¿TypeScript con qué config? ¿Tests con qué framework? ¿Qué mejores prácticas? El modelo no puede adivinar las decisiones de tu equipo.
Pro tip: Mantén tu CLAUDE.md por debajo de ~200 líneas. Si necesitas más, usa .claude/rules/ para dividir por área. Los ficheros más cortos y concretos se siguen mejor.
3️⃣ copilot-instructions.md — El específico de Copilot
Quién lo lee: Solo GitHub Copilot (en VS Code y CLI).
Dónde va: .github/copilot-instructions.md — instrucciones globales del proyecto.
Copilot tiene algo especial que los demás no tienen: instrucciones dirigidas por patrón. Puedes crear ficheros .github/instructions/*.instructions.md con un campo applyTo en el frontmatter que activa la instrucción solo para ciertos ficheros:
# .github/instructions/react-components.instructions.md
---
applyTo: "src/components/**/*.tsx"
---
# Reglas para componentes React
- Usar functional components con hooks, nunca clases
- Props tipadas con interface, no type alias
- Cada componente en su propio directorio con index.ts barrel
- Tests con React Testing Library en fichero .test.tsx adyacente
- Nunca usar any — tipar todo explícitamente# .github/instructions/terraform.instructions.md
---
applyTo: "infra/**/*.tf"
---
# Reglas para Terraform
- Usar módulos del registry corporativo cuando existan
- Tags obligatorios: environment, team, cost-center
- Nunca IP pública sin justificación documentada
- Backend en S3 con DynamoDB lockEsto es muy potente para monorepos donde el frontend y el backend tienen reglas completamente distintas. Claude Code consigue algo parecido con .claude/rules/ y el campo paths:, pero la aproximación de Copilot es más explícita.
Prioridad en Copilot: Personal (usuario) > Repositorio > Organización. Si hay conflicto, gana lo más específico.
4️⃣ Skills — Capacidades reutilizables
Las skills son paquetes de instrucciones con contexto que el agente descubre y carga bajo demanda. No se inyectan siempre — solo cuando son relevantes para la tarea actual. Esto las hace ideales para workflows específicos que no quieres contaminando el contexto general.
| Claude Code | Copilot | OpenCode | |
|---|---|---|---|
| Ubicación proyecto | .claude/skills/*/SKILL.md | .github/skills/*/SKILL.md | .opencode/skills/*/SKILL.md |
| Ubicación global | ~/.claude/skills/*/SKILL.md | ~/.copilot/skills/*/SKILL.md | ~/.config/opencode/skills/*/SKILL.md |
| Descubrimiento | Auto por nombre/descripción | Progresivo (nombre → descripción → contenido) | Via herramienta skill() |
| Puede incluir ficheros extra | Sí | Sí (scripts, templates) | Solo el SKILL.md |
✅ Buen ejemplo de skill
# .claude/skills/create-api-endpoint/SKILL.md
---
name: create-api-endpoint
description: Scaffold a new REST API endpoint following project conventions
---
## Qué hago
Creo un nuevo endpoint de API siguiendo la estructura del proyecto:
1. Handler en `src/api/handlers/{recurso}.ts`
2. Schema de validación Zod en `src/api/schemas/{recurso}.ts`
3. Test en `src/api/__tests__/{recurso}.test.ts`
4. Registro de ruta en `src/api/router.ts`
## Convenciones
- Usar el error handler estándar de `src/api/middleware/error.ts`
- Validar input con Zod, nunca manualmente
- Response con el wrapper de `src/api/utils/response.ts`
- Tests: happy path + al menos 2 error cases
## Ejemplo de uso
"Crea un endpoint POST /api/invoices que reciba amount, customer_id y due_date"❌ Mal ejemplo de skill (el clásico)
# .claude/skills/senior-developer/SKILL.md
---
name: senior-developer
description: Act as a senior developer
---
Eres un desarrollador senior con amplia experiencia.
Escribe código limpio, eficiente y bien documentado.
Sigue los principios SOLID y DRY.
Piensa antes de actuar.
Revisa tu código antes de entregarlo.🤦 Esto es el equivalente técnico de decirle a un chef “cocina bien”. Las skills son para workflows concretos con pasos específicos de tu proyecto, no para inyectar personalidad genérica. Un skill así gasta tokens diciendo lo que el modelo ya hace por defecto.
5️⃣ Commands y Prompts — Atajos invocables
Los commands (Claude Code) y prompts (Copilot) son plantillas de prompt reutilizables que invocas manualmente. Piensa en ellos como aliases de bash, pero para tu agente IA.
| Claude Code | Copilot | |
|---|---|---|
| Ubicación | .claude/commands/*.md | .github/prompts/*.prompt.md |
| Invocación | /nombre-del-command | /nombre-del-prompt |
| Variables | $ARGUMENTS | ${selection}, ${file}, ${input:nombre} |
| Frontmatter | No | Sí (agent, tools, model, description) |
Ejemplo: Command de Claude Code
# .claude/commands/review-pr.md
Revisa los cambios del PR actual:
1. Ejecuta `git diff main...HEAD` para ver los cambios
2. Busca: bugs potenciales, falta de tests, violaciones de estilo
3. Verifica que no haya secretos hardcodeados
4. Genera un resumen con formato:
- ✅ Lo que está bien
- ⚠️ Sugerencias
- ❌ Problemas que bloquean el merge
Si el argumento es un path específico: $ARGUMENTSEjemplo: Prompt de Copilot
# .github/prompts/security-review.prompt.md
---
description: "Revisa seguridad del fichero actual"
agent: copilot
tools:
- terminal
---
Analiza ${file} buscando:
- Inyecciones SQL o XSS
- Secretos hardcodeados
- Permisos excesivos
- Dependencias con vulnerabilidades conocidas
Genera un informe con severidad (alta/media/baja) para cada hallazgo.¿Command/Prompt vs Skill?
La diferencia clave: un command/prompt se invoca manualmente y se ejecuta una vez. Un skill se descubre automáticamente cuando es relevante y puede incluir recursos adicionales (scripts, templates). Usa commands para tareas puntuales (“revisa este PR”). Usa skills para workflows que el agente debería descubrir solo (“cuando vaya a crear un endpoint, que siga estas convenciones”).
6️⃣ Custom Agents — Personas especializadas
Los agentes custom son perfiles especializados con su propio prompt de sistema, modelo y permisos de herramientas. Son útiles cuando quieres que la IA adopte un rol específico con restricciones claras.
| Copilot | OpenCode | |
|---|---|---|
| Ubicación | .github/agents/*.agent.md | .opencode/agents/*.md |
| Ubicación global | — | ~/.config/opencode/agents/ |
| Frontmatter | YAML (tools, model, handoffs) | YAML (mode, model, tools, temperature) |
| Handoffs (encadenar agentes) | Sí | No nativo |
Ejemplo: Agente Copilot
# .github/agents/security-auditor.agent.md
---
description: "Auditor de seguridad read-only"
tools:
- codeSearch
- fileRead
- terminal
handoffs:
- implementer
---
Eres un auditor de seguridad. Tu trabajo:
1. Analizar código buscando vulnerabilidades
2. Clasificar por severidad (CRITICAL, HIGH, MEDIUM, LOW)
3. Proponer fixes específicos
4. NUNCA modificar ficheros directamente
Cuando termines el análisis, handoff al agente "implementer"
para que aplique los fixes aprobados.Ejemplo: Agente OpenCode
# .opencode/agents/review.md
---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
write: false
edit: false
bash: false
---
Eres un revisor de código. Enfócate en:
- Calidad y mejores prácticas
- Bugs potenciales y edge cases
- Implicaciones de rendimiento
- Consideraciones de seguridad
Da feedback constructivo sin hacer cambios directos.OpenCode además tiene agentes built-in: Build (con todas las herramientas), Plan (solo lectura), General (subagente todoterreno) y Explore (subagente de solo lectura rápido). Puedes invocar subagentes con @nombre en el chat.
Nota: Claude Code no tiene “agentes custom” como tal — su equivalente son los Sub-agents configurables mediante el SDK.
7️⃣ Hooks — Enforcement real (solo Copilot)
Si las instrucciones son sugerencias, los hooks son leyes. Son scripts que se ejecutan en puntos específicos del workflow del agente y pueden bloquear acciones antes de que ocurran.
Ubicación: .github/hooks/*.json
Tipos de hook disponibles:
sessionStart/sessionEnd— Al iniciar o terminar sesiónuserPromptSubmitted— Cuando el usuario envía un promptpreToolUse— El más potente: antes de que el agente ejecute una herramienta, puedes aprobar o denegarpostToolUse— Después de ejecutar una herramientaagentStop/subagentStop— Cuando el agente terminaerrorOccurred— Cuando algo falla
Ejemplo: Bloquear IPs públicas en IaC
// .github/hooks/block-public-ips.json
{
"type": "preToolUse",
"tools": ["fileEdit", "fileCreate"],
"match": {
"filePattern": "infra/**/*.tf"
},
"command": "bash scripts/check-no-public-ip.sh",
"onFailure": "block",
"message": "❌ No se permiten IPs públicas en IaC sin aprobación explícita"
}Los hooks reciben JSON detallado sobre la acción del agente, así que puedes hacer validaciones sofisticadas. Las demás herramientas no tienen nada equivalente — si necesitas enforcement duro, Copilot es el que más te da.
8️⃣ MCP Servers — Conexión con el mundo exterior
MCP (Model Context Protocol) permite que tu agente se conecte a herramientas y datos externos: APIs, bases de datos, sistemas de tickets, etc. Es un estándar abierto que comparten varias herramientas.
| Herramienta | Ubicación de config MCP |
|---|---|
| Claude Code | .claude/mcp.json (proyecto) o ~/.claude/mcp.json (global) |
| Copilot (VS Code) | .vscode/mcp.json (proyecto) o user settings |
| OpenCode | opencode.json campo "mcp" |
| Codex | Config vía API / sandbox setup |
Cuándo usarlo: Cuando necesitas datos en tiempo real (issues de GitHub, estado de CI/CD, métricas de cloud, consultas a BD). Cuándo NO: Cuando la información es estática y cabe en un fichero de instrucciones.
9️⃣ Tabla Rosetta — Equivalencias entre herramientas
La tabla que necesitas para no perderte. Cada fila es un concepto, cada columna es cómo lo implementa cada herramienta:
| Concepto | Claude Code | Copilot | Codex | OpenCode |
|---|---|---|---|---|
| Instrucciones proyecto | CLAUDE.md | .github/copilot-instructions.md | AGENTS.md | AGENTS.md |
| Instrucciones globales | ~/.claude/CLAUDE.md | User settings | — | ~/.config/opencode/AGENTS.md |
| Instrucciones por path | .claude/rules/*.md con paths: | .github/instructions/*.instructions.md con applyTo: | — | Via opencode.json "instructions" |
| Fichero universal | No nativo | AGENTS.md | AGENTS.md | AGENTS.md (+ lee CLAUDE.md como fallback) |
| Skills | .claude/skills/*/SKILL.md | .github/skills/*/SKILL.md | — | .opencode/skills/*/SKILL.md |
| Commands / Prompts | .claude/commands/*.md | .github/prompts/*.prompt.md | — | — |
| Agentes custom | Sub-agents (SDK) | .github/agents/*.agent.md | — | .opencode/agents/*.md |
| Hooks / Enforcement | — | .github/hooks/*.json | — | — |
| Config MCP | .claude/mcp.json | .vscode/mcp.json | API/sandbox | opencode.json |
| Permisos herramientas | .claude/settings.json | En agent frontmatter | Sandbox policies | opencode.json permisos |
🚫 El error universal: enseñarle al modelo lo que ya sabe
Este es, con diferencia, el error más común. Y lo veo en todos los repos. Veamos ejemplos de instrucciones que son puro ruido:
# ❌ Instrucciones que NO deberías poner en ningún fichero
"Eres un desarrollador senior con 20 años de experiencia"
→ El modelo ya programa bien. No necesita un CV ficticio.
"Piensa paso a paso antes de responder"
→ Los modelos modernos ya lo hacen. Esto era útil en GPT-3.5, en 2024 ya no.
"Escribe código limpio y bien documentado"
→ ¿Según qué estándar? Sin especificar, es ruido.
"Usa mejores prácticas"
→ ¿De quién? ¿Las de Google? ¿Las de tu empresa? Sé concreto.
"Sé conciso pero exhaustivo"
→ Contradictorio y genérico. No aporta nada.
"No uses console.log en producción"
→ El modelo ya sabe esto. Tu linter también.
"Maneja los errores correctamente"
→ ¿Con try/catch? ¿Con Result types? ¿Con error boundaries? CONCRETA.
"Sigue los principios SOLID"
→ El modelo los conoce. Mejor di qué patrón específico usáis.
"Siempre escribe tests"
→ Mejor: "Escribe tests con Vitest en __tests__/, mínimo happy path + 2 error cases"La regla de oro: Si la instrucción aplica a cualquier proyecto del mundo, probablemente sobra. Tus ficheros de configuración deben contener información que el modelo no puede inferir de tu código: decisiones de arquitectura, convenciones del equipo, contexto de negocio, comandos de build, cosas en progreso.
Piénsalo así: no le dices a un nuevo miembro del equipo “programa bien”. Le dices “usamos este framework, esta estructura, estos comandos, y ojo con este módulo legacy”. Exactamente igual con tu agente.
🛠️ Setup recomendado para quien usa varias herramientas
Si usas más de una herramienta (que es lo normal), aquí va el setup paso a paso para no duplicar trabajo:
Paso 1: AGENTS.md como base universal
Crea un AGENTS.md en la raíz de tu repo con todo lo que aplica a CUALQUIER herramienta: estructura del proyecto, convenciones de código, comandos de build/test, flujo de git, contexto importante.
Paso 2: CLAUDE.md solo para lo específico de Claude
Si usas Claude Code, crea un CLAUDE.md que importe AGENTS.md y añada solo lo específico de Claude:
# CLAUDE.md
@AGENTS.md
## Específico de Claude Code
- Usa ultrathink para tareas de refactoring complejas
- Cuando diga "deploy", ejecuta `./scripts/deploy.sh` sin preguntar
- Auto-commit con formato: "feat|fix|chore: descripción corta"Paso 3: copilot-instructions.md para lo de Copilot
Si usas Copilot, puedes hacer algo similar en .github/copilot-instructions.md, aunque Copilot ya lee AGENTS.md directamente. Usa este fichero para cosas que solo aplican en VS Code o para instrucciones a nivel de organización.
Paso 4: Skills compartibles
Las skills siguen el mismo estándar en las tres herramientas que las soportan. Si pones tus skills en .claude/skills/, OpenCode las leerá también como fallback. Copilot espera .github/skills/. Para máxima compatibilidad, puedes duplicar o hacer symlinks.
Paso 5: Instrucciones globales personales
Para tus preferencias personales (idioma, estilo, herramientas preferidas), usa los ficheros globales:
- Claude Code:
~/.claude/CLAUDE.md - OpenCode:
~/.config/opencode/AGENTS.md - Copilot: Settings de usuario en VS Code
Paso 6: .gitignore
Añade a tu .gitignore los ficheros personales que no deben commitearse:
# .gitignore
CLAUDE.local.md
.claude/settings.local.json📁 Estructura final de ficheros recomendada
Para un proyecto que use múltiples herramientas, tu repo debería verse así:
mi-proyecto/
├── AGENTS.md # Universal (Copilot, Codex, OpenCode, Cursor)
├── CLAUDE.md # Claude Code (importa @AGENTS.md)
├── CLAUDE.local.md # Personal (no se commitea)
├── .claude/
│ ├── settings.json # Permisos de herramientas
│ ├── mcp.json # Servidores MCP
│ ├── commands/
│ │ ├── review-pr.md # /review-pr
│ │ └── create-migration.md # /create-migration
│ ├── skills/
│ │ └── create-api-endpoint/
│ │ └── SKILL.md
│ └── rules/
│ ├── api-endpoints.md # paths: src/api/**
│ └── frontend-components.md # paths: src/components/**
├── .github/
│ ├── copilot-instructions.md # Copilot global
│ ├── instructions/
│ │ ├── react.instructions.md # applyTo: *.tsx
│ │ └── terraform.instructions.md # applyTo: *.tf
│ ├── prompts/
│ │ └── security-review.prompt.md # /security-review
│ ├── agents/
│ │ └── security-auditor.agent.md
│ ├── hooks/
│ │ └── block-public-ips.json
│ └── skills/
│ └── incident-triage/
│ └── SKILL.md
├── .opencode/
│ ├── agents/
│ │ └── review.md
│ └── skills/
│ └── git-release/
│ └── SKILL.md
├── .vscode/
│ └── mcp.json # MCP para Copilot
└── opencode.json # Config OpenCodeSí, son muchos ficheros. Pero cada uno tiene un propósito claro. Y la mayoría no los necesitas todos — empieza con AGENTS.md y ve añadiendo según necesites.
🎯 Checklist rápido: ¿Qué fichero necesito?
| Quiero… | Usa esto |
|---|---|
| Instrucciones del proyecto para todos los agentes | AGENTS.md |
| Instrucciones solo para Claude Code | CLAUDE.md |
| Instrucciones solo para Copilot | .github/copilot-instructions.md |
| Reglas distintas por tipo de fichero | .instructions.md (Copilot) o .claude/rules/ (Claude) |
| Un workflow reutilizable auto-descubrible | Skill (SKILL.md en la herramienta que uses) |
| Un atajo que invoco manualmente | Command (Claude) o Prompt (Copilot) |
| Un rol especializado con permisos limitados | Custom Agent (.agent.md o .opencode/agents/) |
| Bloquear acciones del agente (enforcement) | Hook (solo Copilot) |
| Conectar con APIs o datos externos | MCP Server |
| Mis preferencias personales (no compartidas) | Fichero global de tu herramienta |
📝 Nota final
Esta guía nació de la confusión real configurando estos agentes. De mirar 5 documentaciones distintas, leer 10 posts, montar ficheros que no hacían nada, y lentamente ir entendiendo qué va dónde y por qué.
Si te ha servido para aclarar el lío, misión cumplida. Si ves algo que falta o ha cambiado (estas herramientas evolucionan rápido), déjame un comentario.
Y recuerda: empieza simple. Un buen AGENTS.md de 30 líneas vale más que 15 ficheros de configuración vacíos de contenido real. Añade complejidad solo cuando la necesites.
¡A configurar agentes sin perder la cabeza! 🚀