create-agentic-dev-env 0.2.0 → 0.2.1

package/README.md

@@ -60,6 +60,7 @@ claude-md/       # CLAUDE.md managed 區段的內容
 
 ### 設計重點
 
+- **Context 管理是底層原則**：agent 的 context 是最稀缺資源，所有文件與流程設計都遵守「常駐最小化、細節按需載入、導航短細節深」——CLAUDE.md 區段只寫「何時做＋去哪看」，細節留在知識庫等被載入
 - **服務 registry 兩層結構**：`index.md` 是全服務概覽（模擬工程師「先總覽定位、再查細節」的認知路徑），每個服務一份 YAML 記錄 repo 位址、技術棧、依賴關係——agent 據此自主 clone 與開發
 - **知識分層**：ADE 只收「跨服務知識、取得服務的最小資訊、產品規格」三類；bootstrap 流程與服務內部慣例歸服務 repo 自己的文件，不複製會過期的副本
 - **PRD → Spec 生命週期**：PO 用 skill 建標準化 PRD（含盲點拷問）→ 轉入 spec 並標 `🚧 尚未實作` → RD 開發完成後由 skill 核對實作、移除標記、開 PR 收尾；另有 `ade-spec-audit` 定期巡檢，抓 hotfix 等計畫外變更造成的規格漂移

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agentic-dev-env",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Scaffold and manage team Agentic Dev Environment (ADE) knowledge repos",
   "repository": {
     "type": "git",

package/template/CLAUDE.md

@@ -4,12 +4,10 @@
 
 ## PRD / Spec 生命週期
 
-- `knowledge/prd/`：一次開發一檔的需求文件，歷史文件不迭代（草稿 → 已確認 → 已實作）
-- `knowledge/specs/`：當前功能的真相來源，持續迭代；`🚧 尚未實作` 標記代表已定案未開發
-
-流程：PO 用 `ade-create-prd` 建 PRD → 確認後用 `ade-prd-to-spec` 更新 spec（標 🚧）→ RD 於工作目錄開發 → 開發完成 RD 跑 `ade-align-spec`（注入工作目錄的 skill）開 PR 回本 repo 收尾。
+PO 用 `ade-create-prd` 建 PRD → 確認後用 `ade-prd-to-spec` 更新 spec（標 🚧）→ RD 於工作目錄開發 → 開發完成 RD 跑 `ade-align-spec`（注入工作目錄的 skill）開 PR 回本 repo 收尾。文件定位與狀態規則見 `knowledge/prd/README.md`、`knowledge/specs/README.md`。
 
 ## 編輯慣例
 
+- **任何文件或流程的設計都遵守 `knowledge/README.md` 的「底層原則：Context 管理」**——常駐最小化、細節按需載入、導航短細節深
 - 服務描述檔必須符合 `knowledge/services/_template.yaml` 欄位結構，並同步更新 `services/index.md` 總覽；收錄範圍遵守 `knowledge/README.md` 的分層規則
 - 修改 spec 時沿用既有詞彙；PRD 只在「已實作」前可改

package/template/claude-md/section.md

@@ -21,6 +21,4 @@
 
 ### 知識維護
 
-- 發現知識過期、缺漏，或學到新慣例 → 用 `ade-contribute` skill 開 PR 回 ADE repo
-- 要註冊新服務 → 用 `ade-add-service` skill
-- `.claude/ade/` 與 `.claude/skills/ade-*/` 為 managed 區域，勿直接修改
+`.claude/ade/` 與 `.claude/skills/ade-*/` 為 managed 區域、視同唯讀；回流、註冊服務、建立流程等維護動作由 ade-* skills 引導。

package/template/knowledge/README.md

@@ -2,6 +2,16 @@
 
 本檔是 ADE 知識分層的唯一權威定義；其他文件提到分層時一律指回這裡。
 
+## 底層原則：Context 管理
+
+**這是貫穿 ADE 一切文件與流程設計的核心邏輯**，任何新增或修改設計時都先過這一關：agent 的 context 是最稀缺的資源，每一份文件都要回答「這段內容值得在什麼時機、以什麼成本進入 context？」
+
+- **常駐內容最小化**：CLAUDE.md 區段只寫「何時做＋去哪看」，一條一行
+- **參考技巧**：細節分檔存放、按需載入；skill body 精簡，超過一頁的細節拆出去引用
+- **導航短、細節深**：總覽檔（index）給定位用的一兩行，細節留在單體檔案（services 的 index/yaml 雙層就是這個原則的體現）
+
+本檔以下的分層規則、process 的放置決策規則（`process/README.md`），都是這個原則在各自領域的應用。
+
 ADE 只收錄三類知識：
 
 ## 1. 跨服務知識
@@ -24,10 +34,6 @@ agent 進入服務 repo 之前必需的：repo URL、預設分支、技術棧概
 
 服務內部的規範、慣例、架構細節，歸服務 repo 自己的 CLAUDE.md 或 AGENTS.md（有哪個讀哪個，都有就都讀）；都沒有就讀 code。服務內部慣例**不回流**到 ADE。
 
-## Context 管理原則
-
-所有文件的載入設計都要考慮 agent 的 context 成本：常駐內容（CLAUDE.md 區段）最小化，只寫「何時做＋去哪看」；細節分檔存放、按需載入（參考技巧）；導航檔短、細節檔深。
-
 ## 過期修正規則
 
 ADE 側資訊（定位、repo 位址／分支、技術棧、依賴關係）與服務 repo 現實不符時：**以服務 repo 為準**繼續手頭工作，**任務收尾時**用 `ade-contribute` 開 PR 修正 ADE，無需先徵詢——PR 本身就是 review 閘門。

package/template/skills/ade-add-process/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ade-add-process
-description: 為團隊建立或修改流程慣例，依三層機制（常駐規則、skill、參考文件）落地到 ADE 知識庫，讓所有 init 過的環境 follow。使用者說「建立一個流程」「定一個慣例」「以後都這樣做」「每次都要」「把這個做法固定下來」時使用。
+description: 為團隊建立或修改流程慣例並落地到 ADE 知識庫。使用者說「建立一個流程」「定一個慣例」「以後都這樣做」「每次都要」「把這個做法固定下來」時使用。
 ---
 
 # 建立／修改流程

package/template/skills/ade-contribute/SKILL.md

@@ -14,7 +14,7 @@ description: 將工作過程中發現的知識缺口、過期文件、新慣例
 3. **開 issue 記錄缺口**：一段話描述缺什麼／哪裡過期、在哪個工作情境發現的——issue 是查重與追蹤的協調點
 4. Clone 到暫存目錄：`git clone <source> <tmpdir>/ade`，建立分支，修改 `knowledge/` 下對應文件
    - 修改前先讀原文，沿用既有格式與詞彙
-   - 服務描述檔必須符合 `knowledge/services/_template.yaml` 的欄位結構；收錄範圍遵守 `knowledge/README.md` 的分層規則
+   - 服務描述檔必須符合 `knowledge/services/_template.yaml` 的欄位結構；收錄範圍遵守 `knowledge/README.md` 的分層規則與「底層原則：Context 管理」（常駐最小、細節分檔按需載入）
 5. Commit、push 分支，開 PR 並連結 issue（描述加 `Closes #<issue 編號>`；GitHub 用 `gh pr create`，GitLab 用 `glab mr create`）
    - gh/glab 不可用或未登入時的降級路徑：push 分支後，把 compare／new-MR 網址給使用者，請人手動開
 6. 告知使用者 PR 連結；merge 後在工作目錄執行 update 即可取得新版