Escritura para agentes
El lector de todo lo que escribas con esta habilidad es un agente que solo tiene el texto. No vio la conversación, no puede preguntar qué quisiste decir, y actuará según lo que digan las palabras, literalmente y con todo el esfuerzo. La mayoría de los fallos provienen de la brecha entre lo que sabes y lo que quedó en la página. Así que trabaja desde la posición del lector: antes de escribir, define dónde termina el trabajo, en qué situación se encuentra el lector y qué material necesita; luego escríbelo en palabras que el lector pueda usar sin ti.
Dos tipos de entrada
Una solicitud aproximada ("escribe un resumen para que un agente corrija la prueba de inicio de sesión inestable"): recopila los hechos de la conversación y del espacio de trabajo, luego redacta desde cero.
Un prompt existente: consérvalo. Haz el conjunto más pequeño de ediciones que corrija lo que realmente está mal, mantén su estructura y redacción donde funcionen, y no añadas ningún requisito que su autor no haya indicado. Una reescritura completa oculta qué cambio importó y silencia intenciones que el autor tenía. Los valores predeterminados a continuación aún se aplican: si al prompt le falta una frase de rol, un ejemplo o una verificación final, agrégalos. Cada vez que añadas algo, ya sea uno de estos o una regla que cierre una brecha real, enuméralo al entregar.
Si un hecho que solo el usuario conoce cambiaría lo que el lector entrega o lo que puede hacer, pregunta antes de escribir: como máximo unas pocas preguntas, cada una con tu respuesta recomendada. De lo contrario, elige un valor predeterminado sensato y enuméralo como una suposición.
Antes de escribir
Dónde termina el trabajo
Indica el objetivo, por qué es importante (quién usa el resultado y para qué), qué cuenta como hecho y qué debe devolver. Describe el destino, no la ruta: da el resultado, los criterios de éxito y las restricciones, y deja que el lector elija el camino. Los modelos actuales planifican mejor que una secuencia que tú prescribas, y un paso que adivinaste mal igual se ejecuta. Enumera pasos solo cuando el orden en sí mismo sea un requisito, como una migración que debe ejecutarse antes de un despliegue.
Antes: 1. Abre refresh.ts. 2. Envuelve refresh() en try/catch. 3. Reintenta tres veces. 4. Ejecuta las pruebas.
Después: Cuando una sesión caduca, el cliente debe renovar el token silenciosamente para que el usuario permanezca conectado. Hecho cuando el nuevo caso de tiempo de espera en tests/auth/refresh.test.ts pase y ninguna prueba existente falle. Mantén la API pública de AuthClient sin cambios, porque otros tres paquetes la llaman.
Convierte los adjetivos de calidad en barras que el lector pueda aplicar. "Minucioso", "conciso" y "solo los importantes" se aplican literal e impredeciblemente: un revisor al que se le pide informar solo problemas importantes encontrará los menores y guardará silencio sobre ellos. Nombra el umbral, o nombra qué conservar y qué recortar. Si un paso posterior filtra los resultados, pide todo.
Antes: Revisa cuidadosamente e informa solo problemas importantes.
Después: Informa cada problema que encuentres, incluyendo aquellos de los que no estés seguro, y etiqueta cada uno como "rompe el comportamiento" o "solo estilo". Un paso posterior hace el filtrado.
En qué situación se encuentra el lector
Cuando el texto asigna una tarea (un resumen, prompt de sistema, issue, plan o handoff), comienza con una frase de rol: quién es el lector, su función en esta tarea y la situación en la que se encuentra. "Eres el revisor de código de esta solicitud de extracción, que no escribiste; el equipo planea fusionarla hoy." El rol establece la perspectiva del lector y de qué es responsable. Las descripciones de una herramienta o habilidad no tienen rol; dicen qué hace la cosa y cuándo usarla.
Luego dile al lector qué no puede ver desde donde está: si alguien puede responder preguntas durante la tarea o si se ejecuta sin supervisión; quién más trabaja en los mismos archivos o sistemas; si sus cambios son revisados o reversibles; si debe evaluar o cambiar cosas; y qué puede hacer sin preguntar, incluyendo si puede delegar más. Nombra las situaciones específicas que justifiquen detenerse para informar. "Pregunta si no estás seguro" deja al lector adivinando, y termina preguntando sobre todo o nada.
Te ejecutas sin supervisión; nadie puede responder preguntas hasta que termines. Detente e informa solo si la corrección eliminaría datos o tocaría código fuera de src/auth/. Otro agente está editando docs/ al mismo tiempo, así que deja ese directorio intacto y no reviertas cambios que no hiciste.
Qué material necesita el lector
Para cada fuente, da su ubicación y qué tomar de ella. Señala lo que el lector puede abrir por sí mismo (rutas de archivo, comandos, URL a las que pueda acceder) en lugar de parafrasear, para que lea lo real. Escribe completo todo lo que exista solo en tu contexto: decisiones tomadas en la conversación, las propias palabras del usuario sobre un requisito, resultados de comandos que ejecutaste, enfoques ya descartados y por qué.
Antes: Consulta docs/ y nuestra discusión anterior.
Después: Lee la sección "Reembolsos" de docs/billing.md para la regla de redondeo. Un requisito no está en ningún archivo; las palabras del usuario fueron: "los reembolsos parciales nunca deben exceder el cargo original, incluso después de la conversión de moneda".
Cuando incluyas registros, texto del usuario o la salida de otro agente, ponlo en un bloque claramente marcado y di que es material para trabajar, no instrucciones. Mantén tus propias instrucciones fuera de dichos bloques, porque el texto entre comillas o en bloques de datos comúnmente se trata como contenido sin autoridad.
Escribirlo
Usa las palabras del lector, no las tuyas. Mientras trabajabas acuñaste etiquetas ("opción B", "el camino perezoso", "el problema P2") y abreviaturas ("→ contención de bloqueo") que no significan nada para el lector. Reemplaza cada una con lo que representa, define los términos técnicos reales una vez, y escribe como si explicaras desde cero. Al describir trabajo realizado anteriormente, di quién lo hizo, para que el lector no crea que tomó esas acciones por sí mismo.
Antes: Opción B descartada (→ contención de bloqueo); continuar con init perezoso, cuidado con la trampa P2.
Después: La sesión anterior descartó reconstruir el grupo de conexiones en cada solicitud: bajo carga, la latencia p95 subió de 80 ms a 400 ms debido a la contención de bloqueo. El enfoque actual crea el grupo en el primer uso. Un problema conocido permanece: ...
Da a cada regla su razón en una cláusula ("…porque un script analiza este campo"). La razón permite que el lector maneje casos que no listaste y muestra hasta dónde llega la regla. Omítela solo cuando cualquier modelo competente ya sepa la razón o el contexto la haga obvia.
Indica cada regla una vez, en el lugar que le corresponde. La repetición no añade peso; hace que el lector aplique demasiado la regla (las líneas repetidas de "pregunta primero" se convierten en estancamientos en pasos seguros), y las copias se separan con las ediciones. Por la misma razón, usa una redacción sencilla: sin mayúsculas, IMPORTANTE o presión como "esto es crítico" o "no seas perezoso". Reserva palabras absolutas como nunca y siempre para invariantes reales, como límites de seguridad y acciones irreversibles.
No prescribas cómo pensar. Omite "piensa paso a paso" y solicitudes de escribir el razonamiento en la respuesta o en etiquetas; los modelos actuales razonan por sí mismos, y algunos rechazan solicitudes de transcribir su razonamiento. Si necesitas ver por qué, pide una explicación breve o la evidencia de apoyo, como referencias de archivo:línea o salida de comandos.
Al corregir una falla conocida, escribe el principio detrás de ella con su razón, no una prohibición sobre la única instancia que viste. Una lista de prohibiciones cubre solo lo que lista; un principio cubre también los casos vecinos.
Antes: No uses Object.create(). No uses proto.
Después: Prefiere la composición explícita sobre la manipulación de prototipos, porque los revisores aquí favorecen el código que se lee de arriba a abajo.
Escribe en párrafos. Usa listas solo para elementos que sean verdaderamente paralelos o secuenciales: campos, pasos ordenados, verificaciones independientes. Las viñetas eliminan los "porque" y "a menos que" que conectan las instrucciones, y los lectores tienden a reflejar el formato que reciben.
Incluye un ejemplo corto de lo que el lector debe producir, marcado como ejemplo; transmite forma, tono y nivel de detalle mejor que un párrafo de descripción. Omítelo solo cuando el resultado esperado sea inconfundible solo con las palabras, como un solo comando para ejecutar.
Termina un texto que asigna tareas con una verificación que el lector ejecute antes de reportar como hecho: el comando o prueba que demuestra el resultado cuando exista, de lo contrario los criterios de hecho para repasar. Pídele que indique claramente cualquier cosa que no haya podido verificar.
Entregar
Entrega el texto terminado, listo para pegar o ya escrito en su archivo, en el idioma del prompt existente o el que el usuario solicite. Fuera de él, enumera en unas pocas líneas las suposiciones que hiciste y que el usuario quizás quiera cambiar. Mantén tus notas de diseño fuera del texto en sí.
Antes de entregar, lee el borrador como lo haría el lector: capaz, pero teniendo solo esta página. Dondequiera que tenga que adivinar lo que quisiste decir, corrige la página.