EGS — 為什麼 AI 代理需要工程治理規範

想像一個工程團隊，每個成員都有不同版本的規範手冊。有些人遵循上個月的版本，有些人根本沒有手冊。每次新人加入，都需要口頭重新解釋所有不成文的規則。

這就是沒有治理規範的多代理系統的真實樣貌。

問題：沒有規範的 AI 代理

AI 代理的問題不是能力不足，而是行為不一致。

每個 Claude 的 session 都從零開始。沒有記憶延續，沒有自動的行為校準。如果你不明確告訴代理「怎麼做」，它就會用自己的默認行為填補空白——而那些默認行為不一定符合你的需求。

SuperPortia 在實際運作中遇到了具體的失敗案例：

「編輯了三次錯誤的檔案」事件：代理確信自己在改正確的路徑，因為 ADR-0010 文件說那是「正確的 repo」。但 launchd 實際上還在從舊的 monorepo 路徑執行服務。代理在那個不會生效的檔案上改了三次，才發現自己一直在看錯地方。沒有一個規則要求代理在編輯前先確認「哪個路徑實際上正在執行」。

文件壓縮缺陷：代理在寫文件時，自然地把內容精簡成摘要。- Added README.md、Synced .claude/、See ADR for details。這在程式碼注解裡是美德，在交接文件裡是嚴重缺陷——下一個 session 的代理拿到這份文件，完全無法接手工作，因為所有背景、路徑、決策理由都被壓縮掉了。這個問題反覆出現，直到被明確定性為「嚴重缺陷」並寫入規則。

SS2 設定漂移事件：兩台機器（SS1 Mac、SS2 Windows）各自維護 .claude/ 設定。隨著時間推移，SS2 落後了 11 個 hook、2 個版本的 EGS 規則。當代理在 SS2 上工作時，行為和 SS1 完全不同——但沒有人在事發前注意到這個漂移。

這三個事件有個共同點：都是可預防的，只要有明確的書面規範。

EGS 是什麼

EGS（Engineering Governance Spec）是 SuperPortia 的工程規範手冊。它定義了所有代理應該怎麼寫程式、怎麼寫文件、哪些決策需要人工確認、以及如何分類行為。

目前版本是 v1.2，已記錄在 Universal Brain（entry ID: ub-5d9f36e55da6）並推送至 superportia-ops 的 main 分支（commit 5493d56）。

EGS 的核心架構概念是 Progressive Disclosure（PD）——漸進式揭露，三層載入：

L1 — CLAUDE.md        ← 每個 repo 的入口，最精簡
L2 — Rules            ← 行為規則，每個 session 自動載入
L3 — Skills           ← 操作 SOP，按需載入

這個設計解決了一個基本矛盾：你希望代理知道所有重要規則，但把所有規則塞進 context 既浪費 token，又讓代理在開始工作前要讀大量前置材料。PD 的解法是：行為規則（L2）永遠載入，工具操作流程（L3）只在需要時才載入。

Rules 和 Skills 的區別

v1.2 最關鍵的概念釐清就是這個。

Rules（規則）：行為模式，描述代理「應該怎麼做事」。例如：寫完任何 .md 文件都必須跑六項自檢清單、在任何技術決策前先驗證知識新鮮度、不能直接問 Captain 要 API token。這些是習慣，不是程序。它們需要永遠載入（L2），因為它們影響所有工作的方式。

Skills（技能）：操作 SOP，描述「如何執行特定工具或流程」。例如：怎麼跑 sync script、如何走新專案建立的完整流程、如何查詢 Cloudflare Dashboard。這些是程序，不是習慣。只在執行對應任務時才需要（L3）。

在 v1.2 之前，有 4 個 Skills 實際上是行為規範偽裝成 SOP——它們描述的是代理應該怎麼做事，而不是怎麼使用工具。v1.2 把它們轉換成了 Rules，並新增了 5 個 Rules 覆蓋缺漏的行為領域。

