Persistent Instructions

Qué son y qué significa persistir

Persistent Instructions es guía reutilizable disponible más allá de una solicitud inmediata para orientar cómo un sistema AI realiza trabajo dentro de un alcance definido. Puede expresar convenciones, restricciones, formas de comprobar resultados o expectativas de colaboración. La definición de trabajo del Atlas describe la función de esa guía, sin imponer un formato de archivo ni una jerarquía única de productos.

Persistente no significa permanente, inmutable, siempre cargada ni globalmente autoritativa. La guía puede revisarse, aplicarse solo a parte del proyecto o dejar de estar disponible en una ejecución concreta. Su conservación en un repositorio no demuestra que el runtime la descubrió. Tampoco su carga garantiza que el modelo la cumpla o que otra capa impida una acción contraria.

El problema aparece cuando varias tareas comparten acuerdos. Repetir manualmente cómo probar un proyecto o qué archivos son generados puede producir omisiones y divergencias. Conservar instrucciones puede facilitar continuidad, pero agrega documentación que mantener. El objetivo no es acumular reglas: interesa disponer de guía aplicable, actual y comprensible para el trabajo real, sin transformar cada preferencia ocasional en una obligación indefinida.

Repository Instructions y documentación

Repository Instructions aplica esa guía a una base de código. Puede describir layout relevante, comandos de build y tests, convenciones, fronteras arquitectónicas, expectativas de revisión y operaciones excluidas. Son ejemplos posibles, no campos de un schema obligatorio. Una tarea pequeña no necesita recibir toda la historia de decisiones del proyecto para respetar una convención concreta.

Documentación e instrucciones tienen propósitos semánticos distintos. «Payments verifica el importe antes de cobrar» explica comportamiento; «no modifiques el contrato de Payments en este encargo» guía una acción. Un README puede contener ambos tipos de texto. Ni su extensión ni su proximidad a un archivo decide automáticamente qué fragmentos tienen autoridad sobre el agente.

La guía de repositorio tampoco sustituye el código o los tests como evidencia de comportamiento actual. Si contradice una interfaz observada, hay una discrepancia que investigar; no corresponde convertir silenciosamente uno de los dos en verdad universal. Puede haber una regla deliberadamente más exigente que el estado existente o una instrucción obsoleta. Su dueño y propósito ayudan a resolver esa diferencia.

Prompt, instrucciones, skills y perfiles

task-prompts comunica el encargo actual; las instrucciones persistentes aportan guía reutilizable para varias interacciones. No son categorías incompatibles de representación: un runtime puede insertar esa guía en un prompt. La distinción es función y ciclo de vida. Una tarea puede pedir una excepción, pero solo puede desplazar guía cuando la autoridad y política aplicables lo permiten.

agent-skills agrupa un procedimiento o capacidad reutilizable con posibles recursos; puede contener instrucciones, pero la guía de un repositorio no se convierte automáticamente en skill. agent-profiles configura un especialista y sus características; puede incluir guía y restricciones de herramientas. Ninguno queda definido únicamente por contener Markdown. Los canónicos enlazados desarrollan esas diferencias sin crear configuraciones reales en este repositorio.

En un repositorio .NET, «usar la estructura de tests existente» expresa guía. Un procedimiento para investigar una regresión y una configuración de especialista en pruebas tienen otros propósitos. Pueden colaborar sin reemplazarse. Mantener esas fronteras evita crear un canonical por cada filename o describir instrucciones como si otorgaran herramientas y capacidades de ejecución.

Scope: qué trabajo queda alcanzado

Scope indica dónde o cuándo es aplicable una instrucción: organización, usuario, repositorio, directorio, subtree, tarea, sesión o perfil. Son dimensiones posibles; no una escalera universal de precedencia. Una regla específica para tests puede resultar irrelevante al editar documentación, aunque el agente pueda leerla. La guía necesita un alcance interpretable para no introducir obligaciones ajenas al encargo.

Algunos productos descubren guía de directorios ascendentes o cargan reglas según rutas; otros usan configuraciones y superficies distintas. La herencia es una solución de implementación al problema de aplicabilidad, no una propiedad universal de Markdown. Conocer dónde se busca y qué se carga permite comprobar el alcance efectivo en vez de inferirlo del archivo más cercano.

La precisión también reduce sobrecarga. Una instrucción de migraciones puede apuntar a documentación especializada cuando la tarea afecta datos, sin exigir leerla antes de una corrección ortográfica. Una regla excesivamente amplia puede consumir contexto y distraer del cambio. Restringir alcance no debe utilizarse para eludir una política de mayor autoridad que sí aplica.

Authority: quién puede dirigir una decisión

Authority es la capacidad reconocida de una fuente para orientar o restringir el trabajo bajo el contrato de ejecución. Puede involucrar políticas de plataforma, organización, usuario, mantenimiento del repositorio y autor del encargo. Texto recuperado también puede parecer una instrucción sin tener autoridad. Distinguirlo es necesario aun cuando resulte relevante para comprender el sistema.

