604e38cf07
- CLAUDE.md: 紅區治理章節 - Skills 01/03: 版本更新 - ADR/Architecture: 標準化 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
346 lines
9.4 KiB
Markdown
346 lines
9.4 KiB
Markdown
# 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 視為開發失敗！**
|
||
|
||
### 範例
|
||
|
||
```tsx
|
||
// ❌ 錯誤 - 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 技術，將純白背景濾除：
|
||
|
||
```tsx
|
||
// ✅ 正確 - 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 色塊 + 字體排版 |
|
||
|
||
**範例：**
|
||
|
||
```tsx
|
||
// ❌ 錯誤 - 依賴實體圖片
|
||
<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 (加入第七章：視覺資產協作規範)*
|