這個區別看起來是學術的，但在執行上有本質差異：Rules 在 L2 確保不會被遺漏，Skills 在 L3 確保不佔用不必要的 context。

v1.2 的關鍵改變

v1.2 的改動集中在三個方向：

一、PD Classification Principle（行為/工具的分類原則）：上面說的 Rules vs Skills 重新劃分。直接結果是 4 個 Skills 轉為 redirect stubs（保留入口但指向 Rules），5 個新 Rules 建立。

二、Mandatory Self-Check（強制文件自檢）：任何 .md 文件寫完之後，代理必須在回覆中輸出一個六項清單：

📋 Doc Quality Self-Check:
- [ ] Context: 有背景說明嗎？
- [ ] Specifics: 有具體數字/路徑/ID 嗎？
- [ ] Before/After: 有變更的前後狀態嗎？
- [ ] Anti-pattern check: 沒有觸犯禁止的做法？
- [ ] Handoff test: 下個 session 看這份文件能接手嗎？
- [ ] Self-contained: 不需要跳轉就能理解？

這個清單要在回覆中可見——不是在代理腦袋裡默默過一遍，而是輸出出來讓人看到。任何一項失敗就要先修文件，修完重新自檢。

三、Formal Glossary（正式詞彙表）：v1.2 加入了 SuperPortia 所有核心術語的正式定義：PK、PD、GSTA、SSoT、HITL、HOTL、EGS、MTAAA、PAM、ADLC、UB、WO、CV、UB Dock、UB 正區。這解決了術語理解漂移的問題——代理和人看到同一個詞，指的是同一件事。

EGS v1.2 核心模組一覽

模組	層級	類型	說明
CLAUDE.md	L1	入口	每個 repo 的最精簡入口，Session 起點
orchestrator-baseline.md	L2	Rule	Opus 行為規範，dispatch packet 要求
cost-awareness.md	L2	Rule	Token 成本紀律，Opus vs Sonnet vs Haiku 角色
documentation-standards.md	L2	Rule	文件詳細度強制標準 + 六項自檢清單
corrections.md	L2	Rule	歷史教訓登記，每個 session 都載入
cross-ship-sync.md	L2	Rule	五鐵律，防止跨機器 config 漂移
task-dispatch/SKILL.md	L3	Skill	dispatch packet 填寫 SOP，按需載入
daily-log/SKILL.md	L3	Skill	工作日誌寫入 SOP，session 結束時載入

Rules 和 Skills 的載入策略

L2 Rules 在每個 session 自動載入，確保行為一致性。L3 Skills 只在需要時才載入，避免在任務開始前就把 context 填滿不相關的內容。這個漸進式揭露（Progressive Disclosure）是 EGS 的核心設計原則。

規則沒有執行機制等於無效

EGS v1.2 的設計教訓：光寫規則不夠。corrections.md 記錄了多個「規則存在但被忽略」的事故。每一條關鍵規則都需要配套的 hook 或結構性約束——例如文件自檢清單有 Stop hook 強制執行，deploy 前 dry-run 有 deploy-gate.sh 阻止繞過。

執行機制：規則怎麼變成真實約束

光有文件是不夠的。EGS 的執行依靠三個機制的組合：

1. Hooks（鉤子）

Claude Code 有 PreToolUse、PostToolUse、Stop 等 hook 類型，讓你可以在代理執行工具前後插入邏輯。SuperPortia 的 superportia-ops repo 有 17 個 hook 檔案，覆蓋：

protect-files.sh（PreToolUse）：在代理嘗試編輯 .env、wrangler.toml、settings.json 等敏感設定檔時，直接拒絕並要求人工授權
session_end_daily_log.sh（Stop hook）：session 結束時自動在 Vault 建立工作日誌 stub，防止零記錄
pre-commit-freshness-check.sh（PreToolUse）：在 git commit 前檢查涉及的套件是否有 Perishable Knowledge 風險

Stop hook 特別重要——它是文件自檢的最後防線。如果代理這次回覆寫了 .md 文件但沒有輸出 Doc Quality Self-Check，Stop hook 會攔截並要求補上，代理才能結束這輪回覆。