Scope y authority son ejes distintos. Una regla junto al archivo puede ser más específica sin poder anular una restricción organizacional. Una solicitud reciente tampoco concede automáticamente una excepción. El Atlas no fija una precedencia independiente del producto: hay que examinar el contrato de la ejecución y conservar explícitamente qué fuentes son aplicables y qué autoridad se les reconoce.

Orden de lectura y autoridad tampoco son equivalentes por definición. Un producto puede documentar overrides en su cadena de guía y otro combinar instrucciones sin establecer un orden general de resolución. Presuponer que «lo último» o «lo más próximo» siempre gana convierte una observación de implementación en una regla falsa. La tabla de ejemplos fechados más abajo conserva esas diferencias.

Conflictos y resolución

Puede haber conflicto cuando el repositorio pide xUnit, el encargo solicita NUnit y una política prohíbe agregar dependencias. Antes de elegir un framework hay que determinar si las instrucciones se refieren a la misma parte del trabajo, si existe una excepción autorizada y qué cambios implicaría. Una diferencia aparente puede resolverse por alcance; una contradicción real no se elimina ignorando una fuente.

Las respuestas posibles incluyen aplicar precedencia explícitamente documentada, elegir guía más específica cuando el contrato lo admite y la autoridad es compatible, aclarar la intención, informar el conflicto o escalar. No constituyen un algoritmo universal. Cuando falta una decisión necesaria, conviene exponer qué alternativas quedan bloqueadas y qué evidencia permitiría continuar, sin inventar aprobación.

En Commerce, descubrir que el área usa xUnit puede ayudar a interpretar el pedido. Si el usuario aclara que solo quiere ampliar las pruebas existentes, el conflicto puede desaparecer sin cambiar dependencias. Si exige introducir NUnit y la política vigente lo prohíbe, la tarea necesita una resolución autorizada. La claridad del resultado importa más que presentar una elección silenciosa como cumplimiento de todas las instrucciones.

Discovery, carga y aplicación

Un archivo existente solo es una fuente potencial. Para influir en una ejecución debe ser descubierto, leído o incorporado por un mecanismo efectivo y considerado dentro de su alcance. Puede haber límites de tamaño, rutas excluidas, carga bajo demanda o diferencias entre clientes. Disponer de un nombre conocido no garantiza que el producto lo reconozca en cualquier ubicación.

Discovery no concede máxima autoridad. Encontrar un archivo de guía puede activar evaluación de scope y precedencia, mientras leer un documento cualquiera puede aportar información sin darle carácter normativo. Conviene poder identificar qué guía participó realmente, sin exigir que cada ejecución imprima todos sus contenidos. Un agente que recuerda una convención de otra sesión no demuestra haber cargado la versión vigente.

La aplicación también puede fallar por ambigüedad, contradicción o interpretación incorrecta. La existencia del mecanismo de carga no prueba cumplimiento. Para requisitos relevantes, la evidencia debe conectar acción y restricción: por ejemplo, el diff permite comprobar que no se modificó código generado. La guía expresa expectativas; no reemplaza comprobaciones ni controles de ejecución.

Formatos de producto: ejemplos fechados

Los ejemplos siguientes fueron consultados el 2026-10-26. Documentan diferencias actuales; no son instrucciones para configurar este repositorio ni una matriz exhaustiva de compatibilidad.

Producto / fuente	Ejemplo de mecanismo	Límite de la generalización
Codex	Cadena de guía global/proyecto con AGENTS.md y overrides documentados.	La precedencia descrita corresponde a ese descubrimiento, no a toda instrucción de cualquier origen.
Claude Code	CLAUDE.md, reglas con scope y otros formatos admitidos según configuración.	Concatena guía; no promete que la última regla resuelva todo conflicto.
GitHub Copilot	Instrucciones de repositorio, paths y agentes.	Soporte y precedencia dependen de cliente y función.
Gemini CLI	Contexto instruccional GEMINI.md, con descubrimiento global/workspace y bajo demanda.	Su carga no define autoridad universal ni el concepto general de memoria.

AGENTS.md, CLAUDE.md, GEMINI.md y copilot-instructions.md son formatos o convenciones de integración, no cuatro conceptos canónicos nuevos. Que varios productos reconozcan un nombre no implica que lo interpreten con igual carga, scope o precedencia. Las guías pueden cambiar; una nota tecnológica futura deberá fechar esos detalles si se materializa.

Instrucciones como contexto, compaction y handoff

Al aplicarse, las instrucciones se vuelven parte del contexto de trabajo. context-engineering-for-software-development abarca además selección de código, observaciones, actualización y transferencia. El documento de guía no contiene necesariamente todo lo que la tarea necesita, y sus instrucciones pueden competir por capacidad de contexto con material informativo útil. Más texto no demuestra mejor orientación.

Compaction puede exigir conservar o recargar guía vigente. Como ejemplo específico, la documentación de Claude Code describe recarga del archivo raíz tras compactar y carga posterior de ciertas reglas según necesidad. No se extiende esa conducta a todos los harnesses. Resumir una instrucción puede perder su excepción o procedencia; recuperar la fuente ayuda a contrastar su significado y aplicabilidad actuales.

