AGENTS.md y CLAUDE.md: qué son y una plantilla para tu hosting

En resumen

Antes: conecta tu IA por SSH →

Lo que podrás hacer

• Un AGENTS.md con tus reglas de seguridad, listo para tu web WordPress o tu proyecto PHP.
• Un CLAUDE.md que apunta a ese mismo archivo, para no mantener dos.
• La certeza de que tu herramienta lo está leyendo.
• Una lista de lo que nunca debe escribirse en ese archivo.

Antes de empezar

• Tu IA instalada y conectada por SSH. Si aún no lo has hecho: conecta tu IA por SSH.
• Si conectaste tu IA con «Conecta tu IA», quizá ya tengas un AGENTS.md y un CLAUDE.md en la carpeta de tu web: no los sobrescribas, pídele a tu IA que añada las reglas que falten (paso 5).
• Los archivos viven en la carpeta de tu proyecto, en tu ordenador.

Abre la terminal en la carpeta de tu proyecto y arranca tu IA:

cd ~/tu-dominio.com
claude

cd ~/tu-dominio.com
codex

# Antigravity 2.0 (app de escritorio): añade ~/tu-dominio.com como proyecto en la app.
# O con su CLI agy, que usa el mismo agente:
cd ~/tu-dominio.com
agy

cd ~/tu-dominio.com
grok

cd ~/tu-dominio.com
npx @deepseek-ai/dsh web
# Se abre en tu navegador, en http://127.0.0.1:3080

Qué es AGENTS.md y por qué existe

Las IA empiezan cada sesión sin memoria. Un archivo de instrucciones es lo primero que leen: el contexto de tu proyecto y las reglas que deben respetar. Es texto normal, en Markdown, y puedes editarlo con cualquier editor.

AGENTS.md es el nombre común que casi todas las herramientas entienden. Claude Code usa CLAUDE.md y Antigravity también lee GEMINI.md. Para no mantener varios archivos iguales, usa un AGENTS.md como fuente y haz que los demás apunten a él.

Qué archivo lee cada herramienta

Estrategia recomendada: un solo AGENTS.md y un CLAUDE.md de una línea:

@AGENTS.md

Qué poner y qué no

Pon:

• El dominio, el alias SSH (ssh hc-tu-dominio.com) y dónde está tu web en el servidor.
• Las reglas de seguridad (siguiente sección).
• Los límites del hosting (sin Node.js, sin sudo).
• Decisiones del proyecto: tema, plugins, estilo, estructura.
• Cómo volver atrás.

No pongas nunca:

• Contraseñas, claves SSH privadas, tokens ni claves de API.
• El contenido de wp-config.php.
• Datos de clientes ni correos de personas.
• Nada que no quieras que lea el servicio de IA que uses: todo lo que tu IA lee viaja a su proveedor.

Cuida dónde lo guardas: no dejes AGENTS.md ni CLAUDE.md en una carpeta que subas a public_html: cualquiera podría descargarlos. Excluye esos archivos al subir con rsync (--exclude 'AGENTS.md' --exclude 'CLAUDE.md').

Reglas de seguridad que conviene tener siempre

1. Agrupa varios comandos en una sola llamada SSH; no abras muchas conexiones seguidas. El servidor puede bloquear temporalmente los inicios de sesión demasiado seguidos.
2. Nunca toques wp-config.php ni contraseñas. Si hace falta un cambio, tu IA te da las líneas y lo haces tú.
3. Haz una copia antes de cambiar. Una exportación de la base de datos y de los archivos, fuera de la carpeta pública.
4. Propón un plan y espera aprobación. Antes de escribir o ejecutar, tu IA explica qué hará y espera tu «adelante».

A estas cuatro añade: usa staging si la web tiene visitas; sin sudo (bloquea tu acceso SSH); pregunta antes de borrar, vaciar o reiniciar algo; no instales skills ni plugins sin avisar.

Pasos

1. 1

   Comprueba si ya tienes uno

   Hecho: paso 1

   Prompt: Comprueba si ya tienes unoCópialo y pégalo en tu IACopiar

   Mira si en esta carpeta existen AGENTS.md, CLAUDE.md o GEMINI.md. Si existen, léelos y dime en una lista corta qué reglas contienen. No cambies nada.

   Revisa antes de aprobar

   Tu IA solo lee archivos de esta carpeta. No ejecuta nada en el servidor.