2. Ops Repo 作為 SSoT

所有規則、技能、hooks 都存放在 superportia-ops repo 的 .claude/ 目錄下。這是唯一的真相來源（SSoT）。

SS1（Mac）用 symlink 連結到 ops repo：

ln -s ../superportia-ops/.claude .claude

這意味著任何 ops repo 有新 push，所有使用 symlink 的 repo 立即生效，不需要手動同步。

3. 五鐵律（Five Iron Rules）— 跨機器同步

SS2 漂移事件催生了 cross-ship-sync.md 的五鐵律：

鐵律一：superportia-ops 是 .claude/ 的唯一 SSoT。要改規則 → 改 ops，不改本地。

鐵律二：Config 只從 ops → ships 流動，永不逆流。SS2 上寫了新技能？先 PR 到 ops，merge 後再 sync 下來。

鐵律三：sync script 執行時，本地 .claude/ 被 ops 版本完全覆蓋。本地未提交的修改會被丟棄。這是設計，不是 bug。

鐵律四：在任何 ship 上新建 skill/rule/hook，必須在 ops repo 上建，再同步到各 ship。

鐵律五：任何 .claude/ 內容衝突，ops repo 版本為準。沒有例外。

這五條規則把「設定漂移」從「可能發生」變成了「結構上不可能發生」——只要規則有被遵守。

真實案例：規則如何從事故中誕生

EGS 的每一條規則背後幾乎都有一個具體事件。corrections.md 記錄了這些教訓，讓它們不會在下次 session 重蹈覆轍。

**「編輯了三次錯誤的檔案」**的教訓變成了一條具體規則：在編輯任何影響正在執行的服務的檔案前，必須先：

ps aux | grep <service> — 確認哪個路徑實際上在執行
grep WorkingDirectory <plist> — 確認 launchd 設定
編輯「正在執行的路徑」，而不是「應該是正確的路徑」

根本原因不是代理犯蠢，而是 ADR-0010 多 repo 遷移執行到一半——程式碼分出去了，launchd 沒更新。結構上製造了一個陷阱，規則的作用是在陷阱發生之前讓代理先停下來驗證。

文件壓縮缺陷的解法是雙重的：documentation-standards.md 明確定義了什麼算「詳細」（有背景、有具體數字、有前後狀態），加上 Stop hook 在技術層面強制要求。規則不只是勸說，還有執行機制配合。

SS2 漂移事件的解法不是「要求代理更小心」，而是改變架構——五鐵律讓單向流動成為結構約束，而不是靠記憶遵守的習慣。

EGS 的位置

在 SuperPortia 的治理層次裡，EGS 不是最高層。最上面是公司憲法（Company Constitution），定義了最基本的行為原則——什麼需要人工確認（HITL）、如何對齊公司目標（GSTA）、知識如何記錄等。

EGS 把憲法的原則轉化成工程實踐的具體規範：程式碼怎麼寫、文件怎麼寫、設定怎麼管理。

憲法是「為什麼」，EGS 是「怎麼做」。

所有衍生的規則檔案（superportia-ops/.claude/rules/ 下的 19 個 .md 文件）是「具體是什麼」。

這個三層結構讓修改變得清晰：要調整一個具體行為，改對應的 rule 檔案；要調整一個工程原則，改 EGS spec；要調整公司運作的根本邏輯，改憲法——每一層改動都有對應的影響範圍。

SuperPortia 用 EGS 管理 AI 代理團隊的方式，本質上和管理人類工程師沒有太大不同：需要書面規範、需要版本控制、需要執行機制、需要從事故中學習並更新規範。

差別在於，代理沒有情境記憶，所以每一條規則都必須是顯式的，不能靠「你懂的」。這反而逼出了一套比很多人類工程團隊更清晰的規範文化。

也可以參考 Context Hub 介紹了解 SuperPortia 的知識管理基礎設施，以及多代理 CLI 協作了解這些規範在實際多 agent 工作流程中如何運作。