Reglas de proyecto para AI Coding: AGENTS.md, CLAUDE.md, Cursor Rules y specs
Aprende cómo AGENTS.md, CLAUDE.md, Cursor Rules, MCP, specs y las puertas de verificación dividen responsabilidades, para que los agentes sigan siendo útiles sin apropiarse de tu release.
Las herramientas de AI coding se comportan mejor cuando el repositorio explica cómo debe hacerse el trabajo. Esa guía aparece como AGENTS.md, CLAUDE.md, Cursor Rules, configs de MCP, specs y puertas de verificación.
Estos archivos son instrucciones y contratos. No sustituyen la revisión humana ni un build en verde.
Respuesta directa
| Artefacto | Función principal |
|---|---|
AGENTS.md / CLAUDE.md / Cursor Rules | Dicen a los agentes las convenciones del proyecto, los límites y los comandos preferidos |
| Specs / briefs de tarea | Definen qué significa «terminado» para un cambio |
| Configs de MCP / herramientas | Controlan qué herramientas externas puede llamar un agente |
| Puertas de verificación | Demuestran el cambio con tests, builds, lint y checklists de revisión |
Usa reglas cortas y aplicables. Los ensayos largos que nadie actualiza se convierten en ruido ignorado.
Para creadores no técnicos, empieza con vibe coding sin perder el control. Para las revisiones de release, usa la checklist de flujo de trabajo.
Cuándo ayuda esta guía
- Tus agentes siguen editando las carpetas equivocadas o inventan patrones nuevos.
- El equipo no se pone de acuerdo sobre qué archivo de instrucciones es la autoridad.
- Quieres habilitar MCP sin otorgar poder ilimitado de red o de repositorio.
- Necesitas una línea clara entre «guía para el agente» y «requisitos de merge».
Explora plugins y skills relacionados en el directorio de plugins de AI Coding.
Archivos de instrucciones: límites, no magia
AGENTS.md
Se usa comúnmente como un brief de agente a nivel de repositorio: stack, estructura, comandos obligatorios, acciones prohibidas y enlaces a documentación más profunda.
Buen contenido:
- Gestor de paquetes y versión requerida de Node/Java/Python
- Cómo ejecutar tests y lint
- Carpetas que los agentes deben evitar
- Cómo nombrar PRs o commits
Mal contenido:
- Marketing copiado y pegado sobre el producto
- Secretos y URLs de producción
- Reglas contradictorias que nadie mantiene
CLAUDE.md
A menudo se usa para guía de proyecto orientada a Claude. Trátalo como AGENTS.md: mantenlo actualizado, específico y breve. Si ambos existen, indica qué archivo prevalece para las reglas compartidas, o mantenlos sincronizados de forma deliberada.
Cursor Rules
Cursor Rules son típicamente instrucciones con alcance de editor/agente (reglas de proyecto o de usuario). Úsalas para:
- Estilo de código y convenciones del framework
- «Siempre ejecuta X antes de decir que está terminado»
- Rutas que necesitan cuidado extra (auth, facturación, migraciones)
No escondas una política de seguridad crítica solo en una regla de usuario personal si el resto del equipo no puede verla.
Specs y porciones de tarea
Las specs responden qué construir y cómo aceptarlo. Las reglas responden cómo deben comportarse los agentes mientras construyen.
Una mini-spec útil incluye:
- Resultado visible para el usuario
- Fuera de alcance
- Archivos o áreas que probablemente se toquen
- Pasos de prueba o comprobación manual
- Nota de rollback si es riesgoso
Los agentes sin spec inventan alcance. Los humanos sin spec discuten después del hecho.
MCP y acceso a herramientas
MCP (y puentes de herramientas similares) permiten que los agentes llamen a sistemas externos. Eso es poderoso y peligroso.
Antes de habilitar herramientas:
- Prefiere acceso de solo lectura primero
- Ponte en lista blanca de hosts y comandos cuando sea posible
- Nunca pegues secretos de producción en configs de MCP que se suban a git
- Registra qué herramientas se ejecutaron para cambios no triviales
La configuración de MCP es control de capacidades, no documentación de producto.
Puertas de verificación
Las reglas pueden decir «ejecuta los tests». Las puertas exigen evidencia:
npm test/npm run build(o los equivalentes de tu stack)- Lint y typecheck cuando corresponda
- Revisión del diff en busca de secretos y cambios de archivos inesperados
- Checklists como revisión de código con IA y checklist de ship
Consulta también puertas de verificación para agentes de AI coding.
Sin puerta en verde no hay «terminado».
Un orden práctico de configuración
- Escribe un
AGENTS.md(o equivalente) de una página con comandos y zonas prohibidas. - Añade Cursor Rules /
CLAUDE.mdsolo para extras específicos de herramienta; evita guerras de duplicación. - Exige una spec breve para cualquier tarea no trivial.
- Habilita las herramientas de MCP de forma acotada.
- Haz que el merge dependa de las puertas de verificación, no de la confianza del agente.
Límites
- Los nombres de archivo y las funciones del producto evolucionan; verifica la documentación actual de Cursor, Claude Code, Codex y otros.
- Las reglas no pueden arreglar una propiedad de producto ambigua.
- Los conjuntos de reglas demasiado largos se saltan; prefiere enlaces a documentos vivos en lugar de pegar todo.
Preguntas frecuentes
¿Necesito todos los tipos de archivo?
No. Empieza con un brief autoritativo más specs para tareas reales. Añade archivos específicos de herramienta cuando el producto los necesite.
¿Dónde deberían vivir los secretos?
En configuración de entorno y gestores de secretos, no en archivos de reglas, prompts o configs de MCP subidas al repositorio.