architext 0.0.3 → 0.0.5

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.
Files changed (118) hide show
  1. package/CHANGELOG.md +56 -1
  2. package/README.md +94 -12
  3. package/README.zh-CN.md +94 -12
  4. package/dist/index.js +43 -39
  5. package/dist/templates/en/briefs/_base.md +44 -11
  6. package/dist/templates/en/briefs/_modules.md +31 -4
  7. package/dist/templates/en/docs/global/api_snapshot.json +24 -0
  8. package/dist/templates/en/docs/global/command_api.json +26 -0
  9. package/dist/templates/en/docs/global/env_registry.json +12 -0
  10. package/dist/templates/en/docs/global/map.json +5 -0
  11. package/dist/templates/en/docs/global/public_api.json +12 -0
  12. package/dist/templates/en/docs/prompts/audit.md +80 -94
  13. package/dist/templates/en/docs/prompts/code.md +100 -109
  14. package/dist/templates/en/docs/prompts/edit.md +52 -47
  15. package/dist/templates/en/docs/prompts/fix.md +49 -42
  16. package/dist/templates/en/docs/prompts/help.md +23 -31
  17. package/dist/templates/en/docs/prompts/inherit.md +110 -116
  18. package/dist/templates/en/docs/prompts/map.md +47 -69
  19. package/dist/templates/en/docs/prompts/plan.md +160 -171
  20. package/dist/templates/en/docs/prompts/recover.md +48 -0
  21. package/dist/templates/en/docs/prompts/ref.md +163 -0
  22. package/dist/templates/en/docs/prompts/remove.md +55 -107
  23. package/dist/templates/en/docs/prompts/revise.md +63 -106
  24. package/dist/templates/en/docs/prompts/scope.md +77 -117
  25. package/dist/templates/en/docs/prompts/start.md +93 -139
  26. package/dist/templates/en/docs/shared/verify-result-handling.md +6 -0
  27. package/dist/templates/en/docs/templates/design.template.md +77 -0
  28. package/dist/templates/en/docs/templates/spec.template.md +60 -25
  29. package/dist/templates/en/rules/00_system.md +36 -79
  30. package/dist/templates/en/rules/01_workflow.md +59 -57
  31. package/dist/templates/en/rules/03_data_governance.md +46 -42
  32. package/dist/templates/en/skills/archi-data-sync/SKILL.md +83 -0
  33. package/dist/templates/en/skills/archi-decompose-roadmap/SKILL.md +166 -151
  34. package/dist/templates/en/skills/archi-design-patterns/SKILL.md +140 -0
  35. package/dist/templates/en/skills/archi-feature-relations/SKILL.md +118 -0
  36. package/dist/templates/en/skills/archi-interview-protocol/SKILL.md +2 -1
  37. package/dist/templates/en/skills/archi-plan-options/SKILL.md +4 -3
  38. package/dist/templates/en/skills/archi-silent-audit/SKILL.md +118 -0
  39. package/dist/templates/en/skills/archi-ui-wireframe/SKILL.md +315 -270
  40. package/dist/templates/zh/briefs/_base.md +46 -14
  41. package/dist/templates/zh/briefs/_modules.md +29 -2
  42. package/dist/templates/zh/docs/global/api_snapshot.json +24 -0
  43. package/dist/templates/zh/docs/global/command_api.json +26 -0
  44. package/dist/templates/zh/docs/global/data_snapshot.json +0 -1
  45. package/dist/templates/zh/docs/global/design_tokens.json +0 -1
  46. package/dist/templates/zh/docs/global/dictionary.json +1 -1
  47. package/dist/templates/zh/docs/global/env_registry.json +12 -0
  48. package/dist/templates/zh/docs/global/error_codes.json +0 -8
  49. package/dist/templates/zh/docs/global/map.json +28 -3
  50. package/dist/templates/zh/docs/global/public_api.json +12 -0
  51. package/dist/templates/zh/docs/global/vision.md +1 -1
  52. package/dist/templates/zh/docs/prompts/audit.md +43 -57
  53. package/dist/templates/zh/docs/prompts/code.md +68 -77
  54. package/dist/templates/zh/docs/prompts/edit.md +44 -39
  55. package/dist/templates/zh/docs/prompts/fix.md +33 -26
  56. package/dist/templates/zh/docs/prompts/help.md +13 -21
  57. package/dist/templates/zh/docs/prompts/inherit.md +81 -87
  58. package/dist/templates/zh/docs/prompts/map.md +23 -45
  59. package/dist/templates/zh/docs/prompts/plan.md +134 -146
  60. package/dist/templates/zh/docs/prompts/recover.md +48 -0
  61. package/dist/templates/zh/docs/prompts/ref.md +163 -0
  62. package/dist/templates/zh/docs/prompts/remove.md +31 -83
  63. package/dist/templates/zh/docs/prompts/revise.md +43 -84
  64. package/dist/templates/zh/docs/prompts/scope.md +53 -93
  65. package/dist/templates/zh/docs/prompts/start.md +75 -121
  66. package/dist/templates/zh/docs/shared/verify-result-handling.md +6 -0
  67. package/dist/templates/zh/docs/templates/design.template.md +77 -0
  68. package/dist/templates/zh/docs/templates/spec.template.md +60 -25
  69. package/dist/templates/zh/rules/00_system.md +37 -80
  70. package/dist/templates/zh/rules/01_workflow.md +60 -58
  71. package/dist/templates/zh/rules/02_tech_stack.md +7 -6
  72. package/dist/templates/zh/rules/03_data_governance.md +43 -39
  73. package/dist/templates/zh/rules/99_context_glue.md +2 -2
  74. package/dist/templates/zh/skills/archi-data-sync/SKILL.md +83 -0
  75. package/dist/templates/zh/skills/archi-decompose-roadmap/SKILL.md +70 -56
  76. package/dist/templates/zh/skills/archi-design-patterns/SKILL.md +140 -0
  77. package/dist/templates/zh/skills/archi-feature-relations/SKILL.md +118 -0
  78. package/dist/templates/zh/skills/archi-interview-protocol/SKILL.md +2 -1
  79. package/dist/templates/zh/skills/archi-plan-options/SKILL.md +26 -25
  80. package/dist/templates/zh/skills/archi-silent-audit/SKILL.md +118 -0
  81. package/dist/templates/zh/skills/archi-ui-wireframe/SKILL.md +317 -269
  82. package/package.json +1 -1
  83. package/dist/templates/zh-Hant/briefs/_base.md +0 -115
  84. package/dist/templates/zh-Hant/briefs/_modules.md +0 -173
  85. package/dist/templates/zh-Hant/docs/global/data_snapshot.json +0 -31
  86. package/dist/templates/zh-Hant/docs/global/design_tokens.json +0 -135
  87. package/dist/templates/zh-Hant/docs/global/dictionary.json +0 -35
  88. package/dist/templates/zh-Hant/docs/global/error_codes.json +0 -19
  89. package/dist/templates/zh-Hant/docs/global/map.json +0 -94
  90. package/dist/templates/zh-Hant/docs/global/roadmap.json +0 -39
  91. package/dist/templates/zh-Hant/docs/global/vision.md +0 -82
  92. package/dist/templates/zh-Hant/docs/prompts/audit.md +0 -150
  93. package/dist/templates/zh-Hant/docs/prompts/code.md +0 -160
  94. package/dist/templates/zh-Hant/docs/prompts/edit.md +0 -87
  95. package/dist/templates/zh-Hant/docs/prompts/fix.md +0 -86
  96. package/dist/templates/zh-Hant/docs/prompts/help.md +0 -69
  97. package/dist/templates/zh-Hant/docs/prompts/inherit.md +0 -270
  98. package/dist/templates/zh-Hant/docs/prompts/map.md +0 -131
  99. package/dist/templates/zh-Hant/docs/prompts/plan.md +0 -252
  100. package/dist/templates/zh-Hant/docs/prompts/remove.md +0 -162
  101. package/dist/templates/zh-Hant/docs/prompts/revise.md +0 -160
  102. package/dist/templates/zh-Hant/docs/prompts/scope.md +0 -198
  103. package/dist/templates/zh-Hant/docs/prompts/start.md +0 -258
  104. package/dist/templates/zh-Hant/docs/templates/plan.template.json +0 -88
  105. package/dist/templates/zh-Hant/docs/templates/scope-brief.template.md +0 -58
  106. package/dist/templates/zh-Hant/docs/templates/spec.template.md +0 -51
  107. package/dist/templates/zh-Hant/docs/templates/ui.template.md +0 -51
  108. package/dist/templates/zh-Hant/rules/00_system.md +0 -123
  109. package/dist/templates/zh-Hant/rules/01_workflow.md +0 -93
  110. package/dist/templates/zh-Hant/rules/02_tech_stack.md +0 -192
  111. package/dist/templates/zh-Hant/rules/03_data_governance.md +0 -102
  112. package/dist/templates/zh-Hant/rules/04_cli_tools.md +0 -50
  113. package/dist/templates/zh-Hant/rules/90_custom_rules.md +0 -21
  114. package/dist/templates/zh-Hant/rules/99_context_glue.md +0 -53
  115. package/dist/templates/zh-Hant/skills/archi-decompose-roadmap/SKILL.md +0 -293
  116. package/dist/templates/zh-Hant/skills/archi-interview-protocol/SKILL.md +0 -86
  117. package/dist/templates/zh-Hant/skills/archi-plan-options/SKILL.md +0 -364
  118. package/dist/templates/zh-Hant/skills/archi-ui-wireframe/SKILL.md +0 -337
