撰寫重要的意圖 — Noea Code 文件

意圖文件記錄你希望軟體滿足的行為與限制。先寫下已決定的內容，再依實作與依據逐步完善。這樣能保持文件易讀，也讓 Agent 保有實作空間。

選擇值得保留的需求

意圖可以描述不同類型的需求：

描述觸發條件與可觀察的結果。「匯出必須可靠」很難檢查；「匯出失敗時，保留目前篩選條件並允許重試」則提供更明確的評估依據。

當某個實作選擇重要到未來變更也必須遵守時，就寫入意圖。尚未決定的細節可以繼續留作實作選擇。

意圖描述軟體必須持續做到的事，不是完成後就刪除的待辦清單。功能完成後保留需求，決定改變行為時才修改對應文字。

對話中也會有本輪工作的指示，可以這樣區分：

判斷句子實際限制的是什麼。「每次匯出前都驗證資料」定義軟體的執行順序，應放在意圖；「這次先調查匯出模組」則是在安排當前任務。

告訴 Agent 哪些指示是長期需求，哪些只適用於這次任務。重要的任務指示必要時應重述，不要假設新對話會繼承它們。

點選側邊欄的新增意圖並輸入名稱。Noea 會在意圖資料夾根目錄建立帶有一級標題的 .noea.md 檔案。

文件使用 Markdown，在同一畫面閱讀與編輯。點選文字即可修改，並可用標題、清單、表格與程式碼區塊組織內容。

例如：

# 每日簽到

使用者每天可以簽到一次。

## 獎勵

連續簽到 7 天後，發放一份獎勵。同一段連續簽到期間只發放一次。

用標題劃分章節，以段落表達不同需求。調查會將整個清單視為一份內容；若想分別調查與討論，請將主題拆成不同段落或章節。

規則尚未明確時，先討論，再請 Agent 提出變更：

我想避免重複發放簽到獎勵。請協助定義這裡的「重複」，等我確認後再提出意圖變更。

做出決定後，請 Agent 將它整理成提議。審閱文字、視需要編輯新內容，然後接受。對話中的一句話，只有寫入意圖文件後才成為文件的一部分。

最後的文字應使用你理解的概念與語言。對陌生術語或新增需求，先問清楚再決定是否保留。好的表達讓你能自行解釋需求，也能在想改變行為時找到該改的句子。

關於提議與建議卡片，請參閱討論與審閱意圖變更。

語言標記為 mermaid 的程式碼區塊可顯示為圖表，用來呈現狀態轉移、工作流程或模組關係。

右上角控制項可切換圖表與原始碼。切至原始碼即可編輯。若語法無效或圖表類型不支援，Noea 會顯示原始碼與原因，其餘文件仍可閱讀。

macOS 使用 ⌘S、Windows / Linux 使用 Ctrl+S，或選擇檔案 → 儲存手動儲存。標題旁的圓點表示未儲存變更。切換分頁會保留變更；關閉文件、專案或離開應用程式時，會提示儲存。

儲存時會統一 Markdown 格式。你也可在外部編輯器維護檔案。若在 Noea 編輯期間磁碟檔案被修改，應用程式會提供重新載入或另存選項，而不會直接覆寫。

新增、替換與刪除文字，對需求有不同影響：

移除「獎勵必須是徽章」不一定讓現有徽章實作不再有效；它可能仍滿足其餘意圖。若要完全取消獎勵，應明確寫出不得再發放獎勵，而不只是刪除獎勵形式的要求。

編輯前，可詢問 Agent 哪些行為會改變、哪些需求應保留。把回答作為討論依據，再檢查實際實作與證據。

儲存後，舊說明會標示先前的文字。新需求若需修改程式碼，先實作再調查；若只想檢查既有行為，可直接調查。