Leo
c2638668e3
leo 2026-08-20：「同一個 plugin 你用，薄殼也用，保證兩邊同步」
「我要你幫雲端做薄殼，永遠都有問題，你要做的就是這組設定
你自己可以 dogfooding」
搬進來：41 支 hook（51 條註冊）／7 支 command／2 支 skill／23 支腳本。
不搬 .env、wiki、docs——那些是知識不是環境。
51 條 hook 路徑全部從 $CLAUDE_PROJECT_DIR/.claude/hooks/ 改成 ${CLAUDE_PLUGIN_ROOT}/hooks/，
零漏網。那正是薄殼一直壞掉的根：雲端 cwd 不是真身，寫死路徑就斷。
尚未驗證：Claude Code 能不能從私有 Gitea repo 裝 marketplace（要憑證）。
下一步就是在本機實際裝一次，通了才動雲端 bootstrap.sh。
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
307 lines
19 KiB
Markdown
307 lines
19 KiB
Markdown
---
|
||
name: cp-write
|
||
description: |
|
||
要寫或改任何 CP（Critical Path）檔案之前必讀——動 system-dev/docs/3-specs/critical-paths/
|
||
底下任何檔案、標記某關卡 ✅/◐/❌、或新增一條 CP 時自動載入。
|
||
leo 2026-07-30：「上次已經跟你討論一次並且寫了正確範本，立刻全部忘光了」。
|
||
三條鐵律：寫目的不寫功能／每步交出 deliverable／code 寫完沒部署不准標 ✅。
|
||
另含 Logseq outliner 格式（給 leo 讀的 md 一律巢狀 bullet、禁表格平攤）。
|
||
---
|
||
|
||
# /cp-write — 寫或改一條 CP（Critical Path）
|
||
|
||
**要動 `system-dev/docs/3-specs/critical-paths/` 底下任何檔案之前，先跑這個。**
|
||
|
||
---
|
||
|
||
## 為什麼有這支 skill
|
||
|
||
leo 2026-07-30：「你去把寫 cp 的方法寫成 skill，**上次已經跟你討論一次並且寫了正確範本，立刻全部忘光了**。」
|
||
|
||
- **忘光的機制**（結構問題，不是記性問題）
|
||
- 規範住在 `TEMPLATE-critical-path.md`（209 行）
|
||
- CC 不會在動筆前主動讀 209 行文件 → 憑印象寫 → 寫成功能清單
|
||
- 「該讀的文件存在」≠「會被讀到」
|
||
- **同一天內 leo 糾正四次**
|
||
- 「不是有定義 CP 的寫法？outliner，步驟，有關任務」
|
||
- 「你不要再去寫一個個功能，**要寫的是目的**，每次交出 deliverable」
|
||
- 「上次說過，CP 有順序的跟無序的兩種」
|
||
- 「CP 每個步驟要拉哪些任務，**不是自己編一堆新任務**…你去搜尋先前的你寫的範本」
|
||
- ⇒ 規範要在**動筆那一刻**被載入，不是躺在檔案裡等人想起來
|
||
|
||
---
|
||
|
||
## 六條鐵律
|
||
|
||
違反就是寫錯，不是風格問題。
|
||
|
||
### 1. 寫目的，不寫功能
|
||
|
||
> leo：「你不要再去寫一個個功能，要寫的是目的，達成那個目的，**每次交出 deliverable**，而不是交出一個程式碼打勾就完成了。」
|
||
|
||
- ❌ 錯：「`/cypher/search` 接 registry」
|
||
- ✅ 對：
|
||
- **目的**：AI 拿到的答案必須是真的——假信號比沒答案更糟
|
||
- **交付物**：查詢回應含 found/missing/unknown，found 附 input_schema
|
||
- **檢查法**：每步唸出來，聽起來像「我要改哪個檔案」→ 重寫成「達成什麼、交出什麼」
|
||
|
||
### 2. 從 tasks 池子撈任務，不在 CP 裡編新任務
|
||
|
||
> leo 2026-07-30：「**如果在這裡編任務，不就是廢掉了原本的 SDD，那到底要照 SDD 做事還是照 CP？**」
|
||
|
||
🔴 **2026-08-10 leo 定調：CP 只標編號，不重抄條目。原話——**
|
||
|
||
> 「CP 寫大計劃，加上描述，然後在 issues 寫明，**在 CP 標示 issue 編號**，
|
||
> 如果是在 issue 的內部 MD，一樣寫 `issue #2, task #?`，在 issue 從**標題層級**來找，
|
||
> 只要能 mapping 某 task。CP 一向就是寫計劃，把所需的 task 標示，**避免同一條目重抄一次**。」
|
||
|
||
> leo 2026-08-10（同日補充，這句是骨架）：
|
||
> 「**SDD 的 tasks 指向 issues，CP 的 tasks 指向 issues，永遠管理 issues。**」
|
||
|
||
- **三層，只有一層可寫**
|
||
```
|
||
SDD tasks ──指向──┐
|
||
├──▶ issue ← 唯一管理處（勾選／s/* 狀態／執行細節／往返對話）
|
||
CP tasks ──指向──┘
|
||
```
|
||
- **issue＝任務池子**（`issue-handle` 2026-08-09 定調）：任務本體、勾選、狀態都只住這裡
|
||
- **SDD＝規格與設計**（為什麼要做、怎麼做）；它的 tasks 是**指向 issue 的清單**，不自己養 checkbox
|
||
- **CP＝大計劃＋排序**（現在先做哪些）；寫目的與描述，任務只放**編號 pointer**＋`w=`
|
||
- **⇒ 兩邊都只是視角，動狀態一律回 issue。**
|
||
- 🔴 **CP 裡不准出現 `- [ ]` / `- [x]`**——checkbox 就是「在發號」，而 CP 不發號
|
||
- 要知道做到哪 → 去看票。CP 只回答「這一步通不通」（三態）
|
||
- **同一條目寫兩次 = 兩份真相 = 必然漂移**（2026-08-10 實錯：CP 四筆停在事發前的世界，
|
||
issue 那邊才是對的；總管花一整輪在對帳）
|
||
- **定址：指到「一張票」，不指票裡的某一行**（D58，leo 2026-08-10）
|
||
> leo：「**充分利用 gitea 的機制，不要硬做個不支援的機制，容易出錯。**」
|
||
|
||
Gitea 原生就會把 issue 引用自動變成可點連結 ⇒ **CP 不必手貼網址、不必造錨點。**
|
||
|
||
```markdown
|
||
- `w=9` Leo/arcrun-rag#52 — 重裝到已有資料的帳號，登入與資料庫一起壞
|
||
```
|
||
|
||
- 🔴 **最好用的判準**：**需要指到票裡的某一行 ＝ 那張票該拆了。**
|
||
這個限制反而**強迫出正確的顆粒度**
|
||
- **票的刀口不是「大小」，是「狀態」**：問「它會不會需要跟隔壁那條不同的狀態？」
|
||
會 → 獨立成執行票；不會 → 留在該票裡當 checkbox
|
||
- **討論票 vs 執行票**：討論票是脈絡（不當工單追），執行票才是 CP 該指的東西
|
||
- ⚠️ **已作廢：隱形錨點 `<a id="tNNN">`**（D53，同日上線同日推翻）——**不要撿回去**。
|
||
它整段推理嚴謹，**但沒有先問「這個平台原生支援嗎」**。
|
||
造任何機制前先問：「原生支援嗎？」「不支援是不是在說我方向錯了？」
|
||
- **自檢**：CP 上任何一行任務，拿它的編號去票裡找得到唯一一條嗎？
|
||
- 找不到 → 你違規了。要嘛去票裡補，要嘛從 CP 刪掉
|
||
- **絕不能留在 CP 裡當「CP 專屬任務」**
|
||
- **`w=` 的正確用法**（leo 原話）
|
||
- 「從**很多任務**中找到跟現在目的**最近**的是誰，**把它排序到前面**」
|
||
- 「**w 是標在 task 裡，這個任務原本在 SDD 的 tasks 中，跟現在的優先級有關，我把它拉出來到前面**」
|
||
- ⇒ `w=` 的意思＝**這個 task 原本躺在 SDD 池子裡，因為跟當前目的相關，被拉到前面**
|
||
- ⇒ 是池子任務**互相比較**後的排序，**不是對單一任務憑感覺打分**
|
||
- ⇒ 同一步內的任務**依 `w=` 由高到低列**，高的先做
|
||
- 🔴 **`w=` 只能標在任務表的任務上，不能標在步驟標題上**
|
||
- leo 2026-07-30：「這個只是標題，不是從 SDD 拉出來的，**它的 w 是跟誰比是 9?**」
|
||
- 【有序】卷的每步都是必經 ⇒ **不需要排序** ⇒ 標了就是假數字
|
||
- 【無序】卷的並列項才需要 `w=`（那時它們互相比較，有意義）
|
||
- 🔴 **`w=` 只排順序，不決定誰進 CP**——進 CP 的門檻是鐵律 5 的反事實測試（最小待辦）
|
||
|
||
> leo：「**tasks 是一個任務池子，CP 是編訂 sprint 的原則。**」
|
||
|
||
- **動筆前先做兩件事**
|
||
- 看先前範本：`system-dev/docs/3-specs/autonomy-dispatch/sprint-2026-07a.md`
|
||
（里程碑表 ＋ `P1>P2>P3` 任務板，做法一致，別重新發明）
|
||
- 撈池子＝撈 issue（不是 grep `tasks.md` 的 checkbox，那份已經只是 pointer 了）：
|
||
```bash
|
||
TOKEN=$(git remote get-url gitea | sed -E 's|.*//[^:]+:([^@]+)@.*|\1|')
|
||
curl -s -H "Authorization: token $TOKEN" \
|
||
"https://git.uncle6.me/api/v1/repos/Leo/<repo>/issues?state=open&labels=s/todo"
|
||
```
|
||
- 🔴 **不帶 token 打私有 repo 回 `{"message":"not found"}`**，長得像「這裡沒東西」
|
||
（2026-08-09 實錯：據此把 24 個 open issue 宣告成不存在）
|
||
- **怎麼列**：一律 outliner 清單（鐵律 6），**必要資訊是「編號 ＋ 一句話 ＋ w ＋ 執行者」**：
|
||
```markdown
|
||
- `w=9` #2 task 3 — 讓 notify_leo 重新發得出訊息
|
||
- `w=7` #2 task 7 — 👤 leo：拿你知道答案的東西查一次
|
||
```
|
||
- 🔴 **沒有 checkbox**（鐵律 2，leo 08-10）——要看做到哪去點那張票
|
||
- 🔴 **一句話是「指路」不是「複製」**：只寫到足以認出是哪一條，
|
||
細節、實測輸出、踩到的坑**一律留在票上**
|
||
- 🔴 **不用表格**（leo 07-31 拍板，見鐵律 6）——07-30 曾說「寫表格也可以」，已被此裁定取代
|
||
- **撈不到才是真缺口** → **去開票**（或在既有票裡加一條 task），然後 CP 標它的編號
|
||
- 在**票**裡加，**不在 CP 裡加**
|
||
- **為什麼特別容易忘**：CP 看起來像 todo list，很自然就在裡面寫「我要做 A、B、C」
|
||
- 那樣做 → 同一任務在票與 CP 各一份 → 必然漂移 → 兩邊都不可信
|
||
- 2026-08-10 實錯：CP 四筆停在事發前的世界（已完成的還空著、已解除的還標危險），
|
||
而票那邊是對的。總管花一整輪對帳，leo 當場問「**我到底要看什麼？**」
|
||
|
||
### 3. 每步有可執行的驗法
|
||
|
||
- 沒有驗法的步驟不算數——那是「宣告完成」的溫床
|
||
- 驗法要是**可執行的動作**（跑什麼指令、看什麼回應），不是「檢查是否完成」
|
||
- **考試三要素必須定義**（leo 2026-07-31：「誰主動、誰被動、正確答案是什麼，這些角色你沒有定義」）
|
||
- **考生（主動）／受測物（被動）／正確答案**——三者寫在每步的「考試角色」行
|
||
- **考不過＝迭代受測物**，不改題目、不怪考生
|
||
- 受測物是環境（指引/引導）→ 考不過改環境（例：步驟 1「我給它一個環境它考不過，就是我的環境要迭代」）
|
||
- 受測物是系統 → 回應不正確改系統（例：「haiku 給它一個需求回應不正確，就是系統要迭代」）
|
||
- **有前端的關，`HTTP 200` 不算驗過**
|
||
- 要抓實際畫面內容：`curl <網址> | grep <該出現的字串>`
|
||
|
||
### 4. 用 PM 的態度定狀態：**deliver 才算通，不是我實測過就算**
|
||
|
||
> leo 2026-07-30：「最終不是要實測，**是要 deliver**，你在本地實測完沒推沒 deploy 也用不了，
|
||
> **最後要讓收的人可以實測**，你要抱着 **PM 的態度**，不是開發者的態度。」
|
||
|
||
- **判準只有一句**：**收的人現在能不能自己驗到？** 不能 → 沒通
|
||
- 「收的人」＝leo／封測者／下一個 AI，看這條 CP 服務誰
|
||
- 三種狀態
|
||
- `✅ 通` — **收的人已經驗到了**（貼他驗到的證據，不是我的）
|
||
- `◐ 半通` — 我這端做完且驗過，但**還沒到收的人手上**；必須標明「卡在哪一段運送」
|
||
- `❌ 斷` — 沒接上／沒發佈／沒人能用
|
||
- 🔴 **開發者態度 vs PM 態度**（開發者會說 → PM 要追問）
|
||
- 「`tsc` 零錯誤、測試綠」→ 部署了嗎？
|
||
- 「commit 了」→ push 了嗎？
|
||
- 「push 了」→ 收的人拿得到嗎？（要不要重裝／解保險）
|
||
- 「部署成功」→ 他點下去看到對的東西嗎？
|
||
- **運送鏈缺一段就不算通**：改完 → commit → push → 打包 → 部署 → **收的人重裝／重連** → 他驗到
|
||
- 反覆的失敗模式：registry 機制完整但沒觸發／`acr search` 寫好沒發佈／
|
||
ingest 通了沒人餵／daemon 修好但 leo 手上還是舊版
|
||
- 每件都「做完了」，**收的人手上沒有**
|
||
|
||
### 5. 拉的是「最小待辦」（MVP），不是「相關任務清單」
|
||
|
||
> leo 2026-07-31：「CP 是要達成這個目標而**從池子裡拉出的最小待辦**，
|
||
> 如果不做這些也通過，就表示這些任務不屬於最小待辦。」
|
||
> 「最小待辦類似 **MVP** 概念——如果有 500 個任務，全部做完要很久，但現在要的是最小待辦。」
|
||
|
||
- **成員資格測試（反事實）**：拉任務進 CP 前問一句——
|
||
「**不做這個，該步的驗法（考試）會不會掛？**」會掛才進。
|
||
只是「跟目的相關」不夠：**相關 ≠ 必要**。
|
||
- **步驟驗法通過時，逐筆對帳還沒完成的**，三選一（leo 原話給的處置）：
|
||
1. **評估出錯** → 檢討選任務的方法（寫進 mistakes.md）
|
||
2. **移出 CP，以後完成**（票留著照常排，CP 刪掉那行 pointer）
|
||
3. **已無需要** → 回票上結案
|
||
- 🔴 非必要任務掛在 CP 上會**稀釋整個儀表板的訊號**——leo 看 CP 判「還差多遠」
|
||
- 🔴 **勾選一律回票上做，不在 CP**（鐵律 2，leo 08-10）
|
||
- 舊版寫「做完就勾」（leo 08-01），指的是**別把做完的事留白**——那個意圖沒變，
|
||
只是**勾的地方換了**：從 CP 換到票
|
||
- CP 這一側對應的動作＝**該步的三態現況要更新**（✅／◐／❌），那才是 CP 的本職
|
||
- **要 leo 做的也是待辦**（leo：「如果有要我做什麼，這也是待辦，但**執行者是我**」）
|
||
- 🔴 **它必須是一張撈得到的票，不能只住 CP**（leo 08-10：「執行到要我 input 時要標示 Stage，
|
||
我去完成，**但 CP 的無法標示**」）
|
||
- CP 是 markdown，**沒有 label 可掛 ⇒ leo 的看板撈不到 ⇒ 對他等於不存在**
|
||
- ⇒ 人閘動作（arm／confirm／真機驗）一律**掛 `s/stage`**（規格見 `issue-handle`），
|
||
CP 這邊只留一行 `👤 leo` 的 pointer
|
||
- 標 `s/stage` **不等於交棒完成**——回覆裡要帶「打開什麼／該看到什麼／什麼算失敗」三件，
|
||
且指令自己先打過（`issue-handle` 有全文）
|
||
- 並同步 status「待 leo」清單＋每日催辦——不是只寫在對話裡
|
||
- 🚚 「合主線／發版／部署／等 arm」＝**運送殘項**，另起一行標 🚚，不佔任務位
|
||
- 🔴 **一筆待辦只准一個執行者**（leo 07-31：「這不是一個任務，是 2 個，
|
||
兩個主詞不同怎麼寫在一起？」）——主詞不同就拆成多筆，各自標執行者；
|
||
有先後依賴用「A 之後」寫在後筆開頭，不用「→」把兩人的事串成一筆
|
||
- **踩雷實例（2026-07-31 arcrun-usable 步驟 1）**：掛了 4 筆 `w=` 高的任務，
|
||
一筆都沒做完、考試照樣 10/10 ＝全非最小待辦；而真擋 ✅ 的那筆
|
||
（安裝器 seed skills）**反而不在清單上**。
|
||
病根＝用「關鍵字相關度」順撈池子（語意相近的多半是同 SDD 的鄰居工單），
|
||
但真最小待辦常在**別的環節**（交付鏈／安裝器／人閘）
|
||
⇒ **從驗法反推需要什麼，不從池子順撈相關的**。
|
||
|
||
### 6. 格式＝Logseq outliner，不用表格
|
||
|
||
> leo 2026-07-31：「我是個 Logseq 用戶……表格 + header 對閱讀不利，我看不出記錄彼此的層級，
|
||
> 全部平攤。**全部用 logseq outliner，可以用 outline + header，不要太花，保持乾淨簡潔。**」
|
||
> 「skill 寫明用 outliner，**不要一改版整個跑掉**。」
|
||
|
||
- **層級用巢狀 bullet 呈現**，不用表格——表格把層級平攤掉，Logseq 讀不出結構
|
||
- header 可以用，但只切大段（卷名／成功標準／六步／總驗收），不要每小節都開 header
|
||
- 不要太花：emoji／粗體節制，狀態記號（✅◐❌／👤）保留因為有功能
|
||
- 適用範圍：**CP、給 leo 讀的一切 md**（wiki、報告、交棒文件同此）
|
||
- 🔴 此條取代 07-30「寫表格也可以」——**改版時不准把格式改回表格**，本鐵律就是防跑掉的錨
|
||
|
||
---
|
||
|
||
## 執行流程
|
||
|
||
### 第一步 — 確認這是哪一條 CP
|
||
|
||
```bash
|
||
ls system-dev/docs/3-specs/critical-paths/
|
||
cat system-dev/docs/3-specs/critical-paths/README.md
|
||
```
|
||
|
||
- **新主題要另立一卷**，不塞進既有卷（leo：「你只有一個，這樣太大了」）
|
||
- **行數門檻**（07-30 實測後修正）
|
||
- 目標 **100 行內**；**上限 200 行**（六步以上的卷，池子任務表格本身就佔百餘行）
|
||
- 超過先問：**多出來的是「池子任務表格」還是「執行細節」？**
|
||
- 池子任務表格 → **留著**，那是 CP 的核心（拉任務＋距離）
|
||
- 執行細節／實測全文／糾正史 → 搬 `_evidence/`，CP 只留一行結論＋指針
|
||
|
||
### 第二步 — 判斷【有序】還是【無序】，標在標題上
|
||
|
||
- **【有序】** — 前步不通，後步沒意義
|
||
- 寫法：步驟 1→N 鏈狀；斷點按順序列、標「前置」
|
||
- 例：安裝→萃取→查詢→MCP／AI 想到→查詢→替換→執行
|
||
- **【無序】** — 並列能力，各自算分
|
||
- 寫法：每項獨立標 `w=`／狀態；**不寫「前置」**
|
||
- 例：「知識可收集、可查、可追」＝三種能力並列
|
||
- **判斷法**：把第 2 步拿掉，第 3 步還有意義嗎？
|
||
- 沒意義 → 有序
|
||
- 還有意義 → 無序
|
||
- **可混合**：有序主鏈 ＋ 無序支線（支線另開一段標【無序】，別硬塞進鏈裡）
|
||
|
||
### 第三步 — 每步寫四件事
|
||
|
||
```markdown
|
||
### 步驟 N｜<一句話目的> `w=9` ◐ 半通
|
||
|
||
**目的**：<達成什麼。沒參與的人也看得懂>
|
||
**交付物**：<交出什麼可驗的東西。不是「改好某個檔案」>
|
||
**驗法**：<可執行的動作。有前端要抓畫面內容>
|
||
**現況**：<實測到什麼。附證據>
|
||
|
||
**最小待辦**（鐵律 5：過反事實測試才進；要 leo 做的標 👤 leo）
|
||
- [ ] <任務——出處 SDD>
|
||
- [ ] 👤 leo：<人閘動作>
|
||
|
||
**移回 SDD 池**（曾拉進來但驗證非必要的，留一行去向）
|
||
```
|
||
|
||
### 第四步 — 斷點與「不在 CP 上」
|
||
|
||
- 🔴 斷點段（outliner，一行一斷點）：`- 步 N <斷點>——前置：<步>；<為什麼卡>`
|
||
- ⚪ 不在 CP 上：`- <項目>（<為什麼不阻斷>）`
|
||
- **一定要寫**——不寫下來就會反覆被它吸走注意力
|
||
|
||
### 第五步 — 進度數字
|
||
|
||
- 卷尾一行：`**進度：N 完成／M 進行中／K 未做（共 T）**`
|
||
- 有機械驗收（如 `verify.sh`）→ **以它為準**，並註明「此清單是人看的」
|
||
|
||
---
|
||
|
||
## 收工檢查
|
||
|
||
逐條自問，答不出來就是沒寫完。
|
||
|
||
1. 每步都是「目的＋交付物」，不是「改哪個檔案」？
|
||
2. 子項是**從池子撈的**（有「出處」欄）？撈不到的標了 `➕ 待加 <SDD>`？
|
||
3. 動筆前**看過先前範本**（`autonomy-dispatch/sprint-2026-07a.md`）？
|
||
4. 標了【有序】／【無序】？
|
||
5. 每步驗法**可執行**？有前端的抓了畫面內容？
|
||
6. **有 `✅` 的，是「收的人驗到」的證據，不是我自己測過？**
|
||
- 運送鏈走完了嗎：改完 → commit → push → 打包 → 部署 → **收的人重裝** → 他驗到
|
||
- 缺任一段 → 最多 `◐`，且要標「卡在哪一段」
|
||
7. 寫了「不在 CP 上」？
|
||
8. 這一卷在 200 行內？超過的部分是「池子任務表格」（可留）還是「執行細節」（要搬）？
|
||
9. **CP 檔真的改了**？（leo 07-26：「我看 CP 也沒用，因為你執行時沒去更新」）
|
||
10. **每筆任務都過了反事實測試**（不做它驗法會掛）？要 leo 做的標了 👤 並進催辦？
|
||
驗法通過的步驟，空 checkbox 對帳完了（檢討／移回池子／標完成或刪）？
|
||
11. **全卷 Logseq outliner、零表格**（鐵律 6）？層級縮排看得出來？沒有太花？
|
||
|
||
---
|
||
|
||
## 相關
|
||
|
||
- 完整規範（含踩雷案例）：`system-dev/docs/3-specs/TEMPLATE-critical-path.md`
|
||
- 分卷規則：`system-dev/docs/3-specs/critical-paths/README.md`
|
||
- 先前範本（拉任務＋標距離）：`system-dev/docs/3-specs/autonomy-dispatch/sprint-2026-07a.md`
|
||
- 執行細節該放哪：`system-dev/docs/3-specs/critical-paths/_evidence/`
|