@@ -1,293 +0,0 @@
1
- ---
2
- name: archi-decompose-roadmap
3
- description: Architext 任務分解專家。五步分解法:先標定專案類型校準基建清單,再雙視角提取業務 Task 和 Infra 任務,NFR 橫切關注點歸併入 goal(不獨立成任務),建立真實依賴鏈並輸出並行批次。產出符合 Tier 1 Schema 的 roadmap.json 任務,作為 `/archi.plan` 的輸入契約。用於任何需要生成或追加 Roadmap 任務的場景。
4
- ---
5
-
6
- # Roadmap 任務分解
7
-
8
- ## 系統流程定位
9
-
10
- ```
11
- Brief → [本 Skill] → roadmap.json 任務
12
-
13
- /archi.plan <task-id>
14
- 讀: vision.md + map.json + tech_stack.md
15
- 寫: spec.md(行為規格/驗收標準)
16
- ui.md(元件結構,AI 編碼真相源)[?UI]
17
- 視覺參考: [[__DOCS_DIR__]]/global/ui_context.md [?UI]
18
- plan.json(可執行步驟 + 測試用例 checkbox)
19
- 也更新: map.json / dictionary.json / data_snapshot.json
20
-
21
- /archi.code → 讀 spec.md + ui.md + plan.json → 寫程式碼
22
- ```
23
-
24
- > **Skill 職責邊界**:
25
- > - 負責:任務的 what(描述)、done 標準(goal)、依賴鏈、設計決策注入、Core 介面契約
26
- > - 不負責:檔案路徑(map.json 管)、變數命名(dictionary.json 管)、測試用例(plan.json 管)、UI 元件結構(ui.md 管)
27
- >
28
- > **Schema 約束(Tier 1 嚴格)**:roadmap.json 由 CLI 的 Zod Schema 校驗,**禁增刪欄位**。
29
-
30
- ## 呼叫模式
31
-
32
- | 模式 | 觸發來源 | 輸入 | 限制 |
33
- |:---|:---|:---|:---|
34
- | 從零建立 | `/archi.start` | Brief 功能清單 | 禁生成 EDIT 任務 |
35
- | 增量追加 | `/archi.scope` | Brief + 已有 Roadmap 上下文 | 禁改已有任務,ID 沿用水位 |
36
-
37
- ---
38
-
39
- ## 分解框架(五步)
40
-
41
- ### Step 0 · 專案類型標定
42
-
43
- 從 Brief 的技術棧 / 專案描述中識別專案類型,確定標準基建清單,防止 Step 2 反推遺漏框架性 Infra。
44
-
45
- | 專案類型 | 腳手架須包含(除通用建置工具鏈外) |
46
- |:---|:---|
47
- | Web SPA / PWA | 路由骨架(如 React Router)+ 全域 App Shell(版面配置 / Provider / 主題注入) |
48
- | 全端 Web(SSR/SSG)| 路由約定(loader/action/頁面)+ API Routes 層 + 全域版面配置 + Auth Session 管理(Cookie/JWT);[?UI] 主題注入 |
49
- | CLI 工具 | logger 模組 + AppError 處理層 + 命令註冊入口 |
50
- | API 服務(REST / GraphQL)| 路由層 + 中介層 + DB 連線層 + 全域錯誤處理;[?GraphQL] Schema 定義層 + DataLoader |
51
- | 行動端 App(原生/跨平台)| 導航骨架(React Navigation / Go Router)+ 平台適配層(iOS/Android 權限、原生模組)+ 環境配置(dev/staging/prod)|
52
- | 小程式 | 頁面路由設定 + 全域 app.js/ts + 請求封裝層 |
53
- | 瀏覽器擴充功能 | manifest.json(V2/V3)+ Background Service Worker + Content Script 注入層 + 訊息匯流排(background ↔ content ↔ popup)+ Popup/Options 頁入口 |
54
- | 桌面端 App(單機)| 主程序入口(Electron main / Tauri main.rs)+ IPC 通訊橋接 + 系統級能力(系統匣、快速鍵)+ 原生檔案系統封裝 |
55
- | Web + 桌面端(Hybrid)| Web 腳手架基礎 + 桌面執行時整合(Tauri/Electron)+ 系統級能力(系統匣、全域快速鍵、系統通知);**桌面整合須獨立拆分為 INF 子任務**(OS 差異大、與 Web 技術棧完全不同,不適用 Step 2 的「同期執行合併」規則) |
56
- | 函式庫 / SDK / NPM 套件 | 雙產物配置(CJS + ESM)+ 公共 API 入口(barrel index.ts)+ 型別宣告生成(.d.ts)+ Changelog / 版本工具鏈;**禁建業務 Task,僅 INF 層** |
57
- | 即時 / 協作型 App | WebSocket 服務層 + 事件 Schema 定義(共享型別)+ 房間/會話管理基礎;[?CRDT] 衝突解決層 |
58
- | AI Agent / MCP 工具 | LLM 客戶端抽象層(provider 無關)+ Prompt 範本管理 + Tool/Function Calling Schema + 對話狀態 / Memory 管理;[?MCP] MCP 協定適配器 |
59
-
60
- **操作(兩個輸出)**:
61
- 1. **注入 Step 2 INF-01**:將對應類型的腳手架清單寫入 INF-01 描述。
62
- 2. **注入 Step 1 場景約束**:按專案類型限定場景句式,Step 1 提取業務場景時須遵守以下約束:
63
-
64
- | 專案類型 | 場景句式範本 | 禁止出現的詞彙 |
65
- |:---|:---|:---|
66
- | CLI 工具 | `使用者可 [執行命令/傳參] → [終端輸出結果]` | 頁面、路由、元件、UI |
67
- | 函式庫 / SDK | `呼叫方可 [呼叫 API X] → [回傳 Y]` | 使用者、介面、互動 |
68
- | API 服務 | `客戶端可 [HTTP METHOD /path] → [回應結構]` | 前端、頁面、元件 |
69
- | 小程式 | `使用者可在 [頁面名] [操作] → [微信端可見結果]` | 後端路由、REST |
70
- | Web SPA / 全端 / 行動端 / 桌面端 | `使用者可 [動作] → [可感知結果]` | (無特殊限制)|
71
-
72
- ---
73
-
74
- ### Step 1 · PM 視角 → 業務 Task
75
-
76
- 從 Brief 功能描述提取使用者場景,聚合為業務 Task。
77
-
78
- 1. 逐條功能轉化為場景句式:`使用者可 [動作] → [可感知結果]`
79
- 2. 共享同一核心流程的場景 → 合併為一個業務 Task
80
- > **注意**:「共享功能域/主題」≠「共享核心流程」。屬於同一功能域(如「社群互動」)但各自有獨立 UI 區域和實作域的場景,須按下方拆分訊號獨立成 Task,禁因主題相同而強行合併。「共享核心流程」僅指:場景在同一 UI 視圖內完成、操作同一資料實體、共享同一狀態流轉。
81
- 3. 粒度校準(核心原則:**一任務 = 一次 `/archi.plan` 會話 = 一個 `tasks/<slug>/` 子目錄**):
82
-
83
- **行為視角(PM)**:
84
-
85
- | 訊號 | 動作 |
86
- |:---|:---|
87
- | 描述含「和」(兩個獨立關注點) | 拆分 |
88
- | DoD 超過 4 條驗收標準 | 拆分 |
89
- | 任務橫跨 3 個以上獨立 UI 區域或實作域 | 拆分 |
90
- | 一次 `/archi.plan` 難以在單一 spec.md 中完整描述行為 | 拆分 |
91
- | 兩任務檔案集合 >50% 重疊 | 合併 |
92
-
93
- > **注意**:若「A 完成後 B 才有意義」,這是順序依賴關係,**禁合併**;在 Step 4 為 B 聲明 `deps: [A]` 即可。
94
-
95
- **實作視角(工程,與行為視角獨立判斷,任一觸發即拆分)**:
96
-
97
- | 訊號 | 動作 | 範例 |
98
- |:---|:---|:---|
99
- | 任務內含 ≥2 個**實作域**,且各域可獨立單元測試 | 拆分 | 純計算層 + UI 渲染層 → 各自獨立 |
100
- | 實作時需同時掌握 ≥3 個相互獨立的技術關注點 | 拆分 | 字元渲染 + 狀態機 + 動效 API → 三件事 |
101
- | 某一關注點有獨立的邊界複雜度(如 IME、Canvas、第三方圖表 API) | 獨立出該關注點 | 輸入捕獲 + IME 單獨成任務 |
102
-
103
- > **為何加入實作視角**:行為視角描述「使用者看到什麼」,實作視角描述「AI 實作時需同時掌握什麼」。一個任務行為上內聚(同一頁面),但工程上橫跨多個不同域時,AI 在 `/archi.code` 階段會因上下文過寬而顧此失彼。
104
-
105
- **粒度上限**:
106
-
107
- > 一個 Roadmap Task = **AI 可不再分解、直接產出一個內聚 spec.md** 的最小功能單元(HTN Primitive 可執行性原則)。
108
-
109
- *分解階段代理指標(以 Brief 描述為依據直接判斷)*:
110
-
111
- | 代理指標 | 上限 | 超出時的動作 |
112
- |:---|:---|:---|
113
- | 任務描述中獨立使用者操作流程數 | ≤ 3 條 | 拆分 |
114
- | 任務涉及的獨立資料實體數(各有獨立狀態流轉)| ≤ 2 個 | 拆分 |
115
- | 描述中「和/並/以及」連接的獨立關注點數 | ≤ 1 處 | 拆分 |
116
- | 任務驗收無法在不執行另一個業務 Task 的情況下獨立完成 | — | 檢查耦合,重劃介面邊界(INVEST-I)|
117
-
118
- > `/archi.plan` 執行中若預估 spec.md Scenario > 6 或 plan.json Phase > 4,須暫停並提示使用者返回 `/archi.scope` 重新拆分,禁強行塞進單一任務。
119
-
120
- **DoD 格式**:`完成後,使用者可 <可驗證的使用者行為>;邊界:<明確不做的事>`
121
-
122
- > DoD 是 `/archi.plan` 生成 spec.md 驗收標準和 plan.json 測試用例的基準。須精準描述使用者可感知結果,禁寫實作細節(檔案路徑、函式名稱、測試命令由 plan 階段決定)。
123
-
124
- 以下情況歸屬父任務,禁獨立成條:**輕量**結果頁 / 完成頁、空狀態頁、確認彈窗。
125
-
126
- > **豁免**:結果頁含獨立資料視覺化元件(圖表庫)、複雜動效邏輯或獨立業務計算時,**不適用**父任務歸屬規則,須獨立成業務 Task。
127
-
128
- ---
129
-
130
- ### Step 2 · 架構師視角 → Infra 任務
131
-
132
- 從業務 Task 反推共享基礎,禁預設基建。
133
-
134
- 對所有業務 Task 問:多個 Task 同時依賴 X 且 X 須在 Task 前存在 → X 是 Infra 任務。
135
-
136
- | Infra 類型 | 判斷標準 |
137
- |:---|:---|
138
- | 專案腳手架 / 全域 Schema / 型別定義 | 所有業務 Task 均依賴;須覆蓋 Step 0 標定的專案類型清單 |
139
- | 共享核心引擎(打字引擎、規則引擎等) | 滿足以下**任一**條件:① 2 個以上業務 Task 直接呼叫;② 純邏輯層、可獨立單元測試、與 UI 完全解耦。`tag: Core` |
140
- | 第三方整合層 | 多個業務 Task 複用同一外部服務 |
141
-
142
- **Core 任務規劃契約**:`tag: Core` 任務的 `description` 末尾須聲明主要導出介面(函式簽名或關鍵 interface 名稱)。
143
- 下游 Task 的 `/archi.plan` 會話可直接對接該介面,無需讀上游實作,保障跨任務規劃的一致性與可預測性。
144
-
145
- **Infra 任務粒度原則:避免微粒化,但禁止跨層堆積**:
146
-
147
- - **禁微粒化**:無實質技術差異的同層配置項(如 ESLint + Prettier + TypeScript strict + commitlint)→ 合併,減少任務數、降低依賴鏈雜訊。
148
- - **禁跨層堆積**:每個獨立的架構層各有獨立技術細節,合併後 AI 上下文同樣會失焦;且將多層堆入同一 INF 任務會把關鍵路徑拉至最長,推遲所有業務 Task 的啟動時機。
149
-
150
- > **架構層參考**(每層有獨立實作邊界,原則上各自成任務):
151
- > 專案腳手架(建置 / 程式碼品質工具鏈)| 資料層(DB 連線 / ORM / 遷移)| 認證層(Auth 中介層 / Session / JWT)| API 路由層(路由註冊 / 中介層鏈 / 全域錯誤處理)| 前端基礎設施(主題 / Design Token / 全域版面配置)| 第三方服務整合(各服務獨立成 INF 任務)
152
-
153
- | 訊號 | 動作 |
154
- |:---|:---|
155
- | 同一架構層內的關聯配置項(如程式碼品質工具鏈各項、或路由骨架與全域錯誤中介層同屬 API 路由層)| 合併 |
156
- | 跨越獨立架構層(如 DB 連線層 + Auth 中介層、或 API 路由 + 前端主題系統)| 拆分 |
157
- | 技術棧完全不同(如本機儲存層 vs 主題配置)| 拆分 |
158
- | 含 OS 級系統 API(系統匣、全域快速鍵、檔案關聯等)| **強制拆分**(Step 0 強制規則,不受「同層合併」條件約束) |
159
- | 某 Infra 產出物被 ≥2 個業務 Task 直接呼叫(介面型) | 獨立成任務(須聲明導出介面契約) |
160
-
161
- **隱式標準功能掃描**:以下功能通常不在 Brief 中出現,須按歸屬分類主動補充(禁遺漏):
162
-
163
- *須補充為獨立業務 Task(Phase 2,有使用者可見行為)*:
164
-
165
- | 檢查項 | 觸發條件 |
166
- |:---|:---|
167
- | 使用者 Profile / 帳號設定頁 | 專案含 Auth(INF 層有認證中介層)|
168
- | 帳號安全 / 密碼設定頁 | 含 Auth 且使用者可修改密碼或綁定第三方帳號 |
169
- | 通知中心 / 訊息列表頁 | 含通知基礎設施且通知有「已讀/未讀」狀態 |
170
-
171
- *須補充為 INF 任務(Phase 1,基礎設施)*:
172
-
173
- | 檢查項 | 觸發條件 |
174
- |:---|:---|
175
- | 通知基礎設施(伺服器推播/訊息佇列層)| ≥1 個 Task 口頭提及「通知/提醒」但未建 INF Task |
176
- | 搜尋基礎設施(PG FTS 索引 / 外部引擎部署)| ≥2 個業務 Task 各自描述「搜尋」功能;須在此決策方案後以 INF Task 承載,下游 Task 依賴它 |
177
- | 權限 / 角色管理層(RBAC)| 含 Auth 且有 ≥2 種使用者角色(如 admin / user)|
178
- | 檔案儲存整合層(S3 / OSS 封裝)| ≥1 個 Task 涉及檔案上傳 / 下載 / 預覽 |
179
- | 電子郵件 / 簡訊發送整合 | Task 提及「發送郵件 / 驗證碼 / 簡訊通知」|
180
- | 支付整合層 | Task 提及「支付 / 下單 / 結帳 / 退款」|
181
-
182
- ---
183
-
184
- ### Step 3 · NFR 過濾
185
-
186
- 以下類型**禁獨立成任務**:注入首個實現該能力的任務 `goal` 末尾(`[NFR] <說明>`);其餘受影響任務僅在 NFR 清單中標注。`/archi.plan` 執行時會將 NFR 注入對應的 spec.md 約束章節。
187
-
188
- > **「首個任務」定義**:在依賴鏈中,`deps` 僅含 INF 層(無業務前置依賴)且最早涉及該 NFR 能力的任務。同層(同 Batch)有多個候選時,取 ID 最小的那個。
189
-
190
- | 類型 | 常見形式 | 注意 |
191
- |:---|:---|:---|
192
- | 國際化 | i18n、多語言、翻譯文案 | — |
193
- | 視覺主題(配置型) | 品牌色 Token、Tailwind 主題色、CSS 變數定義 | NFR,注入腳手架任務 |
194
- | 視覺主題(功能型) | 深色/淺色切換按鈕、OS 偏好偵測、主題持久化 | **非 NFR**,須建立獨立業務 Task(有使用者可見行為) |
195
- | 動效風格規範 | 頁面切換方式、過渡時長約定 | NFR,注入首個含動效的 Task goal |
196
- | 效能優化 | 懶載入、虛擬列表、快取策略 | — |
197
- | 無障礙 | A11y、鍵盤導航、螢幕閱讀器 | — |
198
-
199
- ---
200
-
201
- ### Step 4 · 依賴與並行優化
202
-
203
- - **真實依賴鏈**:禁所有業務 Task 統一只掛 `INF-01`,須反映真實業務關係。
204
- - **業務實體依賴(優先於最小依賴)**:若功能 B 的核心操作主體由功能 A 產生(即 A 完成前 B 的資料實體不存在),則 B 須聲明對 A 的依賴。此規則優先於最小依賴原則。示例:Usage Log 記錄的主體是 Prompt,Prompt 由 FEAT-Prompt_Create 建立 → Usage Log Task 須依賴 Prompt Task,而不僅依賴 INF 層。
205
- - **最小依賴原則**:能並行的任務不加多餘依賴,最大化 Batch 並行度。
206
-
207
- ---
208
-
209
- ## 任務規則
210
-
211
- 1. **ID 生成**:沿用已有 Roadmap 編號水位,從各前綴最大值 +1 起;全新專案從 `INF-01` / `FEAT-01` 起。
212
-
213
- 2. **Phase 歸屬**:
214
-
215
- | 任務類型 | Phase |
216
- |:---|:---|
217
- | 專案腳手架、Schema、全域型別 | Phase 1 (Infrastructure) |
218
- | 共享核心引擎(Step 2 識別) | Phase 1 (Infrastructure) |
219
- | 業務 Task | Phase 2 (Core Features) |
220
- | EDIT-xxx(修改已有功能) | 與被修改任務同 Phase |
221
-
222
- 3. **設計決策注入**:Brief 中已有設計決策 → 注入對應任務 `goal` 末尾:`[使用者預設] <內容>`;同一條決策禁在多任務重複。`/archi.plan` 將其視為不可更改的硬約束,直接寫入 spec.md,不再提問。
223
-
224
- 4. **EDIT 任務**:需修改已有功能 → 建立 `EDIT-xxx`(`tag: Edit`),goal 注明修改範圍;僅增量追加模式下使用。
225
-
226
- 5. **Slug 命名**:`slug` 即 `tasks/<slug>/` 資料夾名,須清晰表達任務內容,格式為 `Pascal_Snake_Case`(如 `Typing_Engine_Core`)。每個任務對應唯一一個 task 子目錄,禁重名。
227
-
228
- ---
229
-
230
- ## Task JSON Schema(Tier 1 嚴格,禁增刪欄位)
231
-
232
- ```json
233
- {
234
- "id": "FEAT-01",
235
- "title": "Task Title In English",
236
- "status": "pending | blocked",
237
- "description": "<1-2 句說明這個任務要建置什麼、涵蓋哪些範圍。Core 任務須在末尾聲明主要導出介面>",
238
- "goal": "完成後,使用者可 <可驗證的使用者行為>;邊界:<明確不做的事>",
239
- "deps": ["INF-01"],
240
- "tag": "Infra | Core | Feature | Edit",
241
- "slug": "Task_Title_Snake_Case"
242
- }
243
- ```
244
-
245
- `deps` 為空或全部 `done` → `pending`;有未完成 deps → `blocked`
246
-
247
- ---
248
-
249
- ## 中間產物
250
-
251
- > 此 Skill 為子程序:產出結構化資料後,控制權交還呼叫方。
252
- > - `/archi.scope` → 呼叫方展示給使用者確認,OK 後寫入 `roadmap.json`
253
- > - `/archi.start` → 呼叫方直接寫入 `roadmap.json`
254
-
255
- 產出三部分資料:
256
-
257
- **① 任務資料**(直接對應 `roadmap.json` 的 phases/tasks 結構):
258
-
259
- ```json
260
- {
261
- "phases": [
262
- {
263
- "id": "phase-1",
264
- "name": "Infrastructure",
265
- "tasks": [
266
- { "id": "INF-01", "title": "...", "status": "pending", "description": "...", "goal": "...", "deps": [], "tag": "Infra", "slug": "..." }
267
- ]
268
- },
269
- {
270
- "id": "phase-2",
271
- "name": "Core Features",
272
- "tasks": [
273
- { "id": "FEAT-01", "title": "...", "status": "blocked", "description": "...", "goal": "...", "deps": ["INF-01"], "tag": "Feature", "slug": "..." }
274
- ]
275
- }
276
- ]
277
- }
278
- ```
279
-
280
- **② NFR 歸併清單**(須隨任務資料一併返回給呼叫方;呼叫方寫入 roadmap 時追加為 `nfr` 頂層欄位;`/archi.plan` 的 `step_1_load` 須讀取此清單):
281
-
282
- | NFR 名稱 | 注入任務 ID | 約束內容摘要 | 影響範圍(其他相關任務 ID)|
283
- |:---|:---|:---|:---|
284
- | (範例)i18n | FEAT-01 | 所有文案須透過 i18n key 引用,禁硬編碼字串 | FEAT-02, FEAT-03 |
285
-
286
- **③ 並行執行批次**(DAG 拓撲層次圖,同一 Layer 內任務可交給不同 AI 會話並行處理):
287
-
288
- ```
289
- Layer 0 ║ INF-01
290
- Layer 1 ║ INF-02 · INF-03 ← 均依賴 INF-01
291
- Layer 2 ║ FEAT-01 · FEAT-02 ← 各自依賴 INF-02 / INF-03
292
- Layer 3 ║ FEAT-03 ← 依賴 FEAT-01
293
- ```
@@ -1,86 +0,0 @@
1
- ---
2
- name: archi-interview-protocol
3
- description: Architext 補充訪談協議。規範資訊缺口的提問方式:選擇題優先、AI 推薦 + [推薦] 標註、[Z] 自訂兜底、AI+/AI- 完整分析、選項說明描述具體行為。產出標準 Q-table 和 INPUT 提示行,供 /archi.start、/archi.scope、/archi.plan 的補充確認步驟引用。
4
- ---
5
-
6
- # 補充訪談協議
7
-
8
- ## 系統流程定位
9
-
10
- ```
11
- 資訊缺口出現
12
-
13
- [本 Skill] → Q-table 輸出 → 等待使用者 INPUT
14
-
15
- 調用方繼續後續步驟
16
- ```
17
-
18
- > **Skill 的職責邊界**:
19
- > - 負責:問題如何提(格式/規則/語氣)
20
- > - 不負責:問什麼內容(由調用方的缺口列表決定)、使用者回答後如何處理(由調用方決定)
21
-
22
- ## 調用方與觸發條件
23
-
24
- | 調用方 | 觸發步驟 | 觸發條件 | 問題數上限 |
25
- |:---|:---|:---|:---|
26
- | `/archi.start` | step_2_supplementary | Brief 有「必須/可補」級缺口 | 3-6 題 |
27
- | `/archi.scope` | step_2_5_supplementary | Brief 有「必須/可補」級缺口 | ≤3 題 |
28
- | `/archi.plan` | step_2 Part 2 Q-table | 架構維度 2+ 合理選項且選擇顯著影響實現 | 按需,能推薦就不展開 |
29
-
30
- ---
31
-
32
- ## 核心規則
33
-
34
- ### 原則:選擇題優先
35
-
36
- 禁開放式提問(如「你想用什麼資料庫?」)。所有問題以選擇題形式呈現,AI 基於上下文給出推薦預設選項,使用者只需確認或換選。目標:使用者不需要專業知識也能做出合理決策。
37
-
38
- ### 規則清單
39
-
40
- | # | 規則 | 細節 |
41
- |:---|:---|:---|
42
- | 1 | **僅問缺口** | 調用方已明確回答的內容禁再提問;Brief 中使用者已填寫的選擇直接採納 |
43
- | 2 | **選項數量** | 每題 3-5 個選項 + `[Z] 自訂`;選項過多說明問題需要拆分 |
44
- | 3 | **推薦標註** | AI 從選項中選出最合理方案,標註 `[推薦]`;須結合當前專案上下文,禁機械套用 |
45
- | 4 | **[Z] 兜底** | 每題必含 `[Z] 自訂 (請描述)`,給無法用預設選項表達的需求留出口 |
46
- | 5 | **選項說明完整** | 說明須包含:① 這個選項是什麼 ② 選了之後專案/程式碼會怎樣 ③ 適合什麼場景(共 2-3 句);禁一詞概括 |
47
- | 6 | **AI+/AI- 完整句子** | 從 AI Agent 執行視角說明優勢和風險;須為完整句子;禁寫「無」——每個方案必有取捨 |
48
- | 7 | **合併相關問題** | 強相關的缺口合併為一題,減少使用者決策次數;弱相關才拆題 |
49
-
50
- ---
51
-
52
- ## 標準輸出格式
53
-
54
- ```
55
- ### 補充確認
56
-
57
- **[Q<n>] 問題標題**
58
- > 為什麼需要這個資訊(一句話,讓使用者理解作答的必要性)
59
-
60
- | ID | 選項 | 說明 | AI+ | AI- |
61
- |:---|:---|:---|:---|:---|
62
- | A [推薦] | 選項名 | 是什麼 + 選了會怎樣 + 適合什麼場景(2-3 句) | 完整句子 | 完整句子 |
63
- | B | ... | ... | ... | ... |
64
- | C | ... | ... | ... | ... |
65
- | Z | 自訂 | (請描述) | - | - |
66
-
67
- (多題時重複上方 Q-table 結構)
68
-
69
- ---
70
- **INPUT**: `Q1答案 | Q2答案 | ...`(題與題用 `|` 分隔;單題多選用空格,如 `A B`)
71
- ```
72
-
73
- ---
74
-
75
- ## 常見錯誤示例
76
-
77
- | 錯誤寫法 | 問題 | 正確寫法 |
78
- |:---|:---|:---|
79
- | `A \| PostgreSQL` | 一詞概括,無法判斷選哪個 | `A \| PostgreSQL \| 關聯式資料庫,適合有明確 Schema 和關聯查詢的場景...` |
80
- | `AI+: 效能好` | 不是完整句子,無實質資訊 | `AI+: 結構化 Schema 讓 AI 直接從型別定義推斷 CRUD 程式碼,減少猜測` |
81
- | `AI-: 無` | 每個方案必有取捨,「無」即逃避 | `AI-: 遷移腳本須隨 Schema 演化同步維護,AI 容易遺漏欄位變更` |
82
- | Q 裡問 Brief 已回答的技術堆疊 | 重複提問降低信任感 | 跳過,直接採納使用者已填寫的選擇 |
83
-
84
- ---
85
-
86
- > **中間產物**:此 Skill 為子程序,產出 Q-table 後控制權交還調用方,等待使用者 INPUT 回覆後調用方繼續執行。