2. 2

   Elige la estrategia de archivos

   Hecho: paso 2

   Con Claude Code

   Claude CodeComandos de este pasoCopiar

   # Crea AGENTS.md (siguiente paso) y este CLAUDE.md de una línea:
   @AGENTS.md
   # Alternativa: el comando /init de Claude Code genera un CLAUDE.md a partir de tu proyecto

   Con Codex CLI

   Codex CLIComandos de este pasoCopiar

   # Solo AGENTS.md, en la raíz del proyecto.
   # Global (para todos tus proyectos): ~/.codex/AGENTS.md

   Con Antigravity

   AntigravityComandos de este pasoCopiar

   # AGENTS.md en la raíz del proyecto (también lee GEMINI.md): la app 2.0, el IDE y la CLI.
   # En la app 2.0, ponlo en la carpeta del proyecto: no lee archivos globales.
   # Global (CLI e IDE): ~/.gemini/AGENTS.md o ~/.gemini/GEMINI.md

   Con Grok Build

   Grok BuildComandos de este pasoCopiar

   # AGENTS.md en la raíz del proyecto (también lee CLAUDE.md).
   # Al abrir Grok Build, confía en la carpeta cuando te lo pida, o no cargará el archivo.

   Con DeepSeek Harness

   DeepSeek HarnessComandos de este pasoCopiar

   # AGENTS.md en la raíz del proyecto (también lee CLAUDE.md).
   # La raíz del proyecto se marca con .git: haz `git init` si no lo tienes.

3. 3

   Copia la plantilla de WordPress

   Hecho: paso 3

   Guárdala como AGENTS.md. Cambia tu-dominio.com por tu dominio y revisa cada línea. Si tu WordPress está en un plan Linux, no tienes WP-CLI ni staging: quita esas líneas y añade en «Decisiones del proyecto» que trabajas por SSH, Git o SFTP (más ideas en Sube tu web).

   AGENTS.md (plantilla)Copiar

   # AGENTS.md: web WordPress de tu-dominio.com
   
   ## Contexto
   - Web: https://tu-dominio.com (WordPress en un plan WordPress de HostCarriel).
   - El agente corre en mi ordenador. No hay nada instalado en el servidor.
   - Conéctate con: `ssh hc-tu-dominio.com` (alias de mi ~/.ssh/config). Usuario y clave ya están configurados; no los muestres.
   - WordPress está en `public_html`. Los comandos de WordPress se hacen con WP-CLI (`wp`) desde esa carpeta.
   - Para PHP en línea de comandos usa la versión de PHP de mi web (el panel de hosting la detecta y «Conecta tu IA» la escribe aquí; si la cambio, te lo diré).
   - Staging: carpeta `staging_html`, URL `staging.tu-dominio.com`. Compruébalo siempre con `wp option get siteurl` antes de escribir.
   
   ## Reglas de seguridad (obligatorias)
   - Agrupa varios comandos en una sola llamada SSH; no abras muchas conexiones seguidas.
   - Al terminar una tarea larga, cierra la conexión compartida con `ssh -O exit hc-tu-dominio.com`.
   - Si ssh falla con «unix_listener», «ControlPath too long» o «ControlSocket», conéctate sin conexión compartida: `ssh -o ControlMaster=no -o ControlPath=none hc-tu-dominio.com`.
   - Nunca toques wp-config.php ni contraseñas. Nunca leas, muestres ni escribas contraseñas, claves ni datos de clientes. Si necesitas un cambio en wp-config.php, dame las líneas y lo hago yo.
   - Haz una copia antes de cambiar nada: exporta la base de datos con WP-CLI a una carpeta FUERA de public_html y dime la ruta.
   - Propón un plan y espera mi aprobación («adelante») antes de escribir o ejecutar cambios.
   - Si la web tiene visitas, trabaja en staging y avísame antes de pasar nada a producción.
   - Pregúntame antes de borrar, vaciar, reiniciar o reinstalar algo. Nada de `rm -rf`, `wp db reset`, `wp db drop` ni `wp site empty`.
   - Haz los cambios de uno en uno y dime cómo deshacer cada uno.
   - No instales skills ni plugins de terceros sin avisarme.
   - No uses `sudo` (en este hosting bloquea mi acceso SSH).
   
   ## Límites del hosting
   - Este plan WordPress está hecho para WordPress: no hay Node.js, Docker ni procesos permanentes.
   - No instales plugins de caché ni de copias: el hosting ya los incluye.
   - Plugins prohibidos por consumo de recursos: BackupWordPress, VersionPress, Broken Link Checker, MyReviewPlugin, LinkMan, Fuzzy SEO Booster.
   - Funciones de PHP desactivadas: exec, passthru, popen, proc_open, shell_exec, system, show_source, parse_ini_file, opcache_get_configuration, opcache_get_status.
   
   ## Cómo volver atrás
   - Copias automáticas diarias y botón «Snapshot» en el panel de hosting («Timeline Backups» → «Restore»).
   - Exportaciones de la base de datos hechas antes de cada cambio.
   - `wp plugin deactivate NOMBRE` (con `--skip-plugins --skip-themes` si WP-CLI falla).
   
   ## Decisiones del proyecto (rellenar)
   - Tema:
   - Plugins activos y para qué sirve cada uno:
   - Estilo y tono de los textos:
   - Lo que no se toca sin preguntarme:

