plugins/tea-sdlc
2
0
Fork 0
Code Issues 3 Pull Requests Actions Releases Activity

feat/delegation-markers/main #64

Merged
admin merged 3 commits from feat/delegation-markers/main into master 2026-09-18 01:19:39 +00:00
Conversation 1 Commits 3 Files Changed 7
+351 -15
jiantw83 commented 2026-09-18 01:18:08 +00:00
Member
Copy Link
Copy Source

摘要

只在意結果的步驟不再把過程塞進主 agent 的脈絡。六個這樣的步驟標上 〔可委派〕，
並以能力描述而非工具名說明怎麼委派——支援子代理的平台交得出去，不支援的自然降級成
「自己做」，同一份正本兩邊都讀得通。

需求議題

#56

工作包議題

#58

變更內容

三顆 commit：

  • 3da822a docs(references): 新增委派判準，四條全部成立才可委派
  • 84cd8fc docs(prompts): 六個只在意結果的步驟標上〔可委派〕
  • f61ef3f test(delegation): 把標記與判準正本雙向綁住

新增：

  • references/delegation.md — 四條判準、能力描述的寫法、部分委派規則，以及標記表
  • test/delegation-assets.test.js — 13 條
  • test/helpers/prompt-doc.js 的 promptSteps — 步驟的名字、有沒有被標記、內文

修改：

  • prompts/sdlc-plan.md、prompts/sdlc-analyze.md、prompts/sdlc-feat.md — 各加一節
    「〔可委派〕的意思」，六個步驟加上標題後綴，三個部分委派的步驟各自寫明哪一半不委派
  • test/helpers/prompt-doc.js — promptStep 改建在 promptSteps 上，標題容得下後綴
  • AGENTS.md — references/ 那一列的列舉補上「委派判準」

被標記的六個：

正本 步驟 委派範圍
sdlc-plan 產生圖解版總覽 產出 HTML；寫回議題不委派
sdlc-analyze 對四份清單列出疑點 全步
sdlc-analyze 算出截止日 全步
sdlc-analyze 產生分析版的圖解總覽 產出 HTML；寫回議題不委派
sdlc-feat 把議題標題翻成英文 全步
sdlc-feat 分批提交 方案計算；實際提交不委派

設計重點

以能力描述表達，不指名工具。 子代理是平台專屬能力，而流程正本必須保持平台中立
（#4 已交付的驗收標準）。這個寫法刻意比它能做到的更模糊——讀到的人第一反應很可能是
「為什麼不直接寫工具名？」所以 delegation.md 明寫「不要把它改寫成工具名」，攔下那個修改。

四條判準，兩條是硬排除，各自寫上理由。 沒有理由的規則遲早會被繞過去。第二條
（不會詢問使用者）是因為子代理問不到使用者，卡在提問就只能自行決定；第四條（不直接寫入
Gitea 或 git）不是因為子代理做不好，而是它的失敗沒有人看著——備妥工作樹失敗會中止
整個領取、實際提交失敗會留下半套 git 歷史。

判準只有一份，正本不複寫。 三份正本各自那一節只留能力描述那一句與指回
references/delegation.md 的指路。抄過去就會有兩份各自演化的判準，而那正是 AGENTS.md
references/ 那一列要防的事。

「認出語言，讀規則正本」不標。 議題的列舉點了它，但它的核心動作含「認不出語言就
停下來問、不要猜」，正是判準第二條硬排除的事；排掉它之後剛好是議題所寫的六個。
這一條事前與 repo 擁有者確認過。

部分委派。 一步裡只有一半合判準時，標記照下並在該步寫明哪一半不委派。這比整步不標好
（不標的話那一半的中間產物照樣塞滿主脈絡），也比整步委派安全（第四條是硬排除）。

雙向斷言。 標記與判準表互為正本，由資產測試綁住。沒有它，兩邊會慢慢漂開，而漂開時
不會有任何東西報錯：多標一步不會壞，少列一項也不會壞，只是下一個讀的人會以為讀到的是全部。

