Instrucciones compartidas

Cómo funciona

El repositorio contiene instrucciones adaptadas a su arquitectura y flujo de trabajo. El equipo las revisa como código y las actualiza cuando cambian sus convenciones. Las plantillas permiten distribuir una base común a nuevos servicios.

Ejemplo: contenido de un archivo de instrucciones

# Convenciones del proyecto

- Usa los componentes y tokens existentes.
- Valida cambios con `npm run check` y `npm run build`.
- Documenta decisiones que cambien contratos públicos.
- Consulta los ejemplos de referencia antes de añadir patrones.

El nombre y el alcance del archivo dependen de la herramienta utilizada. Un archivo breve con enlaces a ejemplos vigentes suele ser más mantenible que un manual completo duplicado.

Archivos según la herramienta

Herramienta	Archivo habitual
Estándar abierto	AGENTS.md (Codex, Cursor, Copilot, Gemini CLI, otros)
Claude Code	CLAUDE.md (puede importar otros archivos con @ruta)
GitHub Copilot	.github/copilot-instructions.md y .github/instructions/*.instructions.md
Cursor	.cursor/rules/*.mdc
Cline	.clinerules
Gemini CLI	GEMINI.md

Para no mantener seis copias, usa AGENTS.md como fuente única y haz que los demás lo referencien (por ejemplo, un CLAUDE.md que contenga @AGENTS.md más lo específico de Claude Code) o enlaces simbólicos.

Niveles

Nivel	Contenido	Responsable
Organización	Seguridad, datos sensibles, estándares comunes	Plataforma / arquitectura
Repositorio	Stack, comandos, estructura, convenciones del servicio	Equipo del servicio
Carpeta/módulo	Reglas específicas (migraciones, frontend, contratos)	Equipo del servicio
Personal	Preferencias individuales (idioma, estilo de respuesta)	Cada persona, sin versionar

Las reglas de organización pueden distribuirse con plantillas de repositorio, un repositorio compartido o un marketplace de plugins.

Qué incluir

• Comandos exactos de build, test, lint y arranque local.
• Estructura del repositorio y dónde vive cada cosa.
• Convenciones no evidentes en el código («los importes van en Dinero, nunca double»).
• Decisiones que no deben revertirse, con enlace al ADR.
• Qué no tocar (código generado, migraciones aplicadas) y qué requiere revisión humana.
• Definición de terminado: qué comprobaciones deben pasar antes de dar una tarea por acabada.

Qué no incluir

• Lo que el código ya muestra o un linter ya impone.
• Secretos, URLs internas sensibles o datos de clientes.
• Manuales extensos: enlázalos (progressive context disclosure).
• Reglas vagas («escribe código limpio»).

Mantenimiento como código

• Revisión en pull request como cualquier cambio.
• Propietario en CODEOWNERS.
• Revisión trimestral: eliminar lo obsoleto y lo que el agente ya hace bien sin indicación.
• Cuando el agente comete el mismo error dos veces, añade una regla; cuando una regla no cambia el comportamiento, quítala.

Criterios de implementación

Asigna responsables, revisa instrucciones contradictorias y prueba su utilidad con tareas representativas. No incluyas secretos. Las instrucciones guían al asistente; los controles obligatorios siguen perteneciendo a CI y al sistema de permisos.