create-agentic-dev-env 1.3.0 → 1.3.2

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 (8) hide show
  1. package/README.md +156 -50
  2. package/lib/runner.js +26 -11
  3. package/package.json +1 -1
  4. package/template/README.md +216 -50
  5. package/template/UPSTREAM-CANDIDATES.md +15 -0
  6. package/template/dot-claude/skills/ade-feedback-upstream/SKILL.md +1 -1
  7. package/template/knowledge/process/ade-dev-workflow/gates.md +1 -1
  8. package/template/skills/ade-contribute/SKILL.md +1 -1
package/README.md CHANGED
@@ -1,85 +1,191 @@
1
1
  # create-agentic-dev-env
2
2
 
3
- 為團隊打造 **Agentic Dev Environment（ADE）**：一個集中管理 domain 知識、流程知識、產品規格的知識庫 repo，讓 AI agent 在任何工作目錄都能取用團隊 knowhow、自主拉取服務進行開發，並把新知識持續回流——團隊的知識從「散落在成員腦中」變成「持久化、可迭代的資產」。
3
+ > 為團隊打造 **Agentic Dev Environment（ADE）**：一個集中管理跨服務知識、產品規格與開發方法的知識庫 repo，一行指令注入到每個人的 Claude Code，讓全隊的 agent 用同一套上下文、同一套做事流程——團隊的知識從「散落在成員腦中」變成「持久化、可迭代的資產」。
4
4
 
5
- ## 運作模式
5
+ ## 這是在解決什麼
6
6
 