解決的問題

  • 讀進來的整份可行性清單、試了又丟的譯名、算到一半的拓撲排序，全部留在主脈絡裡，
    把後面真正需要判斷力的步驟愈擠愈窄。
  • 「哪些步驟交得出去」沒有成文判準，只能憑感覺標，標了也沒有東西擋住標錯的。
  • 一條真 bug：標記位置的斷言原本把三種合法位置寫成 /^#{2,3} /，第二個分支把第一個
    整個吃掉，「### 沒編號的標題 〔可委派〕」會被放行。改成三條互斥的規則。
  • 幾條掃描型斷言會 fail open（掃不到任何東西時照樣是綠的），補上自我檢查。

影響的功能

  • /sdlc-plan、/sdlc-analyze、/sdlc-feat 各多一節說明，六個步驟的標題多一個後綴。
    步驟的做法與產出完全不變——委派與否，兩條路的結果必須一樣。
  • /sdlc-sync、/sdlc-fix、/sdlc-report 沒有可委派的步驟，一個字都沒改（有測試釘住）。
  • 不支援子代理的平台讀到的就是「自己做」，行為與現在完全相同。
  • 沒有任何腳本變更，Gitea 與 git 的行為不變。
  • test/helpers/prompt-doc.js 的 promptStep 介面不變，只是改建在 promptSteps 上，
    並讓步驟標題容得下後綴。

測試結果

npm test（含新增的 13 條）：

ℹ tests 878
ℹ suites 0
ℹ pass 878
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 26026.829237

另外做了三次故意破壞，確認新的斷言真的抓得住（每次都已還原）：

① 從判準表刪掉一列「| `sdlc-feat` | 把議題標題翻成英文 |」  → 3 條失敗
② 把會問使用者的「### 3. 問來源分支」標成可委派            → 9 條失敗
③ 把 sdlc-fix 沒編號的「### 工作包議題」標成可委派          → 2 條失敗
   （這一項在修掉標記位置那條斷言之前是 0 條失敗，正是本次修掉的 bug）

reviewer 可自行重現：git diff origin/master 後 npm test；上面三次破壞用
sed 改一行再跑 node --test test/delegation-assets.test.js 即可。