Un handoff puede señalar qué instrucciones importan y dónde encontrarlas, sin copiar todo su texto ni asumir que la sesión siguiente lo heredará igual. Transferir una guía no cambia su autoridad. Si el repositorio o encargo cambió, el receptor necesita reconsiderar su vigencia. La continuidad informativa tampoco demuestra que haya transferido una aprobación o un permiso técnico.

Instrucciones, permisos y controles

agent-permissions-and-approval-boundaries conserva autorización de acciones y decisiones adicionales. «No hacer push directo» puede ser una instrucción, mientras una regla efectiva del runtime o servicio puede impedir la operación. El texto no concede ni revoca por sí mismo esa capacidad. Una instrucción de no usar producción tampoco elimina una credencial que el entorno expone.

agent-sandboxing limita recursos y consecuencias técnicas. AI Guardrails puede evaluar una entrada, salida o acción y decidir si continúa; sigue siendo distinto de guía que el modelo puede incumplir. Ninguna regla escrita debe presentarse como sustituto de autorización externa, aislamiento o verificación de efectos.

Elemento	Propósito	Persistencia / scope	Seguridad o capacidad efectiva
Prompt	Comunicar el encargo actual.	Interacción/tarea; puede conservarse.	Expresa intención, no concede autoridad técnica.
Persistent Instruction	Guía reutilizable.	Alcance y carga definidos.	Orienta; no es enforcement por sí sola.
Context	Información disponible para decidir.	Activo y cambiante.	Puede incluir datos no confiables.
Memory	Conservar/recuperar información.	Entre momentos/ejecuciones según mecanismo.	Retener no autoriza ni garantiza verdad.
Skill	Procedimiento/capacidad reutilizable.	Descubrimiento/uso según implementación.	Puede incluir recursos; ejecución sujeta a controles.
Agent Profile	Configurar un especialista.	Reutilizable según producto.	Puede configurar acceso; no prueba aislamiento.
Permission	Autorizar una acción.	Política/identidad/contexto.	Su enforcement necesita garantías concretas.
Guardrail	Check/control de ejecución.	Puntos cubiertos por el runtime.	Puede limitar acciones; no seguridad perfecta.

La tabla distingue propósitos, no prohíbe combinaciones. Una skill contiene instrucciones y un perfil puede referenciarlas; una política puede tener expresión textual y aplicación técnica. Importa identificar qué parte comunica guía y qué parte impide efectivamente una acción, en lugar de asignar garantías por la extensión de un archivo.

Mantenimiento y fallos

La guía puede volverse vaga, contradictoria, obsoleta, demasiado amplia o detallada. Un comando retirado puede impedir validar cambios; una regla copiada de otro proyecto puede exigir una dependencia inexistente. Mantener instrucciones requiere revisarlas junto con cambios del repositorio y retirar orientación que ya no corresponde. No hay una cadencia universal ni una garantía de que versionar texto mantenga su contenido correcto.

Un lifecycle útil como síntesis es crear, revisar, delimitar, descubrir/cargar, aplicar, resolver conflictos y actualizar o deprecar. No es un estándar formal. Las instrucciones específicas, accionables y verificables cuando corresponde facilitan detectar desviaciones. Agregar una regla después de cada error sin revisar las anteriores puede aumentar conflicto y ocultar restricciones importantes.

Ejemplo .NET y relaciones en el Atlas

Commerce.Api declara su versión objetivo en los archivos del proyecto y conserva comandos de build/test, convenciones de endpoints y límites de código generado. Las instrucciones reutilizables pueden orientar cómo trabajar allí. El encargo pide agregar una consulta de estado de pedido. El agente combina esa guía con el contrato actual, fuentes relevantes y resultados de herramientas, sin tratar la guía como sustituto del requisito comercial.

Si un test contradice un ejemplo antiguo, se investiga la discrepancia. Si una instrucción parece exigir modificar Payments pero el encargo lo excluye, se conserva la frontera y se resuelve el conflicto. El resultado debe mostrar qué se hizo y comprobó. No hace falta generar un archivo de configuración real ni cargar todo el proyecto para explicar esa responsabilidad.

agent-harness puede descubrir e incorporar guía; coding-agent la utiliza dentro del trabajo delegado. ai-assisted-software-engineering ofrece navegación hacia ambos y hacia contexto. Este canonical mantiene juntos Repository Instructions, scope, authority y conflict resolution. Skills y perfiles conservan sus canónicos propios; los nombres de archivo no introducen conceptos adicionales ni un formato universal.

Fuentes

Fuentes primarias consultadas el 2026-10-26. Definiciones, ejemplos, lifecycle y matriz son síntesis editorial del Atlas. Detalles de carga y precedencia pertenecen a sus productos y pueden cambiar.

• OpenAI: Custom instructions with AGENTS.md, descubrimiento y cadena de guía en Codex.
• Anthropic: How Claude remembers your project, instrucciones, memoria, carga, conflictos y continuidad tras compaction.
• GitHub: Custom instructions y support reference, variación entre clientes y funciones.
• Google: Provide context with GEMINI.md, contexto instruccional y descubrimiento jerárquico/bajo demanda.