4. 4

   Copia la plantilla de PHP (plan Linux)

   Hecho: paso 4

   AGENTS.md (plantilla)Copiar

   # AGENTS.md: proyecto PHP de tu-dominio.com
   
   ## Contexto
   - Proyecto PHP a medida en un plan Linux de HostCarriel. Las carpetas de este proyecto están en mi ordenador.
   - Conéctate con: `ssh hc-tu-dominio.com` (alias de mi ~/.ssh/config). No muestres usuario, clave ni contraseñas.
   - Estructura: `public/` es la única carpeta servida (raíz de documentos); `src/`, `config/`, `templates/` y `database/` quedan fuera.
   - En el servidor, el proyecto está en `mi-app/` y el dominio sirve `mi-app/public`.
   - PHP en línea de comandos: la versión de PHP de mi web, con la ruta completa de su binario (`/usr/bin/phpXY`, XY = versión sin punto; «Conecta tu IA» la escribe aquí). Prefiero ejecutar Composer en mi ordenador y subir `vendor/`; si lo ejecutas en el servidor, usa esa misma ruta: `/usr/bin/phpXY -f /usr/bin/composer install`.
   - Base de datos MySQL creada por mí en el panel de hosting. Variables: DB_HOST, DB_NAME, DB_USER, DB_PASS en `.env` (nunca en el código ni en Git).
   
   ## Reglas de seguridad (obligatorias)
   - Agrupa varios comandos en una sola llamada SSH; no abras muchas conexiones seguidas.
   - Al terminar una tarea larga, cierra la conexión compartida con `ssh -O exit hc-tu-dominio.com`.
   - Si ssh falla con «unix_listener», «ControlPath too long» o «ControlSocket», conéctate sin conexión compartida: `ssh -o ControlMaster=no -o ControlPath=none hc-tu-dominio.com`.
   - Nunca toques contraseñas ni el archivo `.env` del servidor. Nunca los leas, muestres ni escribas en el código, en Git ni en este archivo.
   - Haz una copia antes de cambiar: un commit de Git en mi ordenador y, antes de tocar el servidor, un «Snapshot» pedido por mí en el panel de hosting.
   - Propón un plan y espera mi aprobación («adelante») antes de escribir o ejecutar cambios.
   - Sube con rsync siempre primero en simulación (`-n`), excluyendo `.git/`, `.env`, `node_modules/` y `AGENTS.md`/`CLAUDE.md`. Nunca uses `--delete` sin que yo lo pida.
   - Pregúntame antes de borrar archivos, tablas o datos. Nada de `rm -rf`, `DROP` ni `TRUNCATE` sin aprobación.
   - Código: consultas PDO preparadas, salida escapada, tokens CSRF, `password_hash`/`password_verify`, `display_errors` desactivado y errores en un log fuera de `public/`.
   - Un commit por funcionalidad, con mensaje claro.
   - No instales skills ni plugins de terceros sin avisarme.
   - No uses `sudo` (en este hosting bloquea mi acceso SSH).
   
   ## Límites del hosting
   - No hay Node.js, Docker, procesos permanentes (Redis, colas con workers, WebSockets) ni sudo.
   - Si algo necesita compilarse (JavaScript, CSS), se hace en mi ordenador y se sube el resultado.
   - Las tareas programadas se crean en el panel de hosting («Scheduled Tasks»).
   - `mod_rewrite` y `.htaccess` están activos. El HTTPS se activa desde el panel de hosting, no desde `.htaccess`.
   
   ## Cómo volver atrás
   - Git en mi ordenador (`git revert`) y nueva subida con rsync.
   - Si cambié la raíz de documentos y falla, vuelvo a `public_html`.
   - Copias automáticas del panel de hosting («Timeline Backups» → «Restore»).
   
   ## Decisiones del proyecto (rellenar)
   - Qué hace el proyecto:
   - Librerías de Composer y para qué sirve cada una:
   - Tablas de la base de datos:
   - Lo que no se toca sin preguntarme:

