devlog-tracker

English | 繁體中文

版本 1.6.3

在專案中維護一份 .devlog/devlog.md，把每一輪對話的請求、決策與結果寫成永久紀錄。對話一 /clear 或換 session 就沒了；這份檔案取代那個缺口，讓工作可以中斷再接。沒下過 /devlog-tracker:start 時，裝著也不會動任何檔案。

這是什麼

把「這輪做了什麼、決定了什麼、下一步是什麼」寫進專案內的 devlog.md。Stop hook 保證每輪都寫完才放行；沒明確 /devlog-tracker:start 前不會建立或改動 .devlog/。

devlog.md 只管跨 session 的交接連續性（決策軌跡、目前卡點、完成條件、下一步），並作為 L1（人觸發 continue／開 session 注入後，agent 只靠 SSOT 接手，且必須把本輪狀態寫回本檔）的主入口。不是整個專案的單一真相來源：

• 程式碼／檔案狀態的真相仍是 git
• 完整逐字過程的真相是對話 transcript（/clear 後不存在）
• 設計決策的真相是 docs/design/*.md

這份檔案只是取代「終端機一 clear 就沒了」的缺口，讓工作可以隨時中斷、隨時接續。L2（無人喚醒）與 L3（跨機共享 .devlog/）不在範圍；細節見 docs/design/devlog-as-ssot-assessment.md。

每輪收尾固定寫 Summary／Reply（對使用者說過的話）／Handoff（含未完成時的 完成條件）／Status。接手＝核對工作區 → 做下一步 → 寫回；讀而不寫算交接失敗。

安裝

三個平台對等，各自獨立安裝；同一個專案要用哪個或哪幾個都可以，但同一個平台不要同時用 plugin marketplace 跟 npx init 兩條路線，會讓 hook 觸發兩次。

Claude Code

方式一：plugin marketplace（會自動更新）

/plugin marketplace add gogogohuang/devlog-tracker
/plugin install devlog-tracker@devlog-tracker

指令用 /devlog-tracker:*（例如 /devlog-tracker:start）。

方式二：npx（vendor 進專案，版本可鎖定）

npx devlog-tracker init --claude

會把 hooks 合併進 .claude/settings.local.json（不是 settings.json——合併後的指令路徑含這台機器的絕對路徑，不該 commit；settings.local.json 是 Claude Code 預設 gitignore 的檔案），並把 commands/*.md 轉成 .claude/skills/devlog-<名稱>/SKILL.md，用 /devlog-<名稱> 執行；同時在 CLAUDE.md 加上一段 <!-- devlog-tracker:begin/end --> fallback 說明。

Codex

方式一：plugin marketplace

要測試尚未發布的 checkout，先在這個 repo 的根目錄用本機版本安裝：

codex plugin marketplace add .
codex plugin add devlog-tracker@devlog-tracker

合併並推送後，才改用 GitHub 來源安裝：

codex plugin marketplace add gogogohuang/devlog-tracker
codex plugin add devlog-tracker@devlog-tracker

在要追蹤的專案開新 Codex session，用 /hooks 審核並信任 plugin 附帶的 hooks，再執行 $devlog-start（或從 /skills 選）。plugin 腳本放在 Codex 的快取中，不會在每個專案建立 .devlog-tracker/；執行 $devlog-start 後才會在專案建立 .devlog/ 紀錄資料。若專案之前跑過 npx devlog-tracker init --codex，啟用 plugin 前先從專案的 .codex/hooks.json 移除 devlog-tracker 的 hook 項目，避免同一個 hook 執行兩次。

方式二：npx（vendor 進專案，版本可鎖定）

npx devlog-tracker init --codex

會把 codex/hooks.json 的 hooks 合併進專案 .codex/hooks.json，並從 commands/*.md 產生 .agents/skills/devlog-<名稱>/SKILL.md，用 $devlog-<名稱>（或 /skills 選）執行；同時在 AGENTS.md 加上同一種 fallback 說明區塊。舊版（0.25.0）寫到 .codex/prompts/ 的檔案會在重跑 init 時清掉——Codex 不讀專案層級的 custom prompts。

hook 需要信任審核才會執行。 Codex 會略過尚未信任的新 hook 或變更過的 hook。若使用 npx 安裝，專案的 .codex/ 設定層也須先被信任，專案 hook 才會載入；之後可用 /hooks 查看哪些 hook 定義仍待審核。

• 互動模式：有 hook 待審核時，Codex 啟動時會顯示警告。用 /hooks 檢查並信任它們。之後 hook 的設定有變動（例如重跑 init 讓路徑或指令改變）也可能要再審核一次。
• 非互動的 codex exec（CI、腳本）：未審核的 hook 會被靜默略過。--dangerously-bypass-hook-trust 可以讓它們跑起來，但那個旗標會略過所有 hook 的信任檢查，只適合已經自己確認過 hook 來源的自動化環境。
• 想確認有沒有生效：start 之後送一則訊息，看 .devlog/[email protected] 有沒有出現這一輪的 User Input skeleton；沒有就代表 hook 沒被執行。

沉默或工作區檢查擋住工具時，Codex 可用單一 cat <專案>/.devlog/[email protected] 指令讀取當輪，再用 apply_patch 修改；封鎖訊息會附上專案路徑。

Codex 的 Interrupt hook 會把主執行緒被中斷的輪次標成 INTERRUPTED。Codex 沒有處理其他異常結束的 StopFailure 事件；未收尾輪次會在下次訊息、下次 session start，或 SessionEnd 執行時補記。Codex 的 SessionEnd 原因目前只有 other，切換對話後也可能等閒置一段時間才觸發。正常輪次仍由 Stop hook 強制收尾。從已安裝專案的子目錄啟動 Codex 時，hook 也會找到安裝根目錄。

Lessons Mode 開啟時，Codex 的 SubagentStart hook 會把記錄指引與專案路徑交給子代理。npx 安裝在子代理使用獨立 worktree 時仍會傳主專案路徑；plugin 安裝則使用該 worktree 的路徑。

Cursor

Cursor 支援暫時停用：init --cursor 不再接受，cursor/ 也不會被安裝或發佈。轉接層程式碼仍留在 repo（cursor/、cli/platforms/cursor.js），之後可重新啟用。

兩個平台共通

npx devlog-tracker init

沒帶 --claude／--codex 時會互動式問要裝哪個平台；在沒有 TTY 的環境（例如 CI）且沒帶旗標時，init 不會詢問，直接安裝兩個平台。也可以組合指定，例如 npx devlog-tracker init --claude --codex。

會把 core/scripts/、claude/hooks.json、codex/hooks/、skills/、commands/ 複製進專案的 .devlog-tracker/。重新執行 npx devlog-tracker init 可以升級到套件目前的版本；npx devlog-tracker status 可以查目前裝的版本是否落後。npx devlog-tracker report [--json] [--all-branches] 和 npx devlog-tracker timeline [--all-branches] [--out <路徑>] 跑的是跟 /devlog-tracker:report、/devlog-tracker:timeline 同一支腳本，有 vendored 版本就用它。

若 vendored script 已不存在而留下舊 hook，可執行以下命令清理：

npx devlog-tracker init --prune

此命令只會移除帶有 devlog-tracker 標記、且指向不存在 vendored script 的 hook；有效 hook 與使用者自行設定的 hook 都會保留。它不會重新安裝或複製套件檔案。

Claude Code、Codex、Cursor 可以在同一個工作樹同時使用。三者共用一份 devlog.md，但每個平台各自保有開著的輪次（Claude Code 是 .devlog/.round-current.md，其他平台是 [email protected]／[email protected]）與各自的 Session Handoff；輪次號碼跨平台不重複，Codex／Cursor 的 Round 標題結尾帶 · codex／ · cursor。有兩個以上平台的輪次開著時，clean、keep、keep-all 會拒絕執行。同一個平台在同一個工作樹開多個視窗不支援——它們共用同一格。各平台的安裝要一起升級到同一個 devlog-tracker 版本：某個平台還停在舊版時，它仍寫共用的無後綴檔案，會破壞各平台分開的狀態。細節見 docs/design/multi-platform-concurrency.md。

.devlog-tracker/ 放的是安裝進專案的程式；.devlog/ 放的是這個專案的紀錄資料，執行 start 指令後才會建立。因此 npx init 後先看到 .devlog-tracker/ 是預期行為，單跑 init 不會開始記錄。

init 會把這台機器專屬的絕對路徑寫進各平台的 hooks 設定檔與 .devlog-tracker/env.sh。如果你把這些檔案 commit 進 git，每位隊友都要在自己的機器上跑一次 npx devlog-tracker init（路徑每台機器不同）；或者改成把 .devlog-tracker/ 與產生出來的 hooks 設定檔加進 .gitignore。

若要手動裝（不透過 npx），設定 DEVLOG_TRACKER_ROOT 為本 plugin 的絕對路徑，把對應平台的 hooks.json 的 hooks 合併進專案設定；commands/*.md 會優先讀 DEVLOG_TRACKER_ROOT，否則讀 CLAUDE_PLUGIN_ROOT：

export DEVLOG_TRACKER_ROOT=/absolute/path/to/devlog-tracker
export DEVLOG_PROJECT_DIR="$(pwd)"
bash "$DEVLOG_TRACKER_ROOT/core/scripts/start-devlog.sh"
bash "$DEVLOG_TRACKER_ROOT/core/scripts/status-devlog.sh"
bash "$DEVLOG_TRACKER_ROOT/core/scripts/segment-watch-set.sh" 600
bash "$DEVLOG_TRACKER_ROOT/core/scripts/checkpoint-set.sh" 20
bash "$DEVLOG_TRACKER_ROOT/core/scripts/report-devlog.sh" --json
bash "$DEVLOG_TRACKER_ROOT/core/scripts/timeline-devlog.sh"
# pause / span-open / span-close / compact / keep-move / keep-all / clean / resume / pr / promote：見 commands/*.md

快速開始

在專案裡下一次（依安裝方式擇一）：

/devlog-tracker:start   # Claude Code plugin
/devlog-start           # npx init --claude
$devlog-start           # Codex plugin 或 npx init --codex

之後正常對話即可，每一輪結束前都會被強制檢查、補上 .devlog/devlog.md 的紀錄。/clear 之後 context 是空的；要接著做上一題，下對應的 continue 指令。暫停、歸檔、具名搬走、狀態與 span 見下方指令表。

指令

下表以 Claude plugin 的 /devlog-tracker:* namespace 表示；npx init --claude 裝的是 /devlog-<名稱>，Codex 兩種安裝方式都用 $devlog-<名稱>，指令內容相同。

| 指令 | 做什麼 | |---|---| | /devlog-tracker:start | 跑腳本建立 .devlog/.enabled（缺的 state 檔會補上，已有門檻不重置）。讀檔對進度，不自動開工。.devlog/ 含 prompt，會建議加進 .gitignore，要你同意才改。 | | /devlog-tracker:continue | 讀 .devlog/devlog.md，核對最後一輪 Handoff「工作區」後再依下一步接著做。/clear 之後要接續用這個。細節見 docs/design/continue.md。 | | /devlog-tracker:session-context-off | 停用已確認的專案或 worktree 根目錄的 SessionStart devlog context 注入。Codex 使用 $devlog-session-context-off；設定會持續到執行 session-context-on 移除開關。 | | /devlog-tracker:session-context-on | 移除已確認的專案或 worktree 根目錄的 SessionStart context 開關，恢復預設注入。Codex 使用 $devlog-session-context-on。 | | /devlog-tracker:migrate | 把 devlog.md、分支檔、開著的那一輪與 handoff.md 裡舊格式 #### 的 Handoff／Session Handoff 轉成 XML（備份成 *.pre-migrate）。Stop hook 擋下舊格式的 Handoff 時，會叫 agent 自己跑這個指令。 | | /devlog-tracker:pause | 暫停強制記錄，歷史檔不動，之後可再 start。 | | /devlog-tracker:compact | 腳本把較舊的 DONE 輪次搬到 devlog.archive.md（Checkpoint 與未完成輪留在主檔）。 | | /devlog-tracker:keep | 掃目前分支的主檔分主題（要一次整理所有 devlog 用 keep-all），一次列出建議，確認後把各段各自搬走成 devlog.<name>.md（並在主檔留一個 ## Kept 索引 指標行，含一句主題描述）；也可抽出一段或合併成全部歷史一檔。不是 compact。細節見 docs/design/keep.md。 | | /devlog-tracker:keep-all | 整理所有 devlog，不只目前分支：目前的主檔、其他分支的 devlog.<branch>.md、devlog.archive.md，以及先前 keep／keep-all 產生的所有具名檔。Claude 跨檔依主題重新分段（同一個主題散在 main、feature 分支與 archive 的片段會合回同一檔），一次列出所有建議檔案，確認後由一支腳本整批寫入，全有或全無。既有的具名檔會被拆開重組；各分支未完成的尾巴（最後一個 DONE 之後的 Round）與開著的那一輪不會被搬，搬空的分支檔會被刪除（仍在開發的分支、目前主檔與 devlog.md 除外）。動手前會先把所有會動到的檔備份到 .devlog/.keep-all-backup/<時間戳>/。需要 Node ≥18。細節見 docs/design/keep-all.md。 | | /devlog-tracker:overview | 讀完所有已 keep 的 devlog.<name>.md，整合成跨主題總覽，並列出看起來該進 CLAUDE.md 的規範候選。純讀取，不核對工作區、不等確認、不寫檔。細節見 docs/design/keep.md Kept index。 | | /devlog-tracker:promote | 從已 keep 的檔、lessons 檔與 Checkpoint 的 ### 決策 挑出規範候選並編號列出；只有你選定的才追加到 CLAUDE.md（CLAUDE.md 只有 @AGENTS.md 或只裝 Codex 時改寫 AGENTS.md）的 <!-- devlog-tracker:rules:begin/end --> 受管區塊。只追加、一字不差的重複會跳過；init 不會覆寫這個區塊。 | | /devlog-tracker:search <關鍵字> | 在 devlog.md／devlog.archive.md／已 keep 的 devlog.<name>.md／devlog.lessons.<topic>.md 裡做不分大小寫的字串搜尋；Claude 讀完命中後用自己的話回答（必要時附檔名／標題／行號）。純讀取，不核對工作區、不等確認、不寫檔。 | | /devlog-tracker:report | 印出 devlog 統計：Round 數（主檔 + archive）、各 Status 數、BLOCKED 比例、Checkpoint／keep／lessons 數量、第一輪與最後一輪時間。--all-branches 合計所有 branch 檔。純讀取。機器可讀輸出用 npx devlog-tracker report [--json]。 | | /devlog-tracker:timeline | 把 devlog 產生成離線可開的自足 HTML 時間軸 .devlog/timeline.html（Round 卡片依 Status 上色、穿插 Checkpoint、可依 Status／branch／關鍵字篩選、支援深色模式）。不含 User Input 原文。需要 Node ≥18；--all-branches 納入所有 branch 檔。也可用 npx devlog-tracker timeline。 | | /devlog-tracker:pr | 從這個 branch 的 devlog Rounds 與 git log 產生 PR 描述（Summary／Decisions／Changes／Test plan，不含 User Input 原文），寫到 .devlog/pr-body.md；你確認後才跑 gh pr create 或 gh pr edit。在 main／master 上不執行。 | | /devlog-tracker:resume <name> | 讀具名保存檔的最後一輪與 Handoff，核對「工作區」後提出接續；新工作仍寫回主 devlog.md。 | | /devlog-tracker:clean | 無條件清空 devlog.md（含專案摘要與所有 Round 歷史），不搬移、不備份、不可復原；執行前一定會先問，要明確回覆「清空」才動手。只留目前開著的那一輪，重編成 ## Round 1。 | | /devlog-tracker:status | 查看強制記錄開關、Span、Checkpoint、Segment Watch、Lessons Mode 工作區漂移計數與最後一輪 Status。 | | /devlog-tracker:span | 開啟或關閉自動續接長任務使用的 Span Mode（不要手寫 .span-open JSON）。 | | /devlog-tracker:segment-watch <時間長度> | 調整 Segment Watch 的沉默門檻（預設 10 分鐘）。專案還沒 /devlog-tracker:start 時回報 NOT_STARTED，不會建立任何檔案。 | | /devlog-tracker:checkpoint <輪數> | 調整 Checkpoint Mode 的沉默門檻（預設 20 輪）。專案還沒 start 時回報 NOT_STARTED。 | | /devlog-tracker:lessons-on | 開啟預設關閉的 Lessons Mode（隸屬主開關，沒 start 過會拒絕）。細節見 docs/design/lessons-mode.md。 | | /devlog-tracker:lessons-off | 關閉 Lessons Mode，不動任何已寫的 devlog.lessons.*.md 或索引。 | | /devlog-tracker:lessons [<topic>] | 沒給 topic：印 ## Lessons 索引。給 topic：印該主題檔全文。純讀取，不核對工作區、不等確認。 | | /devlog-tracker:lessons-drift <次數> | 調整 Lessons Mode「工作區漂移重複發生」機制性提醒的門檻（預設 3 次）。隸屬 Lessons Mode，沒開會回報 LESSONS_NOT_ENABLED。 |

善用記下來的內容

有四個指令能把 devlog 變成可以交給別人、或回流到專案的東西：

• report：只給數字（Round 數、各 Status 分布、BLOCKED 比例、Checkpoint／keep／lessons 數量）。npx devlog-tracker report --json 是給 CI 或儀表板用的機器可讀格式；加 --rounds 會附上每個 Round 的資料。
• timeline：產生 .devlog/timeline.html，一頁離線就能開的網頁，可以用瀏覽器看，也可以附在交接資料裡。重跑就會更新，會直接覆寫。
• pr：在 feature branch 上，從這個 branch 的 Rounds 和 git log 產生 .devlog/pr-body.md 草稿，要跑 gh 前會先問你。沒有 gh 或沒登入時，就停在草稿。
• promote：把 keep 檔、lessons、Checkpoint 決策裡該長期遵守的規則，寫進 CLAUDE.md／AGENTS.md 的受管區塊。它會列出編號候選，只寫入你選的那幾條；區塊裡的規則要改或刪，請直接手動編輯。

這四個指令都不會把 ### User Input 原文複製進輸出（唯一的例外是明確加上 report --with-input）。pr-body.md 和 timeline.html 放在 .devlog/ 底下，這個目錄通常已被 gitignore；如果你的專案會 commit .devlog/，別把這兩個檔 commit 進去。report 和 timeline 跟 status 一樣不會開 Round；pr 和 promote 會，因為它們會動到 .devlog/ 以外的東西。細節見 docs/design/read-side-and-promote.md。

強制記錄開著之後

sequenceDiagram
  participant U as 使用者
  participant H as Hooks
  participant C as Claude
  participant D as .devlog/devlog.md

  U->>H: 送出訊息
  H->>D: 先寫 Round skeleton（User Input + IN_PROGRESS）
  C->>D: 補 Summary / Reply / Handoff，改 Status
  C->>H: 這一輪要結束
  alt 沒寫完、標題是空的，或 Status 不合法
    H-->>C: 擋住，要求補寫
  else 寫完了
    H-->>C: 放行
  end

每一輪固定：

• User Input — 送出原文優先（hook 寫入；Claude 不要改寫），常見 token 會遮罩
• Summary — 給人掃的結論
• Reply — 這輪對使用者說過／答應過的話
• Handoff — 給下一輪接手（決策／檔案／工作區／現況／完成條件／下一步）。Handoff 與 Session Handoff 用以行為單位的 XML 標籤寫（<handoff> … <next> …），因為讀者只有下一輪的 agent 與 Stop hook；Summary／Reply 仍是給人看的 Markdown。細節見 docs/design/handoff-xml.md。
• Status — DONE / IN_PROGRESS / BLOCKED / INTERRUPTED 四選一

其中「工作區」是收尾時的 git 快照，進行中／卡住必寫；DONE 若「檔案」有內容（宣稱動過／commit 過檔案）也必寫。「完成條件」在進行中／卡住必寫。

Stop hook 會做這些事：

1. 確認 Summary／Reply／Handoff 標題底下有內容、Status 是上述四值之一；Handoff 必須是 XML 標籤格式，標籤順序為 decisions → files → workspace → state → done-when → next
2. 進行中／卡住時有「完成條件」與「下一步」；「下一步」不是純黑名單空話（例如整節只寫「繼續完成」；字串比對，非語意評分，細節見 docs/design/next-step-blacklist.md）；進行中另做輕量可執行檢查；卡住時「現況」或「下一步」須含缺件句式
3. 機器核對「工作區」是否跟收尾當下的 git 狀態逐字相符（進行中／卡住一律核對，DONE 只在「檔案」非空時核對），避免「已 commit 完成」卻其實沒 commit 這類宣稱跟實際不符

<files> 非空時同樣機器核對：commit 區塊要跟該次 commit 的實際內容逐字相符，未 commit 的區塊只要求宣稱的路徑真的存在變更（不要求涵蓋全部，避免把跨輪殘留算成這輪漏列）。

細節見 docs/design/summary-handoff.md、docs/design/devlog-as-ssot-assessment.md、docs/design/files-verify.md、docs/design/handoff-xml.md 和 SKILL.md。

升級到 XML Handoff

舊輪次是 #### 小節格式，讀取端照樣相容。archive、keep 與 lessons 檔（devlog.archive.md、devlog.<name>.md、devlog.lessons.*.md）永遠不會被改寫。當 Stop hook 在收尾時擋下舊格式的 Handoff，訊息會叫 agent 自己跑對應的 migrate 指令（Claude plugin 用 /devlog-tracker:migrate，Codex 用 $devlog-migrate；底層是 migrate-handoff.sh）再重新結束這一輪——一般情況不用你動手。migrate 會直接改寫 devlog.md、分支 devlog 檔、每個平台開著的 Round（.round-current.md、[email protected]、[email protected]）與交接檔（handoff.md／handoff.<branch>.md 及其 @codex／@cursor 版本），每個改過的檔旁邊留一份 *.pre-migrate 備份；無法精確轉換的輪次保留原樣，列在 SKIP 行。如果 agent 一直寫舊格式、沒有照著修，請更新 plugin 或重跑 npx devlog-tracker init，再使用對應的 start 指令（Claude plugin 用 /devlog-tracker:start，Codex 用 $devlog-start）。

Hook 會自動做的事

正常規則是「一則使用者訊息 = 一輪，結束前一定要寫完 Summary／Reply／Handoff／Status」。下面四個機制各自放寬這條規則的不同一塊，彼此正交、可以同時存在：

| 機制 | 放寬的是 | 解決的問題 | |---|---|---| | Span Mode | 「每次自動喚醒算不算一輪」 | /loop、Workflow 這類被自己排程反覆喚醒、不是使用者手動打字觸發的長任務，每個自動 tick 都強制寫完整 Round，會逼出大量沒意義的紀錄，甚至卡住整條自動化流程 | | Checkpoint Mode | 「有沒有跨輪的摘要路標」 | 一般互動對話每輪都正常寫，但輪數一多，翻閱的人要逐輪爬完才知道整體進度；每段 checkpoint 固定 決策／待解問題／失敗嘗試 三段，SessionStart 注入時較容易抓到卡點 | | Reply Fold | 「一問一答算不算兩輪」 | Claude 用純文字提問、下一則訊息其實是在回答時，預設邏輯（每個 UserPromptSubmit 開新 Round）會把這組問答硬拆成兩個不相關的 Round | | Segment Watch | 「一輪內部要不要留階段性痕跡」 | 一輪做很久（先探索、再決策、再實作、再驗證），憋到最後才寫一次，中途 crash 會把整個過程全部遺失 |

以下是各機制實際觸發時的行為：

自動接續

SessionStart hook 在開新 session、resume、/compact、/fork 時，若目前分支的 .devlog/handoff.md（或 handoff.<branch>.md）非空會先注入這份 Session Handoff 快照，再注入最後一個 Checkpoint（若有，含其中的 ### 待解問題 供接手抓卡點）、## Kept 索引（若有，不是具名檔內容）加上最近兩輪的 Summary / Handoff / Status，不是整份檔。IN_PROGRESS／BLOCKED 收尾時 Stop 會覆寫 handoff 檔，DONE 會刪掉它。使用 /devlog-tracker:session-context-off（Codex：$devlog-session-context-off）可停用已確認的專案或 worktree 根目錄的這項注入；它會寫入 .devlog-session-context，內容精確為三個位元組 off，不含尾端換行。使用 /devlog-tracker:session-context-on（Codex：$devlog-session-context-on）會移除開關並恢復預設注入。設定會持續影響所有新的 SessionStart，直到移除開關。乾淨的 SessionStart 不會搬移或修補 devlog 資料。此開關只影響 devlog-tracker 的 SessionStart context 注入；其他 hooks，包括記錄與保護 hooks，仍會執行。/clear 仍會清空 context 且不注入；要接續請 /devlog-tracker:continue（先核對「工作區」再做下一步）。細節見 docs/design/continue.md、docs/design/session-handoff-file.md。

同輪工作區漂移偵測

同一條對話送出下一則訊息時，UserPromptSubmit 會拿上一輪 Handoff 的「工作區」跟目前 git 狀態比對；不符就注入提示，並讓 PreToolUse 擋住非 devlog 工具，直到這一輪補上含實際快照的 ### 段落（唯讀的 git status／diff／log／show／rev-parse 不受影響，方便自行核對）。Span 安靜 tick、task-notification 與 DONE 不擋。細節見 docs/design/continue.md 與 docs/design/segment-watch.md。

意外中斷

非 usage 的 API 錯誤、SessionEnd、殘留的 .round-open 會把開著的 Round 標成 INTERRUPTED。usage 用光不算中斷。中途取消（例如 Esc）通常是在下一則訊息或**下次 SessionStart（startup / resume / clear / fork）**才補上；PostToolUseFailure 的 is_interrupt 若有觸發，只是 best-effort，不能當成一定會立刻蓋章。Status 下面會多一行 [reason: ...] 內部代號方便之後 debug（例如 dangling:next_prompt）；中斷當下如果是卡在等 AskUserQuestion 的回答，Summary/Handoff 會直接說明，不會寫成「意外」。細節見 docs/design/recording-moments.md。

段落記錄

長輪不要憋到最後，邊做邊寫 ### 段落。同一輪連續約 10 分鐘沒改開著的 round 檔（.round-current.md；Codex／Cursor 是 [email protected]／[email protected]），PreToolUse hook 會擋住下一個工具；先 Read 再 Edit／StrReplace 追加一段（不要 Write 覆寫整檔）。門檻可用 /devlog-tracker:segment-watch <時間長度> 調整。Claude Code subagent／dynamic workflow（PreToolUse 帶 agent_id）不套用父輪這道閥。細節見 docs/design/segment-watch.md。

Checkpoint Mode

累積約 20 輪沒寫跨輪摘要，Stop hook 會要求補一段 ## Checkpoint（Round X-Y）（門檻可調）。內容不用自由段落，標題下固定三小節：

• ### 決策 — 這段期間的定案
• ### 待解問題 — 仍懸而未決的卡點（下一 session 接手的首要線索）
• ### 失敗嘗試 — 試過但放棄的做法，避免下一任重踩

hook 偵測邏輯不變（仍只驗 ## Checkpoint 標題有沒有新增，不驗三段內容）。撰寫規則見 skills/devlog-tracker/references/checkpoint-mode.md；設計見 docs/design/checkpoint-mode.md。

Span Mode

/loop、Workflow 這類自動續接的長任務，不必每個 tick 都寫完整 Round，用 tick 計數當安全閥；崩潰最多漏記固定數量的 tick，不是整段。細節見 docs/design/span-mode.md。

Reply Fold

Claude 用純文字結尾提出問題、下一則訊息才拿到答案時，不用開新 Round——提問前先手動記一段問題原文再跑 await-open.sh 標記，下一則訊息（答案）就會自動折進同一個 Round 當一段 ### 段落，不是拆成兩個不相關的 Round。連續多輪一問一答（例如 grilling）時，中途每題只記問題段落，不必每題重寫 Summary/Reply/Handoff/Status，等整場問答真正結束才收尾一次。AskUserQuestion 在同一 turn 內問答，不用 fold，但仍要用 ### 段落（AskUserQuestion） 記下問題與答案。背景 task-notification（子 agent 完成通知）也會自動走同一套折疊機制，不留原始 XML，只記精簡摘要。細節見 docs/design/reply-fold.md。

分支各自的 devlog 檔

同一個工作目錄裡切換分支時，主檔會依目前 checkout 的分支自動分開：main／master 繼續用 .devlog/devlog.md，其他分支各自用 .devlog/devlog.<branch>.md（斜線轉成 -）。另開一個 git worktree（不同目錄）本來就有自己獨立的 .devlog/，不受這個機制影響。第一次在某分支偵測到還沒有專屬檔案時，只會把 devlog.md 裡還沒完成的尾巴（最後一個 DONE 之後的 Round，連同 handoff.md）剪到該分支的檔案；main 自己的歷史、專案摘要、Checkpoint、Kept／Lessons 索引都留在 devlog.md。最後一輪已經是 DONE，或切到的是不含目前 main 最新 commit 的舊分支時，什麼都不搬，新分支從空檔開始。分支檔的第一行是 origin 標記 <!-- devlog-origin: branch=<原始分支名> -->（渲染時看不到），記下檔名轉換後已經還原不回來的真實分支名；/devlog-tracker:keep-all 靠它分辨分支檔與具名檔，並回報該分支還在開發、已合併或已刪除。這個標記出現前就存在的舊檔維持原樣。細節見 docs/design/branch-scoped-devlog.md。

Lessons Mode（預設關閉，不自動）

開著時，Status 從 BLOCKED 解開、明顯繞路，或工作區漂移累積達門檻（預設 3 次，/devlog-tracker:lessons-drift <次數> 可調）才考慮記一筆開發歷程教訓，per-topic 存成 devlog.lessons.<topic>.md，devlog.md 只留標題索引。Claude Code 上，sub agent／Workflow agent 開始時（SubagentStart）會被注入 lessons-append.sh 的用法（絕對路徑，worktree isolation 也不會寫錯地方），可以自己記一筆；sub agent 回來或背景任務通知到達時，主 session 會看到一句 [Lessons Mode 提示]（failed／killed 另算進共用計數器）。這些訊號都完全不 hook 強制寫入本身、不是知識庫（架構決策仍在 docs/design/*.md）。細節見 docs/design/lessons-mode.md。

測試

bash core/scripts/run-tests.sh   # hook 自檢，含 Codex 轉接層
npm test                          # CLI、timeline renderer 與 scripts 的 node 測試

License

Apache-2.0