關閉工作階段與收尾
專案中累積了多個並行的工作階段：部分已完成，部分在等待業主，部分留下了未提交的程式碼、分支、工作副本以及「留待日後處理」的發現。目標是將此狀態整頓到業主可以關閉所有不必要的部分，且不會遺失任何東西。
你是唯一負責此事的工作階段（協調者）。從此刻起，所有事情都透過你進行：其他工作階段向你提交成果，由你向業主提問，業主將不再進入它們的視窗。
應達成的成果
- 關閉檔案放置在專案中，第一個區段為一個螢幕大小的「現在」頁面。
- 每個結果都在 Git 中（有自己的提交，已合併或明確標記為未合併），或者直接聲明「不在 Git 中，無副本」。
- 「待業主處理」清單 — 按重要性編號，並附上可執行的命令。
- 一個發現佇列，取代新增的工作階段和卡片。
- 多餘的工作階段已歸檔；仍開啟的工作階段需逐一點名，並附上原因和關閉條件。
- 專案看板、狀態文件與記憶符合實際狀況。
規則
每一條規則都源於實際發生的錯誤；案例請參閱 references/lessons.md。
- 事實即命令的輸出結果。 「已提交」、「已合併」、「已部署」、「檢查通過」的依據來自 Git 和實際執行結果，而非工作階段的報告，也不是你自身對一小時前狀況的記憶。來自工作階段報告的數字，需明確標註為「根據工作階段報告」。
- 哪些事可無需業主同意，哪些需要取得同意。
- 無需同意：讀取資料；維護關閉檔案；將暫存資料夾中的必要內容複製到專案中（不覆蓋任何檔案）。
- 在首次報告（步驟 3）之後，在原始請求的範圍內：更新看板、狀態文件和記憶，使其符合事實。
- 僅在取得同意後：提交、合併、刪除分支、副本或標籤、推送至伺服器、部署至測試環境、歸檔工作階段、移動和重新命名業主用以執行指令的套件和腳本。注意：「提交」不等於「推送」，「合併」不等於「刪除副本」。
- 同意的指令可以是具體的 — 針對特定操作：例如「已完成的就逐個關閉」、「已完成的工作提交到它的分支」。將此指令逐字記錄在「現在」頁面上，不要將其擴展到相鄰的操作。
- 業主的話，指的是他在你的視窗中寫下的內容。 他經由其他工作階段轉述的話，屬於該工作階段的報告：對該工作階段是許可，對你則不是。
- 工作階段的數量不會增加。 被關閉的工作階段幾乎總會發現新的缺陷並建立卡片，而業主可能會啟動它們 — 到收尾結束時，工作階段數量可能比開始時還多。立即與業主達成協議：不啟動卡片，發現事項以純文字形式加入佇列。並將此告知所有工作階段（使用「新秩序」範本）。
- 在執行任何修改操作前，請重新讀取狀態。 業主經常會對你和另一個工作階段下達相同的指令。提交前，執行
git log -3、git status，檢查暫存區；修改共用檔案前，檢查它一分鐘前是否已被更改。 - 不要繞過他人的限制。 寫入生產伺服器，以及任何已被或將被權限檢查阻止的操作，都必須由業主執行。不要尋找繞道方法，也不要委派給鄰近的工作階段 — 這同樣是繞道。
- 重要的結果不應由產生它的人來驗證。 合併、部署套件、用於生產的腳本，應由另一位執行者接收結果並進行驗證，而非基於你的判斷。
- 協調資源消耗。 檢查數十個工作階段會消耗大量執行者配額。如果業主有關於成本的規則（請查閱他的 CLAUDE.md），請在開始前說明預估規模。
執行順序
步驟 0. 設定框架
在讀取工作階段日誌之前，先確定四件事；並將其記錄在步驟 3 建立的關閉檔案的「框架」區段中。
- 專案的定義範圍。 專案資料夾及其工作階段曾操作過的所有儲存庫，包括位於其他資料夾中的儲存庫。查找方式：對沒有 Git 的資料夾執行
repo_state.py <專案資料夾>會列出其內部的儲存庫；sessions.py list則會顯示每個工作階段透過git -C存取的資料夾和儲存庫。用一句話向業主確認此清單。 - 狀態存放位置。 協調看板或日誌、狀態文件、記憶。如果沒有看板，則關閉檔案將作為看板使用。不要完整讀取大型看板：透過搜尋規則區段和相關工作階段名稱來查找。
- 不可觸碰的工作階段。 排程和提醒工作階段（在
list輸出中標記為「schedule」）、其他專案的工作階段、下一階段所需的工作階段，以及你自身。 - 業主設立的具體規則：關於提交、推送、生產環境、測試環境、成本。這些規則存在於 CLAUDE.md、看板和記憶中 — 請自行讀取，不要憑記憶轉述。
步驟 1. 清點（僅讀取）
腳本位於此技能的 scripts/ 目錄中，且僅為讀取用途。請從專案資料夾執行（或加上 --root <專案資料夾>）。Claude Code 會自動替換命令中的技能資料夾路徑：技能安裝方式各異（個人資料夾、專案資料夾、外掛），因此不要憑記憶輸入路徑。如果路徑未被正確替換（命令中仍包含 ${...} 形式的變數），請從技能開頭的「此技能的基礎目錄」行中取得資料夾路徑。
python3 -B "${CLAUDE_SKILL_DIR}/scripts/sessions.py" list --days 14
python3 -B "${CLAUDE_SKILL_DIR}/scripts/repo_state.py" <儲存庫> <儲存庫>
python3 -B "${CLAUDE_SKILL_DIR}/scripts/sessions.py" scratch
python3 -B "${CLAUDE_SKILL_DIR}/scripts/sessions.py" cards --days 14
- 依日誌檢視工作階段 —
list：日誌的結尾、業主上次寫入時間、工作階段操作過的資料夾和儲存庫。使用--project <路徑或資料夾名稱>來添加相鄰儲存庫的日誌。請注意，日誌不會反映工作階段是否已歸檔或正在運行。 - 從應用程式檢視工作階段 —
mcp__ccd_session_mgmt__list_sessions。應用程式的工具可能會有延遲：請透過 ToolSearch (select:mcp__ccd_session_mgmt__list_sessions,mcp__ccd_session_mgmt__archive_session,SendMessage,ListAgents) 載入它們，否則你可能會認為它們不存在。設定一個足夠大的limit（預設為 20），若要計算已歸檔的工作階段，請使用include_archived: true。回應包含所有專案的工作階段 — 請根據資料夾進行篩選；回應中不包含目前的工作階段。工作階段在應用程式中的編號 (local_…) 與其在日誌中的編號不同：請根據名稱進行比對。如果缺少該工具，請向業主請求一個工作階段列表的快照。 - 儲存庫狀態 —
repo_state.py：未提交的變更、被忽略的檔案、未合併的分支、工作副本（是否乾淨）、Stash 的內容、未推送的提交、未完成的合併操作。 - 暫存資料夾 —
scratch：當系統清理時會消失的內容（並非在歸檔時，但不會有任何警告）。 - 卡片 —
cards：工作階段建立的卡片，以及其中尚未啟動的卡片。未啟動的卡片應被放入發現佇列。標記為「已啟動但無日誌」表示工作階段已轉移到另一個專案：請使用--project添加該專案。
共用資源（如測試環境、鎖定、測試資料） — 獨立一行說明：鎖定是否可用，是否遺留了其他來源的暫存資料。
步驟 2. 檢查每個工作階段
針對每個工作階段，回答以下問題並填入表格（範本在 references/templates.md）：
| 問題 | 驗證方式 |
|---|---|
| 做了什麼以及結果在哪裡 | 儲存庫、分支、提交雜湊、檔案 |
| 是否已提交 | git status 在其工作副本中顯示為空白 |
| 是否已合併 | git merge-base --is-ancestor <分支> <主分支> |
| 結果是否已記錄 | 讀取專案文件、看板、記憶 |
| 有什麼在等待業主 | 其最後幾則訊息 + 自那時起是否已關閉 |
| 是否有「之後再做…」的承諾 | 日誌的結尾 |
| 其暫存資料夾中有什麼 | sessions.py scratch |
日誌結尾：sessions.py tail "<部分名稱>" --last 40。最後三則回覆會完整顯示，其餘回覆的中間部分會被省略；使用 --chars 0 可顯示完整內容。工作階段的工作副本和分支應取自其最終訊息、包含「資料夾」和「透過 git -C 操作」字樣的行，以及其工作記錄 (--tools)：日誌中的分支欄位通常為空白。
標籤：業主 — 由人類在該視窗中輸入；卡片 — 從卡片啟動的工作階段的第一則訊息：文字由另一個工作階段而非業主撰寫；工作階段 — 來自另一個工作階段的訊息；排程 — 自動化啟動。在輸出中沒有業主的話，並不能證明這些話不存在：在日誌壓縮後，這些話會以轉述的形式呈現。
判斷結果為以下五種之一：
- 立即關閉 — 已完成；結果在 Git 中，或明確標記為「不在 Git 中，無副本」；所有等待業主的事項都已移至「待業主處理」清單，且關閉此工作階段不需要它；
- 待特定操作後關閉 — 說明一個操作以及由誰執行；
- 保留 — 正在運行或是後續所需；說明原因和關閉條件；
- 不可觸碰 — 排程工作階段或屬於其他專案；
- 已歸檔 — 僅檢查其暫存資料夾、工作副本和未提交的變更。
如果工作階段超過十個，且存在 Workflow 工具並獲得業主同意進行並行檢查，請執行 ${CLAUDE_SKILL_DIR}/references/audit-workflow.js（讀取者按組別劃分，獨立驗證儲存位置，總結報告；參數在檔案開頭描述，在 skill 中傳入 ${CLAUDE_SKILL_DIR}）。否則，請自行使用相同的問題清單進行檢查。
此步驟的常見陷阱：
- 一個沒有自身提交的分支並不表示「已合併」：它也可能是一個工作尚未提交的分支，或是一個剛開始、全新的工作階段分支。
- 分支已不存在（Git 回傳錯誤碼 128）— 這不表示「未合併」：從日誌結尾檢查其最頂端提交的雜湊值。
- 一個在日誌中間說「完成」的工作階段，可能在之後發現其自身工作的缺陷。請讀到結尾，而不是第一個「完成」。
- 對一個未經驗證的工作階段的診斷，僅僅是推測。不要將其作為原因記錄到文件中。
步驟 3. 關閉檔案與首次報告
檔案命名為 關閉_工作階段_<YYYY-MM-DD>.md，放置在看板的旁邊（骨架在 references/templates.md）。如果該日期的檔案已存在，請不要建立新檔案或覆蓋舊檔案：請讀取它，僅重寫「現在」區段，將先前的內容移至下方的日誌。在 Git 專案中，此檔案在獲得業主同意前應保持未提交狀態 — 在「不在 Git 中的內容」區段中提及它。
第一個區段是 「現在」頁面：說明所有這些工作的目的和目前的規則、已完成的事項、哪些在 Git 中、哪些工作階段仍開啟、收到了業主的哪些指令以及已執行了哪些、哪些需要他親自執行、發現佇列。下方則是表格和日誌。
每次事件發生後，請重寫此頁面，而非在底部追加：當業主迷失方向時，他會閱讀此頁面。每次修改時，更新標題中的時間，重新計算清單中的數字，並重新閱讀決策區塊 — 「進行中」和「等待中」不應在事情完成後仍然存在。
然後向業主報告：有多少工作階段可以立即關閉，有多少在特定操作後可以關閉，哪些不在 Git 中，以及什麼在等待他。在首次報告中，同時詢問關於具體指令的事項 — 否則你將需要為每個工作階段分別詢問：
- 是否可以邊完成邊關閉已提交成果的工作階段；
- 是否可以將已完成的工作提交到其分支而無需逐個詢問；
- 他是否確認不啟動被關閉工作階段的卡片。
提問的格式請參考「與業主對話」區段。
步驟 4. 收尾
執行順序如下，以確保不會遺失任何東西：儲存 → 提交 → （歸檔工作階段，步驟 5） → 合併 → 清理。
- 將暫存資料夾的資料儲存到專案中：例如測試報告、「之前」的狀態快照、演練記錄。將它們放置在結果的旁邊。如果目標資料夾在
.gitignore中（repo_state.py會顯示「忽略」），則將其記錄在「不在 Git 中的內容」中：已儲存到專案並不表示已提交到 Git。 - 提交已完成的工作 — 將每個工作提交到其自己的分支，僅使用明確的路徑。在提交前，檢查要添加的內容是否包含金鑰、密碼和個人資料。如果一個檔案包含多個工作階段的片段，請透過暫存區將它們分開，不要修改工作檔案。在獨立的 clone 中驗證提交。具體方法參考
references/git-recipes.md。 - 合併 — 在獲得業主同意後，執行合併，並在合併前記錄原始頂端提交的雜湊值。在合併後的結果上執行檢查，而不是在各個分支上單獨執行：三個分別通過檢查的分支，合併後可能導致失敗。
- 刪除副本和分支 — 僅在驗證後執行：確認主分支的歷史記錄包含了該分支的工作提交；副本是乾淨的；其包含測試報告的被忽略資料夾已被處理；沒有開啟中的工作階段在使用此副本。
git branch -d會拒絕刪除未合併的分支，但會默默地刪除沒有自身提交的分支 — 包括活躍工作階段的新分支。不要刪除相鄰專案工作階段的分支和副本：標記為「由該專案處理」。 - 部署到測試環境（如果業主有要求）— 遵循測試環境的規則（鎖定、通知其他使用者、部署前後的檢查）。
- 對於生產環境，僅進行準備。 準備一個經過獨立驗證的腳本，包含計畫、執行和回滾步驟，並在「待業主處理」清單中提供一行包含確切命令的條目。業主可能會執行的舊版套件或腳本存在危險：立即告訴業主「請勿執行舊版」，並在獲得其同意後，將其移至一個名為「已過期 — 請勿執行」的子資料夾，並附上說明。如果你在已告知業主的命令中發現缺陷，請立即以一行文字告訴他「在收到我的消息前，請勿執行此命令」。
- 更新文件和記憶。 版本號、分支頂端狀態、「未合併」、「等待中」 — 使其符合事實。存儲到記憶中的應僅限於持久性知識（規則、陷阱、內容位置）；每日狀態則應存放在專案檔案中。
- 發現事項放入佇列。 每條記錄包含：內容、位置、驗證方式、潛在風險、修正所需動作。
當另一個工作階段仍開啟並正在修改相同檔案時，請對它說「請等待」，並等待其回覆：訊息送達不代表已讀取。在你提交後，則告知「樹狀結構已可用」。如果你正在驗證一個可能被其他工作階段重建的套件，請要求它不要觸碰，並在驗證前後比較其校驗碼。
步驟 5. 關閉工作階段
一旦功能完成的工作階段的資料已被儲存且工作已提交到其分支，即可對其進行歸檔 — 它不需要等待合併或清理副本。歸檔是可逆的 (unarchive_session)，而刪除是不可逆的；請使用歸檔功能。
在歸檔每個工作階段之前：
- 其工作副本是乾淨的，包含測試報告的被忽略資料夾已被處理。根據工具的描述，歸檔預設會刪除應用程式為工作階段建立的工作副本；工作階段透過
git worktree add自行建立的副本則會保留 — 你需要手動清理它們（步驟 4，第 4 點）； - 其暫存資料夾已被處理 — 在表格中標記此項；
- 日誌結尾沒有承諾或未完成的項目。
…
（原文後續內容因長度限制被截斷，但已涵蓋主要流程。）