jiantw83andClaude Sonnet 5
1030f9d403
依 todo.md 執行的規範治理專案：新增 spec-preflight 等 14 個共用規範（含 conventional-commit/pull-request/git-push/issue-read/todo-list/ask-user/ subagent/no-scratch-files/skill-invocation/script-path/action-scaffold/ node-src-layout/plugin-cli/model），擴充 spec-git-safety 與 spec-gitea（token 優先序、機密遮蔽、Wiki 頁名轉義規則）；新增可執行 skill `models`（模型能力 查詢與標籤）與 `todo`（依指定模型產生/附加 todo.md）；新增 plugin.meta.json 單一事實來源與 gen-plugin-files.mjs 樣板產生器，統一四個 repo 的 manifest／ README／AGENTS.md 並移除寫死的本機使用者路徑；新增 shared/scripts/lib 的 log／機密遮蔽三語言參考實作。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
56 lines
5.2 KiB
Markdown
56 lines
5.2 KiB
Markdown
---
|
||
name: spec-subagent
|
||
description: JSC plugins 共用「Subagent 派工規範」：一個明確目標派一個 subagent、subagent 只讀不寫（除非該 skill 明確授權寫入並聲明例外）、回傳結構化結果供主 agent 判讀而非直接面向使用者、派工 prompt 需帶入 /jsc-shared:spec-output 規範、不得改動原始碼與不得直接寫外部系統。當其他 skill 內文引用 spec-subagent 或 /jsc-shared:spec-subagent、或需要派 subagent／Agent 工具執行任務時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||
---
|
||
|
||
# spec-subagent — 共用 Subagent 派工規範
|
||
|
||
所有 JSC skills 需要用 Agent／Task 工具派出 subagent 執行任務時，一律遵守以下規範。
|
||
|
||
## 一個明確目標派一個 subagent
|
||
|
||
- 派工前先把任務拆成一組**明確且彼此獨立**的目標（例如：一個 function、一個指令檔、一個議題、一個實作階段），再對**每一個目標各派一個 subagent**。
|
||
- **不要**把多個不相關目標塞進同一個 subagent 的 prompt（例如同時要求它「分析議題 A 又順便處理議題 B」「產生文件草稿又順便改標籤」）；目標之間有明確依賴或必須共用同一份上下文時才可合併，且合併前要先確認這仍是同一個目標的不同面向，而不是把兩件事湊在一起圖方便。
|
||
- 目標數量不固定時（例如依議題清單、依 function 清單動態展開），一律逐一展開後才派工，不得為了省事而幾個目標共用一個 subagent。
|
||
|
||
## subagent 只讀不寫
|
||
|
||
- subagent 預設**只讀**：只讀取程式碼、設定檔、議題、留言等既有內容，**不落地任何檔案、不修改任何工作目錄的原始碼**。
|
||
- 只有在**該 skill 明確授權**的情況下，subagent 才可以寫入，且必須符合下列兩種之一，不得無宣告地擴大寫入範圍：
|
||
1. **寫草稿檔**：僅限寫入該 skill 指定的草稿目錄（例如 `.docs/` 底下），不可覆蓋或修改原始碼、原始指令檔。
|
||
2. **回傳結構化結果**：不落地任何檔案，把結果整理成結構化內容回傳給主 agent（見下一節）。
|
||
- 派工的 skill 本身必須在文件中**明確聲明**subagent 被授權寫入的範圍（寫哪個目錄、哪些檔案），沒有聲明就一律視為只讀。
|
||
|
||
## 回傳結構化結果，不是直接面向使用者的訊息
|
||
|
||
- subagent 的回傳內容是給**主 agent 判讀**的結構化資料（例如：判斷結果、建議異動、草稿內容、需人工確認項目清單），**不是**直接顯示給使用者的最終訊息。
|
||
- 面向使用者的輸出（回報、確認詢問、劇場模式對白等）一律由**主 agent 統一組織**：主 agent 收齊所有 subagent 的回傳後，才彙整、檢查、排序，最後產出面向使用者的內容。
|
||
- subagent 不得自行決定要不要通知使用者、也不得自行對使用者發言（除非該 skill 明確定義 subagent 本身就是對話的一方，例如人格扮演情境下的發言）。
|
||
|
||
## 派工 prompt 需帶入輸出規範
|
||
|
||
- 派工的 prompt 內必須帶入 `/jsc-shared:spec-output` 的規範內容（或明確引用它），讓 subagent 知道回傳內容的語言／編碼／呈現慣例（繁體中文為主英文為輔、UTF-8 不含 BOM、優先用表格與 Mermaid 呈現、個資（PII）去識別化）。
|
||
- 不得省略這一步：subagent 若沒被告知輸出規範，容易產生語言混雜、編碼錯誤或洩漏個資的回傳內容，主 agent 事後才發現就必須整批重派。
|
||
|
||
## subagent 不得改動原始碼
|
||
|
||
- subagent **不得修改任何工作目錄內的原始碼、設定檔或既有文件**，即使它判斷該怎麼改也只能在回傳內容中描述建議，交由主 agent（或使用者確認後由主 agent）實際落地。
|
||
- 唯一例外是該 skill **明確授權**subagent 直接改動原始碼（例如某個 skill 的設計就是「派 subagent 逐項實作」），此時該 skill 文件必須清楚聲明這項例外與授權範圍，不得含糊帶過。
|
||
|
||
## subagent 不得直接寫外部系統
|
||
|
||
- subagent **不得**直接呼叫外部系統的寫入操作，包括但不限於：Gitea（議題正文／留言／標籤／PR／看板欄位）、Wiki、以及其他任何會對外產生不易復原變更的 API。
|
||
- 這類寫入一律收斂到**主 agent 統一執行**，且必須先經**使用者確認**（例如透過 AskUserQuestion）才能執行；subagent 只負責讀取與分析，把「建議要寫入什麼」整理進結構化回傳內容即可。
|
||
- subagent 需要讀取外部系統（例如讀議題、讀 Gitea 標籤清單）供分析用時不受此限，此節只限制**寫入**。
|
||
|
||
## 快速檢查表
|
||
|
||
| 檢查項目 | 通過條件 |
|
||
| --- | --- |
|
||
| 目標拆分 | 每個 subagent 對應一個明確、獨立的目標 |
|
||
| 讀寫範圍 | 預設只讀；若可寫，該 skill 已明確聲明授權範圍 |
|
||
| 回傳格式 | 結構化內容，供主 agent 判讀，非面向使用者的最終訊息 |
|
||
| 輸出規範 | prompt 已帶入或引用 `/jsc-shared:spec-output` |
|
||
| 原始碼 | 未改動，或該 skill 已明確授權例外 |
|
||
| 外部系統 | 未直接寫入 Gitea／Wiki 等，寫入交由主 agent 且已經使用者確認 |
|