troy-mode 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +14 -0
- package/.claude-plugin/plugin.json +13 -0
- package/LICENSE +21 -0
- package/README.md +87 -2
- package/bin/cli.mjs +503 -0
- package/package.json +44 -4
- package/plugin.json +10 -0
- package/skills/troy-blast-radius/SKILL.md +43 -0
- package/skills/troy-blast-radius/agents/openai.yaml +4 -0
- package/skills/troy-eval/SKILL.md +66 -0
- package/skills/troy-eval/agents/openai.yaml +4 -0
- package/skills/troy-grilling/SKILL.md +28 -0
- package/skills/troy-grilling/agents/openai.yaml +4 -0
- package/skills/troy-how/SKILL.md +35 -0
- package/skills/troy-how/agents/openai.yaml +4 -0
- package/skills/troy-mode/SKILL.md +31 -0
- package/skills/troy-mode/agents/openai.yaml +4 -0
- package/skills/troy-research/SKILL.md +42 -0
- package/skills/troy-research/agents/openai.yaml +4 -0
- package/skills/troy-research/assets/template.md +35 -0
- package/skills/troy-teach-me/SKILL.md +338 -0
- package/skills/troy-teach-me/agents/openai.yaml +4 -0
- package/skills/troy-wait-what/SKILL.md +35 -0
- package/skills/troy-wait-what/agents/openai.yaml +4 -0
- package/skills/troy-why/SKILL.md +30 -0
- package/skills/troy-why/agents/openai.yaml +4 -0
package/plugin.json
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "troy-mode",
|
|
3
|
+
"description": "Cross-project AI Agent workflow playbook and skills toolkit in Traditional Chinese.",
|
|
4
|
+
"author": {
|
|
5
|
+
"name": "Troy",
|
|
6
|
+
"url": "https://github.com/DoubleTian-tw"
|
|
7
|
+
},
|
|
8
|
+
"homepage": "https://github.com/DoubleTian-tw/troy-mode",
|
|
9
|
+
"repository": "https://github.com/DoubleTian-tw/troy-mode"
|
|
10
|
+
}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: troy-blast-radius
|
|
3
|
+
description: 變更影響範圍(爆炸半徑)查核與實證工具。在合併或改動前,找出 grep 看不出來的連鎖破壞風險(隱性依賴、DB 約束、狀態機、跨服務合約),並透過實際執行程式/測試證明關鍵安全假設成立。Use when asked "what could this break", "blast radius of X", or reviewing a risky diff.
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Troy Blast Radius — 變更爆炸半徑與安全實證
|
|
8
|
+
|
|
9
|
+
找出一個改動或 Diff 在「改動範圍之外」可能打壞什麼,並**用真實執行證據(而非紙上談兵)**證明關鍵假設到底安不安全。
|
|
10
|
+
|
|
11
|
+
> 若存在 `~/.agents/CONTEXT.md`,先讀取並遵守其語言與術語規範。搭配 `troy-how`(理解運作)與 `troy-why`(理解動機)使用效果最佳(若未安裝則獨立執行):`troy-blast-radius` 專抓「靠 grep 找不到」的隱性破壞點。
|
|
12
|
+
|
|
13
|
+
## 核心原則:不信任自己寫得很好聽的分析
|
|
14
|
+
|
|
15
|
+
列出所有呼叫端只是基本動作(grep 一秒就做完),真正的價值是抓出**呼叫鏈之外的隱性耦合**,例如:
|
|
16
|
+
- 共用型別/DTO/OpenAPI/序列化欄位變化對下游(前後端、Worker、匯出報表)的影響
|
|
17
|
+
- DB Schema/Migration/CHECK Constraint/既有歷史資料或 Seed/Fixture 的相容性
|
|
18
|
+
- 非同步事件、排程、快取 Key、權限 Guard 順序或並發競爭(TOCTOU)
|
|
19
|
+
- 測試環境假資料、既有測試斷言或全域設定假設
|
|
20
|
+
|
|
21
|
+
## 執行流程
|
|
22
|
+
|
|
23
|
+
### Step 1:界定範圍與取得真實 Diff
|
|
24
|
+
- 若使用者指定某檔案/函式/分支,以此為準;否則檢視當前工作區與 base branch(例如 `git diff` / `git status`)的實際異動。
|
|
25
|
+
|
|
26
|
+
### Step 2:搜出 grep 看不到的隱性耦合
|
|
27
|
+
依本次改動觸及的層面,追查:
|
|
28
|
+
1. **資料與契約邊界**:有沒有跨模組/跨 repo(如前端、Admin、Worker、OpenAPI)消費這個輸出?有沒有字串拼接、反射、動態 key 或序列化依賴?
|
|
29
|
+
2. **狀態與時間軸假設**:有沒有依賴「某件事一定先發生」或「欄位一定非 null」的歷史資料/其他入口?
|
|
30
|
+
3. **錯誤與回滾路徑**:失敗時交易(Transaction)有回滾嗎?有沒有留下半套狀態或重複觸發副作用?
|
|
31
|
+
|
|
32
|
+
### Step 3:實際跑程式/檢查來驗證關鍵假設(Prove It Works)
|
|
33
|
+
挑出這次改動**安全成立最關鍵的 1~2 個事實**,盡可能往下走到最低層級的實證(並在報告寫清楚走到哪一層):
|
|
34
|
+
1. ❌ 只靠嘴說(無價值,禁止)
|
|
35
|
+
2. ⚠️ 指到真實 `file:line` 或套件原始碼位置
|
|
36
|
+
3. ⚠️ 逐步推演錯誤路徑證明觸及不到
|
|
37
|
+
4. ✅ **實際執行現有測試/型別檢查/唯讀探測腳本或聚焦 E2E** 拿回真實輸出證明不會爆(嚴守專案 DB 安全規範,不可觸碰非測試環境)
|
|
38
|
+
|
|
39
|
+
## 回報格式
|
|
40
|
+
|
|
41
|
+
1. **隱性爆炸半徑清單**(依風險高低排序:影響對象、為什麼 `grep` 漏掉、具體檔案與行號)
|
|
42
|
+
2. **關鍵安全假設實證結果**(列出驗證了哪幾個關鍵假設、跑了什麼指令、拿到什麼輸出、停在哪一層實證)
|
|
43
|
+
3. **未覆蓋盲點與建議補測/防護**(若有環境限制無法實測,明確寫出未驗證範圍)
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: troy-eval
|
|
3
|
+
description: 雙盲 A/B 評測工作流程 - 對修改前後的 skill、agent 規範或不同模型執行相同真實任務,以隱藏評分表、真實行為軌跡核查與匿名裁判驗證差異。當使用者呼叫 `/troy-eval`、`$troy-eval` 或說「評測 skill」、「A/B 驗證」、「比較改前改後」、「eval skill」時觸發。
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Troy Eval — 雙盲 A/B 評測工作流程
|
|
8
|
+
|
|
9
|
+
以可控、雙盲(Double-Blind)的方式,對照「對照組(修改前/基準)」與「實驗組(修改後/新版)」在同一真實任務上的實際行為與產出品質,避免僅憑主觀印象或單次試跑產生確認偏誤。
|
|
10
|
+
|
|
11
|
+
> 若存在 `~/.agents/CONTEXT.md`,先讀取並遵守其語言與表達規範。核心機制採雙盲評測原則:防觀察者效應、隱藏評分表、只採信實際操作軌跡與產出證據。
|
|
12
|
+
|
|
13
|
+
## 嚴格禁令(Blinding Non-Negotiables)
|
|
14
|
+
|
|
15
|
+
1. **禁止考試字眼洩漏**:提供給參賽代理的工作目錄名稱、檔案名稱、Prompt 內容中,**嚴禁出現**以下字眼(中英文皆然):
|
|
16
|
+
`eval`、`test`(指考試/評測語意時)、`judge`、`experiment`、`rubric`、`score`、`compare`、`benchmark`、`candidate`、`arena`、`A/B`、`對照組`、`實驗組`。
|
|
17
|
+
2. **自然任務包裝**:Prompt 必須像日常真實工作指令(例如:「請依工作目錄內的規範處理這份變更/需求並回報結果」),不得要求參賽者「展示你如何遵守某條新規則」。
|
|
18
|
+
3. **評分表隔離**:評分標準(Rubric)只能給最後的裁判看,參賽代理全程不可讀取。
|
|
19
|
+
4. **不信自我回報**:評分一律依據實際產出、修改後的程式碼、實跑指令輸出與真實執行軌跡(Transcript 工具呼叫順序),不採信參賽者口頭宣稱「我已確認通過」。
|
|
20
|
+
|
|
21
|
+
## 執行流程
|
|
22
|
+
|
|
23
|
+
### Step 1:定題與撰寫隱藏評分表
|
|
24
|
+
|
|
25
|
+
1. 明確定義變數:
|
|
26
|
+
- **對照組(Baseline)**:例如修改前的規則檔(如 `dev` 分支版本)或無該 skill 的預設環境。
|
|
27
|
+
- **實驗組(Treatment)**:修改後的新版規則/skill 檔。
|
|
28
|
+
- **固定控制變數**:兩組使用相同模型與相同的自然工作輸入。
|
|
29
|
+
2. 撰寫 **3~6 條具體、可客觀判定的評分標準(Rubric)**,存於暫存筆記或對話內部狀態,**不寫進參賽者可見目錄**。
|
|
30
|
+
|
|
31
|
+
### Step 2:建立隔離且去識別化的工作環境
|
|
32
|
+
|
|
33
|
+
於對話專屬暫存目錄(或系統暫存資料夾,避免污染專案 git 工作區)建立兩份獨立工作夾(命名須中性,例如 `work-alpha/`、`work-beta/`):
|
|
34
|
+
|
|
35
|
+
- 放入**完全相同**的任務材料、相關程式碼與依賴(需跑測試或 Git 歷史查證時,一併建立隔離的迷你 Git 倉或環境)。
|
|
36
|
+
- 僅在各自對應位置放入「對照組版本」與「實驗組版本」的規則/skill 檔。
|
|
37
|
+
- 檢查所有檔名、目錄名與文字內容,確認無違反上述 Blinding 禁令。
|
|
38
|
+
|
|
39
|
+
### Step 3:平行派出兩組獨立代理
|
|
40
|
+
|
|
41
|
+
使用**相同模型**,平行啟動兩個獨立 subagent(依當前 AI 工具提供之背景代理機制):
|
|
42
|
+
|
|
43
|
+
- 兩份 Prompt **除了各自讀取的工作目錄路徑不同外,其餘字句 100% 相同**。
|
|
44
|
+
- 明確限制每個代理只能讀取與操作各自被指派的隔離目錄(避免讀到另一組或外部真實專案)。
|
|
45
|
+
- 收集兩組完整產出;若評測目標涉及「步驟順序」(如先紅燈重現再改程式、先補測試再重構),**務必從代理的執行日誌/Transcript 提取真實工具呼叫順序**一併交給裁判。
|
|
46
|
+
|
|
47
|
+
### Step 4:匿名盲審(Blinded Judge)
|
|
48
|
+
|
|
49
|
+
1. **匿名遮罩**:隨機決定將兩組產出對應為「方案 X」與「方案 Y」(記錄對應表於最後解盲使用,裁判不可得知)。
|
|
50
|
+
2. **獨立裁判**:啟動第三個獨立代理擔任裁判(優先選用與參賽者不同模型家族,或高推理模型),僅提供:
|
|
51
|
+
- 任務原始材料
|
|
52
|
+
- Step 1 的隱藏評分表(Rubric)
|
|
53
|
+
- 遮罩後的「方案 X」與「方案 Y」完整產出(及必要之真實執行時間軸)
|
|
54
|
+
3. 要求裁判逐條依證據判定 Pass / Partial / Fail,並給出具體差異與行號理由。
|
|
55
|
+
|
|
56
|
+
### Step 5:解盲、覆核與清理
|
|
57
|
+
|
|
58
|
+
1. 將「方案 X / Y」解盲還原為「改前(Baseline)vs 改後(Treatment)」。
|
|
59
|
+
2. 人工/主代理覆核裁判判決是否與實際產出一致。
|
|
60
|
+
3. 輸出精簡對照報告(預設呈現於對話或 Artifact,不污染專案 repo):
|
|
61
|
+
|
|
62
|
+
| 評分項目 | 改前(Baseline) | 改後(Treatment) | 關鍵證據差異 |
|
|
63
|
+
|---|---|---|---|
|
|
64
|
+
| <標準 1> | ❌ / ✅ | ✅ / ❌ | <具體抓到或漏掉的點> |
|
|
65
|
+
|
|
66
|
+
4. 若實驗組未達預期或出現副作用(例如新規則稀釋既有敏感度),直接指出需微調的條文;**完成後務必刪除暫存評測資料夾**。
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: troy-grilling
|
|
3
|
+
description: 對使用者的計畫、決策或構想進行毫不留情的深度盤問(Grill)。當使用者想要對自己的思考進行壓力測試,或使用任何「grill」觸發詞時使用。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
毫不留情地盤問訪談使用者,直到雙方達成共識。將此過程梳理為**設計樹(design tree)**:每個決策都會分支衍生出依賴於它的後續決策。
|
|
7
|
+
|
|
8
|
+
以**輪次(rounds)**推進這棵決策樹。**前沿(frontier)**是指所有前置條件皆已敲定的決策點:也就是你「現在」就能提問、無需胡亂臆測尚未獲得之答案的問題。在同一輪中提出當前前沿上的所有問題:為每個問題編號並附上你的建議答案。接著等待使用者回覆後,再進行下一輪。
|
|
9
|
+
|
|
10
|
+
每一輪的格式如下:
|
|
11
|
+
|
|
12
|
+
```
|
|
13
|
+
❓ **Q1** - **<問題標題>**: <問題內文,可包含多個段落與選項>
|
|
14
|
+
|
|
15
|
+
➡️ <你的建議答案>
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
❓ **Q2** - **<問題標題>**: <問題內文,可包含多個段落與選項>
|
|
20
|
+
|
|
21
|
+
➡️ <你的建議答案>
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
使用者每一輪的回答都會重塑這棵樹:已敲定的決策會將前沿向外推進,並解鎖依賴於它們的後續問題。重新計算前沿並展開下一輪提問。若某個問題的答案取決於本輪中尚未敲定的另一個問題,則它屬於「後續」輪次,而非本輪。
|
|
25
|
+
|
|
26
|
+
找出「事實」是你的工作,絕非使用者的責任。當前沿上的問題需要來自環境(檔案系統、工具等)的事實時,派遣子 Agent(sub-agent)去查找;切勿向使用者詢問任何你能自行查閱的資訊。不要因此卡住流程:進行中的探索屬於未敲定的前置條件,因此只有其下游的問題需要等待子 Agent 回報;前沿上的其餘問題應立即提出。而「決策」則屬於使用者:將每個決策交付給使用者定奪並等待回覆。
|
|
27
|
+
|
|
28
|
+
當前沿為空時,該流程即告完成:設計樹的每個分支皆已探索完畢,沒有留下任何未經言明的隱性假設。在使用者確認雙方已達成共識之前,切勿擅自採取後續行動。
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: troy-how
|
|
3
|
+
description: 唯讀探索與架構走讀工具。回答「X 怎麼運作」、「這條請求怎麼流過系統」、「新邏輯應該放在哪一層 / 哪個模組」等問題,輸出清晰的心智模型與檔案行號依據。Use when asked how code works, architecture walkthroughs, or placement/ownership questions.
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Troy How — 程式運作與架構走讀
|
|
8
|
+
|
|
9
|
+
唯讀探索 codebase,回答「這塊程式實際怎麼運作?」與「新程式該放在哪一層/誰擁有這份狀態?」的問題。
|
|
10
|
+
|
|
11
|
+
> 查「**為什麼**當初這樣設計」請改用 `troy-why`;查「改動會打壞什麼」請改用 `troy-blast-radius`。
|
|
12
|
+
|
|
13
|
+
## 執行規範
|
|
14
|
+
|
|
15
|
+
1. 若存在 `~/.agents/CONTEXT.md`,先讀取並遵守其語言與術語規範。
|
|
16
|
+
2. **完全唯讀**:嚴禁修改任何檔案或執行會改變狀態的指令。
|
|
17
|
+
3. 若 scope 模糊,先簡短說明你的詮釋範圍並開始探索(若專案有大量檔案,可派一個唯讀 subagent 一次探索整理)。
|
|
18
|
+
4. **必須核對真實檔案與行號**,不可憑記憶猜測符號或流程。
|
|
19
|
+
|
|
20
|
+
## 探索步驟
|
|
21
|
+
|
|
22
|
+
1. **找入口點(Entrypoints)**:從路由 Controller、CLI 指令、Worker / Queue Consumer 或前端頁面元件出發,抓出真實觸發點。
|
|
23
|
+
2. **追完整呼叫鏈(Call Graph & Data Flow)**:
|
|
24
|
+
- 沿線讀實際呼叫的 Service、Helper、Middleware、Guard、Validator 與 ORM / SQL 查詢,列出資料如何轉換、狀態在哪裡寫入與持久化。
|
|
25
|
+
- 若專案有架構或功能文件(例如 `docs/features/`、`AGENTS.md`),比對文件與實際程式碼是否一致(若有落差直接點出)。
|
|
26
|
+
3. **釐清歸屬與分層(Ownership & Placement)**:
|
|
27
|
+
- 若問題涉及「應該放哪裡」,明確指出各層職責(例如邊界驗證 vs 業務邏輯 vs 資料存取)與誰是該狀態的唯一 Owner。
|
|
28
|
+
|
|
29
|
+
## 輸出格式
|
|
30
|
+
|
|
31
|
+
用資深工程師給同事上手的心智模型格式輸出(精簡、無廢話,重要關係超過 3 個元件時附漸進小圖或精簡流程圖):
|
|
32
|
+
1. **一句話定位**:這個子系統在系統中扮演什麼角色。
|
|
33
|
+
2. **核心資料流/呼叫鏈**:附真實 `file:line` 路徑。
|
|
34
|
+
3. **關鍵狀態歸屬與設計邊界**:誰擁有什麼狀態、有哪些隱含前置條件或陷阱。
|
|
35
|
+
4. **(若問落點/如何擴充)建議放置位置與理由**。
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: troy-mode
|
|
3
|
+
description: Troy 個人跨專案工作流總入口(Playbook Router)。依目前任務性質自動分流至最合適的 troy-* skill(研究、追程式流、查歷史理由、評估爆炸半徑、深度盤問、教學講解、白話重述),並落實證據優先紀律。使用 `/troy-mode`、`$troy-mode` 或「用 troy 模式處理」時觸發。
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Troy Mode — 個人 Playbook 總路由
|
|
8
|
+
|
|
9
|
+
在開始任何非瑣碎任務前,先讀取 `~/.agents/CONTEXT.md`(若存在)取得共用語言與對外表達原則,再用你自己的話用 1~2 句重述目標與最小可驗證完成標準,接著依下方路由表分派對應的 `troy-*` skill。
|
|
10
|
+
|
|
11
|
+
## `troy-*` 技能路由表
|
|
12
|
+
|
|
13
|
+
> 若使用者只單獨安裝部分 `troy-*` skill,目標 skill 不存在時直接依該列「核心產出」原則就地執行,不因缺少附屬 skill 而卡住。
|
|
14
|
+
|
|
15
|
+
| 任務意圖 | 呼叫 Skill | 核心產出 |
|
|
16
|
+
| :--- | :--- | :--- |
|
|
17
|
+
| 搞懂「這塊程式**怎麼運作**?邏輯該放哪一層?」 | `troy-how` | 唯讀追蹤呼叫鏈、模組邊界與 State Owner |
|
|
18
|
+
| 搞懂「**為什麼**當初這樣寫/這樣定規則?」 | `troy-why` | 查 `git log` / PR / 歷史文件,拆「事實 vs 推論 vs 空白」 |
|
|
19
|
+
| 評估「改這裡**會不會打壞別處**?」 | `troy-blast-radius` | 追 grep 看不到的隱性依賴並實跑證實關鍵假設 |
|
|
20
|
+
| 計畫/決策/規格還模糊,需要被**壓力測試盤問** | `troy-grilling` | 依設計樹逐輪逼出未定決策,未達共識不動工 |
|
|
21
|
+
| 需要外部一手來源**技術/產品調查筆記** | `troy-research` | 查證一手資料並輸出可追溯研究筆記 |
|
|
22
|
+
| **學觀念**(蘇格拉底反問)或 **Review 快速白話講懂** | `troy-teach-me` | 觀念採反問引導;Review 採漸進小圖 + 平行 `troy-how` / `troy-why` |
|
|
23
|
+
| 剛才 AI 的回答太難懂/跳步,要求**白話重講** | `troy-wait-what` | 唯讀重述上一段回覆,不擴張執行 |
|
|
24
|
+
| 驗證 skill/規範改動前後**實際行為差異** | `troy-eval` | 建立去識別化雙盲對照環境、平行實跑並交由匿名裁判評分 |
|
|
25
|
+
|
|
26
|
+
## 通用執行紀律(所有路由共用)
|
|
27
|
+
|
|
28
|
+
1. **先理解再動手**:改陌生或跨模組程式碼前,優先跑 `troy-how`(結構)或 `troy-why`(脈絡),不在沒看懂合約前猜測修改。
|
|
29
|
+
2. **若專案內已有專屬工作流(例如專案內的 `AGENTS.md`、`.agents/skills/` 或團隊規範)**:`troy-mode` 負責個人分析/調查/審查前導;進入正式實作、修 Bug 或重構時,接回該專案既定的工作流與規範。
|
|
30
|
+
3. **證據優先(Prove It Works)**:不把「應該沒問題」、「能編譯」當完成;報告結論必附真實檔案行號、Commit 或實跑指令輸出。
|
|
31
|
+
4. **最小化決策打擾**:能自己從程式碼/紀錄查證的事實,不反問使用者;只把產品取捨或不可逆風險交給使用者拍板。
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: troy-research
|
|
3
|
+
description: 從一手來源研究不確定的技術、產品或實作問題,並在專案的 Markdown 檔案中記錄可追溯的發現。當決策、架構或規格討論需要外部證據、來源驗證或可行方案比較時使用;請勿用於只能由使用者做決定的情境。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Troy Research
|
|
7
|
+
|
|
8
|
+
將外部可驗證的不確定性轉化為簡短、可追溯的研究筆記。研究旨在確立事實與限制條件,而非替使用者做出產品或商業決策。
|
|
9
|
+
|
|
10
|
+
## 研究前準備
|
|
11
|
+
|
|
12
|
+
1. 定義問題、該問題所影響的決策,以及能回答該問題的來源類型。將範圍收斂至單篇筆記即可回答的程度。
|
|
13
|
+
2. 在建立筆記前確定存放目的地:
|
|
14
|
+
- 若使用者已有提供路徑,請直接使用。
|
|
15
|
+
- 否則,檢視專案中現有的文檔與筆記慣例。優先尋找 `docs/`、`notes/`、`research/`、特定功能文檔以及存放庫說明。絕不檢視機密或敏感檔案。
|
|
16
|
+
- 列出最多三個合理的位置,標註建議選項,並等待使用者選擇。若專案無既有慣例,提供一個合理的預設路徑,切勿在未告知的情況下自行建立全新的文檔結構。
|
|
17
|
+
3. 若該不確定性屬於商業優先級、政策抉擇或任何無法透過客觀資料定案的偏好,跳過研究流程,改用 `troy-grilling`(若未安裝則改以結構化提問)與使用者進行釐清。
|
|
18
|
+
|
|
19
|
+
## 研究工作流程
|
|
20
|
+
|
|
21
|
+
確認輸出路徑後,若環境支援 Agent 委派,將資料來源探索與證據收集委派給後台 Agent(background agent)。提供其研究問題、限制條件與所需的來源標準。委派必須回傳:
|
|
22
|
+
|
|
23
|
+
- 候選結論,且每項主張皆附帶直接來源;
|
|
24
|
+
- 相關版本、日期與適用範圍限制;
|
|
25
|
+
- 矛盾之處、未知事項以及需要在本機測試的項目;以及
|
|
26
|
+
- 仍取決於使用者決策的選項。
|
|
27
|
+
|
|
28
|
+
只要存在一手來源(primary sources),務必優先採用:官方文檔、規格標準、原始碼、第一方 API 參考資料、正式公告或原始研究報告。針對具時效性的主題,需驗證當前資訊並記錄查閱日期。切勿將搜尋摘要片段(search snippets)或二手機構整理視為證據。
|
|
29
|
+
|
|
30
|
+
撰寫前請先檢視研究發現。僅在引用的來源能直接支持時,方可將陳述標記為事實。綜合歸納之處應標記為推論。切勿以看似合理的猜測來填補空白。
|
|
31
|
+
|
|
32
|
+
## 撰寫筆記
|
|
33
|
+
|
|
34
|
+
複製 [assets/template.md](assets/template.md) 至已確認的目的地,且僅填寫重要的章節。在每項支持的主張旁保留直接連結。簡明扼要的筆記優於巨細靡遺的資料堆砌。
|
|
35
|
+
|
|
36
|
+
若研究後仍有實質抉擇尚未定案,請將其記錄在 **需要使用者確認** 區塊下,並列出可行選項、有證據支持的影響,以及所需的決策。接著若有 `troy-grilling` 則調用它;否則請向使用者提出聚焦且中立的問題。切勿將未決定的事項包裝為研究結論。
|
|
37
|
+
|
|
38
|
+
## 邊界原則
|
|
39
|
+
|
|
40
|
+
- 切勿僅因為研究顯示了某個方向,就逕自修改產品規格、原始碼或設定檔。
|
|
41
|
+
- 在使用者提供或選定目的地之前,切勿建立研究筆記。
|
|
42
|
+
- 切勿以此工作流取代專案既有的需求討論流程。在需求或規格討論中,僅將此工作流用於需要外部證據的分支。
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# <研究主題>
|
|
2
|
+
|
|
3
|
+
> 查閱日期:YYYY-MM-DD
|
|
4
|
+
> 研究目的:<此研究要協助釐清的問題或決策>
|
|
5
|
+
|
|
6
|
+
## 研究過程
|
|
7
|
+
|
|
8
|
+
- 問題與範圍:
|
|
9
|
+
- 查閱方式與來源篩選原則:
|
|
10
|
+
- 已檢閱來源:
|
|
11
|
+
- [來源名稱](https://example.com) — <此來源回答的問題>
|
|
12
|
+
|
|
13
|
+
## 發現
|
|
14
|
+
|
|
15
|
+
### <發現或主張>
|
|
16
|
+
|
|
17
|
+
- <事實或明確限制>。[來源名稱](https://example.com)
|
|
18
|
+
- 推論:<由多項證據推導出的判斷;若無則移除此行>。
|
|
19
|
+
|
|
20
|
+
## 結論
|
|
21
|
+
|
|
22
|
+
- <能直接回應研究目的、且已被證據支持的結論>
|
|
23
|
+
|
|
24
|
+
## 不確定與待驗證
|
|
25
|
+
|
|
26
|
+
- <來源不足、版本差異、需在本機或正式環境實測的項目>
|
|
27
|
+
|
|
28
|
+
## 需要使用者確認
|
|
29
|
+
|
|
30
|
+
> 僅在研究無法客觀決定的情況保留本節;以 `troy-grilling` 釐清。
|
|
31
|
+
|
|
32
|
+
- 決策:<需要選擇的事項>
|
|
33
|
+
- 選項 A:<效果與限制>
|
|
34
|
+
- 選項 B:<效果與限制>
|
|
35
|
+
- 需要確認:<使用者的優先順序、規則或偏好>
|