> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://naturgy-comer-documentation-p5mde.vercel.app/api/mcp` to find what you need.

# Escribir y revisar instrucciones de agentes

El cuerpo de una instrucción vive en la plataforma. Esta guía explica cómo
revisar su estructura, sus componentes y sus herramientas sin copiar el cuerpo
en la documentación. En ATC se aplica a los nodos conversacionales y a los
componentes compartidos que cargan.

## Por qué se mantiene una estructura

Cada sección responde a una pregunta distinta: quién es el agente, qué reglas
aplica, en qué orden actúa, qué datos recibe, cómo habla y cuándo deriva. Esa
separación permite localizar la regla que hay que cambiar y revisar sus
duplicados y conflictos. Una regla repetida en Pasos, Frases modelo y un
componente puede divergir; una excepción añadida lejos de su regla puede
contradecirla. Por eso una corrección se integra en su sección propietaria, en
vez de añadir un bloque al principio o al final por conveniencia.

El orden que sigue es el estándar de edición y revisión de ATC. Antes de
reestructurar un nodo existente, lee la versión viva y sus componentes. Si el
nodo difiere, registra la diferencia y su posible efecto antes de mover texto:
reordenar instrucciones puede cambiar qué regla prevalece. No presentes una
reestructura como neutra sin comprobar los conflictos del texto afectado.
Este estándar define cómo ordenar y revisar el contenido; no garantiza que un
modelo concreto siga cada instrucción ni reemplaza pruebas con la versión de
workflow y el modelo que se vayan a usar.

## Estructura recomendada

1. **Frase de rol:** quién es el agente, para quién trabaja, cuál es su límite y qué cuenta como éxito.
2. **Instrucciones:** reglas de negocio y casos límite.
3. **Pasos:** secuencia de la gestión.
4. **Datos disponibles:** variables y forma de leerlas.
5. **Frases modelo:** lenguaje que se puede verbalizar.
6. **Formato de respuesta:** qué se dice y qué se mantiene interno.
7. **Escalados:** cuándo y a dónde sale la conversación.
8. **Ejemplos:** un ejemplo por situación.
9. **Guardrails:** prohibiciones de conducta que aplican siempre y quedan al final.

Cada sección debe hacer una sola cosa. Una regla de negocio no debe esconderse
en un paso, en una frase modelo y en un ejemplo a la vez. Guardrails es la
última sección para mantener juntas las prohibiciones generales y hacerlas
fáciles de revisar; esa ubicación es una convención estructural, no una garantía
de comportamiento específica de un modelo.

## Precedencia

Cuando una regla matiza otra, nómbrala y describe su frontera. No confíes en
mayúsculas ni en una posición que el lector tenga que adivinar. Elimina la regla
derogada o deja explícita la condición que la limita.

Antes de añadir una regla, busca el mismo supuesto en toda la instrucción y en
los componentes que carga. Una segunda copia diverge con el tiempo.

## Componentes

Un componente compartido debe contener una regla separable que aplique a más de
un nodo. Su descripción debe indicar alcance y frontera. El componente debe
aparecer en la sección que corresponde a su función:

* contexto de negocio en Instrucciones;
* mecánica de salida en Escalados;
* estilo en Formato;
* prohibiciones en Guardrails.

Cambiar un componente puede cambiar varios agentes. Explica el alcance y espera
confirmación antes de publicarlo.

## Herramientas y variables

Cada herramienta necesita una descripción que permita al agente verbalizar la
acción antes de ejecutarla. Comprueba nombre, argumentos, condiciones de uso y
consumidor final.

Sigue cada variable hasta su consumidor. Un nombre parecido no demuestra que la
variable exista ni que contenga el valor esperado. Los teléfonos, URL y datos
de cliente deben proceder de una variable o de una herramienta, no de una cifra
fija escrita en la instrucción.

## Lista de revisión

* la frase de rol aparece primero;
* las secciones están en orden y no se repiten;
* Guardrails es la última sección;
* cada componente está en su sección declarada;
* los ejemplos usan marcadores, no datos reales;
* las herramientas tienen argumentos y mensajes utilizables;
* los motivos de escalado coinciden con el catálogo vigente;
* las variables existen y llegan hasta el consumidor;
* las reglas coinciden con las decisiones de negocio;
* las reglas pendientes no se presentan como conducta actual.

## Aplicación a ATC

Antes de revisar un nodo ATC, confirma la organización, el workflow, el entorno
y el identificador de versión. Lee el nodo y cada componente que carga: los
componentes compartidos pueden afectar a varios especialistas y versiones.
Contrasta el comportamiento con la página propietaria de la capacidad y con las
decisiones de negocio aprobadas. Si no puedes leer una parte, márcala como no
verificada; no reconstruyas el cuerpo desde la documentación.

En cada cambio de instrucción:

1. reproduce y cita la llamada, evaluación o auditoría que motiva el cambio;
2. encuentra la regla vigente y todas sus copias en el nodo y sus componentes;
3. elige el lugar propietario según la función de la regla y su alcance;
4. edita el mínimo texto necesario y comprueba que no creas duplicados ni
   contradicciones;
5. revisa herramientas, mensajes previos a la ejecución, argumentos, motivos de
   escalado y variables hasta su consumidor;
6. ejecuta la regresión y las pruebas aplicables al recorrido afectado;
7. deja la publicación de la versión o del componente a la revisión y release
   aprobadas. Un componente compartido requiere revisar todos sus consumidores.

La documentación de la capacidad explica el protocolo para el lector. La ficha
del agente enlaza con ella, pero no la repite. Consulta [Cómo documentar una
cuenta](/method/how-to/documentation), [Preparar y cerrar una release de
workflow](/method/how-to/release) y [Revisar un nodo de
instrucciones](/agent-guide/how-to/skills/review-prompt).