写下你在意的意图 — Noea Code 文档

意图文档保存你希望软件满足的行为与约束。先写清楚已经决定的事情，再根据实现和证据逐步补充，可以让文档保持可读，也给 Agent 留出实现空间。

选择值得长期保留的要求

以下几类内容都适合写入意图：

尽量说明触发条件和可观察的结果。“导出要可靠”不容易检查；“导出失败时保留当前筛选条件，并允许重试”给出了更清楚的判断依据。

当某个实现选择已经重要到你希望后续修改继续遵守它，就把它写进意图。尚未决定的细节可以先留给实现。

意图正文记录软件需要持续满足的要求，不是完成后就删除的任务清单。功能完成后仍应保留这些要求；决定改变行为时，再修改对应的文字。

对话中还会包含这次工作的安排。可以用下面的方式区分：

判断时看一句话实际约束什么。“每次导出前先校验数据”中的“先”定义了软件的执行顺序，仍然适合写进正文；“这次先调查导出模块”则安排当前任务。

提出任务时，明确告诉 Agent 哪些是长期要求、哪些只是这次工作的安排。重要安排应在当次任务中说明，不要假设新对话会自动沿用。

点击侧栏“新建意图”，输入名称。应用会在意图目录根部创建一份 .noea.md 文件，并放入一级标题。

文档使用 Markdown，阅读与编辑在同一界面。点击正文即可修改，可以用标题、列表、表格和代码块组织内容。

例如：

# 连续打卡

用户每天可以完成一次打卡。

## 奖励

连续打卡满 7 天，给用户一个奖励。同一轮连续打卡中，奖励只发放一次。

用标题组织章节，用段落区分不同的要求。调查会把整个列表一起处理；需要分别调查和讨论的主题，可以拆成独立段落或章节。

尚未想清楚时，可以先讨论，再要求 Agent 提出变更：

我希望打卡奖励不会重复领取。请先帮我明确“重复”的范围，等我确认后再提出意图变更。

讨论得到结论后，让 Agent 把决定整理为提议。在审阅界面确认措辞，必要时编辑新文字，再接受。聊天中表达过的意见，只有落实到意图文档里，才成为这份文档的一部分。

整理后的文字应保留你熟悉的概念和说法。遇到不理解的术语或新增要求时，先追问含义和原因，再决定是否保留。好的表达应让你能用自己的话说明要求，也能在下次想改变行为时找到要改的句子。

提议与“建议”卡的处理步骤，见讨论并审阅意图变更。

语言为 mermaid 的代码块可以显示为图。例如状态转换、处理流程和模块关系，都可以用图辅助表达。

图块右上角可以切换图与源码；需要编辑时切到源码。语法错误或图类型暂不支持时，会显示源码和原因，其他正文仍然可以阅读。

编辑后需要手动保存：macOS 按 ⌘S，Windows / Linux 按 Ctrl+S，也可以选择“文件 → 存储”。标题旁的圆点表示有未保存的修改。切换标签页时修改仍保留，关闭文档、关闭项目或退出时会提示保存。

保存会规范化 Markdown 的书写格式。你也可以用外部编辑器维护文件；如果磁盘上的文件在你编辑期间发生变化，Noea 不会直接覆盖它，而是让你选择重新载入或另存。

增加、替换和删除文字，会以不同方式改变你对软件的要求：

删除“奖励必须是徽章”后，现有徽章仍可能是符合其余意图的实现。若你想取消奖励功能，需要明确表达不再发放奖励，而不是仅删掉对奖励形式的要求。

修改前可以先问 Agent：“这处变化会改变哪些行为，哪些要求仍应保持？”把回答当作讨论的依据，随后结合实现和证据检查实际结果。

保存后，旧说明会显示“先前文字”提示。新要求需要改代码时，先推进实现，再调查；只是核实当前行为时，可以直接调查。