7
- ```
8
- ┌──────────────────┐ pnpm dlx … init/update ┌──────────────────────┐
9
- │ ADE repo (xxx) │ ──────────────────────────▶ │ 工作目錄 (hub) │
10
- │ 你團隊的知識庫 │ │ CLAUDE.md + skills │
11
- │ knowledge/ │ ◀────────────────────────── │ workspaces/服務A │
12
- │ skills/ │ contribute PR 回流 │ workspaces/服務B │
13
- └──────────────────┘ └──────────────────────┘
14
- ```
7
+ 團隊有多個服務、多個 repo。每次要 agent 幫忙，都得重講一次「我們有哪些服務」「這功能的規格長怎樣」「我們的 commit 和 MR 怎麼寫」——講過的下次還要再講，每個人講的版本都不太一樣；文件寫了也沒人維護，半年後沒人敢信。
8
+
9
+ 本工具生成並維護一種 repo（**ADE repo**）來把這兩件事抽出來共用：
10
+
11
+ - **知識**（`knowledge/`）— 服務 registry、跨服務流程慣例、產品規格與 PRD。agent 需要時自己去讀，不用人轉述。
12
+ - **方法**（`skills/`）— 十五支 `ade-*` skill，把「怎麼開需求、怎麼開發、怎麼交付、怎麼維護文件」寫成 agent 照著跑的流程。
13
+
14
+ 再加一條讓它不會腐爛的機制：工作目錄裡的知識是**唯讀副本**，agent 用的過程中發現內容與現實不符，會**當場開 PR 修回來**，人只需要 review。
15
+
16
+ **導覽**：[快速上手](#快速上手) · [核心概念](#核心概念) · [Skills](#skills) · [本 repo 結構](#本-repo-結構) · [版本與相容性](#版本與相容性) · [開發與發版](#開發與發版)
17
+
18
+ ---
15
19
 
16
- - **ADE repo**：每間公司／專案一個 private git repo，集中存放服務 registry、流程知識、規格與 PRD
17
- - **工作目錄**：任意目錄跑 `init` 即成為 agent 工作站；agent 讀服務總覽 → clone 服務到 `workspaces/` → 開發
18
- - **回流**：agent 發現知識過期或缺漏時，由內建 skill 引導開 PR 回 ADE repo，人只負責 review
20
+ ## 快速上手
19
21
 
20
- ## 快速開始
22
+ ### 先認識三個地方
23
+
24
+ | | 是什麼 | 誰在動它 |
25
+ | --- | --- | --- |
26
+ | **本 repo**（create-agentic-dev-env） | 腳手架（`create`）＋執行期 runner（`init`／`update`），發佈到 npm | 框架維護者；各 ADE repo 以 issue 回饋機制改良 |
27
+ | **ADE repo** | `create` 生成、每個團隊一份的知識庫 repo，團隊知識與 skills 的**唯一真相來源** | 團隊一律走 PR（agent 端由 `ade-contribute` 引導） |
28
+ | **工作目錄**（hub） | 成員電腦上的一個資料夾，**開 Claude Code 的起點**。裡面有 ADE 的唯讀副本＋全部 skills，底下的 `workspaces/` 放實際要開發的服務 repo | 副本不要手改（update 會整個覆蓋）；`workspaces/` 下的服務 repo 照平常方式開發 |
29
+
30
+ ### 步驟 1：建立你的 ADE repo
21
31
 
22
32
  ```sh
23
- # 1. 建立你的 ADE repo
24
33
  pnpm dlx create-agentic-dev-env my-ade
34
+ ```
25
35
 
26
- # 2. 填 my-ade/package.json 的 repository.url，開始填 knowledge/，push 到 GitHub/GitLab
36
+ 生成的 `my-ade/` 帶完整結構、十五支 skills、一份給團隊讀的 README（安裝步驟、核心概念、場景速查、逐支 skill 詳解都在裡面）。接著：
27
37
 
28
- # 3. 團隊成員在任一工作目錄安裝（SSH 設定見生成的 README）
29
- pnpm dlx "git+ssh://git@github.com/ORG/my-ade.git" init
38
+ 1. 填 `my-ade/package.json` 的 `repository.url`——放 GitHub／GitLab 填 git url；只在本地填絕對路徑（見[本地模式](#本地模式ade-repo-不放-githubgitlab)）
39
+ 2. `git add -A && git commit`（init／update 都從 commit 取內容，沒有 commit 會被擋下），放 GitHub／GitLab 的再 push
40
+ 3. 在 `my-ade/` 開 Claude Code，說「新增服務」（`ade-add-service`）開始填 `knowledge/`
30
41
 
31
- # 4. 之後拉取最新知識
32
- pnpm dlx "git+ssh://git@github.com/ORG/my-ade.git" update
42
+ ### 步驟 2：團隊成員安裝
43
+
44
+ 每人挑一個空目錄當工作目錄（一台機器一個就夠），在裡面執行：
45
+
46
+ ```sh
47
+ pnpm dlx "git+ssh://git@github.com/ORG/my-ade.git" init # SSH 設定見生成的 README
48
+ pnpm dlx "git+ssh://git@github.com/ORG/my-ade.git" init --workspaces ~/projects # 沿用既有 repo 資料夾（symlink）
33
49
  ```
34
50
 
35
- `init` 之後的工作目錄：
51
+ init 在當前目錄建立：
36
52
 
37
53
  ```
38
54
  work-dir/
39
55
  ├── CLAUDE.md # 原有內容不動，插入 <!-- ADE:BEGIN/END --> managed 區段
56
+ ├── .ade.json # source、commit（新鮮度檢查用）、workspaces 位置
40
57
  ├── .claude/
41
- │ ├── skills/ade-*/ # managed，update 整目錄覆蓋
42
- │ └── ade/knowledge/ # 知識庫副本
43
- ├── .ade.json # 來源 git url + commit（保鮮檢查用）
58
+ │ ├── ade/knowledge/ # 知識庫唯讀副本
59
+ │ └── skills/ade-*/ # 全部 ade-* skills
44
60
  └── workspaces/ # agent clone 服務 repo 的作業區（自動 gitignore）
45
61
  ```
46
62
 
47
- ## ADE repo 內容
63
+ > [!IMPORTANT]
64
+ > session 一律從工作目錄根開啟。在 `workspaces/<service>/` 裡直接開 Claude Code 會載不到 ade skills 與知識庫。
65
+
66
+ ### 步驟 3：日後更新
67
+
68
+ ```sh
69
+ pnpm dlx "git+ssh://git@github.com/ORG/my-ade.git" update
70
+ ```
71
+
72
+ 或在工作目錄對 agent 說「更新 ADE」（`ade-update`）：比對版本、提醒未回流的手改、更新後回報新增的 skill。session 開始偵測到落後時也會主動提醒。
73
+
74
+ ### 本地模式：ADE repo 不放 GitHub／GitLab
75
+
76
+ ADE repo 只是本機（或共用磁碟）上的一個 git repo 也能用：`repository.url` 填絕對路徑、commit，安裝與更新改用 `file:` 形式：
77
+
78
+ ```sh
79
+ pnpm dlx "file:/Users/me/my-ade" init # update 同形式；file: 必要，直接給目錄會找不到相依
80
+ ```
81
+
82
+ 迭代迴圈：**日常直接在 ADE repo 內開 Claude Code 改、commit 到 main**（八支 skill 可用，不需要分支或 PR）；從工作目錄回流時 `ade-contribute` push 分支回 repo、由人 `git merge`。改完回工作目錄「更新 ADE」。要知道的三件事：先 commit（沒有 commit 會被擋下，不留殘局）、ADE repo 停在 main（update 取的是當下 checked-out 的 HEAD）、`[upstream-candidate]` 改記在根目錄 `UPSTREAM-CANDIDATES.md`。生成的 ADE repo README 有完整說明。
83
+
84
+ ---
85
+
86
+ ## 核心概念
87
+
88
+ ### 1. 知識單向流出，修改單向流回
89
+
90
+ ```
91
+ ADE repo ──── init / update ────▶ 工作目錄的唯讀副本 ────▶ agent 讀取使用
92
+ ▲ │
93
+ └────────── PR（ade-contribute 引導） ◀─────────── 發現過期 / 要新增
94
+ ```
95
+
96
+ 副本永遠會被 update 整個覆蓋，所以直接改 `.claude/ade/` 等於白改。這是保證而非限制：每個人手上的知識一定是同一份，任何修改都經過 PR 這道 review 閘門。
97
+
98
+ ### 2. 只收三類知識
99
+
100
+ | 收 | 為什麼 |
101
+ | --- | --- |
102
+ | **跨服務知識** | 單一服務無法自述的：服務定位、服務間依賴、跨服務流程與團隊慣例 |
103
+ | **取得服務的最小資訊** | agent 進 repo 之前必需的：repo URL、預設分支、技術棧概要 |
104
+ | **產品規格與需求** | `specs/` 與 `prd/`，spec 的讀者是 PO |
105
+
106
+ **不收**服務內部的規範、架構、安裝啟動測試步驟——那些歸服務自己的 `CLAUDE.md` / `AGENTS.md` / code，ADE 不複製一份會過期的副本。
107
+
108
+ ### 3. 產品規格 ≠ 實作規格
109
+
110
+ **產品規格**是 `knowledge/specs/` 的長期資產，描述產品當前的整體功能，由 PO 持續迭代；**實作規格**是一次開發的產出，活在工作目錄，簽核後凍結。產品規格以 `🚧 尚未實作（PRD: …）` 標記同時承載「已上線現況」與「已定案未開發」。
111
+
112
+ ### 4. 需求的完整生命週期
113
+
114
+ ```mermaid
115
+ flowchart LR
116
+ A["想法"] -->|"ade-create-prd"| B["PRD（已確認）"]
117
+ B -->|"ade-prd-to-spec"| C["spec 標 🚧 尚未實作"]
118
+ C -->|"ade-dev"| D["實作完成"]
119
+ D -->|"ade-align-spec"| E["移除 🚧<br/>PRD 標已實作"]
120
+ E -.->|"ade-spec-audit 定期健檢"| C
121
+ ```
122
+
123
+ PO 把想法問成 PRD（Discovery → 盲點拷問 → `validate-prd.sh`）→ 落進 spec 標 🚧 → RD 走 `ade-dev` 六關開發、`ade-ship` 發 MR → `ade-align-spec` 以實作為準收尾。虛線是補漏：hotfix 與直接改 code 繞過流程時，`ade-spec-audit` 抓規格漂移。
124
+
125
+ ### 5. 判準制開發流程
126
+
127
+ `ade-dev` 六關：規格 → 規劃（Phase 地圖）→ 逐 Phase 實作（輪到才展開、TDD 紅→綠、交前兩軸審查）→ 測試審視 → 沉澱 → Ship。每關只定義產出與過關判準，不規定做法；狀態全落檔、可換 session 接手。Spec Ready G1–G8 全 PASS 的任務可 **auto-pilot** 無人把關跑完，`ade-dev-auto` 批次串接。規則住在 ADE repo 的 `knowledge/process/ade-dev-workflow/`，證據盤點在本 repo [`docs/research/ade-dev/`](docs/research/ade-dev/)（不隨 ADE repo 複製）。
128
+
129
+ ### 6. Context 是最稀缺的資源
130
+
131
+ 貫穿一切設計的底層原則：每份文件都要回答「這段內容值得在什麼時機、以什麼成本進入 context？」常駐最小（CLAUDE.md 區段只寫「何時做＋去哪看」）、按需載入（細節分檔）、導航短細節深（`services/index.md` 一兩行定位，細節在各自 yaml）。
132
+
133
+ ### 7. 機制回饋上游，內容不外流
134
+
135
+ 各 ADE repo 在使用中演化出的 skill 寫法、模板、流程改良，由 `ade-feedback-upstream` 以 issue 回本專案，所有 ADE repo 受益；`knowledge/` 下的公司知識絕不外流。
136
+
137
+ ---
138
+
139
+ ## Skills
140
+
141
+ ADE repo 帶十六支 skill，逐支詳解在生成的 ADE repo README；這裡只列用途。「兩邊」＝工作目錄與 ADE repo 內都可用。
142
+
143
+ | Skill | 一句話 | 可用處 |
144
+ | --- | --- | --- |
145
+ | `ade-help` | 即時掃描列出當前位置可用的 ade-* skills | 兩邊 |
146
+ | `ade-update` | 比對版本、提醒未回流手改、更新並回報新增 skill | 工作目錄 |
147
+ | `ade-contribute` | 修改 ADE 知識庫的唯一通道：工作副本、查重、開 PR（本地模式 push 分支交人 merge） | 工作目錄 |
148
+ | `ade-add-service` | 依 `_template.yaml` 註冊服務並同步總覽 | 兩邊 |
149
+ | `ade-list-service` | 列出已註冊服務，回報總覽與描述檔不一致處 | 兩邊 |
150
+ | `ade-create-prd` | Discovery 7 題 → 對照既有知識 → 建檔 → 盲點拷問 → 機械驗證 | 兩邊 |
151
+ | `ade-prd-to-spec` | 已確認 PRD 融入 spec，標 🚧 尚未實作 | 兩邊 |
152
+ | `ade-dev` | 判準制六關開發流程，含 Spec Ready 與 auto-pilot | 工作目錄 |
153
+ | `ade-dev-auto` | 多任務批次執行器（B1–B4、熔斷） | 工作目錄 |
154
+ | `ade-commit` | commit 慣例解析：專案自述 → commitlint → log 風格 → ADE 預設 | 工作目錄 |
155
+ | `ade-ship` | 發 MR／PR：平台偵測、專案範本優先、內建預設範本、不自動 merge | 工作目錄 |
156
+ | `ade-align-spec` | 開發收尾：以實作為準核對 🚧、PRD 標已實作、開 PR | 工作目錄 |
157
+ | `ade-spec-audit` | spec 定期健檢，抓計畫外變更造成的規格漂移 | 工作目錄 |
158
+ | `ade-add-skill` | 新增 skill 的 meta-skill：問使用對象、定位置、命名、README 同步 | 兩邊 |
159
+ | `ade-add-process` | 建立流程慣例的 meta-skill：三層載體選擇＋context 紀律 | 兩邊 |
160
+ | `ade-feedback-upstream` | 機制改良以 issue 回饋本專案；絕不帶公司內容 | ADE repo 內 |
161
+
162
+ ---
163
+
164
+ ## 本 repo 結構
48
165
 
49
166
  ```
50
- knowledge/
51
- ├── README.md # 知識分層規則（canonical）
52
- ├── services/ # 服務 registry：index.md 總覽導航 + 一服務一份 YAML
53
- ├── process/ # 跨服務的團隊流程知識
54
- ├── specs/ # 當前功能規格，持續迭代的真相來源
55
- └── prd/ # 一次開發一檔的需求文件，歷史文件不迭代
56
- skills/ # init 時注入工作目錄的十五支 ade-* skills（help / update / contribute / add-service /
57
- # list-service / create-prd / prd-to-spec / dev / dev-auto / align-spec / spec-audit /
58
- # commit / ship / add-skill / add-process）；其中七支 symlink 進 .claude/skills/ 在 ADE repo 內也可用
59
- .claude/skills/ # 只在 ADE repo 內工作用（feedback-upstream）
60
- CONTEXT.md # 開發流程詞彙表；產品域詞彙在 knowledge/specs/GLOSSARY.md
61
- claude-md/ # CLAUDE.md managed 區段的內容
167
+ bin/create.js # 腳手架：由 template/ 生成 ADE repo（一次性快照）
168
+ lib/runner.js # 執行期：init / update 的全部邏輯（ADE repo 的 cli.js 一行委派）
169
+ template/ # ADE repo 範本：knowledge/、skills/、dot-claude/、claude-md/、CONTEXT.md、README
170
+ docs/
171
+ ├── dependency-contract.md # framework ↔ ADE repo ↔ 工作目錄的契約，改 runner 或 template 前必讀
172
+ └── research/ade-dev/ # ade-dev 各規則的證據盤點，規則檔以 URL 引用
173
+ test.js # 端到端自測：create → init → update，是契約的可執行版本
62
174
  ```
63
175
 
64
- ### 設計重點
176
+ ## 版本與相容性
65
177
 
66
- - **Context 管理是底層原則**：agent 的 context 是最稀缺資源，所有文件與流程設計都遵守「常駐最小化、細節按需載入、導航短細節深」——CLAUDE.md 區段只寫「何時做＋去哪看」，細節留在知識庫等被載入
67
- - **服務 registry 兩層結構**：`index.md` 是全服務概覽（模擬工程師「先總覽定位、再查細節」的認知路徑），每個服務一份 YAML 記錄 repo 位址、技術棧、依賴關係——agent 據此自主 clone 與開發
68
- - **知識分層**：ADE 只收「跨服務知識、取得服務的最小資訊、產品規格」三類；bootstrap 流程與服務內部慣例歸服務 repo 自己的文件，不複製會過期的副本
69
- - **PRD → Spec 生命週期**：PO 用 skill 建標準化 PRD（模糊想法先跑 Discovery，再盲點拷問，`validate-prd.sh` 機械檢查）→ 轉入 spec 並標 `🚧 尚未實作` → RD 開發完成後由 skill 核對實作、移除標記、開 PR 收尾；另有 `ade-spec-audit` 定期巡檢，抓 hotfix 等計畫外變更造成的規格漂移
70
- - **不綁 forge**：ADE repo 可以只是本機或共用磁碟上的 git repo（`repository.url` 填路徑、`pnpm dlx file:<path>` 安裝）；回流改為 push 分支交人 merge，其餘不變
71
- - **Managed 區塊覆蓋**：工作目錄裡的 ADE 內容視同唯讀，`update` 無條件覆蓋——想改就回 ADE repo 開 PR，強迫知識回流中央
72
- - **判準制開發流程**：`ade-dev` 六關（規格→規劃→逐 Phase 實作→測試審視→沉澱→Ship），每關只定義產出與過關判準、狀態全落檔可換 session 接手；Spec Ready G1–G8 全 PASS 的任務可 auto-pilot 無人把關跑完，`ade-dev-auto` 批次串接。規則住在 `knowledge/process/ade-dev-workflow/`，證據盤點在本 repo `docs/research/ade-dev/`（不隨 ADE repo 複製）
73
- - **消費端自助**：`ade-help` 即時掃描列出可用 skills、`ade-update` 比對版本後更新並回報新增的 skill；交付走 `ade-commit`（專案慣例優先）與 `ade-ship`（平台偵測、專案範本優先）
74
- - **機制回饋上游**：各 ADE repo 演化出的 skill／模板改良，由 `ade-feedback-upstream` skill 開 issue 回本專案（改良來源含各流程沉澱出的 `[upstream-candidate]` issues；只回饋機制，公司知識絕不外流）
178
+ ADE repo 建立時鎖本套件的**精確版本**（create 蓋章），之後上游迭代不影響既存 repo；升級是各 ADE repo 顯式改版號的決定。template 的增修（新 skill、規則）只影響新建的 repo——既有 repo 想要，照 [CHANGELOG](./CHANGELOG.md) 把對應檔案搬進去即可。結構性 breaking change 一律 major bump 並附遷移說明。契約全文見 [`docs/dependency-contract.md`](docs/dependency-contract.md)。
75
179
 
76
- ## 開發
180
+ ## 開發與發版
77
181
 
78
182
  ```sh
79
- node test.js # 端到端自測：create → init → update
183
+ node test.js # 端到端自測
184
+ npm version minor && git push --follow-tags # 發版：release 事件觸發測試與 npm publish
185
+ gh release create vX.Y.Z
80
186
  ```
81
187
 
82
- 零依賴、純 Node（>= 20）。架構與維護紀律見 [AGENTS.md](./AGENTS.md)。
188
+ 零依賴、純 Node（>= 20）。維護紀律見 [AGENTS.md](./AGENTS.md)。
83
189
 
84
190
  ## License
85
191
 
package/lib/runner.js CHANGED
@@ -42,15 +42,26 @@ function update(cwd, ws) {
42
42
  try {
43
43
  // 本地路徑的 clone 不支援 --depth（只會印警告），其餘來源維持淺 clone
44
44
  const depth = fs.existsSync(cfg.source) ? '' : '--depth 1 '
45
- execSync(`git clone ${depth}"${cfg.source}" "${path.join(tmp, 'repo')}"`, { stdio: 'inherit' })
45
+ const repo = path.join(tmp, 'repo')
46
+ execSync(`git clone ${depth}"${cfg.source}" "${repo}"`, { stdio: 'inherit' })
47
+ // 先驗證再清：clone 到沒有 commit 的 repo（本地模式常見）會是空目錄，此時清掉 managed 內容只會留下殘局
48
+ assertAdeRepo(repo)
46
49
  removeManaged(cwd)
47
- install(cwd, path.join(tmp, 'repo'), ws)
50
+ install(cwd, repo, ws)
48
51
  } finally {
49
52
  fs.rmSync(tmp, { recursive: true, force: true })
50
53
  }
51
54
  console.log('ADE update done')
52
55
  }
53
56
 
57
+ function assertAdeRepo(dir) {
58
+ for (const rel of ['knowledge', path.join('claude-md', 'section.md')]) {
59
+ if (!fs.existsSync(path.join(dir, rel))) {
60
+ throw new Error(`${rel} not found in the ADE repo checkout — does the repo have a commit on its default branch?`)
61
+ }
62
+ }
63
+ }
64
+
54
65
  function removeManaged(cwd) {
55
66
  fs.rmSync(path.join(cwd, '.claude', 'ade'), { recursive: true, force: true })
56
67
  const skillsDir = path.join(cwd, '.claude', 'skills')
@@ -75,6 +86,19 @@ function install(cwd, srcDir, wsOverride) {
75
86
  if (!source && !prev.source) {
76
87
  throw new Error('repository.url is not set in the ADE repo package.json; update would not work — fill it in and retry')
77
88
  }
89
+ // srcDir 可能沒有 .git（pnpm dlx file:<本地路徑> 打包時不帶），退而問 source 本身；
90
+ // 兩者都拿不到＝repo 還沒有 commit（或連不到），此時 .ade.json 的保鮮檢查永遠判定落後——寫任何檔案前先擋下
91
+ const src = source || prev.source
92
+ let commit = null
93
+ for (const cmd of ['git rev-parse HEAD', `git ls-remote "${src}" HEAD`]) {
94
+ try {
95
+ commit = execSync(cmd, { cwd: srcDir, stdio: ['ignore', 'pipe', 'ignore'] }).toString().split(/\s/)[0] || null
96
+ if (commit) break
97
+ } catch {}
98
+ }
99
+ if (!commit) {
100
+ throw new Error(`could not resolve the ADE repo commit from ${src} — make sure the repo has at least one commit (and is reachable), then retry`)
101
+ }
78
102
 
79
103
  // update 只清理 ade- 前綴，非前綴 skill 裝了就清不掉
80
104
  const srcSkills = path.join(srcDir, 'skills')
@@ -128,15 +152,6 @@ function install(cwd, srcDir, wsOverride) {
128
152
  if (!gi.split('\n').some((l) => l.trim() === 'workspaces')) {
129
153
  fs.writeFileSync(giPath, (gi ? gi.trimEnd() + '\n' : '') + 'workspaces\n')
130
154
  }
131
- // srcDir 可能沒有 .git（pnpm dlx file:<本地路徑> 打包時不帶），退而問 source 本身
132
- const src = source || prev.source
133
- let commit = null
134
- for (const cmd of ['git rev-parse HEAD', `git ls-remote "${src}" HEAD`]) {
135
- try {
136
- commit = execSync(cmd, { cwd: srcDir, stdio: ['ignore', 'pipe', 'ignore'] }).toString().split(/\s/)[0] || null
137
- if (commit) break
138
- } catch {}
139
- }
140
155
  fs.writeFileSync(prevPath, JSON.stringify({ source: src, commit, workspaces: ws }, null, 2) + '\n')
141
156
  }
142
157
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-agentic-dev-env",
3
- "version": "1.3.0",
3
+ "version": "1.3.2",
4
4
  "description": "Scaffold and manage team Agentic Dev Environment (ADE) knowledge repos",
5
5
  "repository": {
6
6
  "type": "git",
package/template/README.md CHANGED
@@ -1,18 +1,50 @@
1
1
  # __ADE_NAME__
2
2
 
3
- 由 [create-agentic-dev-env](https://github.com/franKobayasi/agentic-dev-env) 產生的 Agentic Dev Environment（ADE）知識庫：集中管理團隊的 domain 知識、流程知識與產品規格，讓 agent 在任何工作目錄都能取用並持續回流更新。
3
+ > 團隊的 **Agentic Dev Environment（ADE）**：把跨服務知識、產品規格與開發方法集中成一份 repo，一行指令注入到每個人的 Claude Code，讓全隊的 agent 用同一套上下文、同一套做事流程。
4
+
5
+ ## 這是在解決什麼
6
+
7
+ 我們有多個服務、多個 repo。每次要 agent 幫忙，都得重講一次「我們有哪些服務」「這功能的規格長怎樣」「我們的 commit 和 MR 怎麼寫」——講過的下次還要再講，而且每個人講的版本都不太一樣；文件寫了也沒人維護，半年後沒人敢信。
8
+
9
+ ADE 把這兩件事抽出來共用：
10
+
11
+ - **知識**（`knowledge/`）— 服務 registry、跨服務流程慣例、產品規格與 PRD。agent 需要時自己去讀，不用人轉述。
12
+ - **方法**（`skills/`）— 十五支 `ade-*` skill，把「我們怎麼開需求、怎麼開發、怎麼交付、怎麼維護文件」寫成 agent 照著跑的流程。
13
+
14
+ 再加一條讓它不會腐爛的機制：工作目錄裡的知識是**唯讀副本**，agent 用的過程中發現內容與現實不符，會**當場開 PR 修回來**，人只需要 review。
15
+
16
+ | 角色 | 用它做什麼 |
17
+ | --- | --- |
18
+ | **PO** | 把模糊想法問成標準 PRD、落進產品規格，並確認規格與實作沒有走鐘 |
19
+ | **RD** | 從工作目錄開 session，agent 自己定位服務、clone repo、照六關流程開發、發 MR |
20
+ | **全員** | 發現知識過期就地回流，不必等誰來維護文件 |
21
+
22
+ **導覽**：[初始設定](#初始設定建-repo-後做一次) · [快速上手](#快速上手) · [核心概念](#核心概念) · [常用場景速查](#常用場景速查) · [Skills](#skills) · [本 repo 結構](#本-repo-結構) · [維護原則](#維護原則)
23
+
24
+ ---
4
25
 
5
26
  ## 初始設定（建 repo 後做一次）
6
27
 
7
- 1. 填 `package.json` 的 `repository.url`（init 會記錄它作為 update 的來源）——放 GitHub／GitLab 填 git url；**只在本地**填絕對路徑（見下方「本地模式」）
8
- 2. Push 到 GitHub / GitLab
9
- 3. 開始填 `knowledge/`：服務用 `knowledge/services/_template.yaml` 格式，一服務一檔，並更新 `services/index.md` 總覽
28
+ 1. 填 `package.json` 的 `repository.url`——放 GitHub／GitLab 填 git url；**只在本地**填絕對路徑（見[本地模式](#本地模式ade-repo-不放-githubgitlab)）
29
+ 2. `git add -A && git commit`（init／update 都從 commit 取內容，沒有 commit 會被擋下），放 GitHub／GitLab 的再 push
30
+ 3. 開始填 `knowledge/`：在本 repo 開 Claude Code 說「新增服務」（`ade-add-service`），或手填 `knowledge/services/_template.yaml` 格式並更新 `services/index.md`
31
+
32
+ ---
10
33
 
11
- ## 使用（團隊成員）
34
+ ## 快速上手
12
35
 
13
- ### 首次使用前：設定 SSH
36
+ ### 先認識兩個地方
14
37
 
15
- init/update 透過 SSH 存取本 repo。先驗證：
38
+ 整套機制只有兩個位置，先分清楚，後面都好懂：
39
+
40
+ | | 是什麼 | 誰在動它 |
41
+ | --- | --- | --- |
42
+ | **ADE repo**（就是本 repo） | 團隊知識與 skills 的**唯一真相來源**，全隊共用一份。 | 一律走 PR（agent 端由 `ade-contribute` 引導） |
43
+ | **工作目錄**（hub） | 你自己電腦上的一個資料夾，是**開 Claude Code 的起點**。裡面有一份 ADE 的唯讀副本＋全部 skills，底下的 `workspaces/` 放實際要開發的服務 repo。 | 副本不要手改（update 會整個覆蓋）；`workspaces/` 下的服務 repo 照平常方式開發 |
44
+
45
+ ### 步驟 1：設定 SSH（只做一次）
46
+
47
+ init／update 透過 SSH 存取本 repo。先驗證：
16
48
 
17
49
  ```sh
18
50
  ssh -T git@github.com # GitLab 則為 git@gitlab.com；出現歡迎訊息即可跳過以下步驟
@@ -22,60 +54,186 @@ ssh -T git@github.com # GitLab 則為 git@gitlab.com；出現歡迎訊息即
22
54
 
23
55
  ```sh
24
56
  ssh-keygen -t ed25519 -C "you@company.com" # 一路 Enter 即可
25
- cat ~/.ssh/id_ed25519.pub # 複製輸出，貼到 GitHub/GitLab 帳號設定的 SSH Keys
57
+ cat ~/.ssh/id_ed25519.pub # 複製輸出，貼到 GitHub／GitLab 帳號設定的 SSH Keys
26
58
  ssh -T git@github.com # 再次驗證
27
59
  ```
28
60
 
29
- ### 安裝
61
+ ### 步驟 2：挑一個目錄，執行 init
30
62
 
31
- 在任一工作目錄執行：
63
+ 自己找一個空目錄當工作目錄（例如 `~/ade-hub`，名字隨意，**一台機器一個就夠**），`cd` 進去執行：
32
64
 
33
65
  ```sh
66
+ mkdir -p ~/ade-hub && cd ~/ade-hub
34
67
  pnpm dlx "git+ssh://git@github.com/ORG/__ADE_NAME__.git" init
35
68
  ```
36
69
 
37
- （public repo 也可用短寫法 `pnpm dlx github:ORG/__ADE_NAME__ init`；private repo 走 `github:` 會因 tarball API 無認證而失敗，請一律用上方 git+ssh 形式）
70
+ init 在**當前目錄**建立以下內容，既有檔案不會被覆蓋：
71
+
72
+ | 產出 | 說明 |
73
+ | --- | --- |
74
+ | `CLAUDE.md` 的 `<!-- ADE:BEGIN/END -->` 區段 | ADE 給 agent 的常駐指引；區段外你原有的內容不動 |
75
+ | `.claude/ade/knowledge/` | 知識庫副本 |
76
+ | `.claude/skills/ade-*/` | 全部 ade-* skills |
77
+ | `workspaces/` | 開發作業區，agent 之後把服務 repo clone 到這裡；自動加入 `.gitignore` |
78
+ | `.ade.json` | 設定檔：`source`（來源 repo）、`commit`（目前知識版本）、`workspaces`（作業區實際位置，預設 `null`＝就在目錄底下） |
79
+
80
+ 裝完長這樣：
81
+
82
+ ```
83
+ ~/ade-hub/ ← 工作目錄（hub）：Claude Code 一律從這裡開
84
+ ├── CLAUDE.md ← 你自己的指引 ＋ ADE managed 區段
85
+ ├── .ade.json ← ADE 設定：來源、版本、workspaces 位置
86
+ ├── .claude/
87
+ │ ├── ade/knowledge/ ← 知識庫唯讀副本（update 會整個覆蓋）
88
+ │ └── skills/ade-*/ ← ade-* skills（同上）
89
+ └── workspaces/ ← 開發用的 repo 都 clone 到這裡
90
+ ├── service-a/
91
+ ├── service-b/
92
+ └── __ADE_NAME__/ ← 要改知識庫時，本 repo 的工作副本也放這
93
+ ```
94
+
95
+ > [!IMPORTANT]
96
+ > **session 一律從工作目錄根開啟。** 在 `workspaces/<service>/` 裡直接開 Claude Code 會載不到 ade skills 與知識庫；需要哪個服務，讓 agent 自己進去。
97
+
98
+ > public repo 可用短寫法 `pnpm dlx github:ORG/__ADE_NAME__ init`；private repo 走 `github:` 會因 tarball API 無認證而失敗，**請一律用上方 git+ssh 形式**。
99
+
100
+ ### 步驟 3（選用）：沿用你既有的 repo 資料夾
101
+
102
+ 已經有固定放 repo 的地方（例如 `~/projects`），不必搬家、也不用重 clone——把它指給 init：
103
+
104
+ ```sh
105
+ pnpm dlx "git+ssh://git@github.com/ORG/__ADE_NAME__.git" init --workspaces ~/projects
106
+ ```
107
+
108
+ `workspaces/` 會建成該資料夾的 symlink：`cd workspaces` 就到 `~/projects`，底下已下載的 repo 直接沿用。實際位置記在 `.ade.json` 的 `workspaces`，事後改這個欄位再跑一次 update 即可重建 symlink。
38
109
 
39
- init 會在當前目錄建立：
110
+ ### 步驟 4：日後更新
40
111
 
41
- - `CLAUDE.md` 的 `<!-- ADE:BEGIN/END -->` managed 區段（原有內容不動）
42
- - `.claude/ade/knowledge/` 知識庫副本、`.claude/skills/ade-*/` skills
43
- - `workspaces/`（agent clone 服務 repo 的作業區，自動加入 .gitignore。已有固定放 repo 的資料夾時用 `init --workspaces <path>` 指向它——`workspaces` 會建成該資料夾的 symlink，`cd workspaces` 即達、已下載的 repo 直接沿用不重 clone）
44
- - `.ade.json`（設定檔：`source` 來源、`commit` 版本、`workspaces` 作業區實際位置（symlink 目標，預設 null）。改 `workspaces` 後跑一次 update 重建 symlink）
112
+ 同一行指令把 `init` 換成 `update`，就會拉到最新的知識與 skills：
113
+
114
+ ```sh
115
+ cd ~/ade-hub
116
+ pnpm dlx "git+ssh://git@github.com/ORG/__ADE_NAME__.git" update
117
+ ```
45
118
 
46
- 之後同指令改跑 `update` 拉取最新知識（update 會直接 clone 最新版，不受 dlx 快取影響）。
119
+ update 直接 clone 最新版，不受 dlx 快取影響。
47
120
 
48
121
  ### 本地模式：ADE repo 不放 GitHub／GitLab
49
122
 
50
- ADE repo 只是本機（或共用磁碟）上的一個 git repo 也能用，SSH 步驟跳過：
123
+ ADE repo 只是本機（或共用磁碟）上的一個 git repo 也能用。步驟 1 跳過，步驟 2／4 的指令換成 `file:` 形式：
51
124
 
52
125
  ```sh
53
- # package.json 的 repository.url 填絕對路徑，例如 /Users/me/team-ade
54
- pnpm dlx "file:/Users/me/team-ade" init # 之後 update 同形式；file: 必要，直接給目錄會找不到相依
126
+ # 一次性：package.json 的 repository.url 填絕對路徑，commit，然後在工作目錄
127
+ pnpm dlx "file:/Users/me/__ADE_NAME__" init # update 同形式；file: 必要，直接給目錄會找不到相依
55
128
  ```
56
129
 
57
- 差別只在回流：沒有 issue／PR，`ade-contribute` 會把分支 push 回這個 repo、回報分支名，由你在 ADE repo 內 `git merge` 後各工作目錄 update。其他 skill 與新鮮度檢查（`git ls-remote <路徑>`）照常。
130
+ 之後的迭代迴圈有兩條路，**日常以 A 為主**：
131
+
132
+ - **A. 直接在本 repo 開 Claude Code** — `ade-add-service`／`ade-create-prd`／`ade-prd-to-spec`／`ade-add-skill`／`ade-add-process` 等八支 skill 都能用，改完 commit 到 main 即可，不需要分支或 PR
133
+ - **B. 從工作目錄回流** — 開發服務時 agent 發現知識過期，`ade-contribute` 會 clone 到 `workspaces/__ADE_NAME__/`、開分支、push 回本 repo 並回報分支名；你回到本 repo `git merge` 即可（沒有 issue／PR）
134
+
135
+ 兩條路收尾都一樣：回工作目錄說「更新 ADE」。session 開始的新鮮度檢查（`git ls-remote <路徑> HEAD`）會自動提醒落後。
136
+
137
+ 三件要知道的：
138
+
139
+ - **先 commit**：init／update 都從 commit 取內容，create 完沒 commit 會被擋下（不會留殘局）
140
+ - **本 repo 停在 main**：`update` 取的是本 repo 當下 checked-out 的 HEAD；在分支上工作時先不要 update，merge 回 main 再更新
141
+ - **機制改良沒有 issue 可開**：各流程沉澱出的 `[upstream-candidate]` 改為 append 到根目錄 `UPSTREAM-CANDIDATES.md`，`ade-feedback-upstream` 從那裡收
58
142
 
59
143
  ### 裝好之後，先記這兩支 skill
60
144
 
61
- - **`/ade-help`** — 「有哪些 skill 可以用？」問它。它即時掃描當前位置真正載得到的 `ade-*` skills 並列出用途，不會像文件一樣過期
62
- - **`/ade-update`** — 說「更新 ADE」，它會先比對版本（一樣就不跑）、提醒手改過的 managed 內容先走 `ade-contribute` 回流（否則被覆蓋），更新完回報版本變化與期間新增的 skill。session 開始偵測到落後時也會主動提醒
145
+ - **`/ade-help`** — 「有哪些 skill 可以用？」問它就對了。它即時掃描當前位置真正載得到的 `ade-*` skills 並列出用途，不會像文件一樣過期。下面的 [Skills](#skills) 表是逐支詳解，`/ade-help` 是隨手可查的目錄。
146
+ - **`/ade-update`** — 步驟 4 的自動版。說「更新 ADE」，它會先比對版本（一樣就不跑）、提醒手改過的 managed 內容先走 `ade-contribute` 回流（否則被覆蓋），更新完回報版本變化與這期間新增的 skill——**新 skill 就是這樣進到你的工作目錄的**。session 開始偵測到落後時也會主動提醒。
63
147
 
64
- ## 結構
148
+ ---
149
+
150
+ ## 核心概念
151
+
152
+ ### 1. 知識單向流出，修改單向流回
65
153
 
66
154
  ```
67
- knowledge/
68
- ├── README.md # 知識分層規則（canonical）
69
- ├── services/ # 服務 registry：index.md 總覽導航 + 一服務一檔 yaml
70
- ├── process/ # 跨服務流程與團隊級慣例
71
- ├── specs/ # 產品規格，持續迭代的真相來源
72
- └── prd/ # 一次開發一檔的需求文件，歷史文件不迭代
73
- skills/ # init 時注入工作目錄的 .claude/skills/（十五支，見下方 Skills）
74
- .claude/skills/ # 在本 repo 內工作用的 skills（ade-feedback-upstream ＋ 七支的 symlink）
75
- claude-md/ # CLAUDE.md managed 區段的內容
76
- CONTEXT.md # ADE 開發流程的統一詞彙表（產品域詞彙另在 knowledge/specs/GLOSSARY.md）
155
+ ADE repo ──── init / update ────▶ 工作目錄的唯讀副本 ────▶ agent 讀取使用
156
+ ▲ │
157
+ └────────── PR（ade-contribute 引導） ◀─────────── 發現過期 / 要新增
158
+ ```
159
+
160
+ 副本永遠會被 update 整個覆蓋，所以**直接改 `.claude/ade/` 等於白改**。這不是限制，而是保證：每個人手上的知識一定是同一份，任何修改都經過 PR 這道 review 閘門。`ade-contribute` 的存在就是把「想改知識」自動導向正確位置——它會在 `workspaces/<ade-repo-name>/` 開分支、改檔、開 PR。
161
+
162
+ ### 2. 只收三類知識
163
+
164
+ 寫進 ADE 的東西要能通過這關（完整規則見 [`knowledge/README.md`](knowledge/README.md)，那份是 canonical）：
165
+
166
+ | 收 | 為什麼 |
167
+ | --- | --- |
168
+ | **跨服務知識** | 單一服務無法自述的：服務定位、服務間依賴、跨服務流程與團隊慣例 |
169
+ | **取得服務的最小資訊** | agent 進 repo 之前必需的：repo URL、預設分支、技術棧概要 |
170
+ | **產品規格與需求** | `specs/` 與 `prd/`，包含單一服務就能完成的功能——spec 的讀者是 PO |
171
+
172
+ **不收**：服務內部的規範、架構細節、安裝啟動測試步驟——那些歸服務自己的 `CLAUDE.md` / `AGENTS.md` / code，clone 下來就有，ADE 不複製一份會過期的副本。
173
+
174
+ ### 3. 產品規格 ≠ 實作規格
175
+
176
+ 兩個詞在 ADE 有嚴格分工，混用會出事（完整詞彙表見 [`CONTEXT.md`](CONTEXT.md)）：
177
+
178
+ - **產品規格（Spec）**— `knowledge/specs/` 的長期資產，描述產品**當前**的整體功能，由 PO 持續迭代。
179
+ - **實作規格**— 一次開發的產出，只描述該次範圍，活在工作目錄，簽核後**凍結**。事後同步產品規格時**以實作結果為準**，不以它為準。
180
+
181
+ 產品規格同時承載「已上線的現況」與「已定案未開發」兩種資訊，靠 `🚧 尚未實作（PRD: …）` 標記區分——所以讀 spec 的人永遠知道哪些行為現在真的存在。
182
+
183
+ ### 4. 需求的完整生命週期
184
+
185
+ ```mermaid
186
+ flowchart LR
187
+ A["想法"] -->|"ade-create-prd"| B["PRD（已確認）"]
188
+ B -->|"ade-prd-to-spec"| C["spec 標 🚧 尚未實作"]
189
+ C -->|"ade-dev"| D["實作完成"]
190
+ D -->|"ade-align-spec"| E["移除 🚧<br/>PRD 標已實作"]
191
+ E -.->|"ade-spec-audit 定期健檢"| C
77
192
  ```
78
193
 
194
+ 1. **PO** 用 `ade-create-prd` 把想法問成 PRD（含 Discovery 與盲點拷問），定案後標「已確認」
195
+ 2. **PO** 用 `ade-prd-to-spec` 把 PRD 融入 `specs/`，新行為標 `🚧`，逐項確認對齊
196
+ 3. **RD** 在工作目錄走 `ade-dev` 六關開發，`ade-ship` 發 MR
197
+ 4. **RD** 開發完跑 `ade-align-spec`：核對實作、移除 🚧、PRD 標「已實作」，開 PR 回本 repo
198
+ 5. 虛線那條是補漏：hotfix 與直接改 code 不會經過上面四步，`ade-spec-audit` 定期抓出這種**規格漂移**
199
+
200
+ 步驟 1、2 在本 repo 或工作目錄都能跑——在工作目錄時走 `ade-contribute`，改的是 `workspaces/` 下的工作副本，最後開 PR。
201
+
202
+ ### 5. Context 是最稀缺的資源
203
+
204
+ 這是貫穿 ADE 一切設計的底層原則：每份文件都要回答「這段內容值得在什麼時機、以什麼成本進入 context？」
205
+
206
+ - **常駐最小**：`CLAUDE.md` managed 區段只寫「何時做＋去哪看」，一條一行
207
+ - **按需載入**：細節分檔存放，skill body 精簡、超過一頁的細節拆出去引用
208
+ - **導航短、細節深**：`services/index.md` 只給一兩行定位，細節在各自的 yaml
209
+
210
+ 新增任何常駐規則前都要先過這一關——這也是為什麼 ADE 的知識不是「把所有文件都塞進去」。
211
+
212
+ ---
213
+
214
+ ## 常用場景速查
215
+
216
+ 在工作目錄開 Claude Code，直接用自然語言說就會觸發對應 skill：
217
+
218
+ | 你想做的事 | 說一句 | 觸發 |
219
+ | --- | --- | --- |
220
+ | 看看現在有哪些 skill 可用 | 「有哪些 skill」 | `ade-help` |
221
+ | 拿到最新知識與新 skill | 「更新 ADE」 | `ade-update` |
222
+ | 知道我們有哪些服務 | 「列出服務」 | `ade-list-service` |
223
+ | 把新服務加進知識庫 | 「新增服務」 | `ade-add-service` |
224
+ | 把一個想法整理成需求文件 | 「建 PRD」 | `ade-create-prd` |
225
+ | 把定案的 PRD 落進規格 | 「PRD 轉 spec」 | `ade-prd-to-spec` |
226
+ | 開始開發一個需求 | 「開始開發」／「繼續開發」 | `ade-dev` |
227
+ | 一次把好幾個任務跑完 | 「批次開發」 | `ade-dev-auto` |
228
+ | 交付：commit 與發 MR | 「commit」／「發 MR」 | `ade-commit`／`ade-ship` |
229
+ | 開發完成，文件收尾 | 「對齊 spec」 | `ade-align-spec` |
230
+ | 懷疑規格跟現況對不上 | 「規格還對嗎」 | `ade-spec-audit` |
231
+ | 發現 ADE 的知識有錯或缺漏 | 「把這個記回知識庫」 | `ade-contribute` |
232
+ | 想把某個做法定成團隊慣例 | 「以後都這樣做」 | `ade-add-process` |
233
+ | 想把某個流程做成 skill | 「新增 skill」 | `ade-add-skill` |
234
+
235
+ ---
236
+
79
237
  ## Skills
80
238
 
81
239
  ### 注入工作目錄的 skills（init 後在工作目錄可用）
@@ -84,19 +242,19 @@ CONTEXT.md # ADE 開發流程的統一詞彙表（產品域詞彙另在 kn
84
242
 
85
243
  | Skill | 用途 | 本 repo |
86
244
  | --- | --- | --- |
87
- | **`ade-help`** | 列出當前位置可用的 ade-* skills 與各自用途（「有哪些 skill」）。清單由 `list-skills.sh` 掃 `.claude/skills/ade-*/SKILL.md` 的 frontmatter 即時產生——不寫死清單，skill 搬家或新增都不用回頭改。 | ✅ |
88
- | **`ade-update`** | 把工作目錄的 managed 內容拉到本 repo 最新版（「更新 ADE」，或 session 開始偵測到落後時）。先用 `git ls-remote` 比對 `.ade.json` 的 `commit`（一樣就不跑）、提醒把 managed 區域的手改先走 `ade-contribute` 回流，才執行 `pnpm dlx <source> update`，最後回報版本變化與期間新增的 skill。只在消費端工作目錄用——本 repo 內用一般 `git pull`。 | — |
89
- | **`ade-contribute`** | 從工作目錄修改本知識庫的**唯一通道**（「改 ADE 的 spec／skill」「回流」）。主動撰寫直接建分支開工；被動回流先查 open issues／PRs 避免重複，沒有才開 issue 記錄缺口、PR 再連回該 issue。工作副本放 `workspaces/<ade-repo-name>/`，已存在就重用、收尾切回主幹。**絕不直接改工作目錄的 `.claude/ade/` 副本**——那是 managed 區域，update 時會被覆蓋。其他 skill 的「開 PR」動作都委派給它。 | — |
90
- | **`ade-add-service`** | 在知識庫註冊新服務（「新增服務」）。依 `knowledge/services/_template.yaml` 建描述檔（`repo` 的 url 與 branch 必填，agent 之後要靠它自主 clone），並同步 `services/index.md` 總覽表。資訊不足會問人，不留空猜測。 | ✅ |
245
+ | **`ade-help`** | 列出當前位置可用的 ade-* skills 與各自用途（「有哪些 skill」「ADE 支援什麼」）。清單由 `list-skills.sh` 掃 `.claude/skills/ade-*/SKILL.md` 的 frontmatter 即時產生——**不寫死清單**，skill 搬家或新增都不用回頭改；掃的是當前位置真正載得到的目錄，工作目錄與 ADE repo 自然列出各自那套。 | ✅ |
246
+ | **`ade-update`** | 把工作目錄的 managed 內容拉到本 repo 最新版（「更新 ADE」，或 session 開始偵測到落後時）。先用 `git ls-remote` 比對 `.ade.json` 的 `commit`（一樣就不跑）、提醒把 managed 區域的手改先走 `ade-contribute` 回流，才執行 `pnpm dlx <source> update`，最後回報版本變化與期間新增的 skill。**只在消費端工作目錄用**——本 repo 內沒有 managed 副本，用一般 `git pull`。 | — |
247
+ | **`ade-contribute`** | 從工作目錄修改本知識庫的**唯一通道**（「改 ADE 的 spec／skill」「回流」）。主動撰寫直接建分支開工；被動回流先查 open issues／PRs 避免重複，沒有才開 issue 記錄缺口、PR 再連回該 issue。工作副本放 `workspaces/<ade-repo-name>/`，已存在就重用、收尾切回主幹，人只需 review PR。本地模式（`source` 是路徑）沒有 issue／PR：push 分支交人 merge。**絕不直接改工作目錄的 `.claude/ade/` 副本**——那是 managed 區域，update 時會被覆蓋。其他 skill 的「開 PR」動作都委派給它。 | — |
248
+ | **`ade-add-service`** | 在知識庫註冊新服務（「新增服務」）。依 `knowledge/services/_template.yaml` 建描述檔（`repo` 的 url 與 branch 必填，agent 之後要靠它自主 clone），並同步 `services/index.md` 總覽表。資訊不足會問人，不留空猜測。在本 repo 直接編輯收尾，在工作目錄則走 `ade-contribute`。 | ✅ |
91
249
  | **`ade-list-service`** | 列出目前所有已註冊的服務（「有哪些服務」）。讀 `services/index.md` 並與目錄下的描述檔比對，回報清單與兩者不一致處。只讀不改。 | ✅ |
92
250
  | **`ade-create-prd`** | 引導 PO 產出標準化 PRD（「建 PRD」），涵蓋「只有模糊想法」到「照範本填寫」兩種起點。想法未成形先跑 **Discovery** 7 題（一批 2–3 題，已有答案的跳過），接著對照服務總覽、既有 spec 與進行中 PRD 用團隊詞彙寫入 `knowledge/prd/`，再進**盲點拷問**（邊界與錯誤情境、跨服務影響、權限安全、資料相容性、驗收可測性、相鄰功能），最後用 `validate-prd.sh` 機械檢查。**不自動翻狀態**——留「草稿」，PO 確認才改「已確認」。 | ✅ |
93
251
  | **`ade-prd-to-spec`** | 把已確認的 PRD 落入規格（「PRD 轉 spec」）。找出受影響的 spec（必要時新建），將需求寫成「功能完成後應有的樣子」，並在每個新增／變更的行為區塊上方加 `🚧 尚未實作（PRD: …）`——spec 因此同時承載「已上線現況」與「已定案未開發」，靠標記區分。完成後回填 PRD 的「Spec 異動摘要」，帶 PO 逐項確認。產出即 RD 開發時的規格依據。 | ✅ |
94
252
  | **`ade-dev`** | 判準制標準開發流程（「開始開發」「繼續開發」）。六關：規格（實作規格，人簽核後凍結）→ 規劃（Phase 地圖）→ 實作（逐 Phase 輪到才展開，TDD 紅→綠，交前兩軸審查）→ 測試審視 → 沉澱 → Ship。每關只定義產出與過關判準，不規定做法；狀態全在 `.ade-dev/`，session 可隨時 `/clear` 換手。內建 **Spec Ready gate G1–G8 與 auto-pilot 模式**，配零容忍煞車與有限重試。規則全在 `knowledge/process/ade-dev-workflow/`，skill 只是指標。 | — |
95
253
  | **`ade-dev-auto`** | 串接多個 ade-dev 任務的批次執行器（「批次開發」）。列出 `.ade-dev/` 下未完成任務供多選，逐顆跑 Spec Ready 判定，不合格的問人補齊或剔除，全數就緒後依序 auto-pilot 執行。只定義批次層 B1–B4 與批次熔斷，任務內判準全在 ade-dev。 | — |
254
+ | **`ade-ship`** | 從服務 repo 分支發出 MR／PR（「發 MR」「ship」），也是 ade-dev 第 6 關與 ade-dev-auto 的交付通道。偵測平台（GitHub → `gh`、GitLab → `glab`，退 API）、專案自有範本優先（GitHub 六個位置＋組織預設、GitLab 設定層與 `.gitlab/merge_request_templates/`）、沒有就用內建 `templates/mr.md`，依實際 diff 填寫後發出並回報 URL。不自動 merge。 | — |
255
+ | **`ade-commit`** | commit 訊息慣例解析，任何要在服務 repo commit 的場景使用。依序找專案自述（CLAUDE.md／AGENTS.md／CONTRIBUTING）→ commitlint 等設定檔 → 既有 git log 風格 → 都沒有才用 ADE 預設（`knowledge/process/git-commit.md`，Conventional Commits）。一個 commit 一件事。 | — |
96
256
  | **`ade-align-spec`** | 開發收尾的文件對齊（「開發完了更新 spec」）。對照實際實作逐一核對該 PRD 的 `🚧 尚未實作` 標記：做完且一致的移除、有出入的**以實作為準**改 spec 並記差異、沒做的保留；驗收項全完成時 PRD 轉「已實作」。最後開 PR 把差異清單交 PO 判斷。只動屬於這次 PRD 的標記。 | — |
97
257
  | **`ade-spec-audit`** | spec 的定期健檢（「規格還對嗎」）。PRD 流程只覆蓋計畫內開發，hotfix 與直接改 code 會讓 spec 悄悄失真——這支補上偵測路徑：逐份 spec 對照實作（缺的 repo 會先 clone），找出行為已變／功能已移除／實作有但 spec 沒記載的漂移，產出清單讓人決定修 spec 還是修 code，確認後開 PR。建議 release 後或定期執行。 | — |
98
- | **`ade-commit`** | commit 訊息慣例解析，任何要在服務 repo commit 的場景使用。依序找專案自述（CLAUDE.md／AGENTS.md／CONTRIBUTING）→ commitlint 等設定檔 → 既有 git log 風格 → 都沒有才用 ADE 預設（`knowledge/process/git-commit.md`，Conventional Commits）。一個 commit 一件事。 | — |
99
- | **`ade-ship`** | 從服務 repo 分支發出 MR／PR（「發 MR」「ship」）。偵測平台（GitHub → `gh`、GitLab → `glab`，退 API）、專案自有範本優先（GitHub 六個位置＋組織預設、GitLab 設定層與 `.gitlab/merge_request_templates/`）、沒有就用內建 `templates/mr.md`，依實際 diff 填寫後發出並回報 URL。不自動 merge。 | — |
100
258
  | **`ade-add-skill`** | 新增 skill 的 meta-skill（「把這個做成 skill」）。先問使用對象再決定位置：消費端工作目錄用 → `skills/ade-*`（init/update 注入）；本 repo 內用 → `.claude/skills/ade-*`；兩邊都用 → 放 `skills/` 加 symlink。並落實 `ade-` 命名規則、context 紀律與 README 同步。 | ✅ |
101
259
  | **`ade-add-process`** | 建立或修改流程慣例的 meta-skill（「以後都這樣做」）。依三層機制選載體：無條件約束 → `claude-md/section.md` 加一行指標；有觸發時機的程序 → 新增一支 `ade-` 前綴 skill；細節 → `process/` 一主題一檔。並執行 context 紀律：常駐層只寫「何時做＋去哪看」，常駐規則超過 10 行時新增前必須與使用者確認取捨。 | ✅ |
102
260
 
@@ -106,18 +264,26 @@ CONTEXT.md # ADE 開發流程的統一詞彙表（產品域詞彙另在 kn
106
264
  | --- | --- |
107
265
  | **`ade-feedback-upstream`** | 把本 repo 演化出的**機制**改良（更好的 skill 寫法、模板結構、流程設計）以 **issue** 回饋給上游 create-agentic-dev-env 框架，由上游維護者決定是否採納，讓所有 ADE repo 受益。改良來源除了日常觀察，也包括本 repo 標題前綴 `[upstream-candidate]` 的 issues（各流程收尾沉澱時經 `ade-contribute` 開出）。鐵律：只回饋機制、**絕不回饋內容**——`knowledge/` 下的公司知識、服務資訊、規格全屬機密，送出前逐行檢查 issue 內文、把公司語彙抽換成通用範例。上游位址記在 `package.json` 的 `ade.upstream`。 |
108
266
 
109
- ## PRD / Spec 流程
267
+ ---
110
268
 
111
- 1. PO 用 `ade-create-prd` 建立標準化 PRD（含 Discovery 與盲點拷問），定案後標「已確認」
112
- 2. PO 用 `ade-prd-to-spec` 把 PRD 融入 `specs/`，新行為標 `🚧 尚未實作`，逐項確認對齊
113
- 3. RD 在工作目錄走 `ade-dev` 六關開發（`workspaces/`），`ade-ship` 發 MR
114
- 4. 開發完成 RD 跑 `ade-align-spec`：核對實作、移除 🚧、PRD 標「已實作」，開 PR 回本 repo
115
- 5. 補漏：hotfix 與直接改 code 不會經過上面四步，`ade-spec-audit` 定期抓出這種規格漂移
269
+ ## 本 repo 結構
116
270
 
117
- 步驟 1、2 在本 repo 或工作目錄都能跑——在工作目錄時走 `ade-contribute`，改的是 `workspaces/` 下的工作副本，最後開 PR。
271
+ ```
272
+ knowledge/
273
+ ├── README.md # 知識分層規則（canonical）
274
+ ├── services/ # 服務 registry：index.md 總覽導航 + 一服務一檔 yaml
275
+ ├── process/ # 跨服務流程與團隊級慣例（含 ade-dev-workflow/ 開發流程規則）
276
+ ├── specs/ # 產品規格，持續迭代的真相來源；GLOSSARY.md 是產品域詞彙
277
+ └── prd/ # 一次開發一檔的需求文件，歷史文件不迭代
278
+ skills/ # init 時注入工作目錄的 .claude/skills/（十五支，見上方 Skills）
279
+ .claude/skills/ # 在本 repo 內工作用的 skills（ade-feedback-upstream ＋ 七支的 symlink）
280
+ claude-md/ # CLAUDE.md managed 區段的內容
281
+ CONTEXT.md # ADE 開發流程的統一詞彙表
282
+ UPSTREAM-CANDIDATES.md # 本地模式下 [upstream-candidate] 的落點（有 issue tracker 時留空）
283
+ ```
118
284
 
119
285
  ## 維護原則
120
286
 
121
- - 工作目錄裡的 ADE 內容是唯讀副本，update 會覆蓋。所有修改都回到本 repo 走 PR——agent 端由 `ade-contribute` 引導完成
122
- - 知識分層：本 repo 只收跨服務知識、取得服務的最小資訊、產品規格三類——完整規則見 `knowledge/README.md`（canonical）
123
- - 使用中演化出的**機制**改良（skill 寫法、模板、流程），用 `ade-feedback-upstream` skill 回饋給 create-agentic-dev-env 上游；公司知識內容絕不外流
287
+ - **副本唯讀**：工作目錄裡的 ADE 內容 update 會覆蓋，所有修改都回到本 repo 走 PR——agent 端由 `ade-contribute` 引導完成
288
+ - **分層有界**：本 repo 只收跨服務知識、取得服務的最小資訊、產品規格三類，完整規則以 [`knowledge/README.md`](knowledge/README.md) 為準
289
+ - **機制回饋、內容不外流**：使用中演化出的**機制**改良（skill 寫法、模板、流程）用 `ade-feedback-upstream` 回饋給 [create-agentic-dev-env](https://github.com/franKobayasi/agentic-dev-env) 上游；`knowledge/` 下的公司知識絕不外流
package/template/UPSTREAM-CANDIDATES.md ADDED
@@ -0,0 +1,15 @@
1
+ # Upstream candidates
2
+
3
+ 各流程收尾沉澱時發現的**機制層**改良（skill 寫法、模板結構、流程設計——非本團隊服務專屬），等 `ade-feedback-upstream` 收割回饋給 create-agentic-dev-env。
4
+
5
+ ADE repo 放 GitHub／GitLab 時用標題前綴 `[upstream-candidate]` 的 issue 記，本檔留空；**本地模式**（沒有 issue tracker）改 append 在此，一則一節。內文只描述機制，不含服務名稱與程式碼；回饋完成的節刪掉。
6
+
7
+ 本檔不會被複製進工作目錄（runner 只複製 `knowledge/`、`skills/`、`claude-md/`）。
8
+
9
+ <!--
10
+ ## YYYY-MM-DD <一句話標題>
11
+
12
+ - 解決什麼問題：
13
+ - 在本 repo 的實際效果：
14
+ - 建議的通用作法：
15
+ -->
package/template/dot-claude/skills/ade-feedback-upstream/SKILL.md CHANGED
@@ -14,7 +14,7 @@ description: 將本 ADE repo 演化出的機制改良（skill 寫法、模板結
14
14
 
15
15
  ## 流程
16
16
 
17
- 1. 取得上游 repo 位址：`package.json` 的 `ade.upstream`（為 null 則詢問使用者）。改良來源除了日常觀察，也包括本 repo 標題前綴 `[upstream-candidate]` 的 issues（各流程收尾沉澱時經 `ade-contribute` 開出，如 ade-dev 第 5 關）
17
+ 1. 取得上游 repo 位址：`package.json` 的 `ade.upstream`（為 null 則詢問使用者）。改良來源除了日常觀察，也包括本 repo 標題前綴 `[upstream-candidate]` 的 issues（各流程收尾沉澱時經 `ade-contribute` 開出，如 ade-dev 第 5 關），以及根目錄 `UPSTREAM-CANDIDATES.md`（本地模式的替代，回饋完把該節刪掉）
18
18
  2. **查重**：查上游的 open issues（`gh issue list -R <upstream>`），同一改良已有記錄 → 在該 issue 留言補充使用經驗，不重複開
19
19
  3. 開 issue（`gh issue create -R <upstream>`），內容包含：
20
20
  - 這個改良解決什麼問題
package/template/knowledge/process/ade-dev-workflow/gates.md CHANGED
@@ -48,7 +48,7 @@
48
48
 
49
49
  - 產品規格與實作一致：有 PRD 走 `ade-align-spec`；無 PRD 但動了產品行為 → 起草產品規格更新、**人確認後**依 `ade-contribute` 流程送出
50
50
  - `notes.md` 收整成清單給人審視：關鍵發現、決策、流程摩擦與改良建議
51
- - 清單中屬**機制層**的改良（skill 寫法、模板結構、流程設計，非本服務專屬），依 `ade-contribute` 在 ADE repo 開一則標題前綴 `[upstream-candidate]` 的 issue——內文只描述機制、不含服務名稱與程式碼；是否回饋上游由 ADE repo 維護者判斷，**不在本流程內執行**
51
+ - 清單中屬**機制層**的改良（skill 寫法、模板結構、流程設計，非本服務專屬），依 `ade-contribute` 在 ADE repo 開一則標題前綴 `[upstream-candidate]` 的 issue（本地模式沒有 issue：append 到 ADE repo 根的 `UPSTREAM-CANDIDATES.md`）——內文只描述機制、不含服務名稱與程式碼；是否回饋上游由 ADE repo 維護者判斷，**不在本流程內執行**
52
52
 
53
53
  ## 第 6 關：Ship
54
54
 
package/template/skills/ade-contribute/SKILL.md CHANGED
@@ -15,7 +15,7 @@ description: 從工作目錄修改中央 ADE 知識庫並開 PR（ADE repo 只
15
15
  3. **判斷起點**，兩種：
16
16
  - **主動撰寫**（使用者明確要求新增或調整 spec、skill、process、服務描述檔）→ 不開 issue，直接進第 4 步
17
17
  - **被動回流**（工作中發現知識庫過期或缺漏）→ 先查重：`gh issue list` / `gh pr list`，同一缺口已有記錄就在該 issue/PR 留言補充，到此結束；沒有才開 issue 描述缺什麼／哪裡過期／在哪個工作情境發現的，issue 是查重與追蹤的協調點
18
- - 〔本地〕查重改看 `git branch -r` 與 `git log origin/main --oneline -30` 有無同一缺口的分支或 commit；不開 issue，缺口描述（缺什麼／哪裡過期／在哪個情境發現）寫進 commit body
18
+ - 〔本地〕查重改看 `git branch -r` 與 `git log origin/main --oneline -30` 有無同一缺口的分支或 commit；不開 issue，缺口描述（缺什麼／哪裡過期／在哪個情境發現）寫進 commit body；`[upstream-candidate]` 類的機制改良則 append 到 ADE repo 根的 `UPSTREAM-CANDIDATES.md`（同樣走分支）
19
19
  4. 修改 `knowledge/` 下對應文件
20
20
  - 修改前先讀原文，沿用既有格式與詞彙
21
21
  - 服務描述檔必須符合 `knowledge/services/_template.yaml` 的欄位結構；收錄範圍遵守 `knowledge/README.md` 的分層規則與「底層原則：Context 管理」（常駐最小、細節分檔按需載入）