Escribir intenciones que importan

Los documentos de intención recogen el comportamiento y las restricciones que quieres que cumpla el software. Escribe lo que has decidido y afínalo a medida que aprendes de la implementación y la evidencia. Así el documento se mantiene legible y el Agente conserva margen para implementarlo.

Elige requisitos que merezca la pena conservar

La intención puede describir varios tipos de requisitos:

Describe la condición que activa el comportamiento y un resultado observable. «La exportación debe ser fiable» es difícil de comprobar. «Si la exportación falla, conservar los filtros actuales y permitir un nuevo intento» ofrece una base más clara para evaluarla.

Cuando una decisión de implementación importa lo suficiente como para que los cambios futuros deban respetarla, escríbela en la intención. Los detalles que aún no has decidido pueden seguir siendo decisiones de implementación.

Separa los requisitos permanentes de la tarea de hoy

La intención describe lo que el software debe seguir haciendo. No es una lista de tareas que se elimina al terminar. Conserva los requisitos después de completar una funcionalidad y modifica el texto pertinente cuando decidas cambiar su comportamiento.

Los chats también contienen instrucciones para la ronda de trabajo actual. Utiliza esta distinción:

Pregúntate qué restringe realmente la frase. «Validar los datos antes de cada exportación» define el orden de ejecución del software y pertenece a la intención. «Investigar primero el módulo de exportación esta vez» organiza la tarea actual.

Indica al Agente qué instrucciones son requisitos permanentes y cuáles solo corresponden a esta tarea. Repite las instrucciones importantes de una tarea cuando sea necesario; no supongas que un chat nuevo las hereda.

Crea y edita un documento

Pulsa Nueva intención en la barra lateral e introduce un nombre. Noea crea un archivo .noea.md en la raíz de la carpeta de intención con un encabezado de primer nivel.

Los documentos usan Markdown, con lectura y edición en la misma vista. Pulsa el texto para editarlo y organízalo con encabezados, listas, tablas y bloques de código.

Por ejemplo:

# Registros diarios

Los usuarios pueden registrar su actividad una vez al día.

## Recompensas

Otorgar una recompensa al usuario después de 7 días consecutivos de registros. Entregar la recompensa solo una vez durante la misma racha.

Utiliza encabezados para las secciones y párrafos para los requisitos distintos. Investigación trata una lista completa como una sola unidad de contenido. Separa los temas en párrafos o secciones cuando quieras investigarlos y debatirlos de forma independiente.

Desarrolla la intención mediante el diálogo

Si una regla aún no está clara, coméntala antes de pedir al Agente que proponga un cambio:

Quiero evitar recompensas duplicadas por registros diarios. Ayúdame a definir qué significa «duplicada» en este caso y espera mi confirmación antes de proponer un cambio de intención.

Cuando llegues a una decisión, pide al Agente que la convierta en una propuesta. Revisa la redacción, edita el nuevo texto si es necesario y acéptala. Una afirmación en el chat solo forma parte del documento de intención cuando queda escrita en él.

El texto resultante debe usar conceptos y un lenguaje que entiendas. Pregunta por los términos desconocidos o los requisitos añadidos antes de decidir conservarlos. Una buena redacción te permite explicar el requisito por tu cuenta y encontrar la frase que debes cambiar cuando quieras otro comportamiento.

Para las propuestas y las tarjetas de sugerencias, consulta Debatir y revisar cambios de intención.

Utiliza diagramas para las relaciones

Un bloque de código con el lenguaje mermaid puede mostrarse como un diagrama. Úsalo para ilustrar transiciones de estado, flujos de trabajo o relaciones entre módulos.

El control de la esquina superior derecha alterna entre el diagrama y su código fuente. Cambia al código fuente para editarlo. Si la sintaxis no es válida o el tipo de diagrama no es compatible, Noea muestra el código fuente y el motivo; el resto del documento sigue siendo legible.

Guarda y trabaja con editores externos

Guarda manualmente con ⌘S en macOS, Ctrl+S en Windows / Linux o Archivo → Guardar. Un punto junto al título indica cambios sin guardar. Cambiar de pestaña los conserva; cerrar el documento o el proyecto, o salir de la aplicación, te pide que los guardes.

Al guardar, se normaliza el formato Markdown. También puedes mantener los archivos en un editor externo. Si un archivo cambia en disco mientras lo editas en Noea, la aplicación ofrece opciones para recargar o guardar como otro archivo en lugar de sobrescribirlo directamente.

Entiende qué significa cambiar la redacción

Añadir, reemplazar y eliminar texto afectan a los requisitos de maneras distintas:

Eliminar «La recompensa debe ser una insignia» no invalida necesariamente una implementación existente con insignias. Puede seguir cumpliendo la intención restante. Para eliminar por completo las recompensas, indica que ya no deben entregarse, en lugar de borrar únicamente un requisito sobre su forma.

Antes de editar, pregunta al Agente qué comportamientos cambiarían y qué requisitos deberían permanecer. Usa la respuesta como base para el diálogo y comprueba después la implementación y la evidencia reales.

Después de guardar, las explicaciones anteriores muestran Texto anterior. Si el nuevo requisito necesita cambios de código, impleméntalo antes de investigar. Si solo quieres comprobar el comportamiento existente, investiga directamente.

Continúa con Trabajar con un Agente en la implementación o Mantener las explicaciones al día.