Запишите важные требования

Документы требований фиксируют поведение и ограничения, которым должна соответствовать программа. Запишите уже принятые решения, затем уточняйте их по мере изучения реализации и доказательств. Так документ остаётся понятным, а у агента сохраняется свобода при реализации.

Выберите требования, которые стоит сохранить

Требования могут быть разными:

Опишите условие срабатывания и наблюдаемый результат. Фразу «Экспорт должен быть надёжным» трудно проверить. «При ошибке экспорта сохранять текущие фильтры и разрешать повторную попытку» даёт более ясную основу для оценки.

Если решение реализации настолько важно, что будущие изменения должны его соблюдать, запишите его в требования. Детали, по которым вы ещё не приняли решение, могут оставаться на усмотрение реализации.

Отделяйте постоянные требования от сегодняшней задачи

Требования описывают то, что программа должна продолжать делать. Это не список задач, который удаляют после завершения работы. Сохраняйте требования после готовности функции и меняйте соответствующие формулировки, когда решите изменить поведение.

Чаты также содержат инструкции для текущего этапа работы. Различайте их так:

Спросите себя, что именно ограничивает предложение. «Проверять данные перед каждым экспортом» определяет порядок выполнения программы и относится к требованиям. «В этот раз сначала исследовать модуль экспорта» организует текущую задачу.

Сообщайте агенту, какие инструкции являются постоянными требованиями, а какие относятся только к этой задаче. При необходимости повторяйте важные инструкции конкретной задачи; не предполагайте, что новый чат их унаследует.

Создайте и редактируйте документ

Нажмите Новое требование (New Intent) на боковой панели и введите имя. Noea создаст в корне папки требований файл .noea.md с заголовком первого уровня.

Документы используют Markdown; чтение и редактирование происходят в одном представлении. Нажмите на текст, чтобы изменить его, и организуйте материал с помощью заголовков, списков, таблиц и блоков кода.

Например:

# Ежедневные отметки

Пользователи могут отмечаться раз в день.

## Награды

Выдавать пользователю награду после семи дней отметок подряд. В пределах одной серии выдавать награду только один раз.

Используйте заголовки для разделов, а отдельные абзацы — для разных требований. Исследование рассматривает целый список как один фрагмент. Разделяйте темы на абзацы или разделы, когда хотите исследовать и обсуждать их независимо.

Уточняйте требования в обсуждении

Если правило ещё неясно, обсудите его до того, как просить агента предложить изменение:

Я хочу предотвратить повторные награды за отметки. Помоги определить, что здесь считается «повторной» наградой, и дождись моего подтверждения, прежде чем предлагать изменение требований.

Когда примете решение, попросите агента оформить его как предложение. Проверьте формулировку, при необходимости отредактируйте новый текст и примите предложение. Сказанное в чате становится частью документа требований только после записи в него.

Итоговый текст должен использовать понятные вам понятия и язык. Прежде чем решать, сохранять ли незнакомые термины или добавленные требования, спросите о них. Хорошая формулировка позволяет самостоятельно объяснить требование и найти предложение для изменения, когда потребуется другое поведение.

Предложения и карточки замечаний описаны в статье Обсуждайте и проверяйте изменения требований.

Показывайте связи на диаграммах

Блок кода с языком mermaid может отображаться как диаграмма. Используйте его для показа переходов между состояниями, рабочих процессов или связей между модулями.

Элемент управления в правом верхнем углу переключает диаграмму и её исходный код. Для редактирования перейдите к исходному коду. Если синтаксис неверен или тип диаграммы не поддерживается, Noea покажет исходный код и причину; остальная часть документа останется читаемой.

Сохраняйте документы и работайте во внешних редакторах

Сохраняйте вручную с помощью ⌘S в macOS, Ctrl+S в Windows / Linux или File → Save. Точка рядом с заголовком отмечает несохранённые изменения. При переключении вкладок они сохраняются; при закрытии документа, проекта или приложения появляется запрос на сохранение.

При сохранении форматирование Markdown нормализуется. Файлы можно также редактировать во внешнем редакторе. Если файл на диске изменится, пока вы редактируете его в Noea, приложение предложит перезагрузить его или сохранить под другим именем вместо прямой перезаписи.

Поймите последствия изменения формулировки

Добавление, замена и удаление текста по-разному влияют на требования:

Удаление фразы «Награда должна быть значком» не обязательно делает существующую реализацию со значком неверной. Она может по-прежнему соответствовать оставшимся требованиям. Чтобы полностью убрать награды, укажите, что их больше нельзя выдавать, а не просто удаляйте требование об их форме.

Перед редактированием спросите агента, какое поведение изменится и какие требования должны остаться. Используйте ответ как основу для обсуждения, затем проверьте фактическую реализацию и доказательства.

После сохранения старые объяснения показывают метку Прежний текст (Previous text). Если новое требование требует изменения кода, сначала реализуйте его, а потом исследуйте. Если вы хотите только проверить существующее поведение, сразу проведите исследование.

Продолжите со статьёй Работайте над реализацией с агентом или Поддерживайте объяснения в актуальном состоянии.