awoooi/GLOBAL_RULES.md

AWOOOI 專案開發憲法與行為準則

本文件為 AWOOOI 專案的最高行為準則。所有開發成員必須 100% 嚴格遵守，沒有例外！

---

第一章：Triage (傷患分級) 異常處理鐵律

🔴 紅燈異常 (立刻停機修復)

以下情況視為紅燈異常，必須立刻停止所有新功能開發：

• 架構阻斷
• API 無法連線 (CORS / Failed to fetch)
• 編譯失敗
• 嚴重的資安漏洞 (如 Multi-Sig 邏輯錯誤)

行為準則：

底層斷了，上面蓋的 UI 也只是壞的。優先修復紅燈，禁止繞過！

🟡 黃燈異常 (記錄 Backlog，延後處理)

以下情況視為黃燈異常，不應打斷開發心流：

• UI 排版稍微跑位
• 非關鍵字的 i18n 翻譯遺漏
• 非阻斷性的 Warning

行為準則：

記錄進 WBS 待辦清單，集中在 Phase 結束前的「Bug Bash」一次解決。

---

第二章：0 個 Hardcode 字串與 i18n 清零鐵律

最高憲法

前端 UI 代碼絕對禁止出現任何寫死的中文或英文字串！

所有 UI 文字必須 100% 透過 next-intl 從字典檔提取，包含但不限於：

• 按鈕文字
• 標籤與標題
• 狀態文字
• 列舉值顯示 (如 CRITICAL → 危急)
• 錯誤訊息
• 表單欄位標籤
• Tooltip 與提示文字

優先級

優先級	語系	說明
1	繁體中文 (zh-TW)	最高優先級預設顯示
2	英文 (EN)	雙軌並行

Hardcoded English 視為開發失敗！

範例

// ❌ 錯誤 - Hardcode (違憲)
<span>CRITICAL</span>
<button>Approve</button>
<span>No recent backup!</span>

// ✅ 正確 - 使用 next-intl
const t = useTranslations('risk')
const tDryRun = useTranslations('dryRun')
<span>{t('critical')}</span>
<button>{t('approve')}</button>
<span>{tDryRun('noRecentBackup')}</span>

違規處理

違背此規則視為開發失敗，必須立即修正後才能繼續其他任務！

---

第三章：防禦性工程與 Zero Trust 鐵律

1. 先質疑，後實作 (Fail Fast & Ask)

遇到以下架構盲區時，絕對禁止自行假設或使用脆弱的臨時方案：

• 缺乏認證憑證
• 狀態機定義不完整
• 可能導致資料遺失 (如 In-memory 儲存稽核日誌)

行為準則：

必須立刻暫停實作，列出選項並向統帥回報 Blocker。

2. 零信任預設 (Zero Trust Defaults)

所有環境變數與安全配置，必須預設為最嚴格狀態：

• MOCK_MODE=False
• 禁止 CORS *
• 禁止重複簽核
• 禁止跳過驗證

3. 強制乾跑 (Dry-run Mandatory)

任何牽涉到基礎設施變更的破壞性操作，必須在程式碼層級實作並呼叫 Dry-run（預檢）機制：

• K8s API 操作
• SSH 命令執行
• Database Drop/Truncate
• 任何不可逆操作

4. 邊界預判 (Edge Case Anticipation)

寫任何邏輯前，必須先思考並實作防呆機制：

• 「如果網路斷線怎麼辦？」→ 重試機制
• 「如果使用者連按兩次怎麼辦？」→ 冪等性設計
• 「如果 K8s API 回應超時怎麼辦？」→ 超時處理

---

第四章：CPO 絕對美學與品牌靈魂鐵律

1. Pixel-Perfect 細節至上

UI 實作必須嚴格講究：

要素	標準
Padding/Margin	必須有「呼吸感」，絕不允許擁擠
Typography	字體大小與粗細必須建立清晰的視覺層級
邊框與陰影	使用微妙的 border-opacity 與 subtle shadows
質感	Nothing.tech 那種「通透感與極簡」

禁止事項：

• 禁止使用預設的、廉價的樣式
• 禁止元素不對齊
• 禁止忽略 hover/active 狀態的視覺回饋

2. 生物機械有機進化

IT AI 的 UI 不要硬綁綁！視覺上必須融合：

風格來源	精髓
openclaw.ai	有機、流線、親和力
Nothing.tech	通透、工業風、極簡

禁止生硬的幾何設計！

3. 品牌靈魂 - Claw 設計語言

AWOOOI 的核心品牌意象為「智慧之眼機械爪 (Mechanical Claw)」：

• Logo 必須體現「Claw」精密抓取的意象
• 側邊欄展開/折疊應模擬爪子開合
• HITL 批准動畫應呈現爪子鎖定的效果
• 顏色基調：純白工業風、金屬光澤、科技感

4. CSS 代碼去背 SOP (CRITICAL)

當整合 Raster 圖像 (JPEG/PNG) 資產時：

絕對禁止直接放上死白貼紙！

必須強制套用 CSS 技術，將純白背景濾除：

// ✅ 正確 - mix-blend-mode 去背
<img
  src="/logo-claw.png"
  className="mix-blend-multiply contrast-[1.1] saturate-[1.1]"
/>

// ✅ 備選 - mask-image 去背
<div
  style={{
    maskImage: 'url(/logo-claw.png)',
    maskSize: 'contain',
    backgroundColor: 'currentColor',
  }}
