透過提案工作階段將想法化為程式碼

當一項需求重要到不適合只用一段自由格式的提示詞處理時，提案工作階段就是正確的入口。HagiCode 不會立刻動手修改，而是先把需求整理成目標、範圍、任務與驗證標準，讓你審查，之後才進入執行。

前置條件

開始提案工作階段之前，請確認你已經：

• 依照安裝指南完成任一種安裝方式（Microsoft Store 或 Desktop）
• 完成精靈設定，這會建立你的第一個 Agent 以及至少一個專案
• 擁有足夠的專案上下文來描述這項變更；若還沒有，請先從建立對話工作階段開始
• 若想了解提案工作階段背後的 OpenSpec 流程，請先閱讀 OpenSpec 簡介

提案工作階段的用途

提案工作階段在以下情況最能發揮效用：

• 變更需要在開始修改前先釐清範圍
• 涉及多個儲存庫、模組或交付項目
• 工作應拆解為可審查的步驟
• 你希望推理與執行的軌跡日後仍然可見

如果你只需要理解儲存庫或進行輕量討論，對話工作階段會更快。如果你需要結構與可追溯性，請繼續使用提案工作階段。

流程總覽

階段	你要做的事	會發生什麼
建立 idea	按一下 New Idea 並描述需求	系統建立提案工作階段，並排入自動最佳化佇列
審查草稿	開啟工作階段卡片	HagiCode 會優化標題與描述，並草擬背景、問題、解決方案與影響
產生計畫	按一下 Generate Plan	Agent 撰寫 OpenSpec 計畫檔案
審查計畫	在 Review 分頁中閱讀計畫	在修改任何程式碼之前，你先確認或調整計畫
執行並封存	執行計畫，然後封存	Agent 執行各項任務，完成的計畫隨即封存

步驟 1：在 New Idea 抽屜面板中描述變更

選取你的專案，然後按一下工作階段看板上方工具列中的 New Idea（嫩芽圖示）。Create Proposal 抽屜面板隨即開啟。

逐項填寫抽屜面板：

• Idea Name 與 Project Name（必填）– 確認這項需求屬於哪個專案。
• Scope – 在 Vault 分頁中，勾選允許 AI 編輯的 vault；由系統管理的 vault 一律為唯讀參考。在 Projects 分頁中，可加入其他專案作為上下文。
• Quick Requests – 一鍵加入的選項，例如 No docs / tests、Self commit、Output English、Ask before edit 與 No backward compatibility。
• You Request – 以自然語言描述實際的變更，最多 14,000 個字元。上方的 Combined preview 會顯示將實際傳送給 AI 的完整內容。

按一下 Submit idea。如果這項工作同時涉及多個儲存庫，請在這裡就定義好邊界，而不要等到執行時才補充。

步驟 2：在詳細檢視中審查提案

送出後，這個 idea 會以卡片形式出現在 Proposal & Review 欄，並帶有狀態徽章。按一下卡片即可開啟提案詳細檢視。

此檢視將計畫、進度與對話整合在一起：

• Workflow steps（左側）顯示提案目前進行到哪裡。步驟分為 Proposal preparation（Session Created、Auto Optimizing、Drafting Ready）、Review and refine（Generating Plan Files、Review Plan）、Execution complete（Executing Plan、Execution Completed）以及 Archive（Archiving、Archived）。
• Planning directions 顯示計畫應探索哪些方向，例如變更地圖、互動流程或架構。可在 Settings → Proposals and planning → Planning Direction 中調整預設值。
• Info 分頁（右側）顯示草擬的描述（Context、Problem、Solution、Impact），以及位於 Chief Complaint 下的原始需求。透過快速操作，你可以 Open Proposal Folder、Optimize Proposal、Open in New Window 或 Delete Session。
• Conversation 與 Review 分頁則收錄與 Agent 的討論，以及對所產生計畫的審查。
• Quick Chat（左下角）讓你無需離開此檢視，就能向 Agent 傳送訊息。

如果目標、範圍或任務拆解在這裡看起來不對，請先修正提案再繼續。這正是此流程的重點。

步驟 3：產生、審查、執行與封存

草稿確認無誤後，按一下 Generate Plan。Agent 會撰寫 OpenSpec 計畫檔案，工作階段隨即進入 Review Plan，讓你在修改任何程式碼之前先檢查結果。審查完成後，工作階段會繼續進入 Executing Plan，最後是 Archiving 與 Archived。

在難以復原的步驟之前，例如產生提案、立即執行或封存，HagiCode 會要求確認。你可以在 Settings → General → Confirm Prompts 中微調這些提示。

執行完成後，可使用 Super Commit 將最終的變更整理成簡潔的 commit 訊息。

步驟 4：在工作階段看板上追蹤提案

當一個專案有多個提案，或同時混有提案與對話時，工作階段看板是最清楚的總覽。

• Proposal & Review 收納正在草擬、產生與審查中的 idea。
• Execution 收納正在執行或已完成的工作階段。
• Archived 讓已完成的工作不佔用主要空間，但仍可供回顧。

每張卡片都會顯示其狀態，例如 Optimizing、Drafted、Reviewing、Executing 或 Execution Complete。你可以透過版面配置切換器變更看板的版面；請參閱工作階段。

何時應優先選擇提案工作階段

在以下情況，請優先選擇提案工作階段：

• 變更很複雜，你不希望 AI 太早即興發揮
• 這項工作日後會被審查，或需要與他人分享
• 涉及多個儲存庫、模組或角色
• 你希望執行歷程與背後的理由能夠重複利用

如果任務仍然很小且屬於探索性質，對話工作階段通常是較輕量的做法。

後續步驟

建立對話工作階段如果在規劃變更之前，你仍需要先理解儲存庫，請從較輕量的對話流程開始。

Super Commit提案執行完成後，請繼續閱讀此指南，從最終的變更產生更簡潔的 commit 訊息。