5. 5

   Pídele a tu IA que lo adapte a tu proyecto

   Hecho: paso 5

   Pega el prompt y, debajo, la plantilla que corresponda. Si ya tienes un AGENTS.md, pídele que lo fusione:

   Prompt: Pídele a tu IA que lo adapte a tu proyectoCópialo y pégalo en tu IACopiar

   Crea en esta carpeta un archivo AGENTS.md para mi proyecto usando la plantilla de HostCarriel que te pego debajo.
   - Si ya existe un AGENTS.md, no lo sobrescribas: fusiónalo y enséñame las diferencias antes de guardar.
   - Rellena solo lo que ya sepas (dominio, alias SSH leyendo mi ~/.ssh/config). NO inventes el resto: pregúntame lo que falte.
   - No escribas contraseñas, claves ni tokens.
   - Después crea un CLAUDE.md con una única línea: @AGENTS.md
   Enséñame el resultado antes de guardarlo.
   
   [PEGA AQUÍ LA PLANTILLA]

   También puedes pedirle a tu IA que redacte las reglas desde cero con las cuatro reglas de seguridad de esta guía, pero una plantilla revisada es más segura que una improvisada.

   Las dos plantillas, en texto plano para descargar: AGENTS-wordpress.md y AGENTS-php.md.

   Por qué

   la plantilla te ahorra escribir las reglas desde cero y deja a tu IA que rellene lo que ya conoce sin inventarse nada.

   Revisa antes de aprobar

   El archivo se escribe en la carpeta de tu proyecto, en tu ordenador. No contiene contraseñas ni claves.

6. 6

   Comprueba que lo lee

   Hecho: paso 6

   Cierra tu IA, ábrela de nuevo en la carpeta del proyecto y pregúntale:

   Prompt: Comprueba que lo leeCópialo y pégalo en tu IACopiar

   Sin ejecutar nada, resume en una lista las reglas de seguridad que has cargado de AGENTS.md y de qué archivo salen.

   Si no menciona las reglas, no ha cargado el archivo. Mira «Problemas frecuentes».

7. 7

   Mantenlo al día

   Hecho: paso 7

   Cuando decidas algo importante (cambias de tema, añades un plugin, cambias la estructura), pídele a tu IA que lo apunte:

   Prompt: Mantenlo al díaCópialo y pégalo en tu IACopiar

   Actualiza AGENTS.md con lo que hemos decidido hoy: [QUÉ]. Solo la sección de decisiones del proyecto. No cambies las reglas de seguridad y no escribas contraseñas.

   Mantenlo corto. Un archivo largo gasta el contexto de tu IA y las reglas importantes se diluyen.

Si algo sale mal

• Tu IA ignoró una regla: repite la regla en el chat, con las mismas palabras. Un archivo de instrucciones es una guía, no un cortafuegos. Tú sigues aprobando cada comando.
• Se coló una contraseña en el archivo: cámbiala de inmediato en el panel de hosting, borra la línea y, si hiciste commit en Git, bórrala también del historial.
• El archivo se quedó en public_html: bórralo del servidor y excluye AGENTS.md y CLAUDE.md al subir con rsync.
• Quieres volver a una versión anterior del archivo: con Git, git checkout -- AGENTS.md.

Si algo te preocupa de seguridad de tu hosting, abre un ticket y te ayudamos con el hosting.

Problemas frecuentes

Tu IA no sigue mis reglas.

Comprueba que el archivo está en la carpeta donde abres tu IA. En Claude Code, si hay un CLAUDE.md sin @AGENTS.md, ignora el AGENTS.md. En Grok Build, confía en la carpeta al abrirlo. En DeepSeek Harness, la raíz la marca .git.

Mis reglas no se cargan completas.

Hay límites: 32 KiB en Codex CLI y 65.536 bytes en DeepSeek Harness. Acorta el archivo.

AGENTS.md y CLAUDE.md dicen cosas distintas.

Deja las reglas solo en AGENTS.md y haz que CLAUDE.md contenga únicamente @AGENTS.md.

Conecta tu IA ya me creó los archivos.

Úsalos como punto de partida y pide a tu IA que añada las reglas que falten (paso 5).

Codex CLI te pide aprobación en cada ssh.

Puede pasar: su sandbox trae la red cerrada. Aprueba solo ssh hacia tu servidor o activa el acceso a red.

La conexión se corta tras muchos comandos seguidos.

Es lo que evita la primera regla: pídele a tu IA que agrupe varios comandos en una sola llamada SSH y revisa la guía de conexión.

Preguntas frecuentes