From 77e75049829e3a45604918078f6d5c4fbe3e7309 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Thu, 27 Aug 2026 11:20:30 +0800 Subject: [PATCH] =?UTF-8?q?docs(sdlc):=20=E5=8F=83=E8=80=83=E6=96=87?= =?UTF-8?q?=E4=BB=B6=E8=88=87=20README=20=E5=90=8C=E6=AD=A5=E9=9A=8E?= =?UTF-8?q?=E6=A2=AF=E3=80=81=E5=B7=A5=E4=BD=9C=E5=8C=85=E9=9A=94=E9=9B=A2?= =?UTF-8?q?=E8=88=87=E6=97=A5=E8=AA=8C=E7=B2=92=E5=BA=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What：`references/branch.md` 新增「分支階梯與 base 推導」一節（只寫拿到 `jsc-git/tools/base-branch.sh --derive` 回應之後要做什麼）與「工作包隔離」一節（歸屬依據、狀態檔欄位、誰寫誰讀、查無歸屬放行、逃生門），閘門分工那一表補上 `claim`、`lock`、`owns`。`references/stage-report.md` 改寫暫存那一節，講明本節只適用於「還沒完成任何任務就停下」的階段。README 的工具表、`implement` 與 `maintain` 兩段說明、參考文件表與相依技能清單同步更新。 Why：階梯表與歸屬狀態檔的正本各有其處——階梯在 `jsc-meta` 的 `references/guidelines.md`，狀態檔格式在 `jsc-hooks`。抄第二份就會有兩份互相打架的規則，但完全不提又會讓實作階段不知道拿到 `7` 或「已建立功能主幹」時該做什麼。 How：兩節都只寫本階段要做的事，並把唯一來源用連結指出去。`branch.md` 的階梯那一節寫成一張「腳本回應 → 這個階段要做的事」對照表，`7` 明寫成「中止並問使用者，不退回 `develop`」。`stage-report.md` 補一句「暫存不等於已寫入」，因為日誌改成一個任務一筆之後，做完事情的階段本來就有日誌可連。 Who：讀 `jsc-sdlc` 參考文件與 README 的人，以及跑實作與維護兩階段的工作階段。 --- README.md | 12 ++++++------ references/branch.md | 30 +++++++++++++++++++++++++++--- references/stage-report.md | 5 ++++- 3 files changed, 37 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 2e25454..9a23ed9 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安 | 腳本 | 用途 | | --- | --- | -| `tools/wp-gate.sh` | 工作包 PR 閘門，把「一個工作包的 PR 沒合併，擋的是相依於它的工作包，不是整份分析」從內文敘述變成程式判定，共三個用法。`check {owner}/{repo} {index} [--since {ISO 時間}]` 查一支 PR：已合併就呼叫 `jsc-hooks` 的 `sdlc-gate.sh wp-unlock` 解鎖並印 `status=merged`；沒合併就印 `status=open` 或 `status=closed-unmerged`（被關掉但沒合併不算完成），接著把 issue 留言、審查評語、行內留言全部逐行印出（`--since` 只印更新的，值取上一輪的 `latest=`），最後一行印 `latest={最新一筆留言的時間戳}` 供寫回分析頁。`check-deps {owner}/{repo} {wp-number}` 查某個候選工作包能不能挑：活抓分析頁 WBS 表的相依欄，逐一核對每個相依工作包的狀態與 PR 是否已合併，只認同一張分析頁上的 `WP-NN` 編號，指到別份計畫的文字項目查不了就列出來要求人工確認，不當成擋人的理由。`lock {owner}/{repo} {index}` 在 PR 開好後轉呼叫 `sdlc-gate.sh wp-lock` 記下未結清（一個工作包一支鎖檔，可以同時記好幾筆平行進行的工作包）。第一行固定 `status=...` 供程式判讀，其後為繁中說明；結束碼 `0`=已合併或無阻擋（含 `check-deps` 的 `ready`）、`1`=未合併或 `check-deps` 判定 `blocked`、`2`=用法錯誤、`3`=相依工具或 PR／分析頁查不到（**查不到就擋，不放行**）。狀態檔由 `jsc-hooks` 管（`$JSC_HOME/wp/{owner}-{repo}-{index}.pr`，不綁 session，開新對話照樣擋），本檔只負責查詢與結清 | +| `tools/wp-gate.sh` | 工作包 PR 閘門，把「一個工作包的 PR 沒合併，擋的是相依於它的工作包，不是整份分析」從內文敘述變成程式判定，共三個用法。`check {owner}/{repo} {index} [--since {ISO 時間}]` 查一支 PR：已合併就呼叫 `jsc-hooks` 的 `sdlc-gate.sh wp-unlock` 解鎖並印 `status=merged`；沒合併就印 `status=open` 或 `status=closed-unmerged`（被關掉但沒合併不算完成），接著把 issue 留言、審查評語、行內留言全部逐行印出（`--since` 只印更新的，值取上一輪的 `latest=`），最後一行印 `latest={最新一筆留言的時間戳}` 供寫回分析頁。`check-deps {owner}/{repo} {wp-number}` 查某個候選工作包能不能挑：活抓分析頁 WBS 表的相依欄，逐一核對每個相依工作包的狀態與 PR 是否已合併，只認同一張分析頁上的 `WP-NN` 編號，指到別份計畫的文字項目查不了就列出來要求人工確認，不當成擋人的理由。`claim {owner}/{repo} {wp-number} [--analyze {分析頁頁名}]` 在領包當下轉呼叫 `sdlc-gate.sh wp-claim` 登錄歸屬。`lock {owner}/{repo} {index} [--wp {wp-number}]` 在 PR 開好後轉呼叫 `sdlc-gate.sh wp-lock` 記下未結清，`--wp` 把 PR 掛到該工作包名下。`owns {owner}/{repo} {index} [--wp {wp-number}]` 比對這支 PR 是不是自己這一包的：`owned` 放行、`foreign` 擋住並指出它掛在哪一包名下、查無歸屬（沒有領取紀錄、工作包還沒掛上 PR）一律 `unowned` 放行只提醒。第一行固定 `status=...` 供程式判讀，其後為繁中說明；結束碼 `0`=已合併或無阻擋（含 `check-deps` 的 `ready`、`claim` 的 `claimed`、`owns` 的 `owned` 與 `unowned`）、`1`=未合併、`check-deps` 判定 `blocked` 或 `owns` 判定 `foreign`、`2`=用法錯誤、`3`=相依工具或 PR／分析頁查不到（**查不到就擋，不放行**），或歸屬登錄不了。狀態檔由 `jsc-hooks` 產生（領取檔 `$JSC_HOME/wp/{owner}-{repo}.claim`、鎖檔 `$JSC_HOME/wp/{owner}-{repo}-{index}.pr`，純文字 key=value 一行一欄），不綁 session，開新對話照樣擋；本檔只讀不寫，寫入一律走 `sdlc-gate.sh` 的子命令 | | `tools/stage-report.sh` | 階段收尾回報，四個階段共用。`stage-report.sh {plan\|analyze\|implement\|maintain}` 加 `--page TYPE:PAGE`（本階段寫過的每一頁，可重複）產出繁中回報：模型閘門判定（轉述 `sdlc-gate.sh report`，不自評）、工作日誌連結（`--worklog`、`--worklog-heading` 組出導向條目標題的錨點）、所有寫入的 wiki 絕對網址。實作階段再加 `--worktree`、`--source-branch`、`--work-branch`、`--target-branch`、`--pr`，來源分支在不在遠端、工作分支幾個 commit、推送了沒，都由腳本現查。沒有工作日誌時警告使用者檢查，並用 `--pending-file`、`--log-hash` 把內容交給 `jsc-log/tools/worklog-pending.sh` 暫存，下次寫日誌一併寫入。結束碼 `0`=完整、`1`=有警告（**警告不是阻擋**）、`2`=用法錯誤、`3`=相依工具找不到 | ## Skills 目錄 @@ -41,11 +41,11 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安 ### `implement` -實作：先確認來源分支（同時是 PR 目標）→ 領包前先跑 `tools/wp-gate.sh check` 把每個已開 PR 但沒合併的工作包留言逐筆印出並修正（以 sub agent 回原 worktree、推同一條工作分支，不開第二個 PR），**這一步只結清舊 PR 的留言，不擋別的工作包**——修不動或純討論的留言忽略但要在回報裡列出，處理過的時間戳寫回分析頁的 PR 欄位當下一輪的 `--since` → 產生工作證鎖定「未完成、無工作證」的候選工作包（交付工作包優先），**每個候選都跑 `tools/wp-gate.sh check-deps` 判斷能不能挑**：活查它在分析頁上的相依工作包是否都已合併，只有相依於它的包才會被一支未合併的 PR 擋住，跟它無關的工作包可以平行進行 → 交付工作包開工前先確認交付內容（API 文件、由使用者輸入，見 `references/deliver-formats.md`）→ **動程式碼前先從 `origin/{source-branch}` 建立 worktree**（`.worktree/{analysis-HASH}/{wp-number}/{repo}`，一個工作包一個 worktree，分支處理依決策樹詢問）→ 在 worktree 內逐項 TDD 實作、每完成一項立即更新 wiki → 程式碼審查 → **每完成一個工作包就 commit、push、PR 回來源分支**（一包一 PR），接著 `tools/wp-gate.sh lock` 上鎖，合併後解鎖並移除 worktree → 詢問交付文件格式（`DELIVER_{HASH}` wiki 頁或 Gitea 議題留言）並產出 → 詢問是否加入維護目錄 → 階段回報（`tools/stage-report.sh`，多報工作目錄與來源、工作、目標三條分支）。寫程式碼時註解只寫「為什麼這樣寫」，工作包編號、分析頁編號、待辦編號、分支名、PR 編號一律不寫進註解，完整清單與白名單見 `jsc-review` 的 `references/comment-scope.md`。 +實作：先確認來源分支（同時是 PR 目標）→ 領包前先跑 `tools/wp-gate.sh check` 把每個已開 PR 但沒合併的工作包留言逐筆印出，動手前先跑 `tools/wp-gate.sh owns` 確認那支 PR 是自己這一包的，再依 `jsc-ask:ask` 決策樹與使用者對每一則留言達成共識才修（以 sub agent 回原 worktree、推同一條工作分支，不開第二個 PR），**這一步只結清舊 PR 的留言，不擋別的工作包**——修不動或純討論的留言忽略但要在回報裡列出，處理過的時間戳寫回分析頁**既有**的 PR 欄位當下一輪的 `--since` → 產生工作證鎖定「未完成、無工作證」的候選工作包（交付工作包優先），**每個候選都跑 `tools/wp-gate.sh check-deps` 判斷能不能挑**：活查它在分析頁上的相依工作包是否都已合併，只有相依於它的包才會被一支未合併的 PR 擋住，跟它無關的工作包可以平行進行 → 領到包立刻跑 `tools/wp-gate.sh claim` 記下歸屬 → 交付工作包開工前先確認交付內容（API 文件、由使用者輸入，見 `references/deliver-formats.md`）→ **動程式碼前先從 `origin/{source-branch}` 建立 worktree**（`.worktree/{analysis-HASH}/{wp-number}/{repo}`，一個工作包一個 worktree，分支處理依決策樹詢問）→ 在 worktree 內逐項 TDD 實作、每完成一項立即更新 wiki → 程式碼審查 → **每完成一個工作包就 commit、push、PR 回來源分支**（一包一 PR），接著 `tools/wp-gate.sh lock --wp` 上鎖並登記 PR 歸屬 → **用 `jsc-gitea/tools/pr-watch.sh` 盯到合併**（預設 60 秒輪詢、不自動退場；退出碼 `0` 已合併或關閉、`10` 有新留言就回頭跑同一套留言修正、`3` 查不到該 PR、`2` 參數或環境有問題），合併後解鎖並移除 worktree → 詢問交付文件格式（`DELIVER_{HASH}` wiki 頁或 Gitea 議題留言）並產出 → 詢問是否加入維護目錄 → 階段回報（`tools/stage-report.sh`，多報工作目錄與來源、工作、目標三條分支）。**每完成一個任務就寫一筆工作日誌**（`jsc-log:worklog`）：一個工作包、一輪 PR 留言修正、一個獨立的修正提交各算一個任務，不等到階段結束才補一次；`stage-report.sh --pending-file` 暫存的內容併進同一次寫入，寫入成功才清除。寫程式碼時註解只寫「為什麼這樣寫」，工作包編號、分析頁編號、待辦編號、分支名、PR 編號一律不寫進註解，完整清單與白名單見 `jsc-review` 的 `references/comment-scope.md`。 ### `maintain` -維護：讀取維護期內的專案，每個專案一個 sub agent：fetch 後切 develop、master 並對齊 `origin/{branch}` → 提出至少五種維護方法，依決策樹讓使用者挑要做哪些 → commit / push / PR → 更新前次維護時間 → 階段回報（`tools/stage-report.sh`）。sub agent 改程式碼時註解只寫「為什麼這樣寫」，議題編號、commit hash、分支名、人名與 `@` 提及一律不寫進註解，完整清單與白名單見 `jsc-review` 的 `references/comment-scope.md`。僅適用於維護期內已交付的專案；尚在實作中或未登記於 `MAINTAIN_CONTENTS` 的專案不適用。 +維護：讀取維護期內的專案，每個專案一個 sub agent：fetch 後切 develop、master 並對齊 `origin/{branch}` → 提出至少五種維護方法，依決策樹讓使用者挑要做哪些 → commit / push / PR → **PR 開好立刻寫一筆工作日誌**（`jsc-log:worklog`，一個專案一筆，下一個專案開工前要先寫完）→ 更新前次維護時間 → 階段回報（`tools/stage-report.sh`）。sub agent 改程式碼時註解只寫「為什麼這樣寫」，議題編號、commit hash、分支名、人名與 `@` 提及一律不寫進註解，完整清單與白名單見 `jsc-review` 的 `references/comment-scope.md`。僅適用於維護期內已交付的專案；尚在實作中或未登記於 `MAINTAIN_CONTENTS` 的專案不適用。 @@ -61,7 +61,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安 | `references/stage-report.md` | 階段回報：四階段都要交的三項（模型能力標籤、工作日誌連結、所有寫入的 wiki 連結）、實作階段多交的四項、沒寫日誌時的暫存規則、提前停止也要回報 | | `references/model-gate.md` | 模型閘門：執行順序、各階段必要標籤、阻擋與回報的鐵則 | | `references/tdd.md` | 接縫、紅綠循環規則、反模式 | -| `references/branch.md` | 分支規則：**一律以遠端 `origin/{branch}` 為準、動作前先 fetch**、分析前確認來源分支、實作沿用同一條來源分支作為 PR 目標（一包一 PR，一個工作包的 PR 沒合併只擋相依於它的工作包，不擋整份分析，閘門分工見該檔）、實作一律在 `.worktree/{HASH}/{wp-number}/{repo}` 內進行——一個工作包一個 worktree，讓互不相依的工作包能平行進行不互相搶路徑（建立前問分支、PR 合併後才移除）、判定遠端預設分支、不破壞未提交變更 | +| `references/branch.md` | 分支規則：**一律以遠端 `origin/{branch}` 為準、動作前先 fetch**、分析前確認來源分支、實作沿用同一條來源分支作為 PR 目標（一包一 PR，一個工作包的 PR 沒合併只擋相依於它的工作包，不擋整份分析，閘門分工與工作包隔離的狀態檔格式見該檔）、分支階梯（表本身在 `jsc-meta` 的 `references/guidelines.md`「PR 分支階梯」，該檔只寫 sdlc 拿到 `jsc-git/tools/base-branch.sh --derive` 的回應之後要做什麼、推不出就中止問使用者）、實作一律在 `.worktree/{HASH}/{wp-number}/{repo}` 內進行——一個工作包一個 worktree，讓互不相依的工作包能平行進行不互相搶路徑（建立前問分支、PR 合併後才移除）、判定遠端預設分支、不破壞未提交變更 | | `references/consensus.md` | 規劃與分析的提問規則：一輪不算問完、共識的兩個判定條件、未決項處理 | | `references/deliver-formats.md` | 交付內容型別：API 文件必備欄位、範例資料優先序、既有端點的新舊參數標示 | @@ -75,7 +75,7 @@ HASH 規則：`{owner}/{repo}` 的共用 wiki hash 一律由 `jsc-gitea/tools/ha - [`jsc-cli`](https://gitea.jsc.idv.tw/plugins/cli)：模型能力標籤與階段閘門判定（`tools/model-tags.sh`、`references/model-tags.md`、`jsc-cli:models`）、偏好模型鏈（`tools/model-config.sh`） - [`jsc-hooks`](https://gitea.jsc.idv.tw/plugins/hooks)：sdlc-gate 階段模型鎖定 -- [`jsc-gitea`](https://gitea.jsc.idv.tw/plugins/gitea)：wiki 讀寫 +- [`jsc-gitea`](https://gitea.jsc.idv.tw/plugins/gitea)：wiki 讀寫、實作階段等 PR 合併的輪詢（`tools/pr-watch.sh`） - [`jsc-review`](https://gitea.jsc.idv.tw/plugins/review)：實作完成後的程式碼審查 - [`jsc-git`](https://gitea.jsc.idv.tw/plugins/git) / [`jsc-pkg`](https://gitea.jsc.idv.tw/plugins/pkg)：維護階段的 commit / PR 與套件更新 -- [`jsc-log`](https://gitea.jsc.idv.tw/plugins/log)：完工後的工作日誌 +- [`jsc-log`](https://gitea.jsc.idv.tw/plugins/log)：工作日誌，每完成一個任務就寫一筆 diff --git a/references/branch.md b/references/branch.md index b1c9fbe..c2c22c5 100644 --- a/references/branch.md +++ b/references/branch.md @@ -60,6 +60,17 @@ SDLC 各階段引用的參考分支與來源分支，**一律指遠端的 `origi - 需要換分支才能讀到正確現況時，**停下來請使用者自己切換**。 - 不代為 `switch`、不 `stash`、不動工作區、不建分支。 +## 分支階梯與 base 推導 + +階梯表本身（哪一種類型往上接哪一條、`{子功能}` 怎麼組、base 為什麼一律由 `jsc-git/tools/base-branch.sh --derive` 推導）的唯一來源，在 `jsc-meta` 的 [`references/guidelines.md`](https://gitea.jsc.idv.tw/plugins/meta/src/branch/develop/references/guidelines.md)「PR 分支階梯」那一節。本檔不抄第二份，只寫 sdlc 拿到腳本回應之後要做什麼： + +| 腳本回應 | 這個階段要做的事 | +| --- | --- | +| 印出一條分支名（結束碼 `0`） | 拿它當 `jsc-git:pr` 的 base，不再自行改判 | +| 結束碼 `7`（推不出唯一合法基底） | **中止並問使用者**，不退回 `develop`——退回 `develop` 就是讓子功能越級直接進主線 | +| stderr 印出「已建立功能主幹」 | 在階段回報裡講明建了哪一條主幹，那是這次實作多長出來的一條分支 | +| 結束碼 `2`（分支名含非 ASCII） | 先把中文簡述翻成英文短語，過 `jsc-git/tools/slugify.sh {類型} {英文短語}` 再重組分支名 | + ## 實作階段的分支選擇 實作在 worktree 內進行，工作分支從 `origin/{source-branch}` 長出來，做完再 PR 回同一條來源分支。 @@ -125,12 +136,25 @@ SDLC 各階段引用的參考分支與來源分支，**一律指遠端的 `origi | 層 | 誰執行 | 做什麼 | | --- | --- | --- | -| 工具閘門 | `tools/wp-gate.sh` | 唯一去問 Gitea 的一方，也是唯一有權解鎖的一方。`check` 查合併狀態、印出全部留言、印 `latest=` 時間戳，只管那一支 PR 自己；`check-deps` 查某個候選工作包能不能挑，活抓分析頁的相依欄逐一核對；`lock` 在 PR 開好後記下未結清（一個工作包一支鎖檔）。結束碼 0 放行、1 擋住、2 用法錯誤、3 查不到（查不到就擋，不放行） | -| hook 提醒 | `jsc-hooks` 的 `sdlc-gate.sh wp-check` | 只讀 `$JSC_HOME/wp/` 的狀態檔，不打網路。`prompt` 模式注入提醒但**不擋提示**；`skill` 模式擋掉 `plan`、`analyze`、`maintain`，放行 `implement`——擋住的是「跳去做別的階段」，不是「回來把這一包做完」。這一層是整個存取庫共用的粗粒度提醒，不是逐工作包判斷，細粒度的相依判斷交給 `check-deps` | +| 工具閘門 | `tools/wp-gate.sh` | 唯一去問 Gitea 的一方，也是唯一有權解鎖的一方。`check` 查合併狀態、印出全部留言、印 `latest=` 時間戳，只管那一支 PR 自己；`check-deps` 查某個候選工作包能不能挑，活抓分析頁的相依欄逐一核對；`claim` 在領包當下登錄歸屬；`lock` 在 PR 開好後記下未結清並把 PR 掛到工作包名下；`owns` 比對某支 PR 是不是自己這一包的。狀態檔的寫入一律轉呼叫 `sdlc-gate.sh`。結束碼 0 放行、1 擋住、2 用法錯誤、3 查不到（查不到就擋，不放行） | +| hook 提醒 | `jsc-hooks` 的 `sdlc-gate.sh wp-check` | 只讀 `$JSC_HOME/wp/` 的狀態檔，不打網路。`prompt` 模式注入提醒但**不擋提示**；`skill` 模式擋掉 `plan`、`analyze`、`maintain`，放行 `implement`——擋住的是「跳去做別的階段」，不是「回來把這一包做完」。這一層是整個存取庫共用的粗粒度提醒，不是逐工作包判斷，細粒度的相依判斷交給 `check-deps`，歸屬比對交給 `owns` | 狀態檔不綁 session：PR 沒合併就是沒合併，開新對話照樣擋。 -查驗程序的細節（何時帶 `--since`、留言逐筆的處理結果、修不動的留言怎麼辦、時間戳寫回哪裡）由 `skills/implement/SKILL.md` 步驟 4 擁有，本檔不重複。 +### 工作包隔離：一個工作階段只碰自己領的那一包 + +同一份分析常有好幾包平行進行，每包各自的 worktree 與 PR。動任何一支 PR 之前先確認它是自己這一包的，靠的是狀態檔而不是記憶——記憶跨不了工作階段。 + +| 項目 | 規則 | +| --- | --- | +| 歸屬依據 | **分析頁上的工作包代號**。不看分支名、不看 worktree 目錄名，那兩個都可能被改，改了也沒有徵兆。`WP-03`、`WP-3`、`3` 視為同一包 | +| 狀態檔 | 領取檔 `$JSC_HOME/wp/{owner}-{repo}.claim`（欄位 `repo`、`wp`、`pr`、`analyze`、`claimed`，一個存取庫一支）與鎖檔 `$JSC_HOME/wp/{owner}-{repo}-{index}.pr`（欄位 `repo`、`index`、`wp`、`locked`）。兩者都是純文字 key=value，一行一欄 | +| 誰寫 | 只有 `jsc-hooks` 的 `sdlc-gate.sh`：領包時 `wp-claim`、開完 PR 時 `wp-lock` 的第四個參數帶工作包代號、結清或交回時 `wp-unclaim` 與 `wp-unlock`。`wp-gate.sh` 一律轉呼叫，**不自己拼檔案**——兩邊各拼各的，格式一改就對不上，而且誰寫壞了看不出來 | +| 誰讀 | `wp-gate.sh owns` 與 `sdlc-gate.sh wp-check`，兩邊都只讀不改 | +| 查無歸屬 | **放行只提醒**：沒有分析頁、查不到工作包代號、領取檔不存在、工作包還沒掛上 PR，一律 `status=unowned` 並 exit 0。這跟「查不到就擋」不衝突——那條講的是查得到卻查失敗，這條講的是根本還沒有歸屬可查，拿不存在的歸屬擋人會讓沒登錄過的工作包全部動不了 | +| 逃生門 | `JSC_WP_GATE=off`，由 hook 那一層認 | + +查驗程序的細節（何時帶 `--since`、怎麼等 PR 合併、留言逐筆的處理結果、修不動的留言怎麼辦、時間戳寫回哪裡）由 `skills/implement/SKILL.md` 步驟 4 與步驟 11 擁有，本檔不重複。 ## 不破壞既有工作 diff --git a/references/stage-report.md b/references/stage-report.md index 842f4e8..11e3433 100644 --- a/references/stage-report.md +++ b/references/stage-report.md @@ -30,7 +30,10 @@ ## 沒寫工作日誌就暫存 -階段跑完卻沒有工作日誌，內容只留在對話裡，換一個工作階段就沒了。所以： +每完成一個任務就要寫一筆工作日誌（一個工作包、一輪 PR 留言修正、一個獨立的修正提交各算一個）， +所以做完事情的階段收尾時本來就有日誌可連。本節講的是**還沒完成任何任務就停下**的那種階段。 + +暫存不等於已寫入。內容只留在對話裡，換一個工作階段就沒了，所以： 1. 把這個階段要記的日誌內容寫成一個檔案。 2. 收尾時一起餵進去：`--pending-file {檔案} --log-hash {LOG_{HASH} 的 HASH}`。