## 摘要 只在意結果的步驟不再把過程塞進主 agent 的脈絡。六個這樣的步驟標上 `〔可委派〕`， 並以**能力描述而非工具名**說明怎麼委派——支援子代理的平台交得出去，不支援的自然降級成 「自己做」，同一份正本兩邊都讀得通。 ## 需求議題 #56 ## 工作包議題 #58 ## 變更內容 三顆 commit： - `3da822a` docs(references): 新增委派判準，四條全部成立才可委派 - `84cd8fc` docs(prompts): 六個只在意結果的步驟標上〔可委派〕 - `f61ef3f` test(delegation): 把標記與判準正本雙向綁住 新增： - `references/delegation.md` — 四條判準、能力描述的寫法、部分委派規則，以及標記表 - `test/delegation-assets.test.js` — 13 條 - `test/helpers/prompt-doc.js` 的 `promptSteps` — 步驟的名字、有沒有被標記、內文 修改： - `prompts/sdlc-plan.md`、`prompts/sdlc-analyze.md`、`prompts/sdlc-feat.md` — 各加一節 「〔可委派〕的意思」，六個步驟加上標題後綴，三個部分委派的步驟各自寫明哪一半不委派 - `test/helpers/prompt-doc.js` — `promptStep` 改建在 `promptSteps` 上，標題容得下後綴 - `AGENTS.md` — `references/` 那一列的列舉補上「委派判準」 被標記的六個： | 正本 | 步驟 | 委派範圍 | | --- | --- | --- | | `sdlc-plan` | 產生圖解版總覽 | 產出 HTML；寫回議題不委派 | | `sdlc-analyze` | 對四份清單列出疑點 | 全步 | | `sdlc-analyze` | 算出截止日 | 全步 | | `sdlc-analyze` | 產生分析版的圖解總覽 | 產出 HTML；寫回議題不委派 | | `sdlc-feat` | 把議題標題翻成英文 | 全步 | | `sdlc-feat` | 分批提交 | 方案計算；實際提交不委派 | ## 設計重點 **以能力描述表達，不指名工具。** 子代理是平台專屬能力，而流程正本必須保持平台中立 （#4 已交付的驗收標準）。這個寫法**刻意比它能做到的更模糊**——讀到的人第一反應很可能是 「為什麼不直接寫工具名？」所以 `delegation.md` 明寫「不要把它改寫成工具名」，攔下那個修改。 **四條判準，兩條是硬排除，各自寫上理由。** 沒有理由的規則遲早會被繞過去。第二條 （不會詢問使用者）是因為子代理問不到使用者，卡在提問就只能自行決定；第四條（不直接寫入 Gitea 或 git）不是因為子代理做不好，而是**它的失敗沒有人看著**——備妥工作樹失敗會中止 整個領取、實際提交失敗會留下半套 git 歷史。 **判準只有一份，正本不複寫。** 三份正本各自那一節只留能力描述那一句與指回 `references/delegation.md` 的指路。抄過去就會有兩份各自演化的判準，而那正是 AGENTS.md `references/` 那一列要防的事。 **「認出語言，讀規則正本」不標。** 議題的列舉點了它，但它的核心動作含「認不出語言就 停下來問、不要猜」，正是判準第二條硬排除的事；排掉它之後剛好是議題所寫的六個。 這一條事前與 repo 擁有者確認過。 **部分委派。** 一步裡只有一半合判準時，標記照下並在該步寫明哪一半不委派。這比整步不標好 （不標的話那一半的中間產物照樣塞滿主脈絡），也比整步委派安全（第四條是硬排除）。 **雙向斷言。** 標記與判準表互為正本，由資產測試綁住。沒有它，兩邊會慢慢漂開，而漂開時 不會有任何東西報錯：多標一步不會壞，少列一項也不會壞，只是下一個讀的人會以為讀到的是全部。 ## 解決的問題 - 讀進來的整份可行性清單、試了又丟的譯名、算到一半的拓撲排序，全部留在主脈絡裡， 把後面真正需要判斷力的步驟愈擠愈窄。 - 「哪些步驟交得出去」沒有成文判準，只能憑感覺標，標了也沒有東西擋住標錯的。 - 一條真 bug：標記位置的斷言原本把三種合法位置寫成 `/^#{2,3} /`，第二個分支把第一個 整個吃掉，「### 沒編號的標題 〔可委派〕」會被放行。改成三條互斥的規則。 - 幾條掃描型斷言會 fail open（掃不到任何東西時照樣是綠的），補上自我檢查。 ## 影響的功能 - `/sdlc-plan`、`/sdlc-analyze`、`/sdlc-feat` 各多一節說明，六個步驟的標題多一個後綴。 **步驟的做法與產出完全不變**——委派與否，兩條路的結果必須一樣。 - `/sdlc-sync`、`/sdlc-fix`、`/sdlc-report` 沒有可委派的步驟，一個字都沒改（有測試釘住）。 - 不支援子代理的平台讀到的就是「自己做」，行為與現在完全相同。 - 沒有任何腳本變更，Gitea 與 git 的行為不變。 - `test/helpers/prompt-doc.js` 的 `promptStep` 介面不變，只是改建在 `promptSteps` 上， 並讓步驟標題容得下後綴。 ## 測試結果 `npm test`（含新增的 13 條）： ``` ℹ tests 878 ℹ suites 0 ℹ pass 878 ℹ fail 0 ℹ cancelled 0 ℹ skipped 0 ℹ todo 0 ℹ duration_ms 26026.829237 ``` 另外做了三次故意破壞，確認新的斷言真的抓得住（每次都已還原）： ``` ① 從判準表刪掉一列「| `sdlc-feat` | 把議題標題翻成英文 |」 → 3 條失敗 ② 把會問使用者的「### 3. 問來源分支」標成可委派 → 9 條失敗 ③ 把 sdlc-fix 沒編號的「### 工作包議題」標成可委派 → 2 條失敗 （這一項在修掉標記位置那條斷言之前是 0 條失敗，正是本次修掉的 bug） ``` reviewer 可自行重現：`git diff origin/master` 後 `npm test`；上面三次破壞用 `sed` 改一行再跑 `node --test test/delegation-assets.test.js` 即可。
jiantw83 added 3 commits 2026-09-18 01:18:09 +00:00
docs(references): 新增委派判準，四條全部成立才可委派 3da822adc6 
只在意結果的步驟——翻譯分支名、算截止日、逐條比對可行性清單、產生 HTML 總覽——
它們的中間產物目前全部留在主脈絡裡，把後面真正需要判斷力的步驟愈擠愈窄。要把這些
交出去，得先說清楚「哪些交得出去」，否則下一個人只能憑感覺標。

