狀態
在儲存庫根目錄維護 STATE.md：一份輕量級的跨工作階段每日報告，讓下一個工作者在大約 15 行內了解專案目前位置、上次工作階段做了什麼、哪些經驗可以立即重用、下一步該做什麼，以及哪些未完成事項不能遺忘。這是讓開發經驗複利成長的回饋循環，而非每次工作階段都重新發掘專案狀態。
STATE.md 是短暫性的（「我們現在在哪裡 / 接下來要做什麼」，每個工作階段會被覆寫）且自成一體——它不是儲存持久性決策、架構或詞彙表的地方，也不應重複這些內容。它採用惰性建立方式：如果檔案不存在，第一次執行時會建立它。
如果專案有規劃權威（例如問題追蹤器、里程碑），該權威負責什麼是工作；它不指定執行的順序和方式——問題可以並行執行，一個問題可以跨越多個工作階段，插入的工作可以優先於已規劃的工作。STATE.md 是工作者對執行的報告：結果以及當前對已追蹤工作的編排（下一步要開始什麼、什麼被中斷並擱置了）。它記錄執行狀態；絕不淪為第二個規劃權威。
此技能自給自足且與正交，無論專案碰巧使用了什麼其他工具（版本控制、問題/任務追蹤器、設計文件）都無關。它假設這些工具可能存在，但不依賴任何特定工具——讀取專案已擁有的任何來源，跳過其餘部分。
精簡書寫——寧可省略也不誤導。 範本中的每個內容項目都是選填的。每當檔案被重寫時，更新日期是必填的。只有在內容準確且對下一個工作階段有用時，才寫入內容行。如果某個值缺失、過時、未經驗證或並非明確有用，請將其省略。錯誤或填充的行比缺失更糟糕。待辦事項使用不同的刪除規則；請遵循步驟 4。
何時執行
- 在工作階段結束時 / 收尾時——您的代理執行環境可能透過工作階段結束鉤子提示執行此操作，或者您自行執行。
- 按需執行，使用主機明確的技能語法調用
state技能。
主要工作者每個工作階段更新一次 STATE.md。並行的子任務和子代理不會更新它。此規則防止同時或重複寫入。
無操作防護： 如果工作階段沒有完成任何實質工作（例如一個簡單的問答回合），保持 STATE.md 不變——最多更新日期。不要用非進度內容攪動檔案。
工作流程
- 收集此工作階段實際完成或更改的內容。 主要來源是當前對話。如果專案有支援工具，請輕微驗證（近期版本控制歷史、問題/任務追蹤器）——將它們視為選用，非必要。
- 僅在你確定目前的巨集階段時才說明它。 預設情況下不要將先前的 STATE.md 的階段向前攜帶——如果它可能已經前進，或者您無法在此工作階段確認當前階段，省略該行，而不是斷言一個過時的階段。（將已完成的階段寫成當前階段是誤導。）使用專案自己的術語。
- 選擇推薦的下一個工作——一個新的工作階段應從哪些開放項目開始，按執行順序。當待辦事項是正確的下一個開始時，將其提升到這裡。
- 協調待辦事項。 對未完成的跨工作階段項目應用此演算法：
- 透過過濾繼承。 從先前的待辦事項和任何未執行的「下一步」項目開始。僅當有證據顯示項目已完成、過時、被選為「下一步」或已記錄在專案的追蹤器中時，才刪除它。追蹤器引用是項目有了新家的證據。檢查對話並在存在追蹤器時與其驗證。當項目狀態不確定時，保留該項目。
- 降級未完成的工作。 僅當被替換的工作未被選為「下一步」時，才將其移至待辦事項。應在下一個工作階段恢復的工作屬於「下一步」。
- 擱置延後的工作。 當一個新接受的項目被延後到下一個工作階段之後且沒有其他歸宿時，添加它。
- 為每個項目指定一個歸宿。 將其放入「下一步」或待辦事項，絕不能同時存在。
- 為每個待辦事項項目蓋上時間戳。 記錄其輸入日期為
自 YYYY-MM-DD。 - 應用五項預算。 當待辦事項超過五項，或某個項目明顯有實質內容時，將項目移至專案的追蹤器，按最舊優先。僅在追蹤器提供引用後才刪除項目。如果沒有追蹤器，保留所有項目。當沒有授權的撰寫者可以建立追蹤器記錄時，也保留所有項目。可見的溢出是信號，表示這些項目仍需要一個持久的歸宿。
- 僅在經驗有助於「下一步」時才添加。 僅當此工作階段的工作與推薦的下一個工作連續或相關時才包含一個註記，這樣註記才會真正被重用。如果下一個工作無關，省略它——對下一個任務沒有幫助的經驗是噪音，不是經驗故事存檔。當專案有
PITFALLS.md時，將持久的環境、工具、權限、沙箱和工具調用指導放在那裡。STATE.md 可以指向相關條目；不應複製該條目。 - 從範本重寫
STATE.md。 覆寫檔案；絕不附加。保持 15 行或更少。如果步驟 4 中的不遺失規則留下多於五個待辦事項項目，允許每個額外項目多一行。不要為了達到行數限制而刪除項目。省略不準確且沒用的內容項目。重新輸出過濾後的待辦事項作為新快照的一部分。蓋上更新日期。 - 不要自動提交。 只需將重寫後的
STATE.md留在工作樹中。它是否被追蹤或作為僅限本機的工作輔助工具，由專案選擇——此技能從不提交它。
範本
# STATE — <專案>
_跨工作階段每日報告（約 15 行，每個工作階段透過 `state` 技能重寫）。持久性決策存在於別處，不在這裡。_
- **階段/里程碑：** <當前階段，使用專案自己的術語——如果你無法確認*當前*階段，則省略>
- **上次工作階段：** <完成的/更改的內容；一行，例如 issue #N>
- **經驗：** <有助於「下一步」的暫時性經驗，或指向相關 `PITFALLS.md` 條目的連結；否則省略>
- **下一步：** <建議接下來要 START 的項目，按執行順序，例如 issue #N>
- **待辦事項：** <未完成且*未選入*「下一步」的跨工作階段延續項目；每項一行>
- <被中斷或擱置的項目，若存在則錨定到追蹤器引用 (#N)> _(自 YYYY-MM-DD)_
- <尚未進入追蹤器的項目——列表溢出時按最舊優先將其提升到那裡> _(自 YYYY-MM-DD)_
_更新於：<YYYY-MM-DD>_
（每個內容項目都是選填的。_更新於 每當檔案被重寫時是必填的。）
護欄
- 對於每個待辦事項更改，遵循步驟 4。絕不要為了達到預算而刪除未完成的工作。
- 對於重寫和行數限制，遵循步驟 6。STATE.md 是當前快照，不是歷史記錄。
- 僅記錄此工作階段的變化。待辦事項是唯一向前攜帶過濾後狀態的欄位。
- 保持檔案自成一體。不要重複持久性決策或依賴特定的追蹤器或工具。
- 使用專案既有的詞彙。