Write intent that matters

Intent documents capture the behavior and constraints you want the software to satisfy. Write what you have decided, then refine it as you learn from the implementation and evidence. This keeps the document readable while leaving the Agent room to implement it.

Choose requirements worth keeping

Intent can describe several kinds of requirements:

Describe the triggering condition and an observable result. “Export must be reliable” is hard to check. “If export fails, preserve the current filters and allow a retry” gives you a clearer basis for evaluation.

When an implementation choice matters enough that future changes must respect it, write it into the intent. Details you have not decided can remain implementation choices.

Separate lasting requirements from today's task

Intent describes what the software must continue to do. It is not a checklist to delete when work is finished. Keep the requirements after a feature is complete, and change the relevant words when you decide to change the behavior.

Chats also contain instructions for the current round of work. Use this distinction:

Ask what the sentence actually constrains. “Validate data before every export” defines the software's execution order and belongs in intent. “Investigate the export module first this time” organizes the current task.

Tell the Agent which instructions are lasting requirements and which apply only to this task. Repeat important task-specific instructions when needed; do not assume a new chat inherits them.

Create and edit a document

Click New Intent in the sidebar and enter a name. Noea creates a .noea.md file at the root of the intent folder with a level-one heading.

Documents use Markdown, with reading and editing in the same view. Click the text to edit it, and organize it with headings, lists, tables, and code blocks.

For example:

# Daily check-ins

Users can check in once a day.

## Rewards

Give the user a reward after 7 consecutive days of check-ins. Issue the reward only once within the same streak.

Use headings for sections and paragraphs for distinct requirements. Investigation treats a whole list as one piece of content. Split topics into separate paragraphs or sections when you want to investigate and discuss them independently.

Develop intent through discussion

If a rule is not clear yet, discuss it before asking the Agent to propose a change:

I want to prevent duplicate check-in rewards. Help me define what “duplicate” means here, and wait for my confirmation before proposing an intent change.

Once you reach a decision, ask the Agent to turn it into a proposal. Review the wording, edit the new text if needed, and accept it. A statement in chat becomes part of the intent document only when it is written there.

The resulting text should use concepts and language you understand. Ask about unfamiliar terms or added requirements before deciding to keep them. Good wording lets you explain the requirement yourself and find the sentence to change when you want different behavior.

For proposals and suggestion cards, see Discuss and review intent changes.

Use diagrams for relationships

A code block with the language mermaid can render as a diagram. Use it to illustrate state transitions, workflows, or relationships between modules.

The control at the top right switches between the diagram and its source. Switch to source to edit. If syntax is invalid or the diagram type is unsupported, Noea shows the source and the reason; the rest of the document remains readable.

Save and work with external editors

Save manually with ⌘S on macOS, Ctrl+S on Windows / Linux, or File → Save. A dot beside the title marks unsaved changes. Switching tabs preserves them; closing the document or project, or quitting the app, prompts you to save.

Saving normalizes Markdown formatting. You can also maintain files in an external editor. If a file changes on disk while you are editing it in Noea, the app offers reload or save-as options rather than overwriting it directly.

Understand what a wording change means

Adding, replacing, and deleting text affect requirements in different ways:

Removing “The reward must be a badge” does not necessarily make an existing badge implementation invalid. It may still satisfy the remaining intent. To remove rewards entirely, say that rewards must no longer be issued rather than only deleting a requirement about their form.

Before editing, ask the Agent which behaviors would change and which requirements should remain. Treat the answer as a basis for discussion, then check the actual implementation and evidence.

After saving, older explanations show Previous text. If the new requirement needs code changes, implement it before investigating. If you only want to check existing behavior, investigate directly.

Continue with Work with an Agent on implementation or Keep explanations up to date.