/>

目標：讓有機設計看起來刻在玻璃 UI 上！

5. 跨界協作 - Gemini 資產生成 SOP

本專案嚴禁使用：

• 醜陋的純文字 Placeholder
• 隨便找的開源 Icon 來充當核心視覺資產

當需要高質感視覺資產時：

1. 在終端機輸出一段『給 Gemini 的圖像生成提示詞 (Prompt)』
2. 標註資產規格（尺寸、格式、透明背景需求）
3. 統帥將該提示詞交給 Gemini 生成完美圖檔
4. 收到圖檔後整合至專案（使用 CSS 去背 SOP）

---

第五章：開發階段與視覺素材戰略 (Phased Visual Strategy)

Phase 1 & 2 (當前階段) - 核心引擎與真實數據 (Function over Form)

絕對禁止在此階段耗費時間進行：

• UI 打磨
• 複雜 SVG/PNG 素材替換
• 微動畫設計
• Logo 視覺調整

視覺降級為『乾淨的 Wireframe 級別』：

• 使用純文字 Typography
• 標準 Tailwind CSS 即可
• 簡潔的 CSS 呼吸燈代替圖片 Logo

唯一目標：

1. 100% 真實 API 資料貫通
2. Multi-Sig 邏輯實作
3. i18n 字串清零
4. 消滅所有 Mock Data

Phase 4 (未來階段) - 視覺靈魂注入 (Visual Soul Injection)

啟動條件：所有後端資料欄位、狀態機與 API 100% 確定不改動後，才准啟動此階段。

屆時將統一實作：

• Q 版、玩具感 (Toy-ish) 的流線型 OpenClaw 品牌資產
• 色彩鮮明的視覺設計
• 精緻的微動畫效果
• 統帥親自批准的品牌視覺素材

---

第六章：決策支援協定 (Decision Support Protocol)

情報完整性

在遇到需要統帥（使用者）進行重大架構、功能或視覺決策的十字路口時，絕對禁止只拋出問題而不給予分析。

標準回報格式

任何決策請求，必須包含以下三個完整板塊：

1. 現況盤點 (Context)

• 我們現在在哪裡？
• 遇到了什麼瓶頸或機會？
• 相關的技術背景與約束條件

2. 戰略選項 (Options)

列出可行的路線，並詳述各自的優劣：

選項	優勢 (Pros)	風險與代價 (Cons)
Path A	...	...
Path B	...	...
Path C	...	...

3. 首席架構師的明確建議 (Architect's Recommendation)

AI 必須根據專案的最終目標，給出一個最推薦的選項，並附上強而有力的理由：

📌 建議選擇：Path X

理由：
1. [具體原因 1]
2. [具體原因 2]
3. [與專案目標的契合度]

禁止事項

• ❌ 只拋出問題，讓統帥自己想答案
• ❌ 列出選項但不給建議
• ❌ 給出模稜兩可的「都可以」回答
• ❌ 缺乏具體分析的空泛建議

---

第七章：視覺資產協作規範 (Asset Collaboration Protocol)

1. 前期階段 (當前) - 純代碼視覺鐵律

絕對禁止要求統帥（使用者）手動下載、搬運實體圖檔 (PNG/JPG/SVG)。

替代方案：

場景	正確做法
Logo	使用 lucide-react 圖示 + CSS Typography (如 Bot, Cpu, Brain)
圖示	使用 lucide-react 圖標庫 (AlertTriangle, Shield, Server 等)
狀態指示器	使用純 CSS 呼吸燈、脈動效果 (animate-ping, animate-pulse)
品牌色塊	使用 Tailwind 漸層背景 (bg-gradient-to-br)
Placeholder	使用高質感的 CSS 色塊 + 字體排版

範例：

// ❌ 錯誤 - 依賴實體圖片
<img src="/logo-claw.png" alt="Logo" />

// ✅ 正確 - 純代碼方案
import { Bot, Sparkles } from 'lucide-react'

<div className="flex items-center gap-3">
  <div className="w-10 h-10 rounded-xl bg-claw-blue/10 flex items-center justify-center">
    <Bot className="w-6 h-6 text-claw-blue" />
  </div>
  <span className="font-mono font-bold tracking-widest">AWOOOI</span>
</div>

2. 最終階段 (延後執行) - 品牌資產批次替換

啟動條件：專案準備正式上線前，所有功能與 API 100% 穩定。

屆時執行：

1. 由統帥統一提供高畫質 3D 渲染品牌圖檔
2. 一次性批次替換所有 Placeholder
3. 確保零破損的視覺升級

3. 違規處理

• ❌ 嘗試讀取 /logo-claw.png 或任何不存在的圖片
• ❌ 要求統帥下載並放入圖片檔案
• ❌ 使用 404 圖片導致 UI 破損

以上行為視為開發失敗，必須立即修正！

---

附錄：其他強制規則

規則	說明
禁止 UAT 環境	只有 Dev + Prod
API 路由規範	使用路徑路由 /api/v1/ (非子域名)
Playwright 測試	必須啟用截圖與錄影
紅燈優先	遇到 API 阻斷等紅燈問題，必須優先修復才能開發新功能
純代碼視覺	前期階段使用 lucide-react + CSS，禁止依賴實體圖片

---

最後更新: 2026-03-20 版本: 2.3 (加入第七章：視覺資產協作規範)