Instrucciones y memoria del proyecto project-instructions
El agente de modernización de experiencias solo sabe lo que hay en la conversación actual y en los archivos del proyecto. Para que siga las convenciones del proyecto en cada conversación, escríbalas en archivos Markdown en el repositorio de Git. Este artículo explica cómo el agente utiliza esos archivos y cómo organizarlos para que funcionen de forma eficaz.
Todo lo que sea Iniciar una nueva conversación se aplica a cada proyecto. Aptitudes personalizadas son una opción avanzada que la mayoría de los proyectos no necesitan.
Lo que el agente recuerda memory
El agente no guarda un recuerdo separado de sus preferencias o de conversaciones anteriores. Todo lo que debe saber en cada conversación debe estar en un archivo que se lea. Como los archivos están en el repositorio de Git, también ayudan a los demás desarrolladores del proyecto y a cualquier otra herramienta de IA que utilicen con él.
Utilice AGENTS.md como punto de entrada agents-md
AGENTS.md es un archivo Markdown en la raíz del repositorio. Sigue un formato abierto que leen muchos agentes de codificación de IA.
El agente usa actualmente modelos Claude, que cargan un archivo de nombre CLAUDE.md desde la raíz del repositorio al principio de cada conversación. La práctica recomendada, que sigue la plantilla de AEM, es un archivo de CLAUDE.md con esta sola línea:
see @AGENTS.md
La referencia @ hace que el agente cargue AGENTS.md junto con CLAUDE.md y lo mantenga en su contexto mientras funciona. Escriba las instrucciones del proyecto en AGENTS.md y deje CLAUDE.md como esta línea. Las instrucciones permanecerán en el formato abierto que también leen otras herramientas de IA, y la configuración seguirá funcionando si cambia el modelo detrás del agente. Ese modelo es un detalle de implementación, por lo que no escriba instrucciones que dependan de él.
Los proyectos creados a partir de la plantilla de AEM actual, para contenido basado en documentos o para la creación de Experience Manager, incluyen ambos archivos y su AGENTS.md contiene reglas generales de codificación de Edge Delivery Services. Guarde ambos archivos. Si el proyecto se creó antes de que las plantillas las incluyeran, pida al agente que las añada desde las plantillas actuales. Para comprobar lo que ha cargado, inicie una nueva conversación y pregunte qué instrucciones de proyecto tiene.
Agregue una breve sección para su proyecto a AGENTS.md:
- Qué es el sitio, su origen y su destino de contenido.
- Las pocas reglas que se aplican a casi todas las tareas.
- Un índice de los otros archivos de instrucciones, con una nota sobre cuándo leer cada uno.
Utilice AGENTS.md menos. El agente lleva todo en cada conversación, así que cada línea ocupa espacio que podría usar para la tarea. Un texto largo y general también dificulta que el agente diga qué reglas importan.
Organizar más archivos de instrucciones organize
Coloque los detalles en archivos separados, agrupados en una carpeta cuando haya varios de ellos. Por ejemplo:
AGENTS.md Entry point: project summary and an index of the files below
project/
blocks.md Blocks, their variants, and how authors fill them
sections-and-templates.md Section styles and page template conventions
design.md Design tokens, typography, spacing, and brand rules
content.md Content, naming, URL, and asset conventions
decisions.md Agreed decisions, with dates and reasons
Hacer referencia a cada archivo de AGENTS.md. El agente abre un archivo al que se hace referencia cuando la tarea lo necesita, por lo que no es necesario asignar un nombre al archivo en cada solicitud:
## Project Instructions
This project migrates the WKND sample site to Edge Delivery Services. Content is document-based and edited in Experience Workspace.
Read these files when the task needs them:
| File | Read when |
|---|---|
| `project/blocks.md` | Creating, changing, or using a block |
| `project/sections-and-templates.md` | Building or styling sections or page templates |
| `project/design.md` | Changing colors, typography, spacing, or other styles |
| `project/content.md` | Importing, writing, or restructuring content |
| `project/decisions.md` | Before changing an agreed convention |
When we agree on a new convention, update the matching file in the same change.
Siga estas directrices:
- Un tema por archivo. Cuando un archivo aumente de tamaño, divida el archivo por tema. A continuación, el agente solo lee lo que necesita la tarea actual y conserva una mayor parte de su contexto para el trabajo en sí.
- Decir cuándo leer un archivo. Una descripción de una línea en el índice es suficiente para que el agente decida.
- Apunta al código. El código es la referencia para ver cómo se implementa algo. Describa la intención y las convenciones, y asigne un nombre al archivo que las implementa en lugar de copiar el código.
- Sin secretos. Estos archivos forman parte del repositorio. Nunca ponga contraseñas, tokens u otras credenciales en ellos.
Edge Delivery Services proporciona los archivos que se han confirmado en el repositorio a menos que se excluyan en el archivo .hlxignore. La plantilla de AEM .hlxignore excluye los archivos de Markdown y aquellos cuyos nombres comienzan con un punto. Escriba archivos de instrucciones en Markdown para que se mantengan excluidos; de lo contrario, se podrían solicitar archivos en otros formatos, como JSON o texto sin formato, desde las direcciones URL del sitio. La consola no muestra .hlxignore, por lo que si necesita cambiarla, edítela en GitHub o en un clon local.
Convenciones de contenido de documento content-conventions
Los autores funcionan mejor con estructuras de contenido magras: un encabezado, texto, imagen y vínculo, sin campos adicionales. Para que el contenido sea tan sencillo, la implementación se basa en convenciones, como qué contenido es opcional o cómo cambia la posición de un elemento su función. Los autores, desarrolladores y el agente solo pueden seguir esas convenciones si están escritas. Modelo de David describe las reglas generales para estas estructuras; haga referencia a él desde sus convenciones de contenido y anote solamente las decisiones propias de su proyecto.
Las convenciones que vale la pena documentar son:
- Variaciones de contenido de un bloque. Para un teaser, por ejemplo: si la imagen y el call to action son opcionales, cómo eligen los autores un título más grande o más pequeño y si un párrafo corto antes del título se convierte en una ceja, una pequeña etiqueta encima del título.
- Variantes de bloque. Qué variantes existen y cuándo utilizarlas cada una.
- Estilos de sección. Qué estilos de la sección existen, como un fondo oscuro o una columna estrecha, qué hacen y qué bloques funcionan dentro de ellos. Algunas secciones pueden esperar que un bloque específico logre un efecto particular.
- Plantillas de página. Convenciones de contenido que las páginas de una plantilla deben seguir, por ejemplo una página de artículo que comienza con una imagen a pantalla completa y termina con vínculos relacionados.
- Reglas de codificación, diseño y contenido. Nomenclatura, tokens de diseño, reglas de marca, convenciones de URL y recursos, y cualquier otra cosa que un nuevo miembro del equipo necesite saber.
Una entrada para un bloque puede ser tan corta como esta:
### Teaser
Promotes one page or offer.
| Content | Required | Convention |
|---|---|---|
| Image | No | Without an image, the text spans the full width. |
| Eyebrow | No | A short paragraph before the heading becomes the eyebrow. |
| Title | Yes | Heading 2 for the standard size, Heading 3 for a compact teaser. |
| Text | No | One or two short paragraphs. |
| Links | No | A bold link becomes a primary button, an italic link a secondary button. |
Variants: `dark` (light text on a dark background).
Works in sections: default, `dark`, and `narrow`.
Cuando la migración crea un bloque, el agente también escribe un LÉAME para desarrolladores y una guía de creación para autores. Ver Lo que el agente proporciona con un bloque. Haga referencia a esos archivos desde el índice en lugar de repetirlos.
Cambiar la forma en que responde el agente reply-style
La forma en que el agente escribe sus respuestas es una convención como cualquier otra, por lo que puede establecerla en AGENTS.md. Por ejemplo, si no desea que finalice cada respuesta sugiriendo pasos siguientes o si desea respuestas más cortas, dígalo:
## How to answer
- Keep answers short: what you changed, where, and anything that needs my decision.
- Don't suggest next steps unless I ask for them.
- Answer in German. Keep code, file names, and commit messages in English.
Estas instrucciones dan forma al texto de las respuestas del agente. Las sugerencias que la consola muestra en Pasos siguientes se generan por separado, por lo que seguirán apareciendo y podrá ignorarlas.
Dejar un registro de cada solicitud trace
Su historial de Git y el historial de versiones de su contenido son el registro de lo que hizo el agente; consulte Rastrear lo que hizo el agente. Para que ese registro sea fácil de seguir, agregue una regla permanente a AGENTS.md para que cada solicitud deje su propia confirmación y carga de contenido:
## After Each Request
- Commit your changes with a message that summarizes my request.
- Push the commit to the `develop` branch. Never push to `main`.
- If pages changed, list them and ask whether to upload them to Experience Workspace.
- La inserción necesita Permitir que LLM use mis credenciales de Git, o el permiso de credenciales de Adobe para repositorios conectados a través de Cloud Manager. Ver Página de configuración. Si el permiso no está disponible, inscríbete con Sync > Push > Code después de cada solicitud.
- Al cargar se necesita el permiso de credenciales de Adobe. La consola permite que el agente cargue contenido únicamente cuando el mensaje se lo pida o cuando usted esté de acuerdo, por lo que la regla incluye la tarea del agente y la respuesta aprueba la carga. Para el contenido de la instancia de autor, cargue las páginas usted mismo.
- La rama de trabajo mantiene las inserciones del agente alejadas del código del sitio activo. Un desarrollador revisa los cambios y los combina en
maincon una solicitud de extracción, tal como se describe en Contribución más amplia, mismo control de producción.
Permitir que el agente mantenga los archivos maintain
No es necesario escribir estos archivos a mano. Pida al agente que los cree y actualice, y después revíselos como haría para revisar el código.
-
Crear la primera versión una vez que existan las primeras plantillas y bloques:
Documente los bloques de este proyecto, las variantes, los estilos de sección, las plantillas de página y los tokens de diseño a partir del código y del contenido importado. Coloque cada tema en su propio archivo corto bajo
project/y agregue un índice con cuándo leer cada archivo enAGENTS.md. -
Mantenerlos actualizados. Agregue una regla permanente a
AGENTS.md, como la última línea del ejemplo anterior, para que el agente actualice los archivos cada vez que cree o cambie un bloque, estilo de sección o plantilla. -
Compruébelo. El agente puede registrar una convención que asumió en lugar de una que usted acordó. Corrija cualquier cosa que esté mal y pregunte de vez en cuando:
Compruebe los archivos de
project/con el código y el contenido actuales. Corrija las instrucciones que estén desactualizadas y divida cualquier archivo que haya crecido demasiado. -
Inclúyalos con el código para que tu equipo y las conversaciones futuras reciban las mismas instrucciones.
Iniciar una nueva conversación new-conversation
Dado que el agente carga AGENTS.md automáticamente, se inicia una nueva conversación con las instrucciones del proyecto y se encuentran los demás archivos a través del índice. Iniciar una nueva conversación con Borrar chat cuando una conversación se haya vuelto larga o se haya alejado de la tarea. Antes de borrarla, pídale al agente que guarde lo que importa:
Antes de borrar el chat, registre las decisiones y convenciones que acordamos en esta conversación en los archivos del proyecto y enumere lo que ha cambiado.
Al borrar, se eliminan los mensajes anteriores y no se puede deshacer. Para mantener la conversación, selecciona Descargar chat primero.
Para obtener un traspaso completo a otra persona o equipo, vea Conservar contexto para personas y agentes.
Avanzadas: Aptitudes personalizadas custom-skills
La mayoría de los proyectos no necesitan habilidades personalizadas. Las habilidades integradas del agente cubren la migración, el diseño, el desarrollo de bloques y la documentación, y mejoran con cada versión. Ver las notas de la versión.
Una aptitud es un conjunto de instrucciones para un tipo de tarea, a menudo paso a paso. Funciona como una sección de AGENTS.md, con una diferencia: el agente solo lee una aptitud cuando realiza esa tarea, en lugar de llevarla a cabo en cada conversación. Considere una aptitud personalizada cuando:
- Las instrucciones para una tarea recurrente alargan
AGENTS.md. - El agente sigue luchando con una tarea específica y repetida y necesita pasos precisos, por ejemplo, extraer imágenes de una galería inusual en el sitio de origen o manejar videos incrustados.
Para añadir una aptitud personalizada:
- Pida al agente que cree la aptitud en su propia carpeta en
.claude/skills/, como.claude/skills/gallery-images/SKILL.md. El archivo comienza con un encabezado corto que le da a la habilidadnameydescriptionde cuándo utilizarla. A continuación se muestran los pasos, las comprobaciones que muestran la tarea realizada correctamente y un breve ejemplo. - Pida al agente que se comprometa y fomente la aptitud. Las vistas de archivos de la consola no pueden almacenar en zona intermedia las carpetas cuyos nombres comiencen con un punto; Vistas de código explica el permiso que necesita el agente para insertarlos y qué hacer sin ellos.
- Pruebe la aptitud en una nueva conversación. Pídale que le asigne un nombre, como “Utilice la habilidad de imágenes de galería para importar esta página”. Para comprobar que el agente lo ha encontrado, pídale que lea la aptitud y que le diga su nombre y descripción. Una lista de las habilidades del agente cubre sus habilidades integradas, por lo que no muestra si las suyas están cargadas.
El encabezado de SKILL.md tiene este aspecto:
---
name: gallery-images
description: Extract the images of the source site's photo galleries, which a script loads. Use when importing pages that contain a gallery.
---
No necesita enumerar la aptitud en AGENTS.md. El agente ve la descripción de cada aptitud en la carpeta y lee una aptitud cuando una tarea coincide, por lo que debe describir con precisión cuándo utilizarla.
Una buena manera de escribir una aptitud es pedir al agente que la solicite justo después de haber completado la tarea correctamente:
Escriba una habilidad en
.claude/skills/gallery-images/SKILL.mdque capture cómo acaba de extraer las imágenes de la galería, incluidas las comprobaciones que utilizó. Entonces comprométete y empújalo.
Las habilidades personalizadas no reemplazan ni cambian las habilidades integradas del agente. Cuando una nueva versión gestione una tarea de forma nativa, elimine la aptitud personalizada que la cubría.
Por qué .claude/skills skills-location
Los agentes basados en Claude, como el que ejecuta actualmente la consola, descubren habilidades por su cuenta en una carpeta .claude/skills/ en la raíz del repositorio. Una aptitud se carga de forma nativa: el agente solo ve la descripción breve de la aptitud hasta que una tarea coincide con ella, se le puede pedir por su nombre y aplica la configuración del encabezado de la aptitud, como las herramientas que puede utilizar. Esto funciona de manera más confiable que una carpeta visible como skills/ que AGENTS.md indexa, donde el agente debe leer el índice y decidir abrir el archivo.
El nombre de la carpeta comienza con un punto, que tiene dos efectos:
- El sitio no lo sirve porque las reglas de
.hlxignoredescritas arriba lo excluyen. - Las vistas de archivos de la consola no lo muestran. Para revisar una aptitud, pídale al agente que la muestre o ábrala en GitHub.
Si el proyecto ya tiene aptitudes en una carpeta visible que AGENTS.md indiza, seguirán funcionando. Para que se carguen de forma nativa, pídale al agente que los mueva a .claude/skills/, agregue el encabezado y elimine las líneas de índice.