四條判準裡有兩條是硬排除，各自寫上理由，因為沒有理由的規則遲早會被繞過去：
第二條（步驟中不會詢問使用者）是因為子代理問不到使用者，一旦卡在提問就只能自行決定；
第四條（不直接寫入 Gitea 或 git）不是因為子代理做不好，而是**它的失敗沒有人看著**
——備妥工作樹失敗會中止整個領取、實際提交失敗會留下半套 git 歷史。

委派一律以**能力描述**表達，不指名任何平台的工具：子代理是平台專屬能力，而流程正本
必須保持平台中立（#4 的驗收標準）。能力描述對不支援的平台是自然降級，同一份正本兩邊
都讀得通，不必維護兩份。這份正本明寫「不要把它改寫成工具名」，因為那是讀到它的人
最可能動手改的地方。

那張「目前標記為〔可委派〕的步驟」表與正本上的標記互為正本，由資產測試雙向綁住。

議題 #58

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
docs(prompts): 六個只在意結果的步驟標上〔可委派〕 84cd8fc41f 
三份正本各加一節說明這個後綴是什麼意思，只留能力描述那一句與指回判準正本的指路，
判準本身不複寫——抄過去就會有兩份各自演化的規則（AGENTS.md 的 references/ 那一列）。

標的是六個：sdlc-plan 的產生圖解版總覽；sdlc-analyze 的對四份清單列出疑點、算出截止日、
產生分析版的圖解總覽；sdlc-feat 的把議題標題翻成英文、分批提交。

其中三步是部分委派，各自在該步寫明哪一半留給主流程：兩份圖解總覽委派的是產出 HTML，
寫回議題的 issue-update 不委派；分批提交委派的是方案計算，實際跑 commit-split.js 不委派。
理由不在這裡複述，指回判準第四條。

**「認出語言，讀規則正本」不標**，儘管議題的列舉點了它。那一步的核心動作含「認不出語言
就停下來問、不要猜」，正是判準第二條硬排除的事；排掉它之後剛好是議題所寫的六個。
這一條與 repo 擁有者確認過。

AGENTS.md 的 references/ 那一列補上「委派判準」，否則那串括號裡的列舉會漏掉新的一份。

議題 #58

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
test(delegation): 把標記與判準正本雙向綁住 f61ef3fa78 
沒有這條斷言，兩邊會慢慢漂開，而漂開時不會有任何東西報錯：正本上多標一步不會壞，
判準表少列一項也不會壞，只是下一個讀的人會以為自己讀到的是全部。

十三條，重點在三處：正本上被標記的集合等於判準表列出的集合；會問使用者的步驟一律
未被標記（判準第二條的迴歸保護，四個點名的步驟加上一次全域掃描）；被標記的步驟碰得到
寫入時要寫明哪一半不委派（第四條）。

掃描類的斷言都補上自我檢查，因為這種測試最常見的壞法是「一條都沒掃到」而它照樣是綠的：
提問語至少要認出四個步驟、至少要掃過四十個步驟。標記位置那一條原本把三種合法位置寫成
`/^#{2,3} /`，那條會把「### 沒編號的標題 〔可委派〕」也放過去，改成三條互斥的規則。

helpers 新增 promptSteps（名字、有沒有標記、內文），promptStep 改建在它上面，
順帶讓步驟標題容得下後綴。

議題 #58

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
admin approved these changes 2026-09-18 01:19:31 +00:00
admin merged commit c545f11ec1 into master 2026-09-18 01:19:39 +00:00
admin deleted branch feat/delegation-markers/main 2026-09-18 01:19:39 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
admin
Labels
Clear labels
ready-for-agent
規格已就緒可交由agent實作
 進行中
工作包正在實作
No labels
Milestone
No items
No Milestone
Assignees
Clear assignees
admin (系統管理員) jiantw83 (Jeffery)
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: plugins/tea-sdlc#64