uncle6me-web
5d00e71275
頂層 D22 決策（leo 2026-07-03 拍板）：推什麼由開發環境歸屬決定， Gitea private＝除機敏值/build 產物/.github 外全 push。 解 T1.5 卡點：雲端工人 clone 拿得到 credential-store-migration.md，可就地改寫 SDD。 機敏掃描兩輪通過（新增 189 檔約 2.1MB，node_modules/dist/wasm 照舊排除）。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
100 lines
4.5 KiB
Markdown
100 lines
4.5 KiB
Markdown
# SDD 協議（每次啟動必讀）
|
||
|
||
## 第零原則：沒讀 SDD 不准動 code
|
||
|
||
任何 `.go` / `.ts` / `.tsx` / `.wasm` 相關變動，**必須**按以下順序執行。**不得簡化，不得跳過**。
|
||
|
||
### 步驟 1：讀總進度
|
||
|
||
先讀 `docs/3-specs/arcrun/arcrun.md`，了解當前 Phase。
|
||
|
||
### 步驟 2：定位對應 SDD
|
||
|
||
根據任務性質找對應 SDD：
|
||
|
||
| 任務類型 | 對應 SDD |
|
||
|---------|---------|
|
||
| Auth primitive WASM 零件（static_key/oauth2/service_account/mtls） | `docs/3-specs/arcrun/credential-primitives-wasm/` |
|
||
| 清除 cypher-executor 裡的 TS 業務邏輯 | `docs/3-specs/arcrun/credential-primitives-wasm/` |
|
||
| WASI shim host functions（kv_get / crypto_decrypt / crypto_sign_rs256） | `docs/3-specs/arcrun/credential-primitives-wasm/` |
|
||
| Auth Recipe 系統（recipe schema、KV 格式） | `docs/3-specs/arcrun/auth-recipe.md` |
|
||
| Landing Page | `docs/3-specs/arcrun/landing-page.md` |
|
||
| CLI / SDK（Python/JS） | `docs/3-specs/arcrun/sdk-and-website/` |
|
||
| arcrun-core-mvp 整體架構 | `docs/3-specs/arcrun-core-mvp/` |
|
||
| Platform Evolution | `docs/3-specs/arcrun-platform-evolution/` |
|
||
| Credential 長期規格（需求源） | `docs/user_requirements/credential_parts.md` |
|
||
|
||
讀 `design.md` 和 `tasks.md` 兩份。
|
||
|
||
### 步驟 3：宣告（強制格式）
|
||
|
||
開始動手前，在回覆開頭**逐字**貼出以下宣告：
|
||
|
||
```
|
||
📋 已讀 SDD：
|
||
- docs/3-specs/arcrun/arcrun.md（當前 Phase：<phase 名稱>）
|
||
- <對應 SDD 的 design.md 路徑>
|
||
- <對應 SDD 的 tasks.md 路徑>
|
||
|
||
🎯 本次對應 task：<task 編號，例如 "Phase 1.3 實作 auth_static_key main.go">
|
||
|
||
📐 本次 task 的 SDD 規範摘要：
|
||
- <重點 1>
|
||
- <重點 2>
|
||
- <重點 3>
|
||
|
||
🚧 執行範圍：
|
||
- 會修改：<檔案清單>
|
||
- 會建立：<檔案清單>
|
||
- 會刪除：<檔案清單>
|
||
```
|
||
|
||
**不做這個宣告 = 違反 SDD 協議 = 停手等 richblack**。
|
||
|
||
### 步驟 4：check tasks.md 狀態
|
||
|
||
動手前：在 tasks.md 把對應 task 的 `- [ ]` 改成 `- [🔄]`（進行中標記）。
|
||
完成後：改成 `- [x]`，不批次更新，每完成一個就立刻改。
|
||
|
||
## 什麼算「任務超出 SDD 範圍」？
|
||
|
||
以下情況屬於 **change**，不是 **modify**，**必須停手並與 richblack 確認**：
|
||
|
||
- SDD 沒寫到的新功能
|
||
- 新增頂層目錄
|
||
- 新增新的 Worker（不管是 cypher-executor / registry / 零件 worker）
|
||
- 修改架構決策（例如「改用 xxx 取代 yyy」）
|
||
- 跨多個子系統的連鎖修改
|
||
|
||
**停手不是怯懦，是專業**。猜錯方向比慢一小時更糟。
|
||
|
||
## 新增 SDD 的完整程序（richblack 確認後怎麼往下走）
|
||
|
||
> 2026-06-03 補：之前協議只寫「停手等確認」，沒寫「確認後怎麼做」，導致 CC 被
|
||
> `pre-write-guard.sh` 規則 4.3 擋下後不知正路、卡死。這節補完整程序。
|
||
|
||
當「新增一個 SDD 子系統」（在 `docs/3-specs/` 下開新頂層目錄）：
|
||
|
||
1. **停手，向 richblack 說明要新建哪個 SDD、為什麼**（change，見上節）。
|
||
2. **取得 richblack 明確確認**後，依序：
|
||
1. **更新白名單**：在 `.claude/hooks/pre-write-guard.sh` 的 `KNOWN_SDDS` 陣列加一行
|
||
`"docs/3-specs/<新目錄名>" # YYYY-MM-DD richblack 確認新建（<一句用途>）`。
|
||
（這步是「執行 richblack 已授權任務的必要步驟」，不是 AI 擅自放寬 guardrail——
|
||
授權脈絡要明確，分類器才放行；沒有明確授權就改白名單 = 越界。）
|
||
2. **建目錄 + 寫 design.md / tasks.md**（白名單放行後才寫得進去）。
|
||
3. **若沒先更新白名單就 Write** → 規則 4.3 會擋你（這是對的，表示你跳了步驟 2.i）。
|
||
|
||
**為什麼白名單而非全放行**：開新 SDD 子系統 = 宣告新架構範圍，是稀有的人類決策點。
|
||
白名單讓「AI 自己無中生有開子系統」必停下（AI 改不了白名單，除非 richblack 明確授權該任務）。
|
||
已許可的目錄內寫檔零摩擦。
|
||
|
||
## 發現 SDD 本身有問題怎麼辦？
|
||
|
||
- SDD 和實作不一致 → 停手，列出矛盾點，與 richblack 確認哪一邊是對的
|
||
- SDD 規範之間互相矛盾（例如禁令 A 和設計 B 衝突）→ 停手，引用矛盾原文，與 richblack 確認
|
||
- **不可以自行猜哪個是對的**。CC 之前兩天就是這樣走錯的。
|
||
|
||
## 為什麼這個協議存在
|
||
|
||
arcrun 規範已經足夠細緻，CC 之前出錯不是因為不懂，而是因為**沒讀**或**讀了覺得「大概是這個意思」就動手**。SDD 協議強制把「先讀 → 定位 → 宣告 → 執行 → 更新」做成一條死規矩，沒有繞